---
title: "Get Smart Money Historical Holdings Data"
method: POST
path: "/api/v1/smart-money/historical-holdings"
tags: ["Smart Money"]
---

# Get Smart Money Historical Holdings Data

`POST /api/v1/smart-money/historical-holdings`

Retrieve historical snapshots of aggregated token balances held by smart traders and funds. This endpoint provides time-series data for trend analysis, backtesting, and performance attribution.

Key Features:

- Daily snapshots of smart money holdings
- Date range filtering (max 4 years lookback)
- Point-in-time pricing and market cap data
- Balance change tracking between snapshots
- Same filtering options as current holdings endpoint

Use Cases:

- Trend Analysis: Track how smart money rotates between assets over time
- Performance Attribution: Combine with price data to estimate ROI
- Backtesting: Validate trading strategies based on historical smart money behavior

## Request body

- SmartMoneyHistoricalHoldingsRequest — Request model for smart money historical holdings endpoint.
  - `date_range` DateOnlyRange, required — Date range model that only accepts YYYY-MM-DD format (no time components).
    - `from` string — Start date in YYYY-MM-DD format
    - `to` string — End date in YYYY-MM-DD format
  - `chains` SmartMoneyHistoricalHoldingsChain[], required — Chains to include in the analysis. Supports ethereum, base, bnb, monad, robinhood, and solana.
  - `filters` SmartMoneyHistoricalHoldingsFilters — Filters for smart money historical holdings endpoint.
    - `include_smart_money_labels` HistoricalSmartMoneyFilterType[] — Smart money category filters
    - `exclude_smart_money_labels` HistoricalSmartMoneyFilterType[] — Smart money category filters
    - `include_stablecoins` boolean — Whether to include stablecoins in the results
    - `include_native_tokens` boolean — Whether to include native tokens (e.g., ETH, SOL) in the results
    - `balance` 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)
    - `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)
    - `balance_24h_percent_change` 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)
    - `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)
    - `share_of_holdings_percent` 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_age_days` 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)
    - `market_cap_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_address` union — Token address filter
      - string
      - string[]
    - `token_symbol` union — Token symbol filter
      - string
      - string[]
  - `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` SortOrderSmartMoneyHistoricalHoldingsSortField[] — Custom sort order. Defaults to sorting by date DESC, value_usd DESC, token_address ASC, chain ASC for stable pagination.
    - `field` 'date' | 'chain' | 'token_address' | 'token_symbol' | 'balance' | 'value_usd' | 'balance_24h_percent_change' | 'holders_count' | 'share_of_holdings_percent' | 'token_age_days' | 'market_cap_usd', required — Enum for sortable fields in smart money historical holdings.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

Smart money historical holdings data

- SmartMoneyHistoricalHoldingsResponse — Response model for smart money historical holdings endpoint.
  - `data` SmartMoneyHistoricalHolding[], required — List of smart money historical holding records
    - `date` string, required — Snapshot date (YYYY-MM-DD)
    - `chain` 'base' | 'bnb' | 'ethereum' | 'monad' | 'robinhood' | 'solana', required — Chains supported for smart money historical holdings endpoint.
    - `token_address` string, required — Address of token
    - `token_symbol` string, required — Token symbol
    - `token_sectors` string[], required — Token sectors
    - `smart_money_labels` string[], required — Array of unique smart money labels present in the aggregated holdings for this token
    - `balance` number — Token balance in human-readable units (accounting for decimals)
    - `value_usd` number — Value of token held by Smart Money at snapshot date
    - `balance_24h_percent_change` number — Balance change of Smart Money for token during the 24 hours prior to snapshot
    - `holders_count` integer, required — Number of Smart Money holders of token at snapshot date
    - `share_of_holdings_percent` number — Share of Smart Money total USD balance at snapshot date
    - `token_age_days` integer, required — Number of days since token was deployed, relative to snapshot date
    - `market_cap_usd` number — Market cap of token at snapshot date
  - `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)