# Perp Flow (`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.

- Category: Derivatives
- MCP tool: `derivatives_flow`
- REST: `GET /derivatives/flow/{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_flow

## What it does

USDT-margined perpetual flow for one coin on a 5m/15m/1h grid, from one venue: the deepest major exchange, or a second venue for coins it doesn't list (e.g. WAVES). Open interest (USD) at every bucket edge joined to taker buy and sell volume (USD), with each stretch read as new longs, new shorts, short covering or long unwind (OI direction × the aggressive side). The second venue publishes the taker split only for its last ~1000 trades, so its older buckets are read from OI against price direction instead, and every read states its basis (taker or price). Reports the window, the open-interest swings of 1% or more with the price and taker flow inside them (flagging aggressors absorbed by passive orders, taker basis only), and the buckets where OI moved most. One venue, not the market-wide aggregate. Use it to say whether a move was positions opening or closing, and which side pushed.

## Parameters

| Name | Type | In | Required | Description |
| --- | --- | --- | --- | --- |
| `symbol` | string | path | yes | Coin symbol, e.g. "ETH". |
| `hours` | integer | query | no | Trailing window in hours, 1–72. Default 24. At 5m the window is capped at about 41h by the venue's 500-snapshot limit. |
| `interval` | string | query | no | Bucket size. Default 15m. One of: `5m`, `15m`, `1h`. |

## Call it

### cURL

```bash
curl "https://mcp.f1ow.com/v1/derivatives/flow/BTC?hours=24&interval=1h" \
  -H "Authorization: Bearer $F1OW_API_KEY"
```

### MCP

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "derivatives_flow",
    "arguments": {
      "symbol": "BTC",
      "hours": 24,
      "interval": "1h"
    }
  }
}
```

### TypeScript

```ts
const res = await fetch("https://mcp.f1ow.com/v1/derivatives/flow/BTC?hours=24&interval=1h", {
  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/flow/BTC?hours=24&interval=1h",
    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_flow",
    "arguments": {
      "symbol": "BTC",
      "hours": 24,
      "interval": "1h"
    }
  }
}

// Or push a fresh result whenever it changes (minimum interval 15 s)
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "subscriptions/subscribe",
  "params": {
    "name": "derivatives_flow",
    "arguments": {
      "symbol": "BTC",
      "hours": 24,
      "interval": "1h"
    },
    "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/flow/BTC?hours=24&interval=1h"
```

## Sample response

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

