API Documentation
Time Series Data and Historical Analysis Queries
Access comprehensive time series data for backtesting, research, and historical analysis. Query OHLCV candles, historical funding rates, whale movement timelines, and aggregated market snapshots across multiple timeframes.
Published March 21, 2026
•
15 min read
•
Research
Historical Data Overview
Smart Money API provides 24 months of historical data enabling comprehensive research, backtesting, and time-based analysis. All historical data is normalized, deduplicated, and available at multiple aggregation levels.
Available historical data includes:
- OHLCV Candles — Open, High, Low, Close, Volume for all traded pairs
- Whale Movements — Historical accumulation/distribution at daily and hourly resolution
- Funding Rates — Historical funding rate snapshots for all perpetual pairs
- Open Interest — Historical OI data across all exchanges and timeframes
- Liquidations — Historical liquidation cascades and pressure points
Data Retention: Full tick data retained for 90 days. Aggregated hourly/daily data retained for 24 months. Raw archives available for download.
OHLCV Candlestick Data
Open-High-Low-Close-Volume data for technical analysis and charting. Available for all cryptocurrency pairs across timeframes from 1-minute to 1-month.
OHLCV Data Structure
{
"timestamp": 1709980800000,
"symbol": "BTCUSDT",
"timeframe": "1h",
"open": 71250.50,
"high": 72500.00,
"low": 71000.25,
"close": 72250.75,
"volume_base": 1234.5,
"volume_quote": 89234500,
"trades": 45678
}
Query OHLCV Data
// Get 1-hour candles for last 30 days
GET /v1/historical/ohlcv?
symbol=BTCUSDT&
timeframe=1h&
lookback=30d&
limit=720
Get your API key in 30 seconds
Ready to build? Grab a free API key (200 calls/day, no card) and start pulling live whale, funding and on-chain data.
Get your API key →Available Timeframes
Timeframe Options
| Timeframe |
Duration |
Use Case |
Max Lookback |
| 1m |
1 minute |
High-frequency trading, scalping |
30 days |
| 5m |
5 minutes |
Intraday, swing trading |
90 days |
| 15m |
15 minutes |
Day trading, signal detection |
180 days |
| 1h |
1 hour |
Medium-term trading, analysis |
365 days |
| 4h |
4 hours |
Swing trading, trend analysis |
24 months |
| 1d |
1 day |
Long-term positioning, research |
24 months |
| 1w |
1 week |
Macro analysis, multi-year trends |
24 months |
| 1M |
1 month |
Strategic positioning |
24 months |
Timeframe Combinations
Query multiple timeframes simultaneously:
GET /v1/historical/ohlcv/multi?
symbol=BTCUSDT&
timeframes=1h,4h,1d&
timestamp=1709980800000
// Returns latest candle for each timeframe
Historical Query Patterns
Time-Based Queries
// Query specific time range
GET /v1/historical/ohlcv?
symbol=BTCUSDT&
timeframe=1h&
start_time=1709894400000&
end_time=1709980800000
// Or use relative lookback
GET /v1/historical/ohlcv?
symbol=BTCUSDT&
timeframe=1d&
lookback=90d
Pagination for Large Datasets
// First page: 1000 candles
GET /v1/historical/ohlcv?
symbol=BTCUSDT&
timeframe=1m&
limit=1000&
start_time=1709980800000
// Next page using cursor
GET /v1/historical/ohlcv?
symbol=BTCUSDT&
timeframe=1m&
cursor=1709981000000&
limit=1000
Aggregation Intervals
Fixed-Time Aggregation
Aggregate data at fixed intervals (hourly, daily, weekly):
// Daily snapshots for 1 month
GET /v1/historical/snapshots?
metrics=whale_net_flow,funding_rate,oi&
interval=1d&
lookback=30d
Custom Aggregation
Aggregate over custom time windows:
// Aggregate 1-minute candles into 15m
GET /v1/historical/ohlcv/resample?
symbol=BTCUSDT&
source_timeframe=1m&
target_timeframe=15m&
lookback=7d
Whale Movement History
Historical Whale Tracking
// Historical whale accumulation patterns
GET /v1/historical/whales?
asset=BTC&
metric=net_accumulation&
interval=1d&
lookback=365d
// Historical movement around price levels
GET /v1/historical/whales/price-correlation?
asset=ETH&
lookback=90d
Whale Data Structure
{
"timestamp": 1709980800000,
"asset": "BTC",
"metric": "net_accumulation",
"value": 50000,
"whale_count": 847,
"exchange_inflow": -12000,
"exchange_outflow": 62000
}
Funding Rate History
Historical Funding Rate Snapshots
// Get hourly funding rate snapshots
GET /v1/historical/derivatives/funding-heatmap?
symbol=BTCUSDT&
exchange=binance&
interval=1h&
lookback=30d
// Compare historical rates across exchanges
GET /v1/historical/derivatives/funding-heatmap/comparative?
symbol=ETHUSDT&
exchanges=bybit,binance,hyperliquid&
interval=4h&
lookback=90d
Funding Rate Statistics
Query aggregated funding rate statistics:
GET /v1/historical/derivatives/funding-stats?
symbol=BTCUSDT&
lookback=365d&
metrics=mean,median,std_dev,min,max
// Response includes:
// - Annual average funding rate
// - Distribution (std dev)
// - Historical extremes
// - Percentile ranks
Backtesting Data Access
Backtesting Query Format
Optimized for backtesting frameworks like Backtrader, VectorBT, and custom engines:
// Get all data for 1-year backtest
GET /v1/backtest/data?
symbols=BTCUSDT,ETHUSDT&
timeframe=1h&
start=2024-01-01&
end=2025-01-01&
fields=ohlcv,funding_rate,oi,whale_flow
Export Formats
Download historical data for offline analysis:
- CSV — Standard columnar format for spreadsheets
- JSON — Structured format with all metadata
- Parquet — Compressed columnar format for data science
- HDF5 — Time series optimized format
// Export as CSV
GET /v1/backtest/export?
symbols=BTCUSDT&
timeframe=1d&
lookback=365d&
format=csv
Practical Examples
Example 1: Research 2024 Bull Market
// Correlate whale movement with price action
GET /v1/historical/correlated-data?
asset=BTC&
start_time=2024-01-01&
end_time=2024-12-31&
include=ohlcv,whale_accumulation,funding_rates&
interval=1d
Example 2: Backtesting Funding Rate Strategy
// Get data for funding rate mean reversion strategy
GET /v1/backtest/data?
symbols=BTCUSDT,ETHUSDT,BNBUSDT&
timeframe=4h&
start=2023-01-01&
end=2025-01-01&
exchange=binance&
fields=funding_rate,open_interest,liquidations
Historical Data Best Practices
1. Choose Appropriate Timeframes
Use the smallest timeframe needed for your analysis. 1-minute data is more expensive than hourly data.
2. Specify Time Ranges
Always use start_time/end_time or lookback parameters. Open-ended queries are inefficient.
3. Cache Historical Queries
Historical data is immutable. Cache aggressively (30-day TTL for monthly data).
4. Use Pagination for Large Results
1-minute data over 1 year = 525,600 candles. Use pagination and streaming for large datasets.
5. Validate Data Completeness
Check response metadata for gaps or missing exchanges before using data in analysis.
Access Historical Data for Research
24 months of OHLCV, whale movement, and funding rate data. Perfect for backtesting, research, and strategy development.
View Plans
Free tier: 30d history. Pro: 24 months. Enterprise: Full archive access.