Perpetuals API
One perpetual market's accounts long versus short over time
How many accounts on the perps venue are long and how many short one of its markets over time — counts, percents and the ratio, in 5-minute, hourly or daily buckets.
/api/external/perps/perps-long-short-history/{symbol}What it returns
How many trading accounts hold a long and how many a short position on one perpetual market, over time, oldest first: the counts, their total, the percent long and short, and long percent divided by short percent. The accounts are those on the venue this family covers — the markets perps-markets lists — not an aggregate across exchanges; derivatives-long-short-history answers other venues by instrument id, with top-trader measures. The newest bucket is normally the one still in progress when the figures were read (complete: false). Chainless — symbol is the market ticker perps-markets lists (e.g. "BTC", "kPEPE"), not an instrument id such as "BTC-USD" and not a token mint or contract address. Buckets are 5 minutes, 1 hour or 1 day; daily history is not contiguous (days can be missing). A ticker with no history answers 404 (unlike perps-market, which answers an unknown ticker with 400).
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/perps-long-short-history/<symbol>"
| Parameter | Description |
|---|---|
intervalquery · string · optional | Bucket width. Defaults to one day.5m1h1d |
limitquery · integer · optional | How many of the most recent buckets to return, 1 to 1000. Defaults to 100. Fewer come back when the market's history is shorter or a bucket carries no figures. limit ≤ 200 keeps the answer under 32 KB. |
symbolpath · 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.
| Field | Type | Description |
|---|---|---|
symbol | string | The market ticker as asked (it is matched case-insensitively). |
interval | string | The bucket width. |
buckets | object[] | Oldest first. |
buckets[].at | number | The bucket's open, unix seconds. |
buckets[].longAccounts | number | null | Accounts holding a long position. null when not stated. |
buckets[].shortAccounts | number | null | Accounts holding a short position. null when not stated. |
buckets[].accounts | number | null | Accounts holding a position, long plus short. null when not stated. |
buckets[].longPercent | number | null | Percent of those accounts long, as stated to two decimals. null when not stated. |
buckets[].shortPercent | number | null | Percent of those accounts short, as stated to two decimals. null when not stated. |
buckets[].ratio | number | null | longPercent divided by shortPercent, as stated to four decimals — from the rounded percents, so it can differ slightly from longAccounts / shortAccounts, and more when one side is small. 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. |
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