Perpetuals API

One venue perpetual's long/short split over time: all accounts or top traders

How one venue's traders on one perpetual lean long versus short over time — all accounts, or top traders by account or by position — with the ratio, 1m to 1w per bucket.

GET/api/external/perps/derivatives-long-short-history/{symbol}

Get a free API key Try it in the API reference

What it returns

How one venue's traders on one perpetual lean, long versus short, over time, oldest first: the share of all accounts (measure=accounts, default), of the venue's top traders' accounts (top-accounts) or of their positions (top-positions), with long divided by short. The newest bucket is normally the one still in progress when the figures were read (complete: false). The two percents are stated separately and are not always a split of 100: on OKX top positions they are small independent figures, not shares of a whole (read ratio), and on HTX and coin-margined Binance instruments top accounts sum well under 100. symbol is the venue's instrument id (e.g. "BTCUSDT", "BTC-USDT-SWAP") — take venue and instrument from a derivatives-coin-venues row whose venue is Binance, OKX, Bybit, Gate or HTX; other venues are not covered here. On OKX the figures are per coin: its USDT- and USD-margined swaps answer the same. An instrument the venue does not list answers 404.

Chains

This endpoint is not tied to a chain: it takes no chain in its request.

Request

Send your key in the x-dex-data-key header. Replace each <placeholder> with a real value.

curl -H "x-dex-data-key: $DEXDATA_API_KEY" \
  "https://api.dexdata.io/api/external/perps/derivatives-long-short-history/<symbol>?venue=Binance"

Parameters
Parameter	Description
`venue` query · string · required	The trading venue, spelled exactly as listed (case-sensitive), as derivatives-coin-venues names it. Only these venues are covered; on HTX only `top-accounts` and `top-positions` answer.`BinanceOKXBybitGateHTX`
`measure` query · string · optional	Whose longs and shorts: every account on the instrument (on OKX, on the coin) (default), the venue's top traders counted by account, or the venue's top traders counted by position size.`accountstop-accountstop-positions`
`interval` query · string · optional	Bucket width. Defaults to one day.`1m3m5m15m30m1h4h6h8h12h1d1w`
`limit` query · integer · optional	How many of the most recent buckets to return, 1 to 1000. Defaults to 100. Fewer come back when the instrument's history is shorter or a bucket carries no figures. limit ≤ 350 keeps the answer under 32 KB.
`symbol` path · string · required	The venue's own instrument id, as `instrument` in derivatives-coin-venues rows: e.g. "BTCUSDT" (Binance, Bybit), "BTC-USDT-SWAP" (OKX), "BTC_USDT" (Gate), "BTC-USDT" (HTX) — not a bare coin ticker such as "BTC", and not a token mint or contract address. Case-insensitive.

Response fields

A JSON response. Every field is always present; null means the value could not be established, never zero.

Response fields of One venue perpetual's long/short split over time: all accounts or top traders
Field	Type	Description
`venue`	string	The trading venue.
`instrument`	string	The instrument id asked for, upper-cased. On OKX the figures are the coin's, whichever of its swaps is asked.
`measure`	string	Whose longs and shorts are counted.
`interval`	string	The bucket width.
`buckets`	object[]	Oldest first.
`buckets[].at`	number	The bucket's open, unix seconds.
`buckets[].longPercent`	number \| null	Percent long, as stated to two decimals — on OKX top positions a small independent figure, not a share of a whole. null when not stated.
`buckets[].shortPercent`	number \| null	Percent short, as stated to two decimals — not always 100 minus longPercent. null when not stated.
`buckets[].ratio`	number \| null	Long divided by short, as stated to two decimals. null when not stated.
`buckets[].complete`	boolean	Whether the figures are final. false only on the newest bucket, which was still in progress when its figures were read.

Price per call

Every call: 6 credits

Charged only when the call succeeds. Prices as of 2026-10-30; the current ones are always in the API reference.

One venue derivatives instrument's price candles with traded volume
Same inputs: symbol, venue.
Large limit orders (walls) in one derivatives instrument's book on one exchange
Same inputs: symbol, venue.
Derivatives large orders brief: the biggest walls in a perp book
Same inputs: symbol, venue.
One venue derivatives instrument's basis against spot over time
Same inputs: symbol, venue.
One coin's futures markets across venues: funding, open interest, volume
Find the coin's venue and instrument id first (Binance, OKX, Bybit, Gate or HTX rows).
One coin's open interest across all venues, as candles over time
The coin's open interest across venues, same bucket widths; takes the coin ticker (BTC), not the instrument id.

Start building with DexData today

Sign in, create a key and make your first call in a minute. Free credits every month, and you only pay for calls that succeed.

Get a free API key