{"uid":"cap_JwCD13nzVPkVpyaDhHSm5","slug":"nansen-historical-balances-1d080ac4","name":"Nansen Historical Balances","description":"Track token and native coin balance changes over time for addresses or entities. Provides snapshots at configurable intervals to analyze holding patterns, transaction activity, and portfolio evolution across multiple blockchains.\n\nWhat it helps to answer:\n\n- Portfolio value changes across different time periods\n- Token accumulation and distribution patterns over selected timeframes\n- New positions entered and exited during specific periods","url":"https://api.nansen.ai/api/v1/profiler/address/historical-balances?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"ProfilerAddressHistoricalBalancesRequest","examples":[{"date":{"to":"2025-05-03T23:59:59Z","from":"2025-05-01T00:00:00Z"},"chain":"ethereum","address":"0x28c6c06298d514db089934071355e5743bf21d60","pagination":{"page":1,"per_page":10}},{"date":{"to":"2025-05-03T23:59:59Z","from":"2025-05-01T00:00:00Z"},"chain":"ethereum","pagination":{"page":1,"per_page":10},"entity_name":"Vitalik Buterin"}],"required":["chain","date"],"properties":{"date":{"type":"object","title":"DateRange","properties":{"to":{"anyOf":[{"type":"string"}],"title":"To","examples":["2025-01-31T23:59:59Z"],"description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"},"from":{"anyOf":[{"type":"string"}],"title":"From","examples":["2025-01-01T00:00:00Z"],"description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"}},"description":"Date range model matching the API schema."},"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 historical balances for"},"filters":{"anyOf":[{"type":"object","title":"ProfilerAddressHistoricalBalancesFilters","properties":{"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_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 balance count 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"},"hide_spam_tokens":{"anyOf":[{"type":"boolean"}],"title":"Hide Spam Tokens","default":true,"description":"Whether to hide spam tokens from results"}},"description":"Filters for profiler address historical balances endpoint.\n\nThese filters control which historical balance data is included.","additionalProperties":false}],"examples":[{"value_usd":{"min":10},"token_symbol":"USDC","hide_spam_tokens":true}],"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":"ProfilerAddressHistoricalBalancesSortOrder","required":["field","direction"],"properties":{"field":{"enum":["block_timestamp","value_usd","token_symbol"],"type":"string","title":"ProfilerAddressHistoricalBalancesSortField","description":"Enum for sortable fields in profiler address historical 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 historical balances for"}},"description":"","additionalProperties":false},"responseSchema":{"type":"object","title":"ProfilerAddressHistoricalBalancesResponse","required":["pagination","data"],"properties":{"data":{"type":"array","items":{"type":"object","title":"ProfilerHistoricalBalance","required":["block_timestamp","token_address","chain","token_symbol"],"properties":{"chain":{"type":"string","title":"Chain","description":"Chain"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Usd balance of the holdings"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Token amount"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Symbol of the token"},"token_address":{"type":"string","title":"Token Address","description":"Token Address"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"The block timestamp as date"}},"description":"Individual profiler historical balance record.\n\nRepresents a single historical token balance from the wallet profiler."},"title":"Data","description":"List of historical 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 historical-balances endpoint.\n\nContains the filtered historical 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_RQr5ICKgscS-OZuEG27Md","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":"Retrieves time-series snapshots of token and native coin balances for a blockchain address or named entity across configurable date ranges and multiple chains.","exampleAgentPrompt":"Show me the historical token balances for Ethereum address 0x28c6c06298d514db089934071355e5743bf21d60 on Ethereum from May 1 to May 3, 2025 — I want to see what tokens they held and their USD values, page 1 with 10 results.","exampleUseCases":null,"resultDescription":"A paginated list of historical balance records, each containing the block timestamp, token symbol, token address, chain, token amount held, and USD value at that point in time, along with pagination metadata indicating current page and whether more pages exist.","failureModes":["Missing required fields (chain or date range) returns a 422 validation error","Invalid chain enum value returns a validation error","Address format mismatch for the specified chain (e.g. EVM address on Solana) may return empty results or an error","Date range with no on-chain activity returns an empty data array","Payment not attached or insufficient balance returns a 402 Payment Required","Pagination page beyond available data returns empty data array with is_last_page=true"],"whenToPreferThis":"Use this endpoint when you need time-series balance history for a specific wallet or named entity — particularly when analyzing how holdings evolved over a defined date window, detecting accumulation or distribution patterns, or auditing portfolio changes. Prefer this over current-balance or trade endpoints when the temporal dimension matters and you need snapshots rather than live state or individual trade events.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-09T18:54:53.391Z","isFirstParty":false,"canonicalSlug":"nansen-historical-balances-1d080ac4"}