Retrieve open perpetual positions for a token on Hyperliquid via Nansen's blockchain analytics API.
What it does
This endpoint returns current perpetual contract positions for a specific token on Hyperliquid, sourced from Nansen's blockchain analytics platform. It provides detailed per-position metrics including entry price, mark price, leverage, unrealized PnL, liquidation price, and position value in USD. Results can be filtered by label type (smart money, whales, public figures, or all traders) and further refined with filters on position side (Long/Short), position value, entry price, unrealized PnL, and more.
The endpoint is part of Nansen's Token God Mode (TGM) suite, which offers comprehensive token-level analytics across multiple chains. It accepts a POST request with a JSON body specifying the token_symbol (e.g., "BTC", "ETH", "SOL") and optional label_type, pagination, filters, and order_by parameters. The response includes a paginated list of position records with address labels from Nansen's wallet profiling system.
Pricing is $0.05 per call via the x402 protocol, or 50 credits (free tier) / 5 credits (pro tier) when using a Nansen API key. Rate limits are enforced per-second and per-minute, reported via response headers.
Capabilities
Use cases
- —Monitor which smart money wallets hold large perpetual positions on a given token
- —Identify highly leveraged positions approaching liquidation for a specific asset
- —Analyze long/short positioning sentiment across labeled trader cohorts
- —Build dashboards showing real-time perp position distribution by wallet label
- —Screen for whale perpetual positions on Hyperliquid tokens
Fit
Best for
- —Crypto traders analyzing smart money perpetual positioning on Hyperliquid
- —Quantitative researchers studying leverage and liquidation risk by trader cohort
- —DeFi analytics dashboards needing per-address perp position data
- —Agents that need structured on-chain derivatives position intelligence
Not for
- —Spot token balance or holder queries (use TGM holders endpoint instead)
- —Historical position snapshots over time (this returns current positions only)
- —Non-Hyperliquid perpetual exchanges
Quick start
curl -X POST https://api.nansen.ai/api/v1/tgm/perp-positions \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{"token_symbol": "BTC", "label_type": "all_traders", "pagination": {"page": 1, "per_page": 10}}'Example
Request
{
"filters": {
"side": [
"Long"
],
"position_value_usd": {
"min": 10000
}
},
"order_by": [
{
"field": "position_value_usd",
"direction": "DESC"
}
],
"label_type": "smart_money",
"pagination": {
"page": 1,
"per_page": 5
},
"token_symbol": "BTC"
}Response
{
"data": [
{
"side": "Long",
"address": "0xa312114b5795dff9b8db50474dd57701aa78ad1e",
"leverage": "10X",
"upnl_usd": 2515.52,
"mark_price": 102512.415,
"entry_price": 100500,
"funding_usd": -45.23,
"address_label": "Smart HL Perps Trader [0xa312]",
"leverage_type": "cross",
"position_size": "1.25",
"liquidation_price": 91000,
"position_value_usd": "128140.51875"
}
],
"pagination": {
"page": 1,
"per_page": 5,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, clear endpoint description, x-payment-info and x-credit-cost metadata, and a confirmed live 402 MPP challenge. Minor deduction because no actual 200 response sample was captured in the probe and the specific TGMPerpPositionsRequest/Response schemas reference $ref components not fully expanded in the crawl.
Warnings
- —No live 200-response example was captured; example_response_json is inferred from the OpenAPI schema and field descriptions.
- —The endpoint only covers Hyperliquid perpetual contracts; other perp exchanges are not supported.
Citations
- —Endpoint returns current perpetual positions for a specific token on Hyperliquid with entry price, mark price, leverage, PnL, and liquidation price.https://api.nansen.ai
- —Pricing is $0.05 per call via x402 protocol, or 50 credits (free) / 5 credits (pro) via API key.https://api.nansen.ai
- —Supports label_type filtering: smart_money, all_traders, whale, public_figure.https://api.nansen.ai
- —Endpoint is live and returned HTTP 402 on HEAD probe (MPP challenge).https://api.nansen.ai/api/v1/tgm/perp-positions