Retrieve Hyperliquid perpetual positions, leverage, PnL, and account health for any wallet address.
What it does
This endpoint returns real-time perpetual position data for a given Hyperliquid wallet address by querying the Hyperliquid API through Nansen's profiler. It provides detailed position-level information including entry price, mark price, unrealized PnL, leverage (type and value), liquidation price, margin used, and return on equity for each open position. Account-level summaries are also included: cross margin account value, total margin used, total net liquidation position, and withdrawable balance.
The endpoint is part of Nansen's broader Profiler API suite, which covers wallet balances, transactions, PnL, counterparties, labels, and related wallets across 25+ chains. This specific endpoint focuses exclusively on Hyperliquid perpetual contracts. It accepts a 42-character hex address and supports optional filters on token symbol, position value, position type, and unrealized PnL, as well as custom sort ordering.
Pricing is $0.01 per call via the x402 protocol, or 10 credits (free tier) / 1 credit (pro tier) when using a Nansen API key. Rate limits are enforced per-second and per-minute, reported in response headers. The endpoint returns HTTP 402 for unauthenticated callers, which is the standard MPP/x402 payment challenge indicating the endpoint is live and ready to accept payment.
Capabilities
Use cases
- —Monitor a trader's open Hyperliquid perpetual positions and unrealized PnL in real time
- —Assess liquidation risk by checking leverage levels and liquidation prices for a wallet
- —Build dashboards showing account health metrics (margin used, withdrawable balance, account value)
- —Track smart money perpetual positioning by querying known wallet addresses
- —Integrate perp position data into automated trading or risk management systems
Fit
Best for
- —Querying real-time Hyperliquid perpetual positions for a specific wallet
- —Assessing account-level margin health and liquidation risk
- —Agents or bots that need per-call pay-as-you-go blockchain analytics
Not for
- —Historical perpetual position snapshots (use profiler/perp-trades or TGM endpoints instead)
- —Spot token balances or DeFi holdings (use profiler/address/current-balance or portfolio/defi-holdings)
- —Aggregated market-wide perp data (use TGM perp-positions or perp-screener endpoints)
Quick start
curl -X POST https://api.nansen.ai/api/v1/profiler/perp-positions \
-H 'Content-Type: application/json' \
-d '{"address": "0xa312114b5795dff9b8db50474dd57701aa78ad1e"}'Example
Request
{
"address": "0xa312114b5795dff9b8db50474dd57701aa78ad1e",
"filters": {
"position_value_usd": {
"min": 1000
}
},
"order_by": [
{
"field": "position_value_usd",
"direction": "DESC"
}
]
}Response
{
"data": {
"time": 1761283435707,
"withdrawable": "2933647.2403759998",
"assetPositions": [
{
"position": {
"size": "-90052.0",
"token_symbol": "MOODENG",
"leverage_type": "cross",
"leverage_value": 5,
"entry_price_usd": "0.311285",
"margin_used_usd": "2020.946984",
"return_on_equity": "3.1976362269",
"position_value_usd": "10104.73492",
"unrealized_pnl_usd": "17927.1615",
"liquidation_price_usd": "39.6872752647"
},
"position_type": "oneWay"
}
],
"margin_summary_account_value_usd": "4643143.4382309997",
"margin_summary_total_margin_used_usd": "1456365.231985"
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, clear pricing ($0.01/call via x402), and a live 402 MPP challenge confirming the endpoint is operational. Response schema references are well-documented with examples. Minor deduction because the crawled docs pages returned 404s (no standalone documentation site), so usage details come entirely from the OpenAPI spec.
Warnings
- —No standalone documentation pages were reachable (api.nansen.ai/docs returned 404); all information is derived from the OpenAPI spec.
- —Response schema uses $ref to PerpPositionsResponse/PerpPositionsData which are fully defined in components but the exact field names in a live response may vary slightly from the schema examples.
Citations
- —Endpoint is POST /api/v1/profiler/perp-positions and returns perpetual positions from Hyperliquid APIhttps://api.nansen.ai
- —Pricing is $0.01 per call via x402 protocol, or 10 credits (free) / 1 credit (pro)https://api.nansen.ai
- —Endpoint returned HTTP 402 on HEAD probe confirming it is live via MPP challengehttps://api.nansen.ai/api/v1/profiler/perp-positions
- —Request requires a 42-character hex address and supports filters on token_symbol, position_value_usd, position_type, unrealized_pnl_usdhttps://api.nansen.ai
- —Response includes assetPositions array with entry_price, mark_price, leverage, liquidation_price, unrealized_pnl, plus account-level margin summarieshttps://api.nansen.ai