Historical Token Flow Summary

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

post

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+

Authorizations

apikeystringRequired

API key for authentication

Body

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.

chainstring · enumRequired

Blockchain chain. Currently base, bnb, ethereum, solana.

Example: ethereumPossible values:

token_addressstringRequired

Token contract address

Example: 0x6982508145454ce325ddbe47a25d4ec3d2311933

apply_blacklist_filterbooleanOptional

When True, exclude blacklisted addresses from the results. Defaults to True.

Default: trueExample: true

Responses

200

Historical TGM token flow summary

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/v1beta1/tgm/historical-token-flow-summary

POST /api/v1beta1/tgm/historical-token-flow-summary HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 184

{
  "chain": "ethereum",
  "token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
  "date_range": {
    "from": "2025-06-01T00:00:00Z",
    "to": "2025-06-07T23:59:59Z"
  },
  "apply_blacklist_filter": true
}

{
  "data": [
    {
      "token_symbol": "PEPE",
      "public_figure_net_flow_usd": 1000000.5,
      "public_figure_avg_flow_usd": 50000.25,
      "public_figure_wallet_count": 10,
      "top_pnl_net_flow_usd": 2000000.75,
      "top_pnl_avg_flow_usd": 100000.5,
      "top_pnl_wallet_count": 15,
      "whale_net_flow_usd": 5000000.25,
      "whale_avg_flow_usd": 250000.75,
      "whale_wallet_count": 25,
      "exchange_net_flow_usd": 3000000.75,
      "exchange_avg_flow_usd": 150000.5,
      "exchange_wallet_count": 0,
      "smart_trader_net_flow_usd": 1500000.5,
      "smart_trader_avg_flow_usd": 75000.25,
      "smart_trader_wallet_count": 20,
      "fresh_wallets_net_flow_usd": 500000.25,
      "fresh_wallets_avg_flow_usd": 25000.75,
      "fresh_wallets_wallet_count": 0
    }
  ],
  "warnings": [
    "text"
  ]
}