Aggregated summary of recent token buyers and sellers with USD trade volumes via Nansen on-chain analytics.
What it does
This endpoint provides an aggregated summary of trade volumes in USD for addresses that bought or sold a specific token on a given chain within a time period. It is part of Nansen's Token God Mode (TGM) suite and can identify net buyers or sellers of any token across 24+ supported blockchains.
The endpoint accepts a POST request with chain, token_address, date range, and an optional buy_or_sell filter (BUY or SELL). Results include each address's bought volume, sold volume, net trade volume (in both token units and USD), and associated Nansen labels. Filters support smart money label inclusion/exclusion, address-level filtering, and numeric range filters on volumes. Pagination (up to 1000 per page) and custom sort ordering are supported. The x-payment-info on the OpenAPI spec lists a fixed price of $0.01 per call via the x402 protocol; alternatively, the credit-based cost is 10 credits (free tier) or 1 credit (pro tier).
The endpoint is live, returning HTTP 402 to unauthenticated callers as expected for an MPP/x402-gated service. Nansen's API is documented via an OpenAPI 3.1.0 spec with full request/response schemas. Rate limits are enforced per-second and per-minute, reported via response headers.
Capabilities
Use cases
- —Identify which addresses are net buyers or sellers of a token over a specific period
- —Filter token trading activity to only smart money or whale wallets
- —Rank addresses by buy or sell volume in USD for a given token
- —Monitor accumulation or distribution patterns for a token across chains
- —Feed on-chain buyer/seller data into trading bots or research dashboards
Fit
Best for
- —Crypto traders analyzing token accumulation/distribution
- —Research analysts profiling who is buying or selling a token
- —Agents that need programmatic on-chain trade summaries
- —DeFi protocols monitoring smart money activity around their token
Not for
- —Real-time sub-second trade streaming (data is aggregated, not tick-level)
- —Non-blockchain or traditional equity market analysis
- —Users needing free unlimited access (endpoint is paid per call)
Quick start
curl -X POST https://api.nansen.ai/api/v1/tgm/who-bought-sold \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{
"chain": "ethereum",
"token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
"buy_or_sell": "BUY",
"date": {"from": "2025-01-01T00:00:00Z", "to": "2025-01-07T23:59:59Z"},
"pagination": {"page": 1, "per_page": 10}
}'Example
Request
{
"date": {
"to": "2025-01-07T23:59:59Z",
"from": "2025-01-01T00:00:00Z"
},
"chain": "ethereum",
"filters": {
"trade_volume_usd": {
"min": 1000
}
},
"order_by": [
{
"field": "bought_volume_usd",
"direction": "DESC"
}
],
"pagination": {
"page": 1,
"per_page": 10
},
"buy_or_sell": "BUY",
"token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933"
}Response
{
"data": [
{
"address": "0x28c6c06298d514db089934071355e5743bf21d60",
"address_label": "Binance 14",
"sold_volume_usd": 5000,
"trade_volume_usd": 20000,
"bought_volume_usd": 25000,
"sold_token_volume": 10000000,
"token_trade_volume": 40000000,
"bought_token_volume": 50000000
}
],
"pagination": {
"page": 1,
"per_page": 10,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1.0 schema with detailed request/response models, clear pricing ($0.01/call via x402), and a live 402 challenge confirmed. Minor deduction because no standalone docs page was crawlable and response schema references ($ref) were not fully resolved in the probe.
Warnings
- —No standalone documentation page found at api.nansen.ai/docs (returns 404); rely on OpenAPI spec for schema details.
- —Exact response field names inferred from OpenAPI $ref to TGMWhoBoughtSoldResponse schema; verify against live responses.
Citations
- —Endpoint path is /api/v1/tgm/who-bought-sold (POST) with operation ID get_tgm_who_bought_sold_api_v1_tgm_who_bought_sold_posthttps://api.nansen.ai
- —Fixed price of $0.01 per call via x402 protocol; credit cost is 10 (free) / 1 (pro)https://api.nansen.ai
- —Endpoint returns 402 to unauthenticated callers, confirming it is livehttps://api.nansen.ai
- —Supports 24+ chains including ethereum, solana, base, arbitrum, etc.https://api.nansen.ai
- —Filters include smart money labels, address, volume ranges; sorting by bought_volume_usd, sold_volume_usd, etc.https://api.nansen.ai