{"uid":"cap_hjABnT3sHHIrsPm5PSER4","slug":"nansen-ai-profiler-historical-token-balances-05c9f11d","name":"Nansen AI - Profiler Historical Token Balances","description":"**Beta — subject to breaking changes.**\n\nToken balances for a wallet address as of a historical snapshot date.\n\nSupports EVM chains (ethereum, base, bnb) and solana. Balances are computed from on-chain transfer history\nup to `as_of_date`. Results are ordered by USD value descending.","url":"https://api.nansen.ai/api/v1beta1/profiler/address/historical-token-balances","method":"GET","headers":{},"bodySchema":{"type":"object","title":"ProfilerHistoricalTokenBalancesRequest","required":["address","as_of_date","chain"],"properties":{"chain":{"enum":["all","base","bnb","ethereum","mantra","solana"],"type":"string","title":"ProfilerHistoricalTokenBalancesChain","description":"Chains supported for Profiler Historical Token Balances endpoint."},"address":{"type":"string","title":"Address","examples":["0xd8da6bf26964af9d7eed9e03e53415d37aa96045"],"description":"Wallet address (EVM hex or Solana base58)"},"as_of_date":{"type":"string","title":"As Of Date","format":"date","examples":["2025-06-15"],"description":"Historical snapshot date — balances are computed up to this date"},"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."},"apply_blacklist_filter":{"type":"boolean","title":"Apply Blacklist Filter","default":true,"examples":[true],"description":"When True, exclude blacklisted addresses from the results. Defaults to True."}},"description":"Request model for the profiler historical token balances endpoint.\n\nReturns token balances for an address as of a historical snapshot date.\nSupports EVM chains (ethereum, base, bnb) and solana.","additionalProperties":false},"responseSchema":{"type":"object","title":"ProfilerHistoricalTokenBalancesResponse","required":["pagination","data"],"properties":{"data":{"type":"array","items":{"type":"object","title":"ProfilerHistoricalTokenBalancesItem","required":["chain","token_address"],"properties":{"name":{"anyOf":[{"type":"string"}],"title":"Name","examples":["Aave"],"description":"Token name"},"chain":{"type":"string","title":"Chain","examples":["ethereum"],"description":"Blockchain chain"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","examples":[85.5],"description":"Token price in USD at as_of_date"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","examples":[8592.75],"description":"Token balance value in USD (token_amount * price_usd)"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","examples":[100.5],"description":"Token balance (adjusted for decimals)"},"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","examples":["AAVE"],"description":"Token symbol"},"token_address":{"type":"string","title":"Token Address","examples":["0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9"],"description":"Token contract address"}},"description":"Single token balance record for an address at a historical date."},"title":"Data","description":"List of token balance records, ordered by value_usd DESC"},"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 the profiler historical token balances endpoint."},"example":null,"exampleRequest":null,"tags":["x402","finance"],"displayCostAmount":"0.05","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.05/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_YqEp9PTrydrOaSfiINOGG","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns historical token balance snapshots for a given wallet address on a specified blockchain as of a particular date.","exampleAgentPrompt":"Can you pull up the historical token balances for Ethereum wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 as of January 1st, 2024, using Nansen's profiler data?","exampleUseCases":null,"resultDescription":"A paginated snapshot of all token balances held by the specified wallet address on the given chain as of the requested date, powered by Nansen's 500M+ labeled address dataset. Excludes blacklisted addresses by default.","failureModes":["Invalid wallet address format returns error (must be EVM hex or Solana base58)","Unsupported chain identifier returns error","Future date or malformed date string for as_of_date returns error","Pagination parameters out of range return error","Payment not received or insufficient USDC balance returns 402","Rate limiting may occur with excessive requests"],"whenToPreferThis":"Use this endpoint when you need a point-in-time snapshot of a wallet's token holdings on a specific historical date, rather than current balances. Ideal for auditing smart money wallets, reconstructing portfolio states at specific dates, or analyzing how whale holdings evolved. Nansen's 500M+ labeled address dataset adds context that generic RPC node queries cannot provide.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T12:40:44.806Z","isFirstParty":false}