# Open Interest (`derivatives_open_interest`)

> Cross-exchange perpetual open interest with historical changes and a one-year baseline — how much leverage is committed, not merely how much changed hands. Venue-specific flow is a separate read.

- Category: Derivatives
- MCP tool: `derivatives_open_interest`
- REST: `GET /derivatives/open-interest/{symbol}`
- MCP App: hosts that support MCP Apps render the result as an interactive view
- x402 price: $0.01 per call (USDC on Base)
- HTML: https://www.f1ow.com/docs/tools/derivatives_open_interest

## What it does

Current market-wide (cross-exchange aggregate) open interest (USD) for one coin's perpetuals, with its 24h and 7d change, the 24h price change, AND the underlying 4h-bucket series. Read OI against price: price up on rising OI is new money opening positions, price up on falling OI is short covering — opposite trades off the same price move. The series makes that read available bucket by bucket instead of once per day (pair it with market_candles at 4h for the price leg), and carries the window's own low/high so the current level can be judged against where it has actually been. A 1y line ranks the level and today's 24h change against a year of daily closes (percentile, range with dates); the change rank is the better read, since the USD level mostly tracks price. Falls back to a single-venue figure if the aggregate source is offline. Set 'points' to trim the series (omit for the full ~10-day window; 0 to suppress it).

## Parameters

| Name | Type | In | Required | Description |
| --- | --- | --- | --- | --- |
| `symbol` | string | path | yes | Coin symbol, e.g. "BTC". |
| `points` | integer | query | no | How many of the newest 4h buckets to emit. Omit for the full window (60 points ~ 10 days); 0 suppresses the series and returns the summary only. |

## Call it

### cURL

```bash
curl "https://mcp.f1ow.com/v1/derivatives/open-interest/ETH" \
  -H "Authorization: Bearer $F1OW_API_KEY"
```

### MCP

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "derivatives_open_interest",
    "arguments": {
      "symbol": "ETH"
    }
  }
}
```

### TypeScript

```ts
const res = await fetch("https://mcp.f1ow.com/v1/derivatives/open-interest/ETH", {
  headers: { Authorization: `Bearer ${process.env.F1OW_API_KEY}` },
});
const data = await res.json(); // the tool's result as JSON, typed in the OpenAPI spec
console.log(data);
```

### Python

```python
import os, requests

res = requests.get(
    "https://mcp.f1ow.com/v1/derivatives/open-interest/ETH",
    headers={"Authorization": f"Bearer {os.environ['F1OW_API_KEY']}"},
)
data = res.json()  # the tool's result as JSON, typed in the OpenAPI spec
print(data)
```

### WebSocket

```jsonc
// wss://mcp.f1ow.com/v1/ws — subprotocol "jsonrpc-2.0", Authorization: Bearer <key>
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "derivatives_open_interest",
    "arguments": {
      "symbol": "ETH"
    }
  }
}

// Or push a fresh result whenever it changes (minimum interval 15 s)
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "subscriptions/subscribe",
  "params": {
    "name": "derivatives_open_interest",
    "arguments": {
      "symbol": "ETH"
    },
    "intervalSeconds": 60
  }
}
```

### x402

```bash
# No account: the first call answers 402 with a PAYMENT-REQUIRED challenge;
# an x402 client pays it in USDC on Base and retries.
curl "https://mcp.f1ow.com/x402/v1/derivatives/open-interest/ETH"
```

## Sample response

Captured 2026-11-13. The JSON is what REST and WebSocket return and the `structuredContent` of an MCP call (trimmed):

```json
{
  "aggregate": true,
  "baseline1y": {
    "change24h": {
      "atOrAboveMs": 1794441600000,
      "available": true,
      "days": 361,
      "high": 15.3604723929357,
      "highMs": 1773619200000,
      "low": -17.4932263789346,
      "lowMs": 1769817600000,
      "median": -0.186727545949317,
      "percentile": 13.2963988919668
    },
    "level": {
      "atOrAboveMs": 1794441600000,
      "available": true,
      "days": 362,
      "high": 41893459760,
      "highMs": 1767312000000,
      "low": 21762879650,
      "lowMs": 1782518400000,
      "median": 30874658601,
      "percentile": 7.4585635359116
    }
  },
  "changes": [
    {
      "changePct": -3.42460223309237,
      "nowUsd": 23824434723.3985,
      "priorUsd": 24669258708,
      "window": "24h"
    },
    {
      "changePct": -16.5485784539869,
      "nowUsd": 23824434723.3985,
      "priorUsd": 28548866253,
      "window": "7d"
    }
  ],
  "found": true,
  "openInterestUsd": 23840041160.8518,
  "priceChangePct24h": -5.70444,
  "series": {
    "intervalHours": 4,
    "points": [
      {
        "forming": false,
        "openInterestUsd": 28557977543,
        "timeMs": 1793707200000
      },
      {
        "forming": false,
        "openInterestUsd": 28378827858,
        "timeMs": 1793721600000
      },
      {
        "forming": false,
        "openInterestUsd": 28383963943,
        "timeMs": 1793736000000
      },
      {
        "forming": false,
        "openInterestUsd": 27810492518,
        "timeMs": 1793750400000
      },
      {
        "forming": false,
        "openInterestUsd": 28737494718,
        "timeMs": 1793764800000
      },
      {
        "forming": false,
        "openInterestUsd": 29255314249,
        "timeMs": 1793779200000
      },
      "… 47 more"
    ],
    "source": "CoinGlass"
  },
  "symbol": "ETH",
  "generatedAt": "2026-11-13T08:05:40.9716241+00:00"
}
```

Over MCP the text report a model reads comes with it:

```text
ETH open interest: $23840041161 | 24h price -5.70%
  24h  -3.4% ($24.67B -> $23.82B)
  7d   -16.5% ($28.55B -> $23.82B)
  1y   level at the 7th percentile of 362 daily closes (CoinGlass aggregate) | low $21.76B (2026-06-27) · median $30.87B · high $41.89B (2026-01-02)
       24h change -3.4% at the 13th percentile of the year's day-on-day changes (median -0.2%, range -17.5% to +15.4%)

