OKX V5 合约限价接口实战：用 price-limit 获取最高买入价与最低卖出价

• 金融科技
• 示例工程

导读

本篇文章围绕 OKX V5 REST API 的公开行情接口/api/v5/public/price-limit（合约限价），完整讲解其请求参数、响应字段、Python 调用示例，以及它在 ai_quant_trade 仓库的okx-marketSkill 包中的定位与实战用法。读完本文后，你将能够在自己的量化策略中拉取任一合约（永续、交割、期权）的当前买卖限价，把"超出限价范围的订单会被交易所拒绝"这一风控约束接入下单前的价格校验流程，并与其他合约行情接口（标记价格、持仓量、资金费率）组合成一套完整的衍生品行情数据采集方案。

一、接口是什么：为什么订单会被"限价"

在衍生品交易中，交易所为了防止市场剧烈波动时出现极端成交价，会为每个合约动态维护一对限价：

• 买入限价（buyLmt）：当前允许的最高买入价；
• 卖出限价（sellLmt）：当前允许的最低卖出价。

/api/v5/public/price-limit就是用来查询这两个限价的公开接口。根据本仓库 限价接口文档 的说明，超出限价范围的订单会被交易所直接拒绝。这意味着，即使你的策略算出目标成交价，若该价格落在限价区间之外，订单也无法进入撮合队列。

接口基本信息

按照仓库中 okx-market/SKILL.md 的说明，OKX 的全部行情类端点均免费公开、无需鉴权，这正是本 Skill 包将其归类为data-source的原因。

二、输入参数

该接口只有 1 个必选参数：

这里的instId遵循 OKX 的命名规范（详见 SKILL.md 参数格式参考）：

• 永续合约（SWAP）：BTC-USDT-SWAP、ETH-USDT-SWAP；
• 交割合约（FUTURES）：BTC-USDT-250328（到期日格式为YYMMDD）；
• 期权（OPTION）：BTC-USD-250328-95000-C（到期日-行权价-方向 C/P）。

三、输出参数

接口响应遵循 OKX V5 的统一格式：code=0表示成功，数据位于data字段。data数组中每个元素包含以下字段：

注意价格与时间戳均为字符串类型，实际计算时需要先转换为float/int——这一点与仓库中 market_data_example.py 对last、vol24h等字段做float(...)强转的处理方式一致。

四、最小可运行示例

原文档给出的核心示例代码如下：

import requests BASE_URL = "https://www.okx.com/api/v5" resp = requests.get(f"{BASE_URL}/public/price-limit", params={"instId": "BTC-USDT-SWAP"}) data = resp.json()["data"][0] print(f"买入上限: {data['buyLmt']}") print(f"卖出下限: {data['sellLmt']}")

运行前确保环境已安装requests：

pip install requests pandas

升级为带错误处理的健壮版本

参考仓库 market_data_example.py 中的get_ticker函数写法（先检查data["code"] != "0"，再读取数据，异常统一捕获返回None），可以将限价查询封装成可复用的函数：

import requests from typing import Optional BASE_URL = "https://www.okx.com/api/v5" def get_price_limit(inst_id: str) -> Optional[dict]: """获取合约当前买卖限价。 Args: inst_id: 合约ID，如 BTC-USDT-SWAP。 Returns: 包含 buyLmt/sellLmt 的字典，失败返回 None。 """ try: resp = requests.get(f"{BASE_URL}/public/price-limit", params={"instId": inst_id}) data = resp.json() if data["code"] != "0": print(f"API错误: {data['msg']}") return None return data["data"][0] except Exception as e: print(f"获取限价失败: {e}") return None if __name__ == "__main__": info = get_price_limit("BTC-USDT-SWAP") if info: buy_lmt = float(info["buyLmt"]) sell_lmt = float(info["sellLmt"]) print(f"买入上限: {buy_lmt}") print(f"卖出下限: {sell_lmt}")

五、实战场景：把限价接入下单前校验

限价接口在量化交易链路中最典型的用途是下单前的价格合法性校验。一个常见的组合流程是：

1. 策略根据信号计算目标买入价target_buy；
2. 调用price-limit获取当前buyLmt；
3. 若target_buy > buyLmt，则拒绝下单或把委托价收敛到buyLmt以内，避免订单被交易所拒绝造成"假成交"错觉。

target_buy = 105000.0 # 策略目标价 info = get_price_limit("BTC-USDT-SWAP") buy_lmt = float(info["buyLmt"]) if target_buy > buy_lmt: print(f"目标价 {target_buy} 超过买入上限 {buy_lmt}，订单将被拒绝，需调整委托价") else: print("价格在限价区间内，可以下单")

这一做法与仓库中 execution-model/SKILL.md 讨论的订单执行模型（尤其涉及"限价系统"对价格约束的影响）在思路上是呼应的：限价是交易所层面强制执行的硬约束，策略层必须感知并顺应它。

与标记价格组合：区分"限价"与"标记价格"

限价（price-limit）与标记价格（mark price）是两个容易混淆的概念：

• 限价约束的是"订单能被接受的价格范围"，属于下单环节的硬边界；
• 标记价格用于计算未实现盈亏和强制平仓，比最新成交价更稳定，属于持仓估值与风控环节。

两个接口都位于/api/v5/public/路径下、限频同为 20 次/2s，且都接受instType（SWAP/FUTURES/OPTION）参数。实际开发中，建议把二者与持仓量接口、资金费率接口一起封装进同一套行情采集模块，统一处理响应解析、类型转换与异常捕获。

六、限频与批量查询注意事项

• 该接口限频为20 次 / 2s，即约 10 QPS。若需要同时校验多个合约，建议串行请求并控制频率，或只对即将下单的那一个合约发起查询，避免触发接口限流。
• 与/api/v5/public/mark-price（可按instType一次拉取全部永续合约的标记价格）不同，price-limit的入参只有instId，不支持按产品类型批量获取全部限价，因此"全市场限价快照"需要通过多次请求拼装。
• 响应中的ts为毫秒级时间戳，可用于判断限价数据的时效性；策略做价格校验时应尽量使用最新一次查询结果，过期的限价没有参考意义。

七、在 okx-market Skill 包中的定位

在 okx-market/SKILL.md 的 13 个行情端点清单中，price-limit是第 11 个，归类于Derivatives Market（衍生品行情），与资金费率、历史资金费率、标记价格、持仓量并列。整个 Skill 包覆盖现货、衍生品、指数三大类行情，配合 market_data_example.py 和 candle_data_example.py 两个示例脚本，可以快速搭建起面向 OKX 市场的行情数据采集与限价风控能力。该 Skill 包位于 ai_quant_trade 仓库的a_全网优秀资源/10_大模型/07_skill包/vibe_trading_skills/目录下，与execution-model、crypto-derivatives等 Skill 共同构成面向加密货币交易场景的技能集合。

小结

• 接口路径：GET /api/v5/public/price-limit，公开、免鉴权，限频 20 次/2s；
• 核心参数：仅instId（必选），如BTC-USDT-SWAP；
• 关键输出：buyLmt（最高可买价）、sellLmt（最低可卖价）、ts（毫秒时间戳）；
• 核心用途：下单前价格合法性校验，避免委托价超出限价区间被交易所拒绝；
• 易错点：价格字段为字符串需强转、单合约查询不支持批量、注意限频控制。

• 金融科技
• 示例工程