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

# Get historical "Token God Mode" (TGM) token flow summary (Beta)

`POST /api/v1beta1/tgm/historical-token-flow-summary`

**Beta — subject to breaking changes.**

Aggregated token flow intelligence with temporally-correct segment labels.
Same response shape as `/tgm/flow-intelligence` plus a `token_symbol` column.

**Key differences from `/tgm/flow-intelligence`:**
- Accepts an explicit `date_range` (no rolling timeframe default)
- Segment labels (Whale, Public Figure, Top PnL, Smart Trader) are resolved
  at `date_to` from history tables to avoid forward-looking bias
- Segment columns are NULL when temporal label coverage does not yet include
  `date_to` (whale/public_figure/top_pnl/exchange coverage starts 2025-03-11;
  smart_trader is available from 2020+

## Request body

- TGMHistoricalTokenFlowSummaryRequest — Request model for the historical token flow summary endpoint. Returns the same per-segment flow intelligence shape as `/tgm/flow-intelligence` but resolved against temporal label history so segment classification reflects who held a label _at_ `date_to` rather than today. Use this for backtests and as-of-date analysis.
  - `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)
  - `apply_blacklist_filter` boolean — When True, exclude blacklisted addresses from the results. Defaults to True.

## Response `200`

Historical TGM token flow summary

- TGMHistoricalTokenFlowSummaryResponse — Response for the historical token flow summary endpoint.
  - `data` TGMHistoricalTokenFlowSummary[], required — List of historical token flow summary records. The endpoint returns a single aggregated row per (token_address, date_to).
    - `token_symbol` string — Symbol of the queried token, resolved from on-chain metadata.
    - `public_figure_net_flow_usd` number — Net flow (USD) for addresses labeled as Public Figure at date_to.
    - `public_figure_avg_flow_usd` number — Geometric mean of absolute flow for Public Figure addresses.
    - `public_figure_wallet_count` integer — Unique wallet count for Public Figure addresses in the period.
    - `top_pnl_net_flow_usd` number — Net flow (USD) for addresses labeled as Top PnL at date_to.
    - `top_pnl_avg_flow_usd` number — Geometric mean of absolute flow for Top PnL addresses.
    - `top_pnl_wallet_count` integer — Unique wallet count for Top PnL addresses in the period.
    - `whale_net_flow_usd` number — Net flow (USD) for addresses labeled as Whale at date_to.
    - `whale_avg_flow_usd` number — Geometric mean of absolute flow for Whale addresses.
    - `whale_wallet_count` integer — Unique wallet count for Whale addresses in the period.
    - `exchange_net_flow_usd` number — Net exchange flow in USD (direction inverted: deposit-to-exchange is positive). Combines CEX transfers and DEX trades.
    - `exchange_avg_flow_usd` number — Geometric mean of absolute exchange flow sizes.
    - `exchange_wallet_count` integer — Always 0 (matching production flow-intelligence — exchange wallet count is not tracked).
    - `smart_trader_net_flow_usd` number — Net flow (USD) for addresses labeled as Smart Trader at date_to. Available from 2020+; before 2025-03-11 covers DEX trades only.
    - `smart_trader_avg_flow_usd` number — Geometric mean of absolute flow for Smart Trader addresses.
    - `smart_trader_wallet_count` integer — Unique wallet count for Smart Trader addresses in the period.
    - `fresh_wallets_net_flow_usd` number — 24h fresh-wallet inflow (USD) from the most recent snapshot taken on or before date_to.
    - `fresh_wallets_avg_flow_usd` number — 7-day daily-average fresh-wallet inflow (USD) from the snapshot.
    - `fresh_wallets_wallet_count` integer — Always 0 (matching production — fresh wallet count is not tracked separately).
  - `warnings` string[] — Optional warnings about the query results, e.g. when segment fields are NULL because temporal label data does not yet cover the requested date_to.

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