Perpetuals API

One trader tier's positioning on one perpetual market over time

How many accounts of one trader tier (whales, shrimp, money printers, rekt…) are long and short one perps market over time, and the USD on each side, hourly or daily.

GET/api/external/perps/perps-tier-history/{symbol}

Get a free API key Try it in the API reference

What it returns

For one tier of traders — a size tier ("shrimp" to "leviathan") or a PnL tier ("giga_rekt" to "money_printer"), as perps-trader-tiers lists them — how many of its accounts are long and short one perpetual market, and the USD of those longs and shorts, over time, oldest first. The accounts are those on the venue this family covers. The account counts are the tier's own and are not comparable with perps-long-short-history, which counts a different population of accounts. The newest bucket is normally the one still in progress (complete: false). Chainless — symbol is the market ticker perps-markets lists (e.g. "BTC", "kPEPE"), not an instrument id and not a token address. Buckets are 1 hour or 1 day. 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/perps-tier-history/<symbol>?tier=shrimp"

Parameters
Parameter	Description
`tier` query · string · required	The trader tier: a size tier or a PnL tier, as `perps-trader-tiers` names them.`shrimpfishdolphinapex_predatorsmall_whalewhaletidal_whaleleviathangiga_rektfull_rektsemi_rektexit_liquidityhumble_earnergrindersmart_moneymoney_printer`
`interval` query · string · optional	Bucket width. Defaults to one day.`1h1d`
`limit` query · integer · optional	How many of the most recent buckets to return, 1 to 1000. Defaults to 100. Fewer come back when the history is shorter or a bucket carries no figures. limit ≤ 200 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 trader tier's positioning on one perpetual market over time
Field	Type	Description
`symbol`	string	The market ticker as asked (it is matched case-insensitively).
`tier`	string	The trader tier.
`interval`	string	The bucket width.
`buckets`	object[]	Oldest first.
`buckets[].at`	number	The bucket's open, unix seconds.
`buckets[].longAccounts`	number \| null	The tier's accounts holding a long position on the market. null when not stated.
`buckets[].shortAccounts`	number \| null	The tier's accounts holding a short position on the market. null when not stated.
`buckets[].longUsd`	number \| null	The USD value of the tier's long positions on the market. null when not stated.
`buckets[].shortUsd`	number \| null	The USD value of the tier's short positions on the market. null when not stated.
`buckets[].complete`	boolean	Whether the bucket had ended when its figures were read. false on the bucket in progress.

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.

The perps venue's traders by size tier and by PnL tier
The tiers, their bounds and their venue-wide lean right now.
Perpetual-futures markets, all of them
List the markets and their tickers first, then ask about one of them.
One perpetual market's accounts long versus short over time
The market's accounts long versus short over time, across all traders (a different count of accounts).
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.
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.

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