feat: Add Binance/Bybit as OHLCV historical data provider

[MrJack93]

Feature: Add Binance/Bybit as OHLCV Historical Data Provider

Status: Proposed
Author: Community
Date: 2026-05-26
Priority: Medium

---

Executive Summary

This feature request proposes adding Binance and Bybit as native OHLCV (candlestick) data providers within OpenAlice's market data system. Currently, users connected to Binance/Bybit for trading must use separate data providers (yfinance, FMP) for historical price data. This creates friction and introduces unnecessary dependencies.

By leveraging CCXT's existing Binance/Bybit connections, OpenAlice can unify trading and analysis into a single data source, eliminating redundant API keys and subscription costs.

---

Problem Statement

Current Limitations

1. Data Provider Fragmentation

┌─────────────────────────────────────────────────┐
│        OpenAlice Market Data Architecture       │
├─────────────────────────────────────────────────┤
│                                                 │
│  Configured Providers:                          │
│  ├─ yfinance (free, limited crypto support)     │
│  ├─ FMP (paid, intraday available)              │
│  ├─ FRED (macro data only)                      │
│  └─ ... other providers ...                     │
│                                                 │
│  NOT Available:                                 │
│  ├─ Binance API (despite CCXT integration)      │
│  ├─ Bybit API (despite CCXT integration)        │
│  └─ Other CCXT-supported exchanges              │
│                                                 │
└─────────────────────────────────────────────────┘

2. Timeframe Limitations for Crypto

Why Binance as a Crypto Data Provider Makes Sense

Legend: ✅ Supported · ⚠️ Limited · ❌ Not supported

Provider	1m	5m	15m	1h	4h	1d	Market Coverage	Practical Limitation
yfinance	⚠️	⚠️	⚠️	⚠️	❌	✅	Only a subset of major crypto tickers	Limited intraday history and incomplete coin coverage.
FMP Free	❌	❌	❌	❌	❌	✅	Limited	No useful intraday crypto support on the free tier.
FMP Pro	✅	✅	✅	✅	❌	✅	Limited and plan-dependent	Intraday access exists, but coverage is not as broad or exchange-native as Binance.
Binance via CCXT	✅	✅	✅	✅	✅	✅	Native Binance pairs	Requires pagination and rate-limit handling, but no extra market data subscription is needed.

FMP Pro intraday support for crypto is not guaranteed and may require additional licenses

3. Architectural Misalignment

Users with Binance/Bybit trading accounts must:

1. Authenticate to Binance/Bybit for trading (already done via CCXT)
2. Separately configure yfinance/FMP for historical data
3. Manage additional API keys/subscriptions
4. Accept data latency and potential provider limitations

This violates the principle of minimal configuration and single source of truth.

---

Proposed Solution

Architecture Overview

┌──────────────────────────────────────────────────────┐
│         Unified Data + Trading Architecture          │
├──────────────────────────────────────────────────────┤
│                                                      │
│  User configures: crypto → "binance"                 │
│                                                      │
│  ┌────────────────────────────────────────────┐      │
│  │  CCXT Layer                                │      │
│  │  ├─ createOrder() → Binance trading API    │      │
│  │  └─ fetchOHLCV() → Binance market data     │      │
│  └────────────────────────────────────────────┘      │
│                           ↓                          │
│  ┌────────────────────────────────────────────┐      │
│  │  OpenTypeBB BinanceProvider                │      │
│  │  ├─ Normalize timeframes                   │      │
│  │  ├─ Handle rate limiting                   │      │
│  │  ├─ Cache OHLCV data                       │      │
│  │  └─ Return standardized format             │      │
│  └────────────────────────────────────────────┘      │
│                           ↓                          │
│  ┌────────────────────────────────────────────┐      │
│  │  AI Tools + UI                             │      │
│  │  ├─ technical analysis                     │      │
│  │  ├─ backtesting                            │      │
│  │  ├─ indicator calculation                  │      │
│  │  └─ portfolio visualization                │      │
│  └────────────────────────────────────────────┘      │
│                                                      │
└──────────────────────────────────────────────────────┘

Implementation Roadmap

Phase 1: Binance Provider (Core)

• Create BinanceProvider class in packages/opentypebb/src/providers/
• Implement fetchOHLCV() method wrapping CCXT fetchOHLCV()
• Add timeframe normalization (CCXT → OpenBB standard)
• Implement rate limiting (Binance API limits: 1200 requests/min)
• Add basic caching layer for repeated queries
• Write unit tests for happy path + edge cases

Phase 2: Configuration & UI

• Add "binance" option to market-data config schema
• Update Web UI provider selector to include Binance
• Add authentication validation (use existing CCXT credentials)
• Document configuration in README

Phase 3: Bybit Provider (Similar)

• Create BybitProvider class
• Test against Bybit's API rate limits and response format
• Add to UI as alternative crypto provider

Phase 4: Polish & Testing

• End-to-end testing with real Binance/Bybit accounts
• Performance benchmarking (response times, data quality)
• Documentation updates
• Migration guide for users currently on yfinance

---

Technical Specification

Configuration

Current (yfinance):

