Track historical token balances over time for any blockchain address or entity via Nansen's on-chain analytics.
What it does
The Nansen Profiler Address Historical Balances endpoint returns time-series snapshots of token and native coin balances for a given wallet address or named entity across multiple blockchains. It accepts a POST request with a chain identifier, date range, and optional filters (token symbol, token address, USD value range, spam token exclusion). Results include block timestamps, token amounts, USD valuations, and token symbols at each snapshot interval.
This endpoint is part of the broader Nansen API v1 suite, which covers smart money tracking, token analytics (Token God Mode), wallet profiling, prediction markets (Polymarket), perpetual trading data (Hyperliquid), and an AI research agent. The historical balances endpoint supports 26+ chains including Ethereum, Solana, Base, Bitcoin, Arbitrum, Polygon, and others. It costs $0.01 per call via the x402 payment protocol (or 10 credits on the free tier, 1 credit on the pro tier). Pagination is supported up to 1000 records per page.
The endpoint is live and returns a 402 Payment Required challenge, confirming x402 protocol support. The full OpenAPI 3.1.0 schema is available with detailed request/response models, filter definitions, and sort field enumerations.
Capabilities
Use cases
- —Track how a wallet's token holdings changed over a specific date range
- —Analyze portfolio evolution for a named entity like 'Binance' or 'Vitalik Buterin' across chains
- —Identify when an address accumulated or distributed specific tokens
- —Build time-series charts of wallet value for compliance or research
- —Monitor cross-chain balance changes for due diligence
Fit
Best for
- —On-chain researchers tracking wallet behavior over time
- —Portfolio analytics tools needing historical balance data
- —Compliance teams auditing address activity across blockchains
- —Trading bots that need historical context on wallet positions
Not for
- —Real-time streaming balance updates (this is snapshot-based)
- —NFT-specific balance tracking (this focuses on fungible tokens)
- —Free high-volume usage without x402 payment capability
Quick start
curl -X POST https://api.nansen.ai/api/v1/profiler/address/historical-balances \
-H 'Content-Type: application/json' \
-H 'Payment-Signature: <x402_payment>' \
-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.0 schema with detailed request/response models, filter enums, and sort fields. The x402 402 challenge was captured confirming the endpoint is live. Price is clearly documented at $0.01 per call. Minor deduction because no example response was directly captured from the live endpoint and crawled docs pages returned no additional content.
Warnings
- —No external documentation pages were accessible beyond the OpenAPI spec (docs/pricing/README all returned 404-like errors)
- —Response example is inferred from the schema, not captured from a live call
Citations
- —Endpoint costs $0.01 per call via x402 protocol, or 10 credits (free) / 1 credit (pro)https://api.nansen.ai
- —Supports 26+ chains including ethereum, solana, base, bitcoin, arbitrum, polygon, etc.https://api.nansen.ai
- —Endpoint is live and returns 402 Payment Required with x402 challengehttps://api.nansen.ai
- —OpenAPI 3.1.0 schema describes ProfilerAddressHistoricalBalancesRequest and ProfilerAddressHistoricalBalancesResponse modelshttps://api.nansen.ai