Perpetuals API

One coin's margin longs and shorts over time

How much of a coin is held long and short on one exchange's margin book over time, in coin units, in 5-minute to daily buckets.

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

Get a free API key Try it in the API reference

What it returns

How much of one coin is held long and how much short on margin, over time, oldest first. The figures are Bitfinex's margin book only — one exchange's spot margin lending, not an aggregate across exchanges and not derivatives positioning (derivatives-long-short-history answers that). Both quantities are in units of the coin, not USD, and are not counts of positions or accounts. The source carries a figure forward until it next updates, so consecutive buckets can repeat exactly; an unchanged run is not evidence that nothing traded. The newest bucket is normally the one still in progress when the figures were read (complete: false). Chainless — symbol is a coin ticker (e.g. "BTC", "ETH"), not a token mint or contract address. A ticker with no history 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/margin-long-short-history/<symbol>"

Parameters
Parameter	Description
`interval` query · string · optional	Bucket width. Defaults to one day.`5m15m30m1h4h12h1d`
`limit` query · integer · optional	How many of the most recent buckets to return, 1 to 4500. Defaults to 100. Fewer come back when the coin's history is shorter. limit ≤ 350 keeps the answer under 32 KB.
`symbol` path · string · required	A coin ticker, e.g. "BTC" — the asset the market is on, not a token mint or contract address, and not scoped to any chain this API otherwise supports.

Response fields

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

Response fields of One coin's margin longs and shorts over time
Field	Type	Description
`symbol`	string	The coin ticker, upper-cased (it is matched case-insensitively).
`interval`	string	The bucket width.
`buckets`	object[]	Oldest first.
`buckets[].at`	number	The bucket's open, unix seconds.
`buckets[].longQuantity`	number \| null	Units of the coin held long on margin. null when not stated.
`buckets[].shortQuantity`	number \| null	Units of the coin held short on margin. 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 perpetual's long/short split over time: all accounts or top traders
The long/short split on derivatives venues rather than one exchange margin book.
One coin's margin borrow rate on one exchange over time
What it has cost to borrow the coin over the same period.
Funding-rate arbitrage: the widest funding gap per coin between two venues
Per coin, the two futures venues with the widest funding-rate gap: long and short leg with rate and open interest, the gap per interval and annualised. Keyed by ticker.
One coin's open interest right now, venue by venue and in total
A coin's derivatives open interest now on each venue and in total, split by margin type, with its change over the last 5 minutes to 24 hours.
One venue derivatives instrument's price candles with traded volume
OHLC price candles with USD volume for one perpetual or dated future on one venue, 1m to 1w per candle, oldest first.
One coin's taker buy and sell volume on perps, summed across venues, over time
A coin's perpetual taker buy and taker sell volume summed across venues, with the net, in USD per bucket from one minute to one week wide. Perpetuals only, not spot.

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