概述
Okx_candle 是一款专为量化交易者设计的Python工具库，旨在提供便捷的OKX交易所历史K线数据管理与实时行情获取功能。它支持现货交易（SPOT）、永续合约（SWAP）、交割合约（FUTURES）和期权（OPTION）等多种产品类型，满足本地模拟交易与实盘决策的数据需求。
通过简洁的API接口，用户可以轻松下载、缓存和读取历史K线数据，并获取实时行情信息。其设计与Binance_candle高度相似，大幅降低多平台量化交易者的学习成本。
核心功能
历史K线数据管理
Okx_candle 为本地模拟交易提供全面的历史数据支持：
- 多产品类型覆盖：支持现货、永续合约、交割合约与期权的历史K线下载
- 灵活时间粒度：支持1m、5m、15m、1h、4h、1d等多种时间维度
- 本地存储优化：采用日期分片的CSV存储格式，无需第三方数据库
- 数据验证机制：严格验证时间间隔、数据起点和终点，确保数据准确性
实时行情数据服务
为实盘交易决策提供实时数据支持：
- 实时K线维护：以多线程方式维护最新K线数据字典
- 行情信息获取：支持全部产品的实时行情数据查询
- 深度信息查询：提供订单簿深度数据与轻量深度信息
- 交易规范查询：获取产品的交易规则与限制信息
安装与快速开始
安装方法
通过pip即可快速安装：
pip3 install okx_candle基本使用示例
以下示例展示如何维护永续合约的实时历史K线数据：
from okx_candle import CandleServer
from pprint import pprint
# 初始化永续合约服务
candleServer = CandleServer('SWAP')
# 启动实时K线维护
candleServer.run_candle_map()
# 查看实时K线数据
pprint(candleServer.candle_map)数据格式说明
K线数据结构
Okx_candle 使用NumPy数组存储K线数据，确保运算效率。每行K线包含9个字段：
| 列索引 | 参数名 | 字段解释 | 数据类型 |
|---|---|---|---|
| 0 | ts | 开盘时间戳（毫秒） | np.float64 |
| 1 | o | 开盘价格 | np.float64 |
| 2 | h | 最高价格 | np.float64 |
| 3 | l | 最低价格 | np.float64 |
| 4 | c | 收盘价格 | np.float64 |
| 5 | vol | 交易量（以张为单位） | np.float64 |
| 6 | volCcy | 交易量（以币为单位） | np.float64 |
| 7 | volCcyQuote | 交易量（以计价货币为单位） | np.float64 |
| 8 | confirm | K线状态（0未完结，1已完结） | np.float64 |
存储规则
历史K线数据按日期分片存储，每个CSV文件保存指定日期指定产品的全部K线数据：
- 时间跨度：00:00:00 ~ 24:00:00
- 时区默认使用'Asia/Shanghai'
- 不同时间粒度的数据终点不同（1m终点为23:59:00，1h终点为23:00:00）
产品类型支持
Okx_candle 支持以下产品类型：
| 产品类别 | 代号 |
|---|---|
| 现货交易 | SPOT |
| 永续合约 | SWAP |
| 交割合约 | FUTURES |
| 期权 | OPTION |
注：目前不支持现货杠杆（Margin）产品。
服务规则配置
CandleRule 类允许用户自定义服务运行规则，以适应不同的交易场景：
from okx_candle import CandleServer, CandleRule
# 自定义规则：调整K线时间粒度为5分钟
CandleRule.BAR = '5m'
candleServer = CandleServer('SPOT', CandleRule)关键配置参数
- SYMBOLS：产品名称过滤条件
- BAR：K线时间粒度设置
- TIMEZONE：时区设置
- DOWNLOAD_TIME：每日下载历史数据的时间
- LENGTH：实时K线数据保留长度
- UPDATE_INTERVAL_SECONDS：实时K线更新频率
👉 获取实时K线工具
实时K线维护
run_candle_map 方法
该方法以阻塞模式等待第一次candle_map更新完毕，随后以异步多线程方式实时更新数据：
from okx_candle import CandleServer
import time
candleServer = CandleServer('SWAP')
candleServer.run_candle_map()
while True:
for symbol in candleServer.candle_map.keys():
print(symbol, candleServer.get_candle_security(symbol, security_seconds=60))
time.sleep(1)数据安全获取
get_candle_security 方法验证K线数据的时效性，确保数据安全可靠：
# 安全获取实时K线数据，设置安全间隔为60秒
secure_data = candleServer.get_candle_security('BTC-USDT-SWAP', security_seconds=60)历史数据下载
按日期下载
download_candles_by_date 方法支持下载指定日期范围的历史数据：
from okx_candle import CandleServer, CandleRule
# 配置下载规则
CandleRule.BAR = '1m'
CandleRule.SYMBOLS = ['BTC-USDT', 'ETC-USDT']
CandleRule.TIMEZONE = 'Asia/Shanghai'
candleServer = CandleServer('SPOT', CandleRule)
# 下载2023年1月1日至10日的数据
candleServer.download_candles_by_date(
start='2023-01-01',
end='2023-01-10'
)每日定时下载
download_daily 方法提供每日自动下载昨日数据的服务：
from okx_candle import CandleServer
candleServer = CandleServer('SPOT')
# 启动每日下载服务
candleServer.download_daily()行情数据获取
行情信息查询
Okx_candle 提供多种行情信息获取方式：
from okx_candle import Market
from pprint import pprint
# 获取全部产品的行情列表
tickers = Market('SPOT').get_tickers()
pprint(tickers)
# 获取全部产品的行情字典
tickersMap = Market('SPOT').get_tickersMap()
pprint(tickersMap)
# 获取单个产品的行情信息
ticker = Market('SPOT').get_ticker('BTC-USDT')
pprint(ticker)深度信息查询
获取订单簿深度信息：
# 获取指定数量的交易深度
books = Market('SPOT').get_books(symbol='BTC-USDT', sz=10)
pprint(books)
# 获取产品轻量深度
books_lite = Market('SPOT').get_books_lite(symbol='BTC-USDT')
pprint(books_lite)高级数据管理
OkxLite 数据管理
OkxLite 基于candlelite的IO底层，提供更灵活的历史数据管理功能：
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'
)
print(candle)多产品数据读取
load_candle_map_by_date 方法支持读取多个产品的历史数据：
from okx_candle import OkxLite
okxLite = OkxLite()
# 读取永续合约多产品数据
candle_map = okxLite.load_candle_map_by_date(
instType='SWAP',
symbols=[],
start='2023-02-05',
end='2023-02-06'
)常见问题
安装与基础使用
Q1：Okx_candle 支持哪些Python版本？
A：Okx_candle 支持Python 3.6及以上版本，建议使用最新版本以获得最佳性能和稳定性。
Q2：是否需要OKX账户秘钥才能使用？
A：获取行情数据不需要秘钥，但某些高级功能可能需要配置API秘钥。
Q3：如何处理数据下载失败的情况？
A：首先检查网络连接，然后确认产品符号是否正确。如果问题持续，可以调整重试机制或联系技术支持。
数据管理与存储
Q4：历史数据存储在什么位置？
A：数据默认存储在CANDLELITE_DATA目录下，可按日期和产品类型组织。用户可以通过配置自定义存储路径。
Q5：如何共享多个项目的历史数据？
A：将CANDLE_BASE_DIR配置为绝对路径（如'/root/CANDLELITE_DATA'），这样不同项目可以访问同一数据源。
Q6：数据验证失败怎么办？
A：检查本地数据完整性，必要时重新下载。确保时间粒度和时区设置与数据采集时一致。
性能与优化
Q7：如何处理大量产品的数据维护？
A：通过SYMBOLS过滤机制只维护需要的产品，调整UPDATE_INTERVAL_SECONDS平衡实时性与资源消耗。
Q8：如何优化数据读取速度？
A：使用load_candle_map_by_date的多进程加速功能，适当设置p_num参数提高读取效率。
Q9：实时K线维护占用资源过多怎么办？
A：减少维护的产品数量，调整LENGTH参数降低内存使用，或增加UPDATE_INTERVAL_SECONDS减少更新频率。