Track historical token and native coin balance changes over time for any blockchain address or entity.
What it does
This endpoint is part of the Nansen API's Profiler suite and provides historical balance snapshots for wallet addresses or named entities across multiple blockchains. It tracks token and native coin balance changes at configurable intervals, enabling analysis of holding patterns, transaction activity, and portfolio evolution.
The endpoint accepts POST requests with a JSON body specifying the address (or entity name), chain, date range, and optional filters (token symbol, token address, value in USD, spam token hiding). It supports pagination (up to 1000 records per page) and custom sort ordering by block timestamp, value in USD, or token symbol. Supported chains include Ethereum, Solana, Base, Arbitrum, Bitcoin, Polygon, BNB, and many others. The response returns timestamped balance records with token address, chain, token amount, USD value, and token symbol.
Pricing is $0.01 per call via the x402 protocol, or 10 credits (free tier) / 1 credit (pro tier) when using a Nansen API key. Rate limits are enforced per-second and per-minute, reported via response headers. The endpoint returns 402 for unauthenticated callers as part of the x402 payment challenge flow.
Capabilities
Use cases
- —Track how a wallet's token holdings changed over a specific date range
- —Analyze portfolio evolution for a named entity like 'Vitalik Buterin' across chains
- —Identify when an address accumulated or distributed a specific token
- —Monitor balance changes for compliance or due diligence investigations
- —Build time-series charts of wallet portfolio value in USD
Fit
Best for
- —Blockchain analysts tracking wallet holding patterns over time
- —Portfolio tracking tools needing historical balance data across chains
- —Investigators performing on-chain due diligence on specific addresses
- —Trading bots that need historical context on wallet behavior
- —Research teams studying token accumulation and distribution patterns
Not for
- —Real-time streaming balance updates (this is snapshot-based)
- —Non-blockchain financial data or traditional bank account balances
- —Free unlimited usage without API key or x402 payment
Quick start
curl -X POST https://api.nansen.ai/api/v1/profiler/address/historical-balances \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{
"address": "0x28c6c06298d514db089934071355e5743bf21d60",
"chain": "ethereum",
"date": {"from": "2025-05-01T00:00:00Z", "to": "2025-05-03T23:59:59Z"},
"pagination": {"page": 1, "per_page": 10}
}'Example
Request
{
"date": {
"to": "2025-05-03T23:59:59Z",
"from": "2025-05-01T00:00:00Z"
},
"chain": "ethereum",
"address": "0x28c6c06298d514db089934071355e5743bf21d60",
"filters": {
"value_usd": {
"min": 10
},
"token_symbol": "USDC",
"hide_spam_tokens": true
},
"pagination": {
"page": 1,
"per_page": 10
}
}Response
{
"data": [
{
"chain": "ethereum",
"value_usd": 5000000,
"token_amount": 5000000,
"token_symbol": "USDC",
"token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"block_timestamp": "2025-05-01"
},
{
"chain": "ethereum",
"value_usd": 4800000,
"token_amount": 4800000,
"token_symbol": "USDC",
"token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"block_timestamp": "2025-05-02"
}
],
"pagination": {
"page": 1,
"per_page": 10,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, clear pricing ($0.01 via x402), and a live 402 challenge captured. Docs pages returned 404 but the OpenAPI spec itself is comprehensive. Minor deduction for no crawlable human-readable documentation beyond the spec.
Warnings
- —No human-readable documentation pages were accessible (docs, pricing pages returned 404)
- —Response schema fields are inferred from the OpenAPI component ProfilerHistoricalBalance; no live 200 response was captured
Citations
- —Endpoint is POST /api/v1/profiler/address/historical-balances with x-credit-cost free:10, pro:1 and x402 price $0.01https://api.nansen.ai
- —Supports chains including ethereum, solana, base, arbitrum, bitcoin, bnb, polygon, and 20+ others via ProfilerChain enumhttps://api.nansen.ai
- —Request accepts address or entity_name, chain (required), date range (required), filters for token_symbol, token_address, value_usd, hide_spam_tokenshttps://api.nansen.ai
- —Response returns ProfilerHistoricalBalance records with block_timestamp, token_address, chain, token_amount, value_usd, token_symbolhttps://api.nansen.ai
- —Endpoint returned HTTP 402 on HEAD probe confirming live MPP/x402 payment challengehttps://api.nansen.ai/api/v1/profiler/address/historical-balances