Perp Trades

Data Freshness & Historical Coverage

For data freshness and historical coverage, see Data Coverage by Chain; this endpoint follows it except where noted below.

• Covers the Hyperliquid perpetuals dataset (reliable from May 2025), not per-chain history — see the Hyperliquid note on the coverage page.

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

post

Retrieve perpetual trade data for a specific token on Hyperliquid. Shows individual trades with detailed information including trader address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and trade metrics.

Key Features:

• Hyperliquid perpetual contracts only

• Smart money filtering capabilities

• Detailed trade breakdown with parsed action fields

• Support for both Long and Short position trading

• Market and Limit order types

Request Parameters:

• token_symbol: Token symbol to fetch trades for (e.g., "BTC", "ETH")

• date: Date range for the trades

• filters: Additional filters for side, action, order_type, etc.

• pagination: Page and per_page parameters

Authorizations

ApiKeyAuth

apikeystringRequired

API key for authentication

Body

application/json

Request model for TGM perp trades endpoint.

This endpoint provides perp trades data for a specific token.

token_symbolstringRequired

Token symbol

Example: BTC

filtersany ofOptional

Additional filters to apply to the query.

Example: {"order_type":["MARKET"],"side":["Long"]}

order_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

• [{"field": "block_timestamp", "direction": "DESC"}] - Sort by timestamp descending
• [{"field": "value_usd", "direction": "DESC"}] - Sort by trade value descending

Default: block_timestamp DESC, transaction_hash ASC, trader_address ASC (ensures stable pagination and prevents duplicate rows)

Responses

200

TGM perp trades data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

402

Payment Required

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

502

Bad Gateway

application/json

503

Service Unavailable

application/json

504

Gateway Timeout

application/json

post/api/v1/tgm/perp-trades

HTTPcURLJavaScriptPython

POST /api/v1/tgm/perp-trades HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 238

{
  "token_symbol": "BTC",
  "date": {
    "from": "2025-07-07T00:00:00Z",
    "to": "2025-07-14T23:59:59Z"
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "order_type": [
      "MARKET"
    ],
    "side": [
      "Long"
    ]
  },
  "order_by": [
    {
      "field": "block_timestamp",
      "direction": "ASC"
    }
  ]
}

{
  "data": [
    {
      "trader_address_label": "Smart Money",
      "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "token_symbol": "BTC",
      "side": "Long",
      "action": "Add",
      "token_amount": 1.5,
      "price_usd": 60000,
      "value_usd": 90000,
      "type": "MARKET",
      "block_timestamp": "2025-10-01T12:40:00Z",
      "transaction_hash": "0x61adb6da30853c5988f0204dd9f6e4abbc878e02c34030a4f707cf4ec3124bcb"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}