# Nansen Perpetual Positions Data

> Nansen Perpetual Positions Data is a paid API for AI agents from api.nansen.ai, paid per call via MPP or x402, $0.01/call, status unknown (last checked 2026-09-13).

Retrieves perpetual contract position data for a specified token or address via Nansen's on-chain analytics platform

## Facts

- Endpoint: GET https://api.nansen.ai/api/v1/profiler/perp-positions
- Price: $0.01/call
- Payment: MPP, x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/api-nansen-ai-01e8659c
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_ze-c0m9g0tutGYWemBHJk

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability api-nansen-ai-01e8659c
```

Example prompt: Can you pull up the current perpetual positions for wallet 0xAbC123... on Nansen — I want to see what perp contracts they're holding, including size, side, and entry price?

## When to prefer this

Use this endpoint when you need structured on-chain perpetual futures position data enriched with Nansen's wallet labels and smart money tagging. Prefer this over raw blockchain queries when you want aggregated, labeled position data rather than raw transaction logs, especially for Hyperliquid perp activity.

## Known failure modes

- Invalid or unsupported wallet/token address returns 400 or empty result
- Address with no perpetual positions returns empty array
- Rate limiting or authentication failure returns 401/429
- Network or provider outage returns 500
- Unsupported chain or protocol returns no data

## How this service works

Get Perpetual Positions Data

## Output

Returns a list of open perpetual contract positions associated with the queried address or token, including details such as position size, direction (long/short), entry price, leverage, and unrealized PnL as tracked by Nansen's on-chain data.

## Example request

```json
{
 "input": {
  "body": {
   "address": "0x1234567890123456789012345678901234567890"
  },
  "type": "http",
  "method": "POST",
  "bodyType": "json"
 }
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "PerpPositionsRequest",
 "required": [
  "address"
 ],
 "properties": {
  "address": {
   "type": "string",
   "title": "Address",
   "examples": [
    "0xa312114b5795dff9b8db50474dd57701aa78ad1e"
   ],
   "maxLength": 42,
   "minLength": 42,
   "description": "User's Hyperliquid address in 42-character hexadecimal format"
  },
  "filters": {
   "anyOf": [
    {
     "type": "object",
     "title": "PerpPositionsFilters",
     "properties": {
      "token_symbol": {
       "anyOf": [
        {
         "type": "string"
        }
       ],
       "title": "Token Symbol",
       "examples": [
        "BTC",
        "ETH",
        "SOL"
       ],
       "description": "Filter by token symbol"
      },
      "position_type": {
       "anyOf": [
        {
         "type": "string"
        }
       ],
       "title": "Position Type",
       "examples": [
        "oneWay"
       ],
       "description": "Filter by position type"
      },
      "position_value_usd": {
       "anyOf": [
        {
         "type": "object",
         "title": "NumericRangeFilter",
         "properties": {
          "max": {
           "anyOf": [
            {
             "type": "number"
            }
           ],
           "title": "Max",
           "examples": [
            50000,
            10000000,
            100
           ],
           "description": "Maximum value (inclusive)"
          },
          "min": {
           "anyOf": [
            {
             "type": "number"
            }
           ],
           "title": "Min",
           "examples": [
            1000,
            1000000,
            -50,
            0
           ],
           "description": "Minimum value (inclusive)"
          }
         },
         "description": "Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"
        }
       ],
       "examples": [
        {
         "min": 1000
        },
        {
         "max": 100000
        },
        {
         "max": 100000,
         "min": 1000
        }
       ],
       "description": "Filter by position value in USD"
      },
      "unrealized_pnl_usd": {
       "anyOf": [
        {
         "type": "object",
         "title": "NumericRangeFilter",
         "properties": {
          "max": {
           "anyOf": [
            {
             "type": "number"
            }
           ],
           "title": "Max",
  
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "PerpPositionsResponse",
 "required": [
  "data"
 ],
 "properties": {
  "data": {
   "type": "object",
   "title": "PerpPositionsData",
   "properties": {
    "time": {
     "anyOf": [
      {
       "type": "integer"
      }
     ],
     "title": "Time",
     "examples": [
      1761283435707
     ],
     "description": "Timestamp"
    },
    "withdrawable": {
     "anyOf": [
      {
       "type": "string"
      }
     ],
     "title": "Withdrawable",
     "examples": [
      "2933647.2403759998"
     ],
     "description": "Withdrawable USD"
    },
    "assetPositions": {
     "anyOf": [
      {
       "type": "array",
       "items": {
        "type": "object",
        "title": "AssetPosition",
        "properties": {
         "position": {
          "anyOf": [
           {
            "$ref": "#/components/schemas/Position"
           }
          ],
          "description": "Position data"
         },
         "position_type": {
          "anyOf": [
           {
            "type": "string"
           }
          ],
          "title": "Position Type",
          "examples": [
           "oneWay"
          ],
          "description": "Position type"
         }
        },
        "description": "Asset position wrapper.",
        "additionalProperties": false
       }
      }
     ],
     "title": "Assetpositions",
     "description": "List of asset positions"
    },
    "crossMaintenanceMarginUsed": {
     "anyOf": [
      {
       "type": "string"
      }
     ],
     "title": "Crossmaintenancemarginused",
     "examples": [
      "722948.2832910001"
     ],
     "description": "Cross maintenance margin used USD"
    },
    "margin_summary_total_raw_usd": {
     "anyOf": [
      {
       "type": "string"
      }
     ],
     "title": "Margin Summary Total Raw Usd",
     "examples": [
      "13987445.0243870001"
     ],
     "description": "Margin summary total raw USD"
    },
    "margin_summary_account_value_usd": {
     "anyOf": [
      {
       "type": "string"
      }
     ],
     "title": "Margin Summary Account Value Usd",
     "examples": [
      "4643143.4382309997"
     ],
     "description": "Margin summary account value USD"
    },
    "cross_margin_summary_total_raw_usd": {
     "anyOf": [
      {
       "type": "string"
      }
     ],
     "title": "Cross Margin Summary Total Raw Usd",
     "examples": [
      "13987445.0243870001"
     ],
     "description": "Cross margin summary total raw USD"
    },
    "m
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/api-nansen-ai-01e8659c/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)