---
title: "Get historical \"Token God Mode\" (TGM) who bought/sold (Beta)"
method: POST
path: "/api/v1beta1/tgm/historical-who-bought-sold"
tags: ["Token God Mode"]
---

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

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

## Request

- Base URL: `https://api.nansen.ai`
- URL: `https://api.nansen.ai/api/v1beta1/tgm/historical-who-bought-sold`
- Auth: API key in header `apiKey`
- TypeScript: <https://skmtc.dev/nansen/apis/nansen-api/docs/api/v1beta1/tgm/historical-who-bought-sold/post.ts> (a function with typed inputs; its response is checked against the schema)

**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)

## Request body

- TGMHistoricalWhoBoughtSoldRequest: 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.
  - `chain` 'base' | 'bnb' | 'ethereum' | 'solana', required: Chains supported for the TGM historical endpoints (pnl-leaderboard, who-bought-sold, top-holders, token-flow-summary).
  - `token_address` string, required: Token contract address
  - `date_range` DateRange, required: Date range model matching the API schema.
    - `from` string: Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)
    - `to` string: End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)
  - `buy_or_sell` 'BUY' | 'SELL': TGM who bought/sold type.
  - `pagination` PaginationRequest: Pagination parameters for API requests.
    - `page` integer: Page number (1-based)
    - `per_page` integer: Number of records per page (max 1000)
  - `filters` TGMHistoricalWhoBoughtSoldFilters: Filters for the historical who-bought-sold endpoint.
    - `include_labels` HistoricalLabelType[]: Include only traders with these temporal smart money labels
    - `trade_volume_usd` NumericRangeFilter: Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number: Minimum value (inclusive)
      - `max` number: Maximum value (inclusive)
  - `order_by` SortOrderTGMHistoricalWhoBoughtSoldSortField[]: Sort order. Defaults to bought_volume_usd DESC. Only the first element is used.
    - `field` 'bought_volume_usd' | 'sold_volume_usd' | 'gross_volume_usd', required: Sortable fields for the historical who-bought-sold endpoint.
    - `direction` 'ASC' | 'DESC', required: Enum for sort directions.

## Response `200`

Historical TGM who-bought-sold data

- TGMHistoricalWhoBoughtSoldResponse: Response model for the historical who-bought-sold endpoint.
  - `data` TGMHistoricalWhoBoughtSold[], required: List of historical who-bought-sold records
    - `address` string, required: Trader address
    - `address_label` string: Temporally-correct label resolved at date_to
    - `is_smart_money` boolean, required: Whether the address had a smart money label at date_to
    - `bought_token_volume` number: Aggregate bought token volume
    - `sold_token_volume` number: Aggregate sold token volume
    - `gross_token_volume` number: Gross token trade volume (bought + sold)
    - `bought_volume_usd` number: Aggregate bought volume in USD
    - `sold_volume_usd` number: Aggregate sold volume in USD
    - `gross_volume_usd` number: Gross trade volume in USD (bought + sold)
  - `pagination` PaginationInfo, required: Pagination information for API responses.
    - `page` integer: Current page number
    - `per_page` integer: Number of records per page
    - `is_last_page` boolean: Whether this is the last page

## 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.dev/nansen/apis/nansen-api.md) - [All operations](https://skmtc.dev/nansen/apis/nansen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nansen/apis/nansen-api/revisions/02a4d2e7d827?raw)