Hourly token inflow/outflow snapshots by holder category (smart money, whales, exchanges, public figures) via Nansen.
What it does
The Nansen TGM Flows endpoint (`/api/v1/tgm/flows`) returns aggregated token flow data segmented by holder category over time. It provides hourly snapshots of balances, inflows, and outflows for specific holder groups: smart money, public figures, whales, top-100 holders, and exchanges. For exchange-labeled queries, the response also breaks out DEX vs CEX inflows and outflows separately. Each data point includes token price, holder count, and total value in USD.
This endpoint is part of Nansen's Token God Mode (TGM) suite, which covers over 25 chains including Ethereum, Solana, Base, Arbitrum, BNB, Polygon, and many more. The endpoint accepts POST requests with chain, token address, date range (ISO 8601), label type, pagination, optional filters (price, value, holder count, inflow/outflow counts), and custom sort order. It costs 1 credit on the Pro plan (10 on Free) per call, or $0.01 via x402 pay-per-request. Rate limits are enforced per-second and per-minute, reported in response headers.
The API returns paginated JSON with a `data` array of flow records and a `pagination` object. Authentication is via an `apiKey` header, or the endpoint can be accessed through the x402 payment protocol (HTTP 402 challenge). The full OpenAPI 3.1 schema is available from the provider, covering request/response models, filters, and sort fields.
Capabilities
Use cases
- —Track smart money accumulation or distribution of a specific token over time
- —Monitor exchange inflows/outflows (CEX vs DEX) to detect potential sell pressure or accumulation
- —Analyze whale holder balance changes and flow patterns for a token on any supported chain
- —Build dashboards showing hourly token flow snapshots segmented by holder type
- —Detect shifts in public figure or top-100 holder positions for a given token
Fit
Best for
- —Crypto traders monitoring smart money and whale activity on specific tokens
- —On-chain analysts building token flow dashboards across multiple chains
- —Quantitative researchers needing hourly holder-segmented flow data
- —DeFi protocols tracking exchange deposit/withdrawal patterns for their token
Not for
- —Real-time sub-second trading signals (data is hourly snapshots)
- —Non-blockchain or traditional finance flow analysis
- —Free-tier users needing high-volume access (10 credits per call on free plan)
Quick start
curl -X POST https://api.nansen.ai/api/v1/tgm/flows \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{
"chain": "ethereum",
"token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
"date": {"from": "2025-01-01T00:00:00Z", "to": "2025-01-07T23:59:59Z"},
"label": "smart_money",
"pagination": {"page": 1, "per_page": 10}
}'Example
Request
{
"date": {
"to": "2025-01-07T23:59:59Z",
"from": "2025-01-01T00:00:00Z"
},
"chain": "ethereum",
"label": "smart_money",
"pagination": {
"page": 1,
"per_page": 10
},
"token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933"
}Response
{
"data": [
{
"date": "2025-01-01",
"price_usd": 0.0000123,
"value_usd": 6150,
"token_amount": 500000000,
"holders_count": 42,
"total_inflows_cex": null,
"total_inflows_dex": null,
"total_outflows_cex": null,
"total_outflows_dex": null,
"total_inflows_count": 15,
"total_outflows_count": 8
}
],
"pagination": {
"page": 1,
"per_page": 10,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, filters, sort fields, and clear pricing ($0.01 via x402). The 402 MPP challenge was captured confirming the endpoint is live. Minor deduction because no actual 200 response sample was captured from the probe, and crawled docs pages returned 404s (only the root health check responded).
Warnings
- —Documentation pages at /docs, /api, /pricing all return 404; the OpenAPI spec is the primary reference.
- —Example response is inferred from the schema, not captured from a live call.
- —DEX/CEX flow breakdown fields are only populated when label=exchange; they are null for other label types.
Citations
- —The /api/v1/tgm/flows endpoint analyzes aggregated token flows by holder category over time with hourly snapshots for smart money, public figures, whales, and exchanges.https://api.nansen.ai
- —The endpoint costs 1 credit (Pro) or 10 credits (Free) per call, or $0.01 via x402 pay-per-request.https://api.nansen.ai
- —Supported label types are whale, public_figure, smart_money, top_100_holders, and exchange.https://api.nansen.ai
- —Supported chains include ethereum, solana, base, arbitrum, bnb, polygon, and 20+ others.https://api.nansen.ai