{"uid":"cap_kqqvqnMTY7ROVu4xLkAKb","slug":"nansen-current-balance-54366e1a","name":"Nansen Current Balance","description":"Retrieve current token holdings for addresses or entities. Returns detailed balance information across specified chains.\n\nWhat it helps to answer:\n\n- Current token holdings with quantities and USD valuations\n- Asset distribution across different blockchain networks\n- Native token versus token balances\n- Stablecoin holdings and percentages\n- Cross-chain portfolio composition\n\nNote: The address field in the response will be empty if entity_name is provided.","url":"https://api.nansen.ai/api/v1/profiler/address/current-balance?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"ProfilerAddressBalancesRequest","examples":[{"chain":"ethereum","address":"0x28c6c06298d514db089934071355e5743bf21d60","pagination":{"page":1,"per_page":10},"hide_spam_token":true},{"chain":"ethereum","pagination":{"page":1,"per_page":10},"entity_name":"Vitalik Buterin","hide_spam_token":true}],"required":["chain"],"properties":{"chain":{"enum":["all","arbitrum","arc","avalanche","base","bitcoin","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"type":"string","title":"ProfilerChain","description":"Chains supported in profiler analysis."},"address":{"anyOf":[{"type":"string"}],"title":"Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60","8zFZHuSRuDpuAR7J6FzwyF3vKNx4CVW3DFHJerQhc7Zd"],"description":"Address to get balances for"},"filters":{"anyOf":[{"type":"object","title":"ProfilerAddressBalancesFilters","properties":{"price_usd":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":1000,"min":0.01}],"description":"Token price range filter in USD"},"value_usd":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":100000,"min":10}],"description":"Balance range filter in USD"},"token_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Token Name","examples":["USD Coin","%Ethereum%"],"description":"Token name filter"},"token_amount":{"anyOf":[{"type":"object","title":"IntegerRangeFilter","properties":{"max":{"anyOf":[{"type":"integer"}],"title":"Max","examples":[100,1000,10000],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"integer"}],"title":"Min","examples":[10,100,1000],"description":"Minimum value (inclusive)"}},"description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"}],"examples":[{"max":1000000,"min":1}],"description":"Token amount range filter"},"token_symbol":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Token Symbol","examples":["USDC","%ETH%"],"description":"Token symbol filter"},"token_address":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Token Address","examples":["0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"],"description":"Token address filter"}},"description":"Filters for profiler address current balance endpoint.\n\nThese filters control which token balances are included.","additionalProperties":false}],"examples":[{"value_usd":{"min":10},"token_symbol":"USDC"}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"ProfilerAddressBalancesSortOrder","required":["field","direction"],"properties":{"field":{"enum":["value_usd","token_symbol"],"type":"string","title":"ProfilerAddressBalancesSortField","description":"Enum for sortable fields in profiler address balances."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}}}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering"},"pagination":{"type":"object","title":"PaginationRequest","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Page number (1-based)"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page (max 1000)"}},"description":"Pagination parameters for API requests."},"entity_name":{"anyOf":[{"type":"string"}],"title":"Entity Name","examples":["Vitalik Buterin","Binance"],"description":"Entity name to get balances for"},"hide_spam_token":{"type":"boolean","title":"Hide Spam Token","default":true,"examples":[true],"description":"Removes suspicious tokens from the balance list"}},"description":"","additionalProperties":false},"responseSchema":{"type":"object","title":"ProfilerAddressBalancesResponse","required":["pagination","data"],"properties":{"data":{"type":"array","items":{"type":"object","title":"ProfilerBalance","required":["chain","address","token_address","token_symbol"],"properties":{"chain":{"type":"string","title":"Chain","description":"Chain"},"address":{"type":"string","title":"Address","description":"Address of the wallet. Empty if entity_name is provided. EVM addresses are returned in lowercase."},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Price of the token"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Token balance value in USD"},"token_name":{"anyOf":[{"type":"string"}],"title":"Token Name","description":"Token name"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Token balance"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"token_address":{"type":"string","title":"Token Address","description":"Address of token"}},"description":"Individual profiler balance record.\n\nRepresents a single token balance from the wallet profiler."},"title":"Data","description":"List of balance records"},"pagination":{"type":"object","title":"PaginationInfo","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Current page number"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page"},"is_last_page":{"type":"boolean","title":"Is Last Page","default":true,"description":"Whether this is the last page"}},"description":"Pagination information for API responses."}},"description":"Response model for profiler address current-balance endpoint.\n\nContains the filtered balance data with metadata."},"example":null,"exampleRequest":null,"tags":["blockchain","smart-money","wallet","tokens","defi","analytics","profiler","dex","pnl","onchain","prediction-market","data"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_AhMLbRAaq_njnyh1Z4hdP","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":"Nansen","brandSlug":"nansen","brandBaseUrl":"https://nansen.ai","brandDocsUrl":"https://docs.nansen.ai","whatItDoes":"Retrieve current token holdings and USD valuations for a blockchain address or named entity across one or more chains.","exampleAgentPrompt":"Using Nansen, pull the current token balances for Ethereum address 0x28c6c06298d514db089934071355e5743bf21d60 — show me all holdings worth more than $100, hide spam tokens, and give me the first page of 10 results.","exampleUseCases":null,"resultDescription":"A paginated list of token balance records, each containing the chain, wallet address, token symbol, token name, token contract address, raw token amount, current USD price per token, and total USD value held. Also includes pagination metadata (current page, per_page, is_last_page). If queried by entity name, the address field in each record will be empty.","failureModes":["Missing required 'chain' field returns 422 validation error","Invalid chain enum value returns validation error","Address not found on specified chain returns empty data array","Both address and entity_name omitted may return empty or error response","Pagination page beyond last page returns empty data with is_last_page=true","Rate limit or payment failure returns 402 or 429 error","Invalid address format may return empty results or validation error"],"whenToPreferThis":"Use this endpoint when you need a real-time snapshot of what tokens a specific wallet address or named entity (e.g. a known fund or public figure) currently holds, including USD valuations. Prefer this over historical or trade-based endpoints when the question is about present holdings rather than past activity. Ideal for portfolio composition analysis, smart money monitoring, and cross-chain asset distribution queries.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-09T18:34:44.514Z","isFirstParty":false,"canonicalSlug":"nansen-current-balance-54366e1a"}