```json
{
  "buckets": 24,
  "caveats": [
    "Binance only: the largest perp venue on the majors, but not the market-wide aggregate. Do not add it to derivatives_open_interest figures.",
    "Open interest is net of both sides and a taker buy can close a short as well as open a long, so a read names the dominant aggressor against the net change, not who holds the positions.",
    "The newest bucket is still forming; its open-interest change is unknown until the next snapshot."
  ],
  "episodes": [
    {
      "absorbed": false,
      "endMs": 1794488400000,
      "oiChangePct": 1.44911735786522,
      "oiEndUsd": 7345230677.3472,
      "oiStartUsd": 7240310087.1116,
      "priceChangePct": -0.917466113295998,
      "priceEnd": 72886.4,
      "priceStart": 73561.3,
      "read": "opened_balanced",
      "readBasis": "taker",
      "startMs": 1794474000000,
      "takerBuyPct": 48.8422013390758,
      "takerBuyUsd": 849794403.686,
      "takerCoveragePct": 100,
      "takerSellUsd": 890082957.2595
    },
    {
      "absorbed": false,
      "endMs": 1794549600000,
      "oiChangePct": -6.83548399658549,
      "oiEndUsd": 6823169003.0088,
      "oiStartUsd": 7323785165.9732,
      "priceChangePct": -4.97269711233944,
      "priceEnd": 68113.1,
      "priceStart": 71677.4,
      "read": "long_unwind",
      "readBasis": "taker",
      "startMs": 1794499200000,
      "takerBuyPct": 45.6620656826249,
      "takerBuyUsd": 5160293609.2275,
      "takerCoveragePct": 100,
      "takerSellUsd": 6140758001.3024
    },
    {
      "absorbed": false,
      "endMs": 1794553200000,
      "oiChangePct": 2.63971098978072,
      "oiEndUsd": 7003280945.03253,
      "oiStartUsd": 6823169003.0088,
      "priceChangePct": 1.36185056641004,
      "priceEnd": 69040.8,
      "priceStart": 68113.2,
      "read": "new_longs",
      "readBasis": "taker",
      "startMs": 1794549600000,
      "takerBuyPct": 55.333986471809,
      "takerBuyUsd": 825996249.5799,
      "takerCoveragePct": 100,
      "takerSellUsd": 666750436.9447
    },
    {
      "absorbed": false,
      "endMs": 1794556800000,
      "oiChangePct": -1.21188036785782,
      "oiEndUsd": 6918409558.15376,
      "oiStartUsd": 7003280945.03253,
      "priceChangePct": -0.703641904497055,
      "priceEnd": 68555,
      "priceStart": 69040.8,
      "read": "long_unwind",
      "readBasis": "taker",
      "startMs": 1794553200000,
      "takerBuyPct": 47.0563928663865,
      "takerBuyUsd": 392649088.4406,
      "takerCoveragePct": 100,
      "takerSellUsd": 441773323.7394
    }
  ],
  "interval": "1h",
  "largestOiBuckets": [
    {
      "oiChangePct": -1.50974514722565,
      "oiChangeUsd": -108174693.306765,
      "priceChangePct": -0.994429951350204,
      "read": "long_unwind",
      "readBasis": "taker",
      "takerBuyPct": 43.0777868318867,
      "timeMs": 1794535200000
    },
    {
      "oiChangePct": -1.27968715554036,
      "oiChangeUsd": -90306519.0582523,
      "priceChangePct": -1.82225273394883,
      "read": "long_unwind",
      "readBasis": "taker",
      "takerBuyPct": 43.4867870999536,
      "timeMs": 1794538800000
    },
    {
      "oiChangePct": -2.32494062570955,
      "oiChangeUsd": -162410577.611103,
      "priceChangePct": -0.641403414594294,
      "read": "long_unwind",
      "readBasis": "taker",
      "takerBuyPct": 43.0215045752291,
      "timeMs": 1794546000000
    },
    {
      "oiChangePct": 2.63971098978072,
      "oiChangeUsd": 180111942.023735,
      "priceChangePct": 1.36185056641004,
      "read": "new_longs",
      "readBasis": "taker",
      "takerBuyPct": 55.333986471809,
      "timeMs": 1794549600000
    },
    {
      "oiChangePct": -1.21188036785782,
      "oiChangeUsd": -84871386.8787766,
      "priceChangePct": -0.703641904497055,
      "read": "long_unwind",
      "readBasis": "taker",
      "takerBuyPct": 47.0563928663865,
      "timeMs": 1794553200000
    }
  ],
  "market": "USDT-margined perpetual",
  "rule": "class = OI direction × taker aggressor (buyers aggressive when buy − sell ≥ 5% of taker volume, sellers when ≤ −5%); where the venue publishes no taker split, price direction stands in (up/down by ≥ 0.10% per bucket, 0.25% per episode or window) and the read says basis = price; OI is flat under 0.10% per bucket and 0.25% per window; an episode is an OI swing of ≥ 1.0% between zigzag pivots (revers…",
  "symbol": "BTC",
  "venue": "Binance",
  "window": {
    "oiChangePct": -4.44594948399867,
    "oiEndUsd": 6918409558.15376,
    "oiStartUsd": 7240310087.1116,
    "priceChangePct": -6.68394930486547,
    "priceEnd": 68644.5,
    "priceStart": 73561.3,
    "read": "long_unwind",
    "readBasis": "taker",
    "takerBuyPct": 47.014862737179,
    "takerBuyUsd": 9440673865.6402,
    "takerCoveragePct": 100,
    "takerSellUsd": 10639516346.5809
  },
  "windowHours": 24,
  "generatedAt": "2026-11-13T08:05:42.4284480+00:00"
}
```

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

```text
BTC Binance USDT-M perp flow, last 24h, 1h buckets (UTC). One venue, not the market-wide aggregate.
  window: price $73561.30 → $68644.50 (-6.68%) · OI $7.24B → $6.92B (-4.45%, -$321.9M) · taker buy 47% ($9.44B buy / $10.64B sell)
    read: long unwind (OI down, sellers aggressive)
  OI swings ≥ 1.0%:
    11-12 09:00–13:00  OI +1.45% (+$104.9M)  price -0.92%  taker buy 49%  positions opened, taker flow balanced
    11-12 16:00–11-13 06:00  OI -6.84% (-$500.6M)  price -4.97%  taker buy 46%  long unwind (OI down, sellers aggressive)
    11-13 06:00–07:00  OI +2.64% (+$180.1M)  price +1.36%  taker buy 55%  new longs (OI up, buyers aggressive)
    11-13 07:00–08:00  OI -1.21% (-$84.9M)  price -0.70%  taker buy 47%  long unwind (OI down, sellers aggressive)
  largest OI buckets:
    11-13 02:00  OI -1.51% (-$108.2M)  price -0.99%  taker buy 43%  long unwind (OI down, sellers aggressive)
    11-13 03:00  OI -1.28% (-$90.3M)  price -1.82%  taker buy 43%  long unwind (OI down, sellers aggressive)
    11-13 05:00  OI -2.32% (-$162.4M)  price -0.64%  taker buy 43%  long unwind (OI down, sellers aggressive)
    11-13 06:00  OI +2.64% (+$180.1M)  price +1.36%  taker buy 55%  new longs (OI up, buyers aggressive)
    11-13 07:00  OI -1.21% (-$84.9M)  price -0.70%  taker buy 47%  long unwind (OI down, sellers aggressive)
  forming 08:00: price $68644.50, taker buy 60% so far, OI change not yet known
```

## Related tools

- [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.
- [Open Interest](https://www.f1ow.com/docs/tools/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.
- [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.