---
title: "Get Historical SM Token Balances (Beta)"
method: POST
path: "/api/v1beta1/smart-money/historical-token-balances"
tags: ["Smart Money"]
---

# Get Historical SM Token Balances (Beta)

`POST /api/v1beta1/smart-money/historical-token-balances`

**Beta — subject to breaking changes.**

Point-in-time smart money token balance aggregates for a given date.

Returns SM token holdings per (chain, token_address) pair filtered by SM labels,
token type, and chain. Includes 24h balance change, holder counts, share of total
SM holdings, and historical market cap.

## Request body

- SmartMoneyHistoricalTokenBalancesRequest — Request model for the historical SM token balances endpoint. Returns smart money token balance aggregates for a given date, filtered by chain, SM label, and token type.
  - `as_of_date` string, date, required — Date to query balances for
  - `chains` SmartMoneyChain[] — Chains to include. Empty list returns all chains.
  - `filters` SmartMoneyHistoricalTokenBalancesFilters — Filters for the historical SM token balances endpoint.
    - `sm_filter` HistoricalSmartMoneyFilterType[] — SM label filter. Empty list includes all SM labels.
    - `include_stablecoins` boolean — Whether to include stablecoin tokens
    - `include_native_tokens` boolean — Whether to include native tokens and LSTs/LRTs
    - `holders_count` 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)
  - `apply_blacklist_filter` boolean — When True, exclude blacklisted addresses from the results. Defaults to True.
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)

## Response `200`

Historical SM token balances data

- SmartMoneyHistoricalTokenBalancesResponse — Response model for the historical SM token balances endpoint.
  - `data` SmartMoneyHistoricalTokenBalance[], required — List of SM token balance records
    - `chain` string, required — Blockchain chain
    - `token_address` string, required — Token contract address
    - `token_symbol` string, required — Token symbol
    - `token_sectors` string[] — Token sector classifications
    - `value_usd` number — Total SM balance in USD
    - `balance_24h_percent_change` number — 24-hour percentage change in token balance amount
    - `holders_count` integer — Number of SM holders with balance > $100
    - `share_of_holdings_percent` number — This token's share of total SM holdings
    - `token_age_days` integer — Days since token deployment as of as_of_date
    - `market_cap_usd` number — Historical market cap on as_of_date (falls back to FDV)
  - `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

## 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)