---
title: "Get Address Historical Balances Data"
method: POST
path: "/api/v1/profiler/address/historical-balances"
tags: ["Profiler"]
---

# Get Address Historical Balances Data

`POST /api/v1/profiler/address/historical-balances`

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

## Request body

- ProfilerAddressHistoricalBalancesRequest
  - `address` string — Address to get historical balances for
  - `entity_name` string — Entity name to get historical balances for
  - `chain` 'all' | 'arbitrum' | 'avalanche' | 'base' | 'bitcoin' | 'bnb' | 'ethereum' | 'hyperevm' | 'injective' | 'iotaevm' | 'linea' | 'mantle' | 'mantra' | 'monad' | 'near' | 'optimism' | 'plasma' | 'polygon' | 'robinhood' | 'sei' | 'solana' | 'sonic' | 'starknet' | 'sui' | 'ton' | 'tron', required — Chains supported in profiler analysis.
  - `date` DateRange, required — Date range model matching the API schema.
    - `from` string — Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)
    - `to` string — End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)
  - `filters` ProfilerAddressHistoricalBalancesFilters — Filters for profiler address historical balances endpoint. These filters control which historical balance data is included.
    - `value_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `token_amount` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
    - `token_symbol` union — Token symbol filter
      - string
      - string[]
    - `token_address` union — Token address filter
      - string
      - string[]
    - `hide_spam_tokens` boolean — Whether to hide spam tokens from results
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)
  - `order_by` SortOrderProfilerAddressHistoricalBalancesSortField[] — Custom sort order to override the endpoint's default ordering
    - `field` 'block_timestamp' | 'value_usd' | 'token_symbol', required — Enum for sortable fields in profiler address historical balances.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

Address historical balances data

- ProfilerAddressHistoricalBalancesResponse — Response model for profiler address historical-balances endpoint. Contains the filtered historical balance data with metadata.
  - `pagination` PaginationInfo, required — Pagination information for API responses.
    - `page` integer — Current page number
    - `per_page` integer — Number of records per page
    - `is_last_page` boolean — Whether this is the last page
  - `data` ProfilerHistoricalBalance[], required — List of historical balance records
    - `block_timestamp` string, required — The block timestamp as date
    - `token_address` string, required — Token Address
    - `chain` string, required — Chain
    - `token_amount` number — Token amount
    - `value_usd` number — Usd balance of the holdings
    - `token_symbol` string, required — Symbol of the token

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `402` — Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)