Retrieve current token balances and USD valuations for any blockchain address or entity via Nansen.
What it does
This endpoint returns current token holdings for a given wallet address or named entity (e.g., "Binance", "Vitalik Buterin") across specified blockchain networks. It is part of Nansen's Profiler suite and provides per-token balance data including token symbol, token amount, price in USD, and total value in USD. The endpoint supports over 25 chains including Ethereum, Solana, Base, Arbitrum, BNB, Polygon, Bitcoin, and more. Results can be filtered by token symbol, token address, token name, value range, and price range. Spam tokens are hidden by default. Pagination and custom sort ordering (by value_usd or token_symbol) are supported.
The endpoint accepts POST requests with a JSON body specifying either an `address` or `entity_name`, plus a required `chain` field. It costs $0.01 per call via the x402 pay-per-request 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 API returns a 402 Payment Required challenge for unauthenticated callers, confirming the endpoint is live and supports x402 payments.
This endpoint is useful for portfolio tracking, wallet profiling, due diligence on on-chain entities, and cross-chain asset distribution analysis. The response includes the address field (empty when querying by entity_name) and detailed balance records with chain, token address, symbol, name, amount, price, and USD value.
Capabilities
Use cases
- —Check current token holdings and USD values for any wallet address across 25+ chains
- —Profile a named entity (e.g., Binance, Vitalik Buterin) to see their cross-chain token distribution
- —Build portfolio dashboards that aggregate balances by chain and token
- —Perform due diligence on counterparty wallets before transactions
- —Monitor stablecoin vs non-stablecoin allocation for a specific address
Fit
Best for
- —Agents that need real-time wallet balance snapshots across multiple chains
- —Portfolio tracking tools requiring per-token USD valuations
- —On-chain research workflows profiling known entities or addresses
- —DeFi applications needing to verify user holdings before interactions
Not for
- —Historical balance tracking over time (use the historical-balances endpoint instead)
- —NFT-specific balance queries (this endpoint covers fungible tokens)
- —Real-time streaming balance updates (this is a request-response API)
Quick start
curl -X POST https://api.nansen.ai/api/v1/profiler/address/current-balance \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-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
}
},
"order_by": [
{
"field": "value_usd",
"direction": "DESC"
}
],
"pagination": {
"page": 1,
"per_page": 10
},
"hide_spam_token": true
}Response
{
"data": [
{
"chain": "ethereum",
"address": "0x28c6c06298d514db089934071355e5743bf21d60",
"price_usd": 1,
"value_usd": 5000000,
"token_name": "USD Coin",
"token_amount": 5000000,
"token_symbol": "USDC",
"token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
},
{
"chain": "ethereum",
"address": "0x28c6c06298d514db089934071355e5743bf21d60",
"price_usd": 3500,
"value_usd": 4376750,
"token_name": "Ether",
"token_amount": 1250.5,
"token_symbol": "ETH",
"token_address": "0x0000000000000000000000000000000000000000"
}
],
"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), live 402 challenge confirmed, and comprehensive endpoint documentation. Minor deduction because no actual successful response was captured in the probe (only the 402 challenge), and the crawled pages beyond the root returned no useful docs.
Warnings
- —No external documentation pages were accessible beyond the API root; all information is derived from the OpenAPI spec.
- —Example response is synthesized from the schema, not captured from a live call.
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 26+ chains including ethereum, solana, base, bitcoin, bnb, polygon, arbitrum, etc.https://api.nansen.ai
- —Accepts address or entity_name with required chain parameterhttps://api.nansen.ai
- —Returns token_address, token_symbol, token_name, token_amount, price_usd, value_usd per balance recordhttps://api.nansen.ai