Historical

The Historical service provides access to the backtesting endpoints under /api/v1beta1/. These endpoints return point-in-time data, making them suitable for historical analysis and strategy backtesting.

Access it via client.Historical.

Historical Token Flow Summary

HistoricalTokenFlowSummary returns temporally-correct token flow intelligence for a specific token and date range.

Endpoint: POST /api/v1beta1/tgm/historical-token-flow-summary

Request

type TGMHistoricalTokenFlowSummaryRequest struct {
    Chain                Chain     `json:"chain"`
    TokenAddress         string    `json:"token_address"`
    DateRange            DateRange `json:"date_range"`
    ApplyBlacklistFilter *bool     `json:"apply_blacklist_filter,omitempty"`
}

ApplyBlacklistFilter controls whether known bot and wash-trading addresses are excluded from the flow calculations.

Example

resp, err := client.Historical.HistoricalTokenFlowSummary(ctx, &nansen.TGMHistoricalTokenFlowSummaryRequest{
    Chain:        nansen.ChainEthereum,
    TokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    DateRange: nansen.DateRange{
        From: "2023-01-01T00:00:00Z",
        To:   "2023-01-07T00:00:00Z",
    },
    ApplyBlacklistFilter: nansen.BoolPtr(true),
})

Response

Each item in resp.Data is a TGMHistoricalTokenFlowSummary. The response may also include a Warnings field with informational messages from the API.

The response fields mirror the live Flow Intelligence endpoint, broken down by holder segment: Public Figures, Top PnL, Whales, Exchanges, Smart Traders, and Fresh Wallets. Each segment has three fields: NetFlowUSD, AvgFlowUSD, and WalletCount.

---

Historical Smart Money Token Balances

HistoricalSmartMoneyTokenBalances returns point-in-time smart money token balances as of a specific date.

Endpoint: POST /api/v1beta1/smart-money/historical-token-balances

Request

type SmartMoneyHistoricalTokenBalancesRequest struct {
    AsOfDate             string                                    `json:"as_of_date"`
    Chains               []Chain                                   `json:"chains,omitempty"`
    Filters              *SmartMoneyHistoricalTokenBalancesFilters `json:"filters,omitempty"`
    ApplyBlacklistFilter *bool                                     `json:"apply_blacklist_filter,omitempty"`
    Pagination           *PaginationRequest                        `json:"pagination,omitempty"`
}

AsOfDate is an ISO-8601 date string (e.g., "2023-01-01").

Filters (SmartMoneyHistoricalTokenBalancesFilters):

Field	Type	Description
SMFilter	[]HistoricalSmartMoneyFilterType	Include only wallets with these historical labels.
IncludeStablecoins	*bool	Whether to include stablecoins.
IncludeNativeTokens	*bool	Whether to include native tokens.
HoldersCount	*IntegerRangeFilter	Filter by number of holders.

Historical Smart Money Labels (HistoricalSmartMoneyFilterType):

Constant	Value
HistoricalLabelFund	"Fund"
HistoricalLabelSmartTrader	"Smart Trader"
HistoricalLabel30DSmartTrader	"30D Smart Trader"
HistoricalLabel90DSmartTrader	"90D Smart Trader"
HistoricalLabel180DSmartTrader	"180D Smart Trader"
HistoricalLabelSmartDexTrader	"Smart Dex Trader"
HistoricalLabel30DSmartDexTrader	"30D Smart Dex Trader"
HistoricalLabel90DSmartDexTrader	"90D Smart Dex Trader"
HistoricalLabel180DSmartDexTrader	"180D Smart Dex Trader"
HistoricalLabelSmartHLPerpsTrader	"Smart HL Perps Trader"

Example

resp, err := client.Historical.HistoricalSmartMoneyTokenBalances(ctx, &nansen.SmartMoneyHistoricalTokenBalancesRequest{
    AsOfDate: "2023-01-01",
    Chains:   []nansen.Chain{nansen.ChainEthereum},
    Filters: &nansen.SmartMoneyHistoricalTokenBalancesFilters{
        SMFilter: []nansen.HistoricalSmartMoneyFilterType{
            nansen.HistoricalLabelFund,
            nansen.HistoricalLabelSmartTrader,
        },
        IncludeStablecoins: nansen.BoolPtr(false),
    },
    Pagination: &nansen.PaginationRequest{
        Page:    nansen.IntPtr(1),
        PerPage: nansen.IntPtr(10),
    },
})

Response

Each item in resp.Data is a SmartMoneyHistoricalTokenBalance:

Field	Type	Description
Chain	string	Blockchain the token is on.
TokenAddress	string	Token contract address.
TokenSymbol	string	Token ticker symbol.
TokenSectors	[]string	Sector classifications.
ValueUsd	*float64	Total value held in USD as of the date.
Balance24HPercentChange	*float64	24-hour balance change percentage.
HoldersCount	*int	Number of smart money holders.
ShareOfHoldingsPercent	*float64	Share of total smart money holdings.
TokenAgeDays	*int	Age of the token in days.
MarketCapUsd	*float64	Market capitalisation in USD.