{"uid":"cap_xEe15jCyUc2byhwdVR3R7","slug":"api-nansen-ai-f7556998","name":"Nansen Address Historical Balances","description":"Get Address Historical Balances Data","url":"https://api.nansen.ai/api/v1/profiler/address/historical-balances","method":"GET","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","avalanche","base","bitcoin","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","ronin","scroll","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":"SortOrder[ProfilerAddressHistoricalBalancesSortField]","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":{"request":{"date":{"to":"2025-01-31","from":"2025-01-01"},"chain":"ethereum","address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"},"response":{"data":[{"chain":"ethereum","value_usd":10.115815534923579,"token_amount":3.3669076951587447,"token_symbol":"RAI","token_address":"0x03ab458634910aad20ef5f1c8ee96f1d6ac54919","block_timestamp":"2025-01-31T23:59:59"},{"chain":"ethereum","value_usd":482.9831420186977,"token_amount":150079.420694201,"token_symbol":"DONUT","token_address":"0xc0f9bd5fa5698b6505f643900ffa515ea5df54a9","block_timestamp":"2025-01-31T23:59:59"},{"chain":"ethereum","value_usd":0.02550871392904809,"token_amount":0.044011284111936354,"token_symbol":"GTC","token_address":"0xde30da39c46104798bb5aa3fe8b9e0e1f348163f","block_timestamp":"2025-01-31T23:59:59"},{"chain":"ethereum","value_usd":0.05274043176741183,"token_amount":1,"token_symbol":"NCR","token_address":"0xdb5c3c46e28b53a39c255aa39a411dd64e5fed9c","block_timestamp":"2025-01-31T23:59:59"},{"chain":"ethereum","value_usd":2.0079631196748613,"token_amount":10000,"token_symbol":"SHIRO","token_address":"0x6c38f26eaee4e1bdf7d2b4d42467b7a8a6082f5a","block_timestamp":"2025-01-31T23:59:59"},{"chain":"ethereum","value_usd":3.4858164528071875,"token_amount":67169001,"token_symbol":"PORK","token_address":"0xb9f599ce614feb2e1bbe58f180f370d05b39344e","block_timestamp":"2025-01-31T23:59:59"},{"chain":"ethereum","value_usd":82998.37552683667,"token_amount":82998.03958,"token_symbol":"USDC","token_address":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","block_timestamp":"2025-01-31T23:59:59"},{"chain":"ethereum","value_usd":3.5641979432047215,"token_amount":49999.99999999999,"token_symbol":"CAGA","token_address":"0xbddc20ed7978b7d59ef190962f441cd18c14e19f","block_timestamp":"2025-01-31T23:59:59"},{"chain":"ethereum","value_usd":7.603284654280626,"token_amount":0.00007246,"token_symbol":"AWBTC_V2","token_address":"0x9ff58f4ffb29fa2266ab25e75e2a8b3503311656","block_timestamp":"2025-01-31T23:59:59"},{"chain":"ethereum","value_usd":5.039356199611907,"token_amount":10000000000,"token_symbol":"CHEEMS","token_address":"0x41b1f9dcd5923c9542b6957b9b72169595acbc5c","block_timestamp":"2025-01-31T23:59:59"}],"pagination":{"page":1,"per_page":10,"is_last_page":false}}},"exampleRequest":{"date":{"to":"2025-01-31","from":"2025-01-01"},"chain":"ethereum","address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"},"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","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"},{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_C36Bp4T-lSQR_HavV2ZqJ","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null},{"uid":"pm_4mhsd31K0M_Ie3eDYXki5","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Retrieves historical token balance snapshots for a given blockchain wallet address over time","exampleAgentPrompt":"Pull the historical token balances for wallet 0x3f5CE5FBFe3E9af3971dD833D26bA9b5C936f0bE from Nansen so I can see how its holdings changed over the past year.","exampleUseCases":null,"resultDescription":"Returns time-series data of token balance snapshots for the specified wallet address, including per-token quantities and values at various historical timestamps, enabling portfolio trend analysis.","failureModes":["Invalid or malformed wallet address returns 400 error","Address not indexed by Nansen returns empty result or 404","Rate limiting or quota exceeded returns 429","Unsupported chain address returns error","No historical data available for very new or inactive addresses"],"whenToPreferThis":"Use this endpoint when you need time-series balance history for a specific wallet rather than just current holdings. Ideal for auditing portfolio changes, tracking smart money accumulation/distribution patterns, or building historical performance charts for a given address. Prefer this over current-balance endpoints when the temporal dimension matters.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-13T12:52:33.166Z","isFirstParty":false}