Daily historical snapshots of aggregated smart money token holdings with up to 4 years lookback
What it does
This endpoint returns historical daily snapshots of aggregated token balances held by smart traders and funds across multiple blockchains (Ethereum, Base, BNB, Monad, Solana). It provides time-series data for trend analysis, backtesting, and performance attribution of smart money behavior. Each snapshot includes token balance, USD value, 24h balance change, holder count, share of total holdings, token age, and market cap at the snapshot date.
The endpoint is part of the Nansen API v1 Smart Money suite. It accepts POST requests with a date range (YYYY-MM-DD format, max 4 years lookback), chain selection, and optional filters for smart money labels (Fund, Smart Trader, 30D/90D/180D Smart Trader), stablecoin/native token inclusion, token address/symbol, balance ranges, holder counts, market cap, and token age. Results are paginated (up to 1000 per page) and sortable by date, value, balance change, holders count, and other fields.
Pricing is $0.01 per call via the x402 protocol, or 10 credits (free tier) / 1 credit (pro tier) when using Nansen API key authentication. The endpoint returns 402 Payment Required for unauthenticated callers, which is the standard x402 payment challenge. Rate limits are enforced per-second and per-minute, reported via response headers.
Capabilities
Use cases
- —Track how smart money rotates between assets over weeks or months
- —Backtest trading strategies based on historical smart money accumulation patterns
- —Attribute portfolio performance to smart money signals over a date range
- —Analyze sector rotation trends among funds and smart traders
- —Compare smart money positioning before and after major market events
Fit
Best for
- —Quantitative researchers needing daily smart money holding snapshots for backtesting
- —Portfolio managers tracking fund and smart trader allocation trends
- —Data analysts building time-series models of smart money behavior
- —DeFi protocol teams monitoring smart money adoption of their token over time
Not for
- —Real-time trading signals (use the current holdings endpoint instead)
- —Individual wallet-level position tracking (use the Profiler endpoints)
- —Non-blockchain or traditional finance data needs
Quick start
curl -X POST https://api.nansen.ai/api/v1/smart-money/historical-holdings \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{
"date_range": {"from": "2025-01-01", "to": "2025-01-31"},
"chains": ["ethereum"],
"pagination": {"page": 1, "per_page": 10}
}'Example
Request
{
"chains": [
"ethereum"
],
"filters": {
"value_usd": {
"min": 1000
},
"include_stablecoins": false,
"include_native_tokens": false,
"include_smart_money_labels": [
"Fund",
"Smart Trader"
]
},
"order_by": [
{
"field": "value_usd",
"direction": "DESC"
}
],
"date_range": {
"to": "2025-01-31",
"from": "2025-01-01"
},
"pagination": {
"page": 1,
"per_page": 10
}
}Response
{
"data": [
{
"date": "2025-01-15",
"chain": "ethereum",
"balance": 125000.5,
"value_usd": 38750155,
"token_symbol": "AAVE",
"holders_count": 42,
"token_address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
"token_sectors": [
"DeFi Lending (Money Markets)"
],
"market_cap_usd": 4690000000,
"token_age_days": 1532,
"smart_money_labels": [
"Fund",
"Smart Trader"
],
"share_of_holdings_percent": 0.85,
"balance_24h_percent_change": 0.023
}
],
"pagination": {
"page": 1,
"per_page": 10,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, clear endpoint description with use cases, explicit pricing ($0.01 via x402), and live 402 challenge confirmed. Minor deduction because no actual response example was captured from the probe (only schema), and crawled docs pages returned 404s.
Warnings
- —Nansen docs pages (/docs, /pricing) returned 404 — documentation may have moved or be hosted elsewhere
- —Response schema references ($ref) were not fully resolved in the probe; example response is inferred from schema definitions
Citations
- —Endpoint costs $0.01 per call via x402 protocolhttps://api.nansen.ai
- —Credit cost is 10 (free tier) / 1 (pro tier) per callhttps://api.nansen.ai
- —Supports chains: ethereum, base, bnb, monad, solana for historical holdingshttps://api.nansen.ai
- —Maximum lookback is 4 years for historical holdings date rangehttps://api.nansen.ai
- —Endpoint returns daily snapshots with balance, value_usd, holders_count, market_cap_usd and other fieldshttps://api.nansen.ai