OKX Local and Real-Time Market Candle Server: A Comprehensive Guide

Introduction to OKX Candle Server

OKX Candle is a powerful tool designed to provide historical and real-time market data for traders using the OKX exchange. Originally maintained as a separate project, its functionality has now been integrated directly into OKX's ecosystem.

👉 Explore OKX's advanced trading tools

Key Features and Design Purpose

1. Historical Data for Local Trading Simulation

• Supports downloading historical candlestick data for:

  • SPOT trading
  • SWAP perpetual contracts
  • FUTURES delivery contracts
  • OPTION derivatives
• Enables efficient data management and fast retrieval

2. Real-Time Trading Decision Support

• Maintains cached updates of real-time historical candlestick data
• Provides access to live market quotes
• Offers 95% similarity with Binance_candle for easier multi-platform trading

Installation Guide

To get started with OKX Candle:

git clone https://github.com/pyted/okx_candle

Getting Started

3.1 Maintaining Real-Time Historical Candles (candle_map)

For perpetual contracts, running run_candle_map initiates multi-threaded maintenance of the candle_map property:

from okx_candle import CandleServer
from pprint import pprint

candleServer = CandleServer('SWAP')  # SWAP for perpetual contracts
candleServer.run_candle_map()
pprint(candleServer.candle_map)

Output shows structured candlestick data for all instruments.

3.2 Daily Historical Candle Downloads

For spot trading, schedule daily downloads of previous day's candles:

from okx_candle import CandleServer
candleServer = CandleServer('SPOT')  # SPOT for spot trading
candleServer.download_daily()

3.3 Real-Time Market Data Retrieval

Get live ticker data for all perpetual contract products:

from okx_candle import CandleServer
from pprint import pprint

candleServer = CandleServer('SWAP')
bookTickerMap = candleServer.market.get_tickersMap()
pprint(bookTickerMap)

Candle Data Specifications

4.1 Data Format

• Stored as np.ndarray for computational efficiency
• Uses np.float64 for all numerical values (converted from OKX's string format)

4.2 Storage Rules

• Data partitioned by date (00:00:00 - 23:59:59 in Shanghai timezone)
• Each CSV file contains complete daily data for specific product

• Strict validation ensures data integrity:

  • Time interval verification
  • Start/end timestamp validation
  • Data length checks

Instrument Types (instType)

Supported product categories:

• SPOT (spot trading)
• SWAP (perpetual contracts)
• FUTURES (delivery contracts)
• OPTION (derivatives)

Note: Margin trading is not supported

👉 Learn more about OKX product offerings

CandleRule Configuration

6.1 Rule Attributes Overview

Customize candle server behavior through various parameters:

from okx_candle import CandleServer, CandleRule
CandleRule.BAR = '5m'  # Set candle granularity to 5 minutes
candleServer = CandleServer('SPOT', CandleRule)

Key Configuration Areas:

1. Product Filtering

   • SYMBOLS: Specify products to include
   • SYMBOLS_FILTER: Products to exclude
   • SYMBOL_CONTAINS: Name substring matching
   • SYMBOL_ENDSWITH: Name suffix matching

2. Candle Parameters

   • BAR: Time granularity (default '1m')
   • TIMEZONE: Data timezone (default 'Asia/Shanghai')

3. Download Settings

   • DOWNLOAD_TIME: Daily download schedule (default '00:10:00')
   • CANDLE_DIR: Base storage directory

4. API Keys

   • Optional for market data access

5. Real-Time Candle Maintenance

   • LOCAL_CANDLE_DAYS: Initial historical data download
   • LENGTH: Number of candles to maintain
   • UPDATE_INTERVAL_SECONDS: Refresh frequency

FAQs

Q: How does OKX Candle ensure data accuracy?

A: Multiple validation checks including time interval verification, timestamp validation, and length requirements ensure only correct data enters the system.

Q: Can I use this for backtesting trading strategies?

A: Absolutely! The historical data download feature makes it perfect for strategy development and backtesting.

Q: What's the difference between candle_map and regular market data?

A: candle_map maintains a constantly updated cache of historical candles with real-time updates, while regular market data provides current snapshots.

Q: How frequently does the real-time data update?

A: By default every 3 seconds, but configurable via UPDATE_INTERVAL_SECONDS.

Q: Is there mobile support for monitoring candle data?

A: While the library is Python-based, you can build mobile interfaces using OKX's API and the data structures provided.

Advanced Features

Historical Data Management with OkxLite

from okx_candle import OkxLite
okxLite = OkxLite()
candle = okxLite.load_candle_by_date(
    instType='SPOT',
    symbol='BTC-USDT',
    start='2023-02-05',
    end='2023-02-06',
)

Market Depth Information

Retrieve order book data with configurable depth:

books = Market('SPOT').get_books(symbol='BTC-USDT', sz=10)

Conclusion

The OKX Candle Server provides traders with powerful tools for both historical analysis and real-time decision making. Its integration with OKX's ecosystem and similarity to Binance's interface makes it particularly valuable for multi-exchange traders.

For the most current updates and documentation, always refer to the official OKX resources and GitHub repository.