Perpetuals API

Whale positions: perpetual positions over $1M open right now

Every open position over $1M right now — account, market, side, size, prices, leverage, margin, PnL, funding — plus the long/short split. Filter by market, side or value.

GET/api/external/perps/perps-whale-positions

Get a free API key Try it in the API reference

What it returns

Every open position worth more than $1,000,000 notional on the perpetual-futures venue this family covers, right now, largest first — the trading account, the coin, which side, size, entry/mark/liquidation price, leverage, margin, unrealized PnL and funding paid — plus a summary of how many are long versus short and their total notional. trader is the same trading-account address perps-trader and perps-trader-positions take, not a wallet on any of this API's chains. Chainless and market-wide: filter to one market with symbol (the ticker perps-markets lists, e.g. "BTC", "kPEPE" — not an instrument id such as "BTC-USD" and not a token mint or contract address). perps-market-positions lists every open position on one market regardless of size. No filter matching anything right now — including a symbol this resource does not track, which reads the same way — answers 200 with an empty list and zero counts, never a 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-whale-positions"

Parameters
Parameter	Description
`limit` query · integer · optional	How many positions to return, largest notional first. Defaults to 50; at most 2000. Applied AFTER `summary` is computed, so `summary.count` can exceed the number of positions returned. limit ≤ 80 keeps the answer under 32 KB.
`symbol` query · string · optional	Keep only one market, by coin ticker, e.g. "BTC". Case-insensitive. Not a token mint or contract address.
`side` query · string · optional	Keep only longs or only shorts.`longshort`
`minValueUsd` query · number · optional	Keep only positions whose `positionValueUsd` is at least this, USD.

Response fields

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

Response fields of Whale positions: perpetual positions over $1M open right now
Field	Type	Description
`positions`	object[]	The positions kept, largest notional first, after every filter and then `limit`.
`positions[].trader`	string \| null	The trading account holding this position, e.g. "0x5b5d…". Not a wallet on this API's chains.
`positions[].symbol`	string \| null	The coin of the perpetual market, e.g. "BTC".
`positions[].side`	string \| null	Long or short, from the sign of the position size.
`positions[].size`	number \| null	Position size in the market's own units (coins), always positive; `side` carries the direction.
`positions[].positionValueUsd`	number \| null	Current notional value of the position, USD.
`positions[].entryPrice`	number \| null	Average entry price, formatted to 4 decimal places. A sub-cent market keeps only 1-2 significant figures (measured), so the true entry can differ slightly from what is published.
`positions[].markPrice`	number \| null	The mark price used for PnL and liquidation, full precision as sent.
`positions[].liquidationPrice`	number \| null	Estimated liquidation price, to 4 decimal places. `null` when the venue has none to give for this position (measured on cross-margin longs only); a real liquidation price under $0.00005 would also read `null`.
`positions[].leverage`	number \| null	The position's configured leverage multiplier — not its current effective leverage.
`positions[].marginMode`	string \| null	The margin mode this position uses.
`positions[].marginUsd`	number \| null	Margin this position uses, USD (on a cross position, positionValueUsd divided by leverage) — not the trading account's total equity.
`positions[].unrealizedPnlUsd`	number \| null	Current unrealized profit and loss, USD.
`positions[].fundingPaidUsd`	number \| null	Net funding since the position was opened, USD. Positive means the position PAID funding; negative means it RECEIVED funding.
`positions[].openedAt`	number \| null	Unix seconds the position was opened.
`positions[].updatedAt`	number \| null	Unix seconds this snapshot was last updated (measured within a few minutes of the read).
`summary`	object	Computed over EVERY position matching the filters, before `limit` truncates `positions` — `count` can exceed `positions.length` when more positions match than `limit` returns.
`summary.count`	integer	How many positions matched the filters, before `limit`.
`summary.long`	object
`summary.long.count`	integer	How many matching positions are long.
`summary.long.positionValueUsd`	number	Their combined notional value, USD.
`summary.short`	object
`summary.short.count`	integer	How many matching positions are short.
`summary.short.positionValueUsd`	number	Their combined notional value, USD.

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.

Perpetual-futures markets, all of them
List the markets and their tickers first, to filter by one of them.
Open positions in one perpetual-futures market
Every open position on one market, not only the ones over $1,000,000.
Whale alerts: perpetual positions over $1M just opened or closed
The recent opens and closes that produced today's standing whale positions.
Liquidation levels for one perpetual-futures market
Where a market's liquidations would cluster if price moved.
Max-pain liquidation level, per coin
The individual large positions that would be force-liquidated at these levels.
The market-wide derivatives indices by day, with one coin's whale index
The derivatives risk index and derivatives market index as one daily series, oldest first, plus one coin's signed whale index on the same days when a ticker is given.

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