Historical Token Who Bought/Sold

Get historical "Token God Mode" (TGM) who bought/sold (Beta)

post

Beta — subject to breaking changes.

Aggregated buy/sell volumes per trader for a specific token over a historical date range. Labels are resolved at the query end date using temporal label history tables to avoid forward-looking bias.

Key differences from /tgm/who-bought-sold:

• Accepts an explicit date_range (no rolling default)

• Labels resolved at date_to, not the current state

• Response uses gross_token_volume / gross_volume_usd (bought + sold totals) and adds is_smart_money

• min_trade_volume_usd filter is applied server-side (default 10 USD)

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

Request model for the historical who-bought-sold endpoint.

Returns aggregated buy/sell volumes per trader for a token with temporally-correct labels resolved at date_to. Uses label history tables to avoid forward-looking bias.

chainstring · enumRequired

Blockchain chain

Example: ethereumPossible values:

token_addressstringRequired

Token contract address

Example: 0x6982508145454ce325ddbe47a25d4ec3d2311933

buy_or_sellstring · enumOptional

Whether to return net buyers or net sellers

Default: BUYPossible values:

filtersany ofOptional

Optional filters applied server-side

order_byany ofOptional

Sort order. Defaults to bought_volume_usd DESC. Only the first element is used.

Responses

200

Historical TGM who-bought-sold 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

post

/api/v1beta1/tgm/historical-who-bought-sold

HTTPcURLJavaScriptPython

POST /api/v1beta1/tgm/historical-who-bought-sold HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 357

{
  "chain": "ethereum",
  "token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
  "date_range": {
    "from": "2025-06-01T00:00:00Z",
    "to": "2025-06-07T23:59:59Z"
  },
  "buy_or_sell": "BUY",
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "include_labels": [
      "Whale",
      "Smart Trader"
    ],
    "trade_volume_usd": {
      "min": 10
    }
  },
  "order_by": [
    {
      "field": "bought_volume_usd",
      "direction": "ASC"
    }
  ]
}

{
  "data": [
    {
      "address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "address_label": "Whale",
      "is_smart_money": true,
      "bought_token_volume": 1000.5,
      "sold_token_volume": 500.25,
      "gross_token_volume": 1500.75,
      "bought_volume_usd": 25000,
      "sold_volume_usd": 12500,
      "gross_volume_usd": 37500
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}