Retrieve current token balances and USD valuations for any blockchain address or entity via Nansen's profiler API.
What it does
The Nansen Profiler Address Current Balance endpoint returns detailed token holdings for a given wallet address or named entity across specified blockchains. It reports token symbols, amounts, USD prices, and total values, supporting multi-chain queries (Ethereum, Solana, Base, BNB, Arbitrum, and 20+ others). You can filter by token symbol, address, name, price, or value, and sort results by USD value or symbol. Spam token filtering is enabled by default.
This endpoint is part of the broader Nansen API v1, which provides on-chain analytics including smart money tracking, token flows, PnL analysis, prediction market data, and an AI research agent. The current-balance endpoint accepts POST requests with a JSON body specifying either an `address` or `entity_name`, a required `chain` field, and optional filters and pagination. It costs $0.01 per call via the x402 payment protocol (or 10 free-tier / 1 pro-tier Nansen credits). Rate limits are exposed via response headers. The endpoint returned a valid 402 x402 challenge during probing, confirming it is live and accepting payments.
Capabilities
Use cases
- —Check current token holdings and USD values for any EVM or Solana wallet address
- —Look up portfolio composition for a named entity like 'Binance' or 'Vitalik Buterin'
- —Monitor cross-chain asset distribution for compliance or research
- —Feed wallet balance data into trading bots or portfolio dashboards
- —Filter holdings by token symbol or minimum USD value for reporting
Fit
Best for
- —On-chain researchers needing per-address token breakdowns with USD pricing
- —Trading agents that need real-time wallet balance snapshots across 25+ chains
- —Portfolio trackers integrating Nansen's labeled entity data
Not for
- —Historical balance time-series (use the historical-balances endpoint instead)
- —DeFi protocol position breakdowns (use the portfolio/defi-holdings endpoint instead)
- —Free high-volume usage without payment (each call costs $0.01 via x402)
Quick start
curl -X POST https://api.nansen.ai/api/v1/profiler/address/current-balance \
-H 'Content-Type: application/json' \
-d '{
"address": "0x28c6c06298d514db089934071355e5743bf21d60",
"chain": "ethereum",
"hide_spam_token": true,
"pagination": {"page": 1, "per_page": 10}
}'Example
Request
{
"chain": "ethereum",
"address": "0x28c6c06298d514db089934071355e5743bf21d60",
"filters": {
"value_usd": {
"min": 10
}
},
"pagination": {
"page": 1,
"per_page": 10
},
"hide_spam_token": true
}Response
{
"data": [
{
"chain": "ethereum",
"address": "0x28c6c06298d514db089934071355e5743bf21d60",
"price_usd": 1,
"value_usd": 500000000,
"token_name": "USD Coin",
"token_amount": 500000000,
"token_symbol": "USDC",
"token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}
],
"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/call via x402), live 402 challenge confirmed, and comprehensive documentation in the spec. Minor deduction because no standalone docs page was crawlable and example response is inferred from schema rather than captured.
Warnings
- —No dedicated documentation site was reachable (docs, pricing, README all returned 404-like errors)
- —Example response is constructed from the OpenAPI schema, not from an actual API response
Citations
- —Endpoint costs $0.01 per call via x402 protocolhttps://api.nansen.ai
- —Endpoint accepts POST with ProfilerAddressBalancesRequest schema including address, entity_name, chain, filters, paginationhttps://api.nansen.ai
- —Supports 25+ chains including ethereum, solana, base, bnb, arbitrum, etc.https://api.nansen.ai
- —402 x402 challenge was returned confirming the endpoint is livehttps://api.nansen.ai