# Nansen Token God Mode Perpetual Positions

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

Retrieves Token God Mode (TGM) perpetual contract position data for a specific token, showing on-chain smart money perp exposure

## Facts

- Endpoint: GET https://api.nansen.ai/api/v1/tgm/perp-positions
- Price: $0.05/call
- Payment: MPP, x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/nansen-c8b5c368
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_rceGvtRd8IuPDlviJfY2_

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 nansen-c8b5c368
```

Example prompt: Pull the Token God Mode perp positions data from Nansen for ETH — I want to see how smart money wallets are positioned in perpetual contracts right now, especially large longs and shorts.

## When to prefer this

Use this endpoint when you need on-chain perpetual futures positioning data enriched with Nansen's smart money wallet labels for a specific token. Prefer this over generic DEX data endpoints when the goal is to understand institutional or whale-level perp exposure rather than spot holdings or trade history.

## Known failure modes

- Invalid or unrecognized token address returns an error or empty result
- Token not supported on tracked perp venues returns no data
- Authentication/payment failure returns 402 or 401 error
- Rate limit exceeded returns 429 error
- Malformed POST body returns 400 bad request
- No positions found for a low-liquidity or new token

## How this service works

Get "Token God Mode" (TGM) perp positions data

## Output

Returns a list of perpetual contract positions for the queried token, including wallet addresses with Nansen labels, position sizes, direction (long/short), leverage, and other on-chain perp metrics reflecting smart money exposure.

## Example request

```json
{
 "token_symbol": "AAVE"
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMPerpPositionsRequest",
 "required": [
  "token_symbol"
 ],
 "properties": {
  "filters": {
   "anyOf": [
    {
     "type": "object",
     "title": "TGMPerpPositionsFilters",
     "properties": {
      "side": {
       "anyOf": [
        {
         "enum": [
          "Long",
          "Short"
         ],
         "type": "string",
         "title": "PositionSide",
         "description": "Shared enum for position side direction."
        },
        {
         "type": "array",
         "items": {
          "enum": [
           "Long",
           "Short"
          ],
          "type": "string",
          "title": "PositionSide",
          "description": "Shared enum for position side direction."
         }
        },
        {
         "type": "null"
        }
       ],
       "title": "Side",
       "examples": [
        "Long",
        [
         "Short",
         "Long"
        ]
       ],
       "description": "Position side filter (Long or Short)"
      },
      "address": {
       "anyOf": [
        {
         "type": "string"
        },
        {
         "type": "array",
         "items": {
          "type": "string"
         }
        },
        {
         "type": "null"
        }
       ],
       "title": "Address",
       "examples": [
        "0x28c6c06298d514db089934071355e5743bf21d60"
       ],
       "description": "Trader address filter"
      },
      "upnl_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": [
        {
         "max": 10000,
         "min": -1000
        }
       ],
       "de
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMPerpPositionsResponse",
 "required": [
  "data",
  "pagination"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "TGMPerpPosition",
    "required": [
     "leverage"
    ],
    "properties": {
     "side": {
      "anyOf": [
       {
        "enum": [
         "Long",
         "Short"
        ],
        "type": "string",
        "title": "PositionSide",
        "description": "Shared enum for position side direction."
       }
      ],
      "examples": [
       "Long"
      ],
      "description": "Position direction (Long/Short)"
     },
     "address": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Address",
      "examples": [
       "0x1234567890123456789012345678901234567890"
      ],
      "description": "The wallet address of the trader."
     },
     "leverage": {
      "type": "string",
      "title": "Leverage",
      "examples": [
       "5X"
      ],
      "description": "The leverage applied to the position."
     },
     "upnl_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Upnl Usd",
      "examples": [
       500
      ],
      "description": "Unrealized profit/loss including funding."
     },
     "mark_price": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Mark Price",
      "examples": [
       50500
      ],
      "description": "The current mark price of the asset."
     },
     "entry_price": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Entry Price",
      "examples": [
       50000
      ],
      "description": "Average price where the position was opened."
     },
     "funding_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Funding Usd",
      "examples": [
       10.5
      ],
      "description": "Net funding paid (-) or received (+) since entry."
     },
     "address_label": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Address Label",
      "examples": [
       "Smart Money"
      ],
      "description": "Wallet or labeled entity holding the position."
     },
     "leverage_type": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Leverage Type",
      "examples": [
       "cross"
      ],
      "description": "The type of leverage used, e.g., cross or is
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-c8b5c368/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)