---
title: "Perp Flow (OI × Taker, Binance or Bybit)"
method: GET
path: "/derivatives/flow/{symbol}"
tags: ["derivatives"]
---

# Perp Flow (OI × Taker, Binance or Bybit)

`GET /derivatives/flow/{symbol}`

## Request

- Base URL: `https://mcp.f1ow.com/v1`
- URL: `https://mcp.f1ow.com/v1/derivatives/flow/{symbol}`
- Auth: one of:
  - HTTP bearer
  - none

USDT-margined perpetual flow for one coin on a 5m/15m/1h grid, from one venue: Binance, or Bybit for coins Binance 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). Bybit publishes the taker split only for its last ~1000 trades, so older Bybit 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.

## Path parameters

- `symbol` string, required: Coin symbol, e.g. "ETH".

## Query parameters

- `hours` integer: 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` '5m' | '15m' | '1h': Bucket size. Default 15m.

## Response `200`

The result.

- object
  - `data` object
    - `symbol` string, required
    - `venue` string, required
    - `market` string
    - `interval` string
    - `windowHours` integer
    - `buckets` integer
    - `takerSplitFromMs` integer: When the venue covers only part of the window: the first bucket with a taker split
    - `window` object
      - `priceStart` number
      - `priceEnd` number
      - `priceChangePct` number
      - `oiStartUsd` number
      - `oiEndUsd` number
      - `oiChangePct` number
      - `takerBuyUsd` number
      - `takerSellUsd` number
      - `takerBuyPct` number
      - `takerCoveragePct` number: Share of volume whose taker split is known
      - `readBasis` 'taker' | 'price'
      - `read` 'new_longs' | 'new_shorts' | 'short_covering' | 'long_unwind' | 'opened_balanced' | 'closed_balanced' | 'oi_flat'
    - `episodes` object[]: Open-interest swings of at least 1% between zigzag pivots, oldest first
      - `startMs` integer
      - `endMs` integer
      - `oiStartUsd` number
      - `oiEndUsd` number
      - `oiChangePct` number
      - `priceStart` number
      - `priceEnd` number
      - `priceChangePct` number
      - `takerBuyUsd` number
      - `takerSellUsd` number
      - `takerBuyPct` number
      - `takerCoveragePct` number
      - `readBasis` 'taker' | 'price'
      - `read` string
      - `absorbed` boolean: Aggressors pushed one way, price went the other (taker basis only)
    - `largestOiBuckets` object[]
      - `timeMs` integer
      - `oiChangeUsd` number
      - `oiChangePct` number
      - `priceChangePct` number
      - `takerBuyPct` number
      - `readBasis` 'taker' | 'price'
      - `read` string
    - `rule` string
    - `caveats` string[]
  - `text` string, required: Human-readable rendering of the result.
  - `meta` ResponseMeta
    - `generatedAt` string, date-time: When the data was produced (source timestamp where the provider has one), ISO 8601 UTC

## Other responses

- `400`: An argument is missing or invalid.
- `401`: No credential was sent.
- `402`: x402 route: a priced call without a valid payment (challenge in the base64 PAYMENT-REQUIRED header). Metered routes: the account balance or access period is spent.
- `403`: The credential was rejected.
- `500`: Unexpected server error.
- `502`: The data source could not answer.

---

[API](https://skmtc.dev/f1ow/apis/f1ow-api.md) · [All operations](https://skmtc.dev/f1ow/apis/f1ow-api/llms.txt) · [OpenAPI document](https://skmtc.dev/f1ow/apis/f1ow-api/revisions/6974f25b6067?raw)