CryptoKlineVisionData Usage

Fetch market data for: $ARGUMENTS

Use automatic failover between data sources.

Quick Start

from ckvd import CryptoKlineVisionData, DataProvider, MarketType, Interval
from datetime import datetime, timedelta, timezone

# Create manager for USDT-margined futures
manager = CryptoKlineVisionData.create(DataProvider.BINANCE, MarketType.FUTURES_USDT)

# Fetch data with automatic failover (cache → Vision → REST)
# IMPORTANT: Always use UTC timezone-aware datetimes
end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(days=7)

df = manager.get_data(
    symbol="BTCUSDT",
    start_time=start_time,
    end_time=end_time,
    interval=Interval.HOUR_1
)

print(f"Loaded {len(df)} bars")
manager.close()

Key Concepts

Concept	Quick Reference
Market Types	SPOT, FUTURES_USDT, FUTURES_COIN
Intervals	MINUTE_1, MINUTE_5, HOUR_1, HOUR_4, DAY_1
FCP Priority	Cache (~1ms) → Vision (~1-5s) → REST (~100-500ms)
Symbol Format	BTCUSDT (spot/futures), BTCUSD_PERP (coin-margined)

High-Level API

For simpler use cases, use fetch_market_data:

from ckvd import fetch_market_data, DataProvider, MarketType, Interval, ChartType
from datetime import datetime, timedelta, timezone

df, elapsed_time, records_count = fetch_market_data(
    provider=DataProvider.BINANCE,
    market_type=MarketType.FUTURES_USDT,
    chart_type=ChartType.KLINES,
    symbol="BTCUSDT",
    interval=Interval.HOUR_1,
    start_time=datetime.now(timezone.utc) - timedelta(days=30),
    end_time=datetime.now(timezone.utc)
)
print(f"Loaded {records_count} bars in {elapsed_time:.2f}s")

Examples

Practical code examples:

• @examples/basic-fetch.md - Single/multiple symbols, market types
• @examples/error-handling.md - Exception patterns, validation, retries

Helper Scripts

Utility scripts for common operations:

# Validate symbol format
uv run -p 3.13 python docs/skills/ckvd-usage/scripts/validate_symbol.py BTCUSDT FUTURES_COIN

# Check cache status
uv run -p 3.13 python docs/skills/ckvd-usage/scripts/check_cache.py BTCUSDT futures_usdt 1h

# Diagnose FCP behavior (with debug logging)
uv run -p 3.13 python docs/skills/ckvd-usage/scripts/diagnose_fcp.py BTCUSDT futures_usdt 1h --days 3

TodoWrite Task Templates

Template A: Fetch Data for Symbol

1. Determine market type from symbol format (BTCUSDT vs BTCUSD_PERP)
2. Create CryptoKlineVisionData manager with correct MarketType
3. Define UTC time range with datetime.now(timezone.utc)
4. Call get_data() with symbol, interval, and time range
5. Validate returned DataFrame (not empty, monotonic index)
6. Close manager when done

Template B: Debug Empty Results

1. Validate symbol format for market type (validate_symbol_for_market_type)
2. Verify time range is in the past and UTC-aware
3. Enable debug logging (CKVD_LOG_LEVEL=DEBUG)
4. Test each FCP source individually with enforce_source
5. Check cache directory exists and has data
6. Document root cause and resolution

Template C: Switch Market Type

1. Identify current market type and symbol format
2. Map symbol to new market type format (e.g., BTCUSDT -> BTCUSD_PERP)
3. Create new manager with target MarketType
4. Verify data fetches correctly for new market type
5. Update any dependent code with new symbol format

---

Post-Change Checklist

After modifying this skill:

• Quick Start code example still matches actual API
• Helper script commands are correct and scripts exist
• @-links to references/ and examples/ resolve
• Append changes to evolution-log.md

---

Detailed References

For deeper information, see:

• @references/market-types.md - Detailed market type documentation
• @references/intervals.md - Complete interval reference
• @references/fcp-protocol.md - FCP architecture and debugging
• @references/debugging.md - Debugging techniques and troubleshooting
• @references/evolution-log.md - Skill change history