Vibe-Trading OKX 现货K线数据接口实战指南从 OHLCV 拉取、解析到分页全流程【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading本文以 Vibe-Trading 仓库内置的 OKX 行情数据技能文档K线数据.md为核心系统讲解 OKX V5 REST API 的/api/v5/market/candles接口涵盖完整的输入/输出参数、二维数组的 9 字段解析规则、限频与翻页机制、可直接运行的 Python 拉取示例并对照仓库源码说明该接口在 Vibe-Trading 交易 Agent 中的实际落地方式。读完本文你将能够独立完成拉取任意 OKX 现货标的的 OHLCV 历史行情 → 转为结构化 DataFrame → 用于技术指标计算或策略回测的完整流程。接口定位OKX 行情技能中的核心数据源在 Vibe-Trading 的技能体系中OKX 行情能力由技能包okx-market提供。该技能的入口文档 SKILL.md 声明了其用途通过 OKX V5 REST API 获取现货、衍生品、指数等加密货币行情数据包括实时价格、K线、资金费率、持仓量等。所有行情类接口均为公开接口无需注册账号、无需 API Key 鉴权免费调用只需 Python 3.9 运行环境并安装requests与pandaspip install requests pandas在该技能维护的 13 个行情端点中K线接口/market/candles与 单个行情、批量行情 同属现货行情Spot Market分类是量化分析与策略研发最常使用的数据端点——因为技术指标计算、趋势判断、回测引擎的 bar 级数据几乎全部依赖它。输入参数详解/api/v5/market/candles的请求参数如下名称类型必选描述instIdstrY交易产品ID如BTC-USDTbarstrNK线周期默认1m。可选1m/3m/5m/15m/30m/1H/2H/4H/6H/12H/1D/1W/1MafterstrN请求此时间戳之前的数据毫秒用于翻页beforestrN请求此时间戳之后的数据毫秒limitstrN返回条数默认 100最大 300关键要点instId 格式规范现货标的为BTC-USDT、ETH-USDT这种币种-计价币种格式。若扩展到合约或指数格式不同如永续BTC-USDT-SWAP、指数BTC-USD详见 SKILL.md 的 Instrument Format Reference 一节。bar 周期枚举共 13 档从 1 分钟1m到 1 月1M。注意小时级别为大写H1H/2H/4H/6H/12H天/周/月为大写D/W/M大小写不能写错。单次返回上限默认返回最近 100 根limit最大只能取 300。最多返回 1440 条历史数据更早的数据必须通过after/before分页获取。翻页语义after传入某个毫秒时间戳时返回该时间戳之前更早的K线before则返回该时间戳之后更新的K线。两者配合limit即可逐页向前翻取全部历史。限频约束该接口限频为40 次/2s每秒 20 次批量拉取历史时需在请求间加入间隔或使用节流避免触发 OKX 的速率限制。输出参数二维数组的 9 字段解析接口返回的data字段是一个二维数组而非对象数组每条K线按固定索引顺序排列索引描述0开盘时间毫秒时间戳1开盘价Open2最高价High3最低价Low4收盘价Close5成交量币6成交额计价货币7成交额报价货币8K线状态0未完结1已完结理解这 9 个字段是正确解析数据的前提索引 0-4为标准的 OHLCV 前四要素时间、开、高、低、收。索引 5-7是三组量能数据成交量以基础币种计如 BTC 数量成交额计价货币与成交额报价货币分别以instId中的币种与计价币种计。对BTC-USDT而言两者数值通常相同都是 USDT 计价但若涉及非 USDT 计价对则需区分。索引 8的confirm状态字段非常实用0表示当前这根K线尚未收盘最后一根未完结K线1表示已完结。做回测或指标计算时应过滤掉confirm0的未完结K线避免未来函数/前视偏差。从源码结构可以印证这一点Vibe-Trading 的 OKX 连接器在 sdk.py 的_candle_to_dict中按位置索引解析该数组并特别注释了confirm字段永远是 OKX 7 字段与 9 字段K线形态的最后一个元素应从尾部读取而非固定索引——这正对应文档中索引 8 的约定也提示我们在写解析器时要对行长度做防御性处理。接口调用与 DataFrame 转换完整可运行示例文档给出了最直接的调用方式。使用 Python 的requests发起 GET 请求pandas完成结构化import requests import pandas as pd BASE_URL https://www.okx.com/api/v5 # 获取 BTC-USDT 日线最近30根 resp requests.get(f{BASE_URL}/market/candles, params{ instId: BTC-USDT, bar: 1D, limit: 30 }) candles resp.json()[data] # 转为 DataFrame columns [ts, open, high, low, close, vol, volCcy, volCcyQuote, confirm] df pd.DataFrame(candles, columnscolumns) df[ts] pd.to_datetime(df[ts].astype(int), unitms) for col in [open, high, low, close, vol]: df[col] df[col].astype(float) print(df[[ts, open, high, low, close, vol]].head()) # 获取 ETH-USDT 4小时K线 resp requests.get(f{BASE_URL}/market/candles, params{ instId: ETH-USDT, bar: 4H, limit: 50 })这段代码的操作要点列名对齐columns列表的 9 个名字与输出参数表的索引 0-8 一一对应这正是二维数组转 DataFrame 的关键。时间戳转换OKX 返回的毫秒时间戳需先astype(int)再通过unitms转为datetime否则 pandas 会将其当作纳秒导致时间错乱。数值化OKX 返回的所有价格与量能字段都是字符串必须astype(float)后才能参与数值计算。数据方向OKX 的 candles 接口默认按时间从新到旧返回。文档示例直接head()展示而仓库示例脚本 candle_data_example.py 中额外执行了df.sort_values(ts).reset_index(dropTrue)将数据升序排列便于后续按时间顺序计算技术指标。如果你发现指标计算方向反了多半是这个原因。响应结构数据样例逐字段解读接口的标准响应体如下code0表示成功数据在data字段{ code: 0, data: [ [1773763200000, 73915.5, 74800, 71966, 72144.3, 5129.27, 377618988.24, 377618988.24, 0], [1773676800000, 73269.1, 76011.8, 73158, 73917.4, 8631.72, 642101158.54, 642101158.54, 1], [1773590400000, 71478.1, 74500, 71300, 73269.1, 8461.09, 620450708.74, 620450708.74, 1] ] }逐行解读第一根[1773763200000, 73915.5, ..., 0]开盘时间1773763200000毫秒对应某日 00:00 UTC开73915.5、高74800、低71966、收72144.3成交 5129.27 BTC、成交额约 3.78 亿 USDTconfirm0 表示这是当前未完结的K线其价格会随行情继续变动。第二、三根confirm1代表已完结的历史K线是可用于回测的确定数据。顺带一提OKX 的错误响应同样是 JSON 结构code非0时msg字段携带错误原因。仓库的 candle_data_example.py 就做了data[code] ! 0的显式检查并打印data[msg]而连接器 sdk.py 的_business_error也会把code/msg拼装成错误信息——判断请求成败不要只看 HTTP 状态码务必检查业务层code字段。向前翻页拉取 1440 根以上的历史数据由于单次最多返回 1440 条、单页最大 300 条获取更长历史必须翻页。翻页的核心技巧是取当前返回中最早一根K线的开盘时间戳作为下一次请求的after参数循环直至取满所需条数import requests import pandas as pd import time BASE_URL https://www.okx.com/api/v5 columns [ts, open, high, low, close, vol, volCcy, volCcyQuote, confirm] def fetch_candles(inst_id: str, bar: str, total: int 1440) - pd.DataFrame: 分页拉取历史K线返回升序 DataFrame。 frames [] after # 首次请求不带 after取最新数据 page_size 300 # 每页最大 300 while len(frames) * page_size total: params {instId: inst_id, bar: bar, limit: str(page_size)} if after: params[after] after resp requests.get(f{BASE_URL}/market/candles, paramsparams).json() rows resp.get(data, []) if not rows: break # 已到历史尽头 frames.append(pd.DataFrame(rows, columnscolumns)) after rows[-1][0] # 最早一根的时间戳继续向前翻 time.sleep(0.1) # 40次/2s 限频下保持安全间隔 df pd.concat(frames, ignore_indexTrue) df[ts] pd.to_datetime(df[ts].astype(int64), unitms) for col in [open, high, low, close, vol]: df[col] df[col].astype(float) return df.sort_values(ts).reset_index(dropTrue) df fetch_candles(BTC-USDT, 1D, total1440) print(f共拉取 {len(df)} 根日K)注意三点after使用最早一根数组末尾因为默认新→旧返回的时间戳每页之间time.sleep(0.1)以适配 40 次/2s 的限频未完结的confirm0行在回测场景中应过滤。衍生端点指数K线对照K线能力在 OKX 技能中还有一对孪生端点——指数K线/api/v5/market/index-candles详见同目录的 指数K线.md。二者差异点维度现货K线/market/candles指数K线/market/index-candlesinstId交易产品BTC-USDT指数IDBTC-USD限频40次/2s20次/2slimit 上限300100输出字段9 字段含量额6 字段仅 OHLC confirm指数K线不含成交量与成交额仅返回ts/open/high/low/close/confirm六列用于分析基准价格走势。仓库示例脚本 candle_data_example.py 同时封装了get_candles与get_index_candles两个函数INDEX_CANDLE_COLUMNS即为 6 列版本可对照学习。在 Vibe-Trading 中的落地从脚本到交易连接器OKX K线数据在本仓库中有两个层面的落地可作为进阶参考1. 技能脚本层开箱即用仓库提供了完整的可执行示例 candle_data_example.py运行后依次输出 BTC-USDT 日线、ETH-USDT 4H 线、BTC-USD 指数日线三组数据python agent/src/skills/okx-market/scripts/candle_data_example.py该脚本包含完整的错误处理code ! 0时打印msg、时间戳转换、数值化与升序排序是比文档示例更工程化的参考实现。2. 交易连接器层量化生产路径在 Vibe-Trading 的交易层OKX 连接器 sdk.py 通过可选的python-okxSDK 封装了行情能力其中get_historical_barssdk.py直接对应本文的K线接口它内置了规范周期 token 到 OKXbar参数的映射表_BAR_MAPsdk.py例如1h→1H、1d→1D并做了大小写归一化——这说明OKX 的 bar 参数大小写敏感上层调用需先做格式映射响应中的 K线数组经_candle_to_dict转为字典confirm按尾部位置读取与文档索引 8 的约定一致连接器为只读层readonly: bool True行情查询无需任何密钥但若涉及账户/交易接口则需在~/.vibe-trading/okx.json配置api_key/api_secret/passphrase/profilepaper/live-readonly/live并配合check_status的header_flaguid_pin纸面交易守卫机制。常见问题与排查建议返回数据为什么比请求少OKX 最多只保留 1440 根K线历史超过部分必须翻页单页超 300 会被截断。价格字段参与计算报错所有数值字段是字符串先astype(float)。时间列看起来不对毫秒时间戳须用unitms转换且注意默认返回顺序是从新到旧。回测结果莫名包含未来数据检查是否过滤了confirm0的未完结K线。请求被限流遵守 40 次/2s指数K线为 20 次/2s翻页循环中加sleep或使用带退避的重试逻辑。小结/api/v5/market/candles是 Vibe-Trading OKX 行情技能中最重要的数据端点之一它免费、免鉴权13 档周期覆盖分钟级到月级9 字段二维数组完整描述了每根K线的 OHLC、三组量额与完结状态。掌握其参数语义、数组解析规则与after/before翻页机制即可为技术指标计算、策略回测与实时监控提供可靠的行情底座。需要继续深入时可研读 SKILL.md 了解其余 12 个端点或对照 sdk.py 查看生产级封装实现。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考