# Historical Holdings

{% hint style="info" %}
**Note:** This is a beta endpoint. The data provided may be subject to changes, corrections, or improvements as we continue to refine our Smart Money analytics. 
{% endhint %}

## Get Smart Money Historical Holdings Data

> 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

```json
{"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apiKey","description":"API key for authentication"}},"schemas":{"SmartMoneyHistoricalHoldingsRequest":{"properties":{"date_range":{"$ref":"#/components/schemas/DateOnlyRange","description":"Date range for historical data (YYYY-MM-DD format). If 'to' is omitted, defaults to today. Maximum lookback is 4 years."},"chains":{"items":{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsChain"},"type":"array","title":"Chains","description":"Chains to include in the analysis. Supports ethereum, base, bnb, monad, and solana."},"filters":{"anyOf":[{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsFilters"}],"description":"Additional filters to apply"},"premium_labels":{"anyOf":[{"type":"boolean"}],"title":"Premium Labels","description":"Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels (20 credits, currently available to internal users only)."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/SortOrder_SmartMoneyHistoricalHoldingsSortField_"},"type":"array"}],"title":"Order By","description":"Custom sort order. Defaults to sorting by date DESC, value_usd DESC, token_address ASC, chain ASC for stable pagination."}},"additionalProperties":false,"type":"object","required":["date_range","chains"],"title":"SmartMoneyHistoricalHoldingsRequest","description":"Request model for smart money historical holdings endpoint."},"DateOnlyRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in YYYY-MM-DD format"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in YYYY-MM-DD format"}},"type":"object","title":"DateOnlyRange","description":"Date range model that only accepts YYYY-MM-DD format (no time components)."},"SmartMoneyHistoricalHoldingsChain":{"type":"string","enum":["base","bnb","ethereum","monad","solana"],"title":"SmartMoneyHistoricalHoldingsChain","description":"Chains supported for smart money historical holdings endpoint."},"SmartMoneyHistoricalHoldingsFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Smart money category filters"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Smart money category filters"},"include_stablecoins":{"anyOf":[{"type":"boolean"}],"title":"Include Stablecoins","description":"Whether to include stablecoins in the results","default":false},"include_native_tokens":{"anyOf":[{"type":"boolean"}],"title":"Include Native Tokens","description":"Whether to include native tokens (e.g., ETH, SOL) in the results","default":false},"balance":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token balance range filter in human-readable units"},"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Value range filter in USD"},"balance_24h_percent_change":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"24-hour balance change percentage range filter"},"holders_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of holders range filter"},"share_of_holdings_percent":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Share of holdings percentage range filter"},"token_age_days":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token age range filter in days"},"market_cap_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Market cap range filter in USD"},"token_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Address","description":"Token address filter"},"token_symbol":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Symbol","description":"Token symbol filter"}},"additionalProperties":false,"type":"object","title":"SmartMoneyHistoricalHoldingsFilters","description":"Filters for smart money historical holdings endpoint."},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Enum for smart money filter options."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","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"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","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"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"SortOrder_SmartMoneyHistoricalHoldingsSortField_":{"properties":{"field":{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"SortOrder[SmartMoneyHistoricalHoldingsSortField]"},"SmartMoneyHistoricalHoldingsSortField":{"type":"string","enum":["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"],"title":"SmartMoneyHistoricalHoldingsSortField","description":"Enum for sortable fields in smart money historical holdings."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"SmartMoneyHistoricalHoldingsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SmartMoneyHistoricalHolding"},"type":"array","title":"Data","description":"List of smart money historical holding records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"SmartMoneyHistoricalHoldingsResponse","description":"Response model for smart money historical holdings endpoint."},"SmartMoneyHistoricalHolding":{"properties":{"date":{"type":"string","title":"Date","description":"Snapshot date (YYYY-MM-DD)"},"chain":{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsChain","description":"Chain name"},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"token_sectors":{"items":{"type":"string"},"type":"array","title":"Token Sectors","description":"Token sectors"},"smart_money_labels":{"items":{"type":"string"},"type":"array","title":"Smart Money Labels","description":"Array of unique smart money labels present in the aggregated holdings for this token"},"balance":{"anyOf":[{"type":"number"}],"title":"Balance","description":"Token balance in human-readable units (accounting for decimals)"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Value of token held by Smart Money at snapshot date"},"balance_24h_percent_change":{"anyOf":[{"type":"number"}],"title":"Balance 24H Percent Change","description":"Balance change of Smart Money for token during the 24 hours prior to snapshot"},"holders_count":{"type":"integer","title":"Holders Count","description":"Number of Smart Money holders of token at snapshot date"},"share_of_holdings_percent":{"anyOf":[{"type":"number"}],"title":"Share Of Holdings Percent","description":"Share of Smart Money total USD balance at snapshot date"},"token_age_days":{"type":"integer","title":"Token Age Days","description":"Number of days since token was deployed, relative to snapshot date"},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market cap of token at snapshot date"}},"type":"object","required":["date","chain","token_address","token_symbol","token_sectors","smart_money_labels","holders_count","token_age_days"],"title":"SmartMoneyHistoricalHolding","description":"Individual smart money historical holding record."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."}},"headers":{"XNansenCreditsUsed":{"description":"Number of credits consumed by this API request","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Time in seconds until the rate limit window resets","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via the x402 protocol. The `Payment-Required` response header contains a base64-encoded JSON object describing accepted payment options (scheme, network, asset, amount, recipient). To pay, include a `Payment-Signature` header with a base64-encoded signed payment payload. See https://www.x402.org for protocol details.","headers":{"Payment-Required":{"description":"Base64-encoded JSON describing accepted payment options","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","description":"Empty object. Payment details are in the Payment-Required header."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"array","items":{"type":"object","properties":{"loc":{"type":"array","items":{"type":"string"}},"msg":{"type":"string"},"type":{"type":"string"}}}}}}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}},"paths":{"/api/v1/smart-money/historical-holdings":{"post":{"tags":["Smart Money"],"summary":"Get Smart Money Historical Holdings Data","description":"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.\n\nKey Features:\n\n- Daily snapshots of smart money holdings\n- Date range filtering (max 4 years lookback)\n- Point-in-time pricing and market cap data\n- Balance change tracking between snapshots\n- Same filtering options as current holdings endpoint\n\nUse Cases:\n\n- Trend Analysis: Track how smart money rotates between assets over time\n- Performance Attribution: Combine with price data to estimate ROI\n- Backtesting: Validate trading strategies based on historical smart money behavior","operationId":"get_smart_money_historical_holdings_api_v1_smart_money_historical_holdings_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsRequest"}}},"required":true},"responses":{"200":{"description":"Smart money historical holdings data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsResponse"}}},"headers":{"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"}}}}}}
```