# Nansen Historical Who Bought Sold

> Nansen Historical Who Bought Sold is a paid API for AI agents from api.nansen.ai, paid per call via x402, $0.05/call, status unknown (last checked 2026-10-13).

Returns aggregated buy/sell volumes per trader for a specific token over a historical date range, with smart money labels resolved at the query end date to avoid forward-looking bias.

## Facts

- Endpoint: GET https://api.nansen.ai/api/v1beta1/tgm/historical-who-bought-sold?utm_source=zero.xyz
- Price: $0.05/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/nansen-historical-who-bought-sold-aaee3d17
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_VukhacmsvyFvARpnhl7Sm

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-historical-who-bought-sold-aaee3d17
```

Example prompt: Show me all smart money traders who bought or sold the Ethereum token at 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on Ethereum between January 1 and March 31 2024, filtering to only include Whale and Smart Trader labels.

## When to prefer this

Use this endpoint when you need historical (not current) buy/sell breakdowns per trader for a specific token, especially when temporal accuracy of labels matters — i.e., you want smart money classification as it existed at the end date, not today's labels. Prefer over /tgm/who-bought-sold when you need an explicit date range rather than a rolling window, or when gross volume metrics are needed alongside directional volumes.

## Known failure modes

- Missing required fields (chain, token_address, date_range) returns 422 validation error
- Unsupported chain value returns enum validation error
- Invalid token address format returns error
- Date range with date_from after date_to returns error
- Token with no trading activity in the date range returns empty data array
- Rate limiting or authentication failure returns 401/429
- Pagination cursor out of bounds returns empty results

## How this service works

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

## Output

A paginated list of trader addresses with their aggregated buy volumes, sell volumes, and gross trading volumes (in both USD and token units) over the specified date range, each tagged with a temporally-correct smart money label and an is_smart_money boolean resolved at the query end date.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMHistoricalWhoBoughtSoldRequest",
 "required": [
  "chain",
  "token_address",
  "date_range"
 ],
 "properties": {
  "chain": {
   "enum": [
    "arbitrum",
    "avalanche",
    "base",
    "bnb",
    "ethereum",
    "hyperevm",
    "injective",
    "iotaevm",
    "linea",
    "mantle",
    "mantra",
    "monad",
    "near",
    "optimism",
    "plasma",
    "polygon",
    "ronin",
    "scroll",
    "sei",
    "solana",
    "sonic",
    "starknet",
    "sui",
    "ton",
    "tron"
   ],
   "type": "string",
   "title": "TGMChain",
   "description": "Chains supported in TGM (Token God Mode) endpoints."
  },
  "filters": {
   "anyOf": [
    {
     "type": "object",
     "title": "TGMHistoricalWhoBoughtSoldFilters",
     "properties": {
      "include_labels": {
       "anyOf": [
        {
         "type": "array",
         "items": {
          "enum": [
           "30D Smart Trader",
           "90D Smart Trader",
           "180D Smart Trader",
           "Fund",
           "Smart Trader",
           "Smart Dex Trader",
           "30D Smart Dex Trader",
           "90D Smart Dex Trader",
           "180D Smart Dex Trader",
           "Public Figure",
           "Exchange",
           "Whale",
           "BananaGun Bot User",
           "Top Maestro Bot User",
           "Top BananaGun Bot User",
           "Maestro Bot User",
           "Early MAGIC Miner",
           "First Mover LP",
           "First Mover Staking",
           "Profitable LP",
           "Smart HL Perps Trader"
          ],
          "type": "string",
          "title": "HistoricalLabelType",
          "description": "Filter by entity label type. Includes legacy label classes (e.g. Smart Dex Trader) that appear in historical data."
         }
        }
       ],
       "title": "Include Labels",
       "examples": [
        [
         "Whale",
         "Smart Trader"
        ]
       ],
       "description": "Include only traders with these temporal smart money labels"
      },
      "trade_volume_usd": {
       "anyOf": [
        {
         "type": "object",
         "title": "NumericRangeFilter",
         "properties": {
          "max": {
           "anyOf": [
            {
             "type": "number"
            }
           ],
           "title": "Max",
           "examples": [
            50000,
            10000000,
            100
           ],
           "description": "Maximum value (inclusive)"
          },
          "min": {
           "an
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMHistoricalWhoBoughtSoldResponse",
 "required": [
  "data",
  "pagination"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "TGMHistoricalWhoBoughtSold",
    "required": [
     "address",
     "is_smart_money"
    ],
    "properties": {
     "address": {
      "type": "string",
      "title": "Address",
      "examples": [
       "0x28c6c06298d514db089934071355e5743bf21d60"
      ],
      "description": "Trader address"
     },
     "address_label": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Address Label",
      "examples": [
       "Whale"
      ],
      "description": "Temporally-correct label resolved at date_to"
     },
     "is_smart_money": {
      "type": "boolean",
      "title": "Is Smart Money",
      "examples": [
       true
      ],
      "description": "Whether the address had a smart money label at date_to"
     },
     "sold_volume_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Sold Volume Usd",
      "examples": [
       12500
      ],
      "description": "Aggregate sold volume in USD"
     },
     "gross_volume_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Gross Volume Usd",
      "examples": [
       37500
      ],
      "description": "Gross trade volume in USD (bought + sold)"
     },
     "bought_volume_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Bought Volume Usd",
      "examples": [
       25000
      ],
      "description": "Aggregate bought volume in USD"
     },
     "sold_token_volume": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Sold Token Volume",
      "examples": [
       500.25
      ],
      "description": "Aggregate sold token volume"
     },
     "gross_token_volume": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Gross Token Volume",
      "examples": [
       1500.75
      ],
      "description": "Gross token trade volume (bought + sold)"
     },
     "bought_token_volume": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Bought Token Volume",
      "examples": [
       1000.5
      ],
      "description": "Aggregate bought token volume"
     }
    },
    "description": "Single historical who-bought-sold record.\n\nAggregated buy
… (truncated)
```

## More

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