{
  "enabled": true,
  "backend": "typebb-sdk",
  "providers": {
    "equity": "yfinance",
    "crypto": "yfinance",
    "currency": "yfinance"
  }
}

After implementation (Binance):

{
  "enabled": true,
  "backend": "typebb-sdk",
  "providers": {
    "equity": "yfinance",
    "crypto": "binance",
    "currency": "yfinance"
  }
}

API Query Format

Input:

interface CryptoHistoricalQuery {
  symbol: string           // "BTCUSDT" or "BTC/USDT"
  start_date?: string      // YYYY-MM-DD
  end_date?: string        // YYYY-MM-DD
  interval: string         // "1m", "5m", "15m", "1h", "4h", "1d"
  provider?: string        // "binance"
  [key: string]: unknown
}

Output:

interface CryptoHistoricalData {
  date: string             // ISO 8601 timestamp
  open: number
  high: number
  low: number
  close: number
  volume: number | null
  vwap: number | null
  [key: string]: unknown
}

Timeframe Support

Binance supports:

• Minutes: 1m, 3m, 5m, 15m, 30m
• Hours: 1h, 2h, 4h, 6h, 8h, 12h
• Daily: 1d
• Weekly: 1w
• Monthly: 1M

Initial support: 1m, 5m, 15m, 30m, 1h, 4h, 1d (most commonly used)

Rate Limiting

Binance API limits:

• 1200 requests per minute (general)
• 10 requests per second (IP-based)

Implementation:

• Use token bucket algorithm
• Log rate limit warnings
• Gracefully handle 429 responses

Error Handling

// Example: Symbol not found
throw new ProviderError(
  "Symbol INVALIDBTC not found on Binance",
  { provider: "binance", symbol: "INVALIDBTC" }
);

// Example: Timeframe not supported
throw new ProviderError(
  "Timeframe 2m not supported by Binance",
  { provider: "binance", timeframe: "2m" }
);

---

Benefits

For Users

• 🔓 No additional API keys — use existing Binance/Bybit credentials
• 💰 Free intraday data — no subscription costs
• ⚡ Faster data — direct exchange API instead of third-party aggregators
• 📊 All timeframes — 1m through 1M granularity
• 🎯 Better accuracy — official exchange data, no aggregation lag

For OpenAlice

• 🏗️ Architectural alignment — single source of truth for trading + analysis
• 📈 Reduced dependencies — fewer third-party data providers to manage
• 🔐 Credential reuse — no additional secret management
• 🚀 Competitive advantage — built-in support for major exchanges

---

Risks & Mitigations

Risk	Severity	Mitigation
Binance API changes	Medium	Monitor official docs, add integration tests
Rate limiting issues	Medium	Implement backoff, cache responses
Data staleness	Low	Document cache TTL, use WebSocket for real-time
Symbol format differences	Low	Normalize input (accept "BTC/USDT" or "BTCUSDT")
Breaking changes in CCXT	Medium	Pin CCXT version, test on upgrades

---

Testing Strategy

Unit Tests

// Test 1: Fetch 1h candles for BTCUSDT
const result = await binanceProvider.fetchOHLCV({
  symbol: "BTCUSDT",
  interval: "1h",
  start_date: "2024-05-01",
  end_date: "2024-05-07"
});
expect(result.length).toBeGreaterThan(0);
expect(result[0].open).toBeLessThan(result[0].high);

// Test 2: Handle invalid timeframe
await expect(
  binanceProvider.fetchOHLCV({
    symbol: "BTCUSDT",
    interval: "2m"
  })
).rejects.toThrow("Timeframe 2m not supported");

// Test 3: Rate limiting
// 1201 concurrent requests should not exceed 1200/min

Integration Tests

• Real Binance API calls with small query sets
• Test with multiple symbol formats
• Verify data consistency vs. official Binance UI
• Performance benchmarking

Edge Cases

• Symbols with special characters (e.g., "USDC-USDT")
• Gap handling (markets with low liquidity)
• DST transitions
• Market data gaps during exchange maintenance

---

Documentation Updates Needed

1. README.md — Add Binance to provider list
2. docs/opentypebb-tutorial.md — Update provider configuration section
3. src/domain/market-data/README.md — Add Binance provider docs
4. CLAUDE.md — Reference this feature as load-bearing for crypto trading

---

Acceptance Criteria

• BinanceProvider implemented and passing all unit tests
• Configuration UI updated to include "binance" option
• All supported timeframes (1m–1d) working correctly
• Rate limiting implemented and tested
• Documentation complete and accurate
• E2E test with real Binance account confirms data accuracy
• No performance regression vs. yfinance provider
• Bybit support (Phase 3) optional but preferred

---

References

• CCXT Binance API: https://github.com/ccxt/ccxt/wiki/Manual#binance
• Binance API Docs: https://binance-docs.github.io/apidocs/
• OpenBB Architecture: See packages/opentypebb/
• Similar Issues: None currently open

---

Questions for Discussion

1. Symbol Format: Should we auto-normalize "BTC/USD" → "BTCUSDT" or require exact format?
2. Bybit Timeline: Implement in Phase 3, or parallel with Binance?
3. Caching Strategy: In-memory only, or persistent cache layer?
4. WebSocket Support: Future enhancement for real-time candles?