# Nansen Historical Balances

> Nansen Historical Balances is a paid API for AI agents from Nansen at api.nansen.ai, paid per call via MPP, $0.01/call, status unknown (last checked 2026-10-09).

Retrieves time-series snapshots of token and native coin balances for a blockchain address or named entity across configurable date ranges and multiple chains.

## Facts

- Endpoint: POST https://api.nansen.ai/api/v1/profiler/address/historical-balances?utm_source=zero.xyz
- Price: $0.01/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-09
- Activations on Zero: 0
- Provider: Nansen
- Docs: https://docs.nansen.ai
- Website: https://nansen.ai
- Tags: blockchain, smart-money, wallet, tokens, defi, analytics, profiler, dex, pnl, onchain, prediction-market, data
- Canonical page: https://www.zero.xyz/c/nansen-historical-balances-1d080ac4
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_JwCD13nzVPkVpyaDhHSm5

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability nansen-historical-balances-1d080ac4 -d '<json body>'
```

Example prompt: 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.

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

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.

What it helps to answer:

- Portfolio value changes across different time periods
- Token accumulation and distribution patterns over selected timeframes
- New positions entered and exited during specific periods

## Output

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.

## Request schema (JSON Schema)

```json
{
 "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"
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "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."
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-historical-balances-1d080ac4/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)