---
title: "Get \"Token God Mode\" (TGM) position intelligence data"
method: POST
path: "/api/v1/tgm/position-intelligence"
tags: ["Token God Mode"]
---

# Get "Token God Mode" (TGM) position intelligence data

`POST /api/v1/tgm/position-intelligence`

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.

## Request body

- TGMPositionIntelligenceRequest — Request model for TGM position-intelligence endpoint. This endpoint provides position intelligence analytics for perpetual contracts on Hyperliquid, showing aggregated position sizes by different trader cohorts.
  - `token_address` string, required — Token address (for perps and hyperliquid, validation is skipped)

## Response `200`

TGM position intelligence data

- TGMPositionIntelligenceResponse — Response model for TGM position-intelligence endpoint. Contains position intelligence data with pagination and metadata.
  - `data` TGMPositionIntelligence[], required — List of TGM position intelligence records
    - `smart_trader_longs_usd` number — Sum of absolute long sizes for addresses labeled Smart HL Perps Trader.
    - `smart_trader_shorts_usd` number — Sum of absolute short sizes for addresses labeled Smart HL Perps Trader.
    - `smart_trader_total_usd` number — Total absolute position size for addresses labeled Smart HL Perps Trader.
    - `whale_longs_usd` number — Sum of absolute long sizes for addresses labeled Whale.
    - `whale_shorts_usd` number — Sum of absolute short sizes for addresses labeled Whale.
    - `whale_total_usd` number — Total absolute position size for addresses labeled Whale.
    - `public_figure_longs_usd` number — Sum of absolute long sizes for addresses labeled Public Figure.
    - `public_figure_shorts_usd` number — Sum of absolute short sizes for addresses labeled Public Figure.
    - `public_figure_total_usd` number — Total absolute position size for addresses labeled Public Figure.

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `402` — Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)