# Nansen Position Intelligence

> Nansen Position Intelligence is a paid API for AI agents from Nansen at api.nansen.ai, paid per call via MPP, $0.01/call, status unknown (last checked 2026-10-10).

Returns aggregated long/short position sizes for a perpetual contract token on Hyperliquid, broken down by trader cohorts (Smart Money, Whales, Top PnL, Public Figures).

## Facts

- Endpoint: POST https://api.nansen.ai/api/v1/tgm/position-intelligence?utm_source=zero.xyz
- Price: $0.01/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-10
- Activations on Zero: 0
- Provider: Nansen
- Docs: https://docs.nansen.ai
- Website: https://nansen.ai
- Tags: blockchain, smart-money, wallet, tokens, defi, analytics, profiler, dex, pnl, onchain, prediction-market, data
- Canonical page: https://www.zero.xyz/c/nansen-position-intelligence-2d307a23
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_4rDm21DAPWUoYRVhFQurW

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-position-intelligence-2d307a23 -d '<json body>'
```

Example prompt: Pull up the Nansen position intelligence for BTC on Hyperliquid — I want to see how whales and smart money traders are positioned, whether they're net long or short, and what the public figures are doing.

## When to prefer this

Use this endpoint when you need cohort-segmented position analysis for perpetual contracts on Hyperliquid — specifically when you want to compare how smart money, whales, and public figures are positioned relative to each other. Prefer this over general trade data endpoints when the goal is sentiment analysis or positioning intelligence across trader segments rather than individual trade records.

## Known failure modes

- Missing token_address returns 422 validation error
- Invalid or unsupported token symbol returns empty data array
- Network timeout or upstream Hyperliquid data unavailability returns 5xx error
- Authentication failure (missing or invalid API key) returns 401 unauthorized

## How this service works

This endpoint provides position intelligence analytics for perpetual contracts on Hyperliquid, showing aggregated position sizes (longs, shorts, and totals) broken down by various trader cohorts (Smart Money, Whales, Top PnL, Public Figures). It can be used for analyzing position distributions and sentiment across different trader segments.

## Output

Returns an array of position intelligence records with aggregated USD position sizes for each trader cohort: whale longs/shorts/total, smart trader (Smart HL Perps Trader) longs/shorts/total, top PnL trader longs/shorts/total, and public figure longs/shorts/total for the specified perpetual contract token.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMPositionIntelligenceRequest",
 "required": [
  "token_address"
 ],
 "properties": {
  "token_address": {
   "type": "string",
   "title": "Token Address",
   "examples": [
    "BTC"
   ],
   "minLength": 1,
   "description": "Token address (for perps and hyperliquid, validation is skipped)"
  }
 },
 "description": "Request model for TGM position-intelligence endpoint.\n\nThis endpoint provides position intelligence analytics for perpetual contracts\non Hyperliquid, showing aggregated position sizes by different trader cohorts.",
 "additionalProperties": false
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMPositionIntelligenceResponse",
 "required": [
  "data"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "TGMPositionIntelligence",
    "properties": {
     "whale_longs_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Whale Longs Usd",
      "examples": [
       2000000.5
      ],
      "description": "Sum of absolute long sizes for addresses labeled Whale."
     },
     "whale_total_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Whale Total Usd",
      "examples": [
       3000000.75
      ],
      "description": "Total absolute position size for addresses labeled Whale."
     },
     "whale_shorts_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Whale Shorts Usd",
      "examples": [
       1000000.25
      ],
      "description": "Sum of absolute short sizes for addresses labeled Whale."
     },
     "smart_trader_longs_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Smart Trader Longs Usd",
      "examples": [
       1000000.5
      ],
      "description": "Sum of absolute long sizes for addresses labeled Smart HL Perps Trader."
     },
     "smart_trader_total_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Smart Trader Total Usd",
      "examples": [
       1500000.75
      ],
      "description": "Total absolute position size for addresses labeled Smart HL Perps Trader."
     },
     "public_figure_longs_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Public Figure Longs Usd",
      "examples": [
       500000.5
      ],
      "description": "Sum of absolute long sizes for addresses labeled Public Figure."
     },
     "public_figure_total_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Public Figure Total Usd",
      "examples": [
       750000.75
      ],
      "description": "Total absolute position size for addresses labeled Public Figure."
     },
     "smart_trader_shorts_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Smart Trader Shorts Usd",
      "examples": [
       500000.25
      ],
      "description": "Sum of absolute short sizes for addresses labeled Smart HL Perps Trader."
     },
     "public_
… (truncated)
```

## More

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