x402basequality 0.88

Query Hyperliquid perpetual positions for any wallet address via Nansen's on-chain analytics API.

Price
per_call
Protocol
x402
Verified
no
Endpoint
https://api.nansen.ai/api/v1/profiler/perp-positions

What it does

The Nansen Profiler Perp Positions endpoint retrieves real-time perpetual contract positions for a given wallet address on Hyperliquid. It returns detailed position data including entry price, mark price, unrealized PnL, leverage, liquidation price, margin usage, and funding costs for each open position. The endpoint also provides account-level summaries such as total account value, margin used, and withdrawable balance.

This endpoint is part of the broader Nansen API v1, which offers over 40 endpoints spanning smart money tracking, wallet profiling, token analytics (Token God Mode), prediction market data (Polymarket), perpetual trading leaderboards, and AI-powered research agents. The perp-positions endpoint specifically accepts a POST request with a 42-character hex address and optional filters for token symbol, position value, position type, and unrealized PnL. Results can be sorted by fields like position_value_usd or unrealized_pnl_usd.

Pricing is $0.01 per call via the x402 protocol. The endpoint also supports traditional API key authentication with a credit-based system (10 credits on free tier, 1 credit on pro). Rate limits are exposed via response headers. The API returns standard JSON with pagination support.

Capabilities

hyperliquid-perp-positionswallet-profilingperpetual-futures-dataon-chain-analyticsreal-time-position-trackingleverage-monitoringunrealized-pnlliquidation-pricex402-payment

Use cases

  • —Monitor a specific trader's open Hyperliquid perpetual positions in real time
  • —Build risk dashboards showing leverage, liquidation prices, and margin usage for tracked wallets
  • —Integrate perp position data into trading bots or portfolio management tools
  • —Analyze smart money perpetual positioning for research or signal generation
  • —Track unrealized PnL across multiple positions for a given address

Fit

Best for

  • —Querying real-time Hyperliquid perp positions by wallet address
  • —Agents or bots that need per-call payment without API key subscriptions
  • —Developers building DeFi analytics dashboards with perpetual futures data

Not for

  • —Historical perpetual position snapshots (use profiler/perp-trades or TGM endpoints instead)
  • —Spot token balances or ERC-20 holdings (use profiler/address/current-balance)
  • —Non-Hyperliquid perpetual exchanges

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": "ETH",
          "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

URLhttps://api.nansen.ai/api/v1/profiler/perp-positions
Transporthttp
Protocolx402
Pay to0x93053f1e7A5eFEDa532Fe69CbbE43cBEc3A0F13f
CurrencyUSD COIN

Quality

0.88/ 1.00

Full OpenAPI 3.1 schema with detailed request/response models, clear pricing ($0.01/call via x402), live 402 challenge confirmed, and comprehensive endpoint documentation. Minor deductions: no crawled external docs beyond the OpenAPI spec, and response schema references are not fully resolved in the probe.

Warnings

  • —No external documentation pages were reachable beyond the OpenAPI spec (docs, pricing, README all returned 404).
  • —Response schema uses $ref to PerpPositionsResponse which is provided in components but example response is inferred from schema examples rather than a live call.

Citations

Provenance

Indexed fromx402_bazaar
Enriched2026-04-22 02:55:01Z · anthropic/claude-opus-4.6 · v2
First seen2026-04-21
Last seen2026-04-22

Agent access

JSONhttps://clawmart.sh/api/listings/jjctqY
Query Hyperliquid perpetual positions for any wallet address via Nansen's on-chain analytics API. — Clawmart · Clawmart