Series (4h buckets, 53 points spanning 236h, oldest first, source CoinGlass):
  window low $23.56B / high $30.39B | now at 4% of window range
  2026-11-03 12:00     $28.56B         —
  2026-11-03 16:00     $28.38B    -0.63%
  2026-11-03 20:00     $28.38B    +0.02%
  2026-11-04 00:00     $27.81B    -2.02%
  2026-11-04 04:00     $28.74B    +3.33%
  2026-11-04 08:00     $29.26B    +1.80%
  2026-11-04 12:00     $30.17B    +3.14%
  2026-11-04 16:00     $29.95B    -0.74%
  2026-11-04 20:00     $29.99B    +0.14%
  2026-11-05 00:00     $29.98B    -0.05%
  2026-11-05 04:00     $30.28B    +1.01%
  2026-11-05 08:00     $30.39B    +0.38%
  2026-11-05 12:00     $27.59B    -9.23%
  2026-11-05 16:00     $28.45B    +3.11%
  2026-11-05 20:00     $28.02B    -1.50%
  2026-11-06 00:00     $28.18B    +0.58%
  2026-11-06 04:00     $28.57B    +1.38%
  2026-11-06 08:00     $28.55B    -0.08%
  2026-11-06 12:00     $28.53B    -0.07%
  2026-11-06 16:00     $28.29B    -0.83%
  2026-11-06 20:00     $28.21B    -0.30%
  2026-11-08 04:00     $27.82B    -1.37%
  2026-11-08 08:00     $27.86B    +0.13%
  2026-11-08 12:00     $27.89B    +0.13%
  2026-11-08 16:00     $27.84B    -0.18%
  2026-11-08 20:00     $26.05B    -6.43%
  2026-11-09 00:00     $26.31B    +0.98%
  2026-11-09 04:00     $25.93B    -1.43%
  2026-11-09 08:00     $26.16B    +0.89%
  2026-11-09 12:00     $26.57B    +1.56%
  2026-11-09 16:00     $26.32B    -0.95%
  2026-11-09 20:00     $26.17B    -0.56%
  2026-11-10 00:00     $26.06B    -0.42%
  2026-11-10 04:00     $26.24B    +0.69%
  2026-11-10 08:00     $26.26B    +0.08%
  2026-11-10 12:00     $24.71B    -5.90%
  2026-11-10 16:00     $25.01B    +1.24%
  2026-11-10 20:00     $24.99B    -0.11%
  2026-11-11 00:00     $25.12B    +0.54%
  2026-11-11 04:00     $25.24B    +0.47%
  2026-11-11 08:00     $25.22B    -0.08%
  2026-11-11 12:00     $25.14B    -0.30%
  2026-11-11 16:00     $25.05B    -0.35%
  2026-11-11 20:00     $24.78B    -1.10%
  2026-11-12 00:00     $24.84B    +0.26%
  2026-11-12 04:00     $25.03B    +0.74%
  2026-11-12 08:00     $24.67B    -1.42%
  2026-11-12 12:00     $25.02B    +1.41%
  2026-11-12 16:00     $24.85B    -0.66%
  2026-11-12 20:00     $24.83B    -0.10%
  2026-11-13 00:00     $23.56B    -5.10%
  2026-11-13 04:00     $23.79B    +1.00%
  2026-11-13 08:00     $23.82B    +0.13%
```

## Related tools

- [Perp Flow](https://www.f1ow.com/docs/tools/derivatives_flow) — Bucket-by-bucket open interest joined to taker buy/sell volume. Distinguish new positions from short covering and long unwind, with absorbed flow flagged. Coverage is stated; where taker data is unavailable, the read uses price direction and says so.
- [Liquidation History](https://www.f1ow.com/docs/tools/derivatives_liquidations) — Market-wide long/short liquidations and venue splits, ranked against a year of daily totals. A separate order sample reveals timing, cascades and the largest forced exits; its coverage is stated, never scaled up to the whole market.
- [Funding](https://www.f1ow.com/docs/tools/funding_current) — Current perpetual funding, normalized to an eight-hour rate and annualized, with history and a one-year percentile baseline. Positive means longs pay shorts; it is a cost of holding, not a direction forecast.
- [Market Regime](https://www.f1ow.com/docs/tools/research_regime) — What kind of market you are trading in. Seven forces — trend, volatility, cycle, sentiment, leverage stress, ETF liquidity, rotation — each voting with its own reasoning and its own threshold for changing the call.