欧易API全攻略：交易、数据，只需这一篇就够了！

欧易API接口详解

本文档旨在提供对欧易（OKX）API接口的全面且深入的技术解析，针对数字资产交易开发者，详细涵盖包括现货、合约、期权等常用交易接口的核心功能，并结合真实交易场景和代码示例，帮助开发者快速上手，降低学习曲线，高效地利用欧易API进行自动化交易策略开发、量化投资研究、以及市场数据的实时获取和分析。我们将深入探讨认证机制、数据格式、请求方式、错误处理，以及高级功能如websocket实时订阅等，旨在提升开发者在欧易平台上构建高性能交易应用的能力。

API概览

欧易API提供一套全面的RESTful接口，旨在让用户能够通过编程方式无缝访问和管理其欧易账户，获取实时的市场数据，并执行各种交易操作。该API接口套件细致地划分为多个类别，以满足不同的用户需求，并提供精细化的权限控制：

• 公共接口 : 此类接口提供无需任何身份验证即可访问的公开数据，例如最新的市场行情数据（包括价格、成交量等）、所有可用的交易对信息（包括交易对的名称、交易规则等）、以及其他与市场相关的统计数据。这些接口是了解市场动态和构建数据驱动型应用程序的基础。
• 交易接口 : 交易接口允许用户通过程序化方式进行各种交易操作，包括创建和提交订单（限价单、市价单等）、撤销未成交的订单、以及查询订单的当前状态和历史记录。为了保障账户安全，使用交易接口必须进行严格的身份验证，通常涉及API密钥和签名机制。
• 账户接口 : 账户接口提供对用户账户相关信息的查询功能，例如账户当前的余额情况（包括可用余额和冻结余额）、历史交易记录的详细信息、以及其他与账户相关的设置和配置。同样，访问账户接口需要有效的身份验证。
• 资金接口 : 资金接口允许用户执行资金划转操作，例如在不同的账户之间转移资金（例如从交易账户转移到资金账户），以及进行充值和提现操作。由于涉及资金安全，资金接口需要最高级别的身份验证，并可能需要额外的安全措施，例如双重验证。
• 合约接口 : 此类接口专门为永续合约和交割合约的交易和数据查询而设计。用户可以通过合约接口进行合约交易、查询合约的市场深度、获取历史K线数据、以及管理其合约持仓。访问合约接口需要进行身份验证，并且可能需要开通相应的合约交易权限。
• 期权接口 : 期权接口为期权交易者提供了全面的工具，可以进行期权交易、查询期权的市场行情、获取期权链数据、以及管理其期权持仓。与合约接口类似，期权接口的使用也需要身份验证，并可能需要满足一定的期权交易资格要求。

认证

欧易API 使用 API Key 进行身份验证，这是访问平台各种功能和服务的基础。API Key 可以在欧易官方网站的 API 管理页面中方便地创建和集中管理。在创建 API Key 的过程中，必须仔细设置与该 Key 关联的相应权限，这些权限定义了允许该 Key 执行的操作范围。常见的权限包括但不限于读取账户信息（如余额、交易历史等）、进行现货和合约交易、访问行情数据等。选择合适的权限对于安全至关重要，避免授予不必要的权限可以降低潜在的安全风险。

当调用需要身份验证的 API 接口时，必须在 HTTP 请求头中包含特定的身份验证信息。这些信息使欧易服务器能够验证请求的来源和权限。所需的请求头包括：

• OK-ACCESS-KEY : 这是你在 API 管理页面创建的 API Key，用于标识你的身份。
• OK-ACCESS-SIGN : 这是使用你的 Secret Key 和请求数据生成的数字签名，用于验证请求的完整性和真实性。这是防止请求被篡改的关键安全措施。
• OK-ACCESS-TIMESTAMP : 这是请求发送时的时间戳，采用 UTC 时间标准，精确到秒。时间戳用于防止重放攻击，确保请求在有效期内。
• OK-ACCESS-PASSPHRASE : 这是你在创建 API Key 时设置的 Passphrase，类似于密码，进一步增强了 API Key 的安全性。

签名的生成过程是确保 API 请求安全的关键步骤。以下是详细的签名生成方法：

1. 构建签名字符串： 将请求的时间戳 (timestamp)、HTTP 方法 (method，例如 GET、POST、PUT、DELETE)、请求路径 (requestPath，不包含域名) 以及请求体 (body，如果存在) 按照特定的顺序拼接成一个字符串。这个字符串包含了请求的关键信息，用于生成签名。
2. HMAC SHA256 加密： 使用你的 Secret Key 对上述拼接的字符串进行 HMAC SHA256 加密。HMAC (Hash-based Message Authentication Code) 是一种消息认证码算法，它使用密钥来生成哈希值，从而验证数据的完整性和真实性。SHA256 是一种常用的哈希算法，提供较高的安全性。
3. Base64 编码： 将 HMAC SHA256 加密后的二进制结果进行 Base64 编码。Base64 是一种将二进制数据转换为 ASCII 字符串的编码方式，方便在 HTTP 请求头中传输。

各种编程语言都提供了用于实现 HMAC SHA256 加密和 Base64 编码的库或模块。例如，在 Python 中可以使用 hmac 和 base64 模块，在 JavaScript 中可以使用 crypto 模块。选择合适的库，并参考欧易的官方文档，可以确保正确地生成签名。

常用API接口详解

以下是一些常用的欧易API接口的详细说明，旨在帮助开发者更好地理解和使用这些接口进行交易、数据分析等操作：

现货交易API

• 获取交易对信息（GET /api/v5/public/instruments）： 此接口允许开发者查询所有或指定交易对的详细信息，包括交易对名称、最小交易数量、价格精度等，是进行交易策略开发的基础。详细参数包括币种、交易类型（现货、合约等）。
• 下单（POST /api/v5/trade/order）： 用于创建新的交易订单，包括市价单、限价单、止损单等多种类型。必须指定交易对、交易方向（买入或卖出）、订单类型、数量和价格（对于限价单）。高级选项包括指定只减仓（reduce-only）以平仓现有仓位。
• 取消订单（POST /api/v5/trade/cancel-order）： 允许开发者取消尚未成交的订单。需要提供交易对和订单ID。为避免竞态条件，建议在取消订单前再次确认订单状态。
• 获取订单详情（GET /api/v5/trade/order）： 查询指定订单的详细信息，包括订单状态、成交数量、平均成交价格等。需要提供交易对和订单ID。
• 获取历史订单（GET /api/v5/trade/orders-history）： 查询历史交易订单，支持分页和时间范围过滤。可以根据订单状态、时间范围等条件筛选历史订单。

账户API

• 获取账户余额（GET /api/v5/account/balance）： 查询账户中各种币种的可用余额、冻结余额等信息。可以指定查询特定币种的余额。
• 获取账户账单明细（GET /api/v5/account/bills）： 查询账户的资金变动记录，包括充值、提现、交易等。支持分页和时间范围过滤。

市场数据API

• 获取K线数据（GET /api/v5/market/candles）： 获取指定交易对的历史K线数据，包括开盘价、最高价、最低价、收盘价和成交量。可以指定K线周期（如1分钟、5分钟、1小时等）。
• 获取最新成交价（GET /api/v5/market/ticker）： 获取指定交易对的最新成交价、24小时涨跌幅、24小时成交量等信息。
• 获取深度数据（GET /api/v5/market/depth）： 获取指定交易对的买卖盘口深度数据，用于了解市场买卖力量分布。

合约交易API (如果适用)

• 获取合约信息（GET /api/v5/public/instruments）： (类似于现货) 用于查询合约交易对的详细信息，包括合约类型、合约乘数等。
• 合约下单（POST /api/v5/trade/order）： 与现货类似，但用于合约交易。需要指定杠杆倍数、保证金模式等参数。
• 获取持仓信息（GET /api/v5/account/positions）： 查询当前合约持仓信息，包括持仓数量、平均持仓价格、未实现盈亏等。

注意事项： 使用API接口需要进行身份验证，通常需要提供API Key和Secret Key。务必妥善保管API Key和Secret Key，避免泄露。 注意API接口的频率限制，避免频繁调用导致IP被封禁。 在进行交易操作前，务必进行充分的测试，确保交易策略的正确性。 详细的API文档请参考欧易官方网站。

1. 获取市场行情数据 (公共接口)

• 接口地址 : /api/v5/market/tickers
• 请求方法 : GET
• 功能描述 : 此接口用于获取指定交易对的实时行情数据，无需身份验证即可访问。用户可以通过该接口获取最新的市场动态，包括价格、成交量和价格变动等关键指标。
• 参数 :
  • instId : 交易对ID，用于指定要查询的交易对。例如， BTC-USDT 代表比特币与 USDT 的交易对， ETH-BTC 代表以太坊与比特币的交易对。必须提供有效的交易对 ID，否则接口将返回错误。请参考交易所提供的交易对列表获取准确的 instId 。
• 返回值 : 接口返回一个 JSON 格式的数据结构，包含交易对的最新价格（通常称为“last”或类似字段）、24 小时成交量（通常称为“vol24h”或类似字段）、24 小时涨跌幅（通常称为“change24h”或类似字段）、最高价（通常称为“high24h”或类似字段）、最低价（通常称为“low24h”或类似字段）等信息。返回值的具体字段名称和数据类型取决于交易所的具体 API 文档。请务必查阅官方 API 文档以获取详细的字段解释。
• 注意事项 :
  • 频率限制：为防止滥用，交易所通常会对公共接口设置频率限制。超出限制的请求可能会被拒绝。请合理控制请求频率。
  • 数据延迟：虽然数据是实时更新的，但可能存在轻微的延迟。对于需要高精度数据的应用，请考虑使用更高级的接口或订阅实时数据流。
  • 错误处理：请务必处理接口返回的错误信息。常见的错误包括无效的 instId 、超出频率限制和服务器错误。

GET /api/v5/market/tickers?instId=BTC-USDT

{ "code": "0", "msg": "", "data": [ { "instId": "BTC-USDT", "last": "27000", "open24h": "26500", "high24h": "27500", "low24h": "26000", "vol24h": "1000", "volCcy24h": "27000000", "ts": "1678886400000" } ] }

2. 下单 (交易接口)

• 接口地址 : /api/v5/trade/order
• 请求方法 : POST
• 参数 :

• instId (交易对ID): 指定进行交易的加密货币交易对。 例如： BTC-USDT (比特币兑USDT)。 该参数是所有交易请求的必要组成部分，用于明确指示交易发生的市场。
• tdMode (交易模式): 定义交易的保证金模式。可选值包括：
  • cash (现货): 使用账户中的可用余额进行交易，不涉及杠杆。
  • cross (全仓): 账户中所有可用资金均可用作保证金，风险较高，收益也可能较高。
  • isolated (逐仓): 为单个交易对分配特定数量的保证金，风险限定于该保证金数额。
  选择适当的交易模式取决于风险承受能力和交易策略。
• side (交易方向): 指定交易的意图。 buy (买入) 表示希望购买指定数量的加密货币； sell (卖出) 表示希望出售指定数量的加密货币。
• ordType (订单类型): 定义订单的执行方式。
  • market (市价单): 以当前市场最优价格立即执行订单。 市价单保证成交，但不保证成交价格。
  • limit (限价单): 只有当市场价格达到或超过指定价格时，订单才会执行。 限价单允许控制成交价格，但不能保证一定成交。
• sz (数量): 指定要购买或出售的加密货币数量。 数量必须是正数，并且符合交易所对交易对的最小交易数量要求。
• px (价格): 指定限价单的价格。 只有在订单类型为 limit (限价单) 时才需要提供此参数。 价格应以交易对的报价货币表示 (例如，对于 BTC-USDT，价格应以 USDT 表示)。

POST /api/v5/trade/order { "instId": "BTC-USDT", "tdMode": "cash", "side": "buy", "ordType": "limit", "sz": "0.01", "px": "26000" }

{ "code": "0", "msg": "", "data": [ { "ordId": "1234567890", "clOrdId": "", "tag": "", "sCode": "0", "sMsg": "" } ] }

3. 撤单 (交易接口)

• 接口地址 : /api/v5/trade/cancel-order
• 请求方法 : POST
• 描述 : 用于取消尚未完全成交的订单。通过此接口，用户可以撤销挂单，释放冻结的资金或加密货币。请注意，订单的撤销可能并非总是立即成功，例如当订单正在被撮合时。
• 请求参数 :
  • instId : 交易对ID，指定要撤销订单的交易市场。例如 BTC-USDT 表示比特币兑美元泰达币的交易对。请确保提供的交易对ID与要撤销的订单相匹配。
  • ordId : 订单ID，要撤销的具体订单的唯一标识符。这个ID是在创建订单时由交易所返回的。请务必提供正确的订单ID，否则撤单操作将会失败。
  • 可选参数 ：部分交易所可能支持通过客户端订单ID ( clOrdId ) 进行撤单。
• 请求示例 :

  
  {
    "instId": "BTC-USDT",
    "ordId": "1234567890"
  }
  

• 返回值 : 返回一个JSON对象，包含撤单操作的状态和相关信息。
  • code : 状态码，表示撤单操作的结果。例如， 0 表示成功，其他值可能表示失败。
  • msg : 状态信息，提供关于撤单结果的详细描述。
  • data : 一个数组，包含撤单订单的相关数据。
    • ordId : 被撤销的订单ID。
    • state : 订单状态，通常会显示为"canceled"或类似的状态。
• 返回值示例 :

  
  {
    "code": "0",
    "msg": "",
    "data": [
      {
        "ordId": "1234567890",
        "state": "canceled"
      }
    ]
  }
  

• 注意事项 :
  • 频繁的撤单操作可能会影响交易速度和效率。
  • 务必处理撤单失败的情况，例如网络问题或订单已被完全成交。
  • 部分交易所对于撤单操作可能存在频率限制。

POST /api/v5/trade/cancel-order { "instId": "BTC-USDT", "ordId": "1234567890" }

{ "code": "0", "msg": "", "data": [ { "ordId": "1234567890", "sCode": "0", "sMsg": "" } ] }

4. 查询订单详情 (交易接口)

• 接口地址 : /api/v5/trade/order
• 请求方法 : GET
• 参数 :
  • instId : 交易对ID，用于指定需要查询的交易对。例如， BTC-USDT 表示比特币与USDT的交易对。该参数为必填项，用于确定订单所属的交易市场。
  • ordId : 订单ID，是唯一标识符，用于精确定位需要查询的订单。该ID由交易平台在订单创建时生成，是查询订单详情的关键参数。请确保提供正确的订单ID。
• 返回值 :

  返回JSON格式的数据，包含订单的详细信息。具体字段包括：

  • 订单状态 ( state ): 例如， live (未成交), partially_filled (部分成交), filled (完全成交), canceled (已撤销)。
  • 成交数量 ( filledSz ): 已经成交的合约数量或币的数量。
  • 订单价格 ( px ): 订单的委托价格。
  • 订单类型 ( ordType ): 例如， market (市价单), limit (限价单), post_only (只挂单)。
  • 订单方向 ( side ): buy (买入) 或 sell (卖出)。
  • 创建时间 ( cTime ): 订单创建的时间戳。
  • 更新时间 ( uTime ): 订单最后更新的时间戳。
  • 手续费 ( fee ): 交易产生的手续费。
  • 手续费币种 ( feeCcy ): 支付手续费的币种。
  • 平均成交价格 ( avgPx ): 订单的平均成交价格。

  通过查询订单详情接口，可以全面了解订单的执行情况，包括成交数量、订单状态、手续费等关键信息。 请注意，不同的交易平台可能返回的字段略有差异，请参考具体的API文档。

GET /api/v5/trade/order?instId=BTC-USDT&ordId=1234567890

{ "code": "0", "msg": "", "data": [ { "instId": "BTC-USDT", "ordId": "1234567890", "clOrdId": "", "tag": "", "px": "26000", "sz": "0.01", "ordType": "limit", "side": "buy", "tdMode": "cash", "state": "filled", "avgPx": "26000", "fillSz": "0.01", "feeCcy": "USDT", "fee": "0.000026", "ts": "1678886400000" } ] }

5. 获取账户余额 (账户接口)

• 接口地址 : /api/v5/account/balance
• 请求方法 : GET
• 功能描述 : 此接口用于查询用户账户的资金余额情况。通过指定币种，可以查询特定币种的余额；不指定币种，则返回所有币种的余额信息。
• 请求参数 :
  • ccy : 币种代码。例如， BTC 代表比特币， USDT 代表泰达币。这是一个可选参数。如果不提供此参数，API 将返回用户账户中所有币种的余额信息。如果提供了此参数，API 将仅返回指定币种的余额信息。
• 返回值 :

  API 返回一个 JSON 对象，其中包含账户的可用余额、冻结余额等详细信息。

  • 可用余额 : 指的是账户中可以立即用于交易或提现的资金数量。
  • 冻结余额 : 指的是由于挂单、锁仓或其他原因而暂时无法使用的资金数量。
  • 其他信息 : 返回值可能还包含账户的总资产、风险率等其他相关信息，具体取决于交易所的实现。
• 示例 :
  • 请求所有币种余额: GET /api/v5/account/balance
  • 请求 BTC 余额: GET /api/v5/account/balance?ccy=BTC
• 注意事项 :
  • 在调用此接口之前，请确保已进行身份验证。
  • 请仔细阅读 API 文档，了解返回值的具体结构和含义。
  • 频繁调用此接口可能会触发频率限制，请合理控制调用频率。

GET /api/v5/account/balance?ccy=USDT

{ "code": "0", "msg": "", "data": [ { "ccy": "USDT", "bal": "1000", "frozenBal": "100", "availBal": "900", "availEq": "900" } ] }

错误处理

欧易API采用标准的HTTP状态码与JSON格式的错误码相结合的方式，为开发者提供详尽的错误反馈信息。通过状态码，开发者可以快速了解请求的大致状态，而JSON错误码则提供了更细粒度的错误原因分析。常见的HTTP状态码及其对应含义包括：

• 400 Bad Request : 该状态码表明请求参数存在错误。具体表现为参数缺失、参数格式不正确、参数值超出有效范围等。开发者应仔细检查请求体、URL参数以及Headers，确保所有参数符合API文档的要求。
• 401 Unauthorized : 此状态码表示客户端尝试访问受保护的资源，但未提供有效的身份验证凭据，或提供的凭据无效。通常，这意味着API密钥不正确、签名验证失败，或者API密钥未被授权访问该资源。请确认API密钥已正确配置，并且签名算法与欧易的要求一致。检查API密钥是否已过期或被禁用。
• 429 Too Many Requests : 当客户端在短时间内发送过多请求时，服务器会返回此状态码，表示请求频率超过了设定的限制。为了避免触发此错误，开发者应实施速率限制策略，例如使用令牌桶算法或漏桶算法来平滑请求流量。 可以通过阅读欧易官方API文档，了解具体的速率限制规则和推荐的请求频率。
• 500 Internal Server Error : 此状态码指示服务器在处理请求时遇到了意外错误。这通常是服务器端的问题，与客户端的请求无关。如果频繁出现此错误，应及时联系欧易官方技术支持团队，并提供相关的请求信息（例如请求时间、请求URL、请求参数等），以便他们进行问题排查和修复。

开发者在集成欧易API时，必须建立完善的错误处理机制。根据不同的HTTP状态码和JSON错误码，采取相应的应对措施。例如，当遇到 400 错误时，应仔细检查并修正请求参数；当遇到 401 错误时，应重新生成签名或检查API密钥的有效性；当遇到 429 错误时，应降低请求频率或实现重试机制；当遇到 500 错误时，应记录错误日志并联系欧易技术支持。详细的错误码列表及其含义，以及推荐的错误处理策略，请务必参考欧易官方API文档，并定期更新，以便及时应对API的变更。

实战案例

以下是一个使用Python语言调用欧易（OKX）API获取BTC-USDT永续合约市场实时行情数据的示例。我们将通过简单的HTTP请求，获取包括最新成交价、最高价、最低价等关键的市场信息。

import requests
import

url = "https://www.okx.com/api/v5/market/tickers"
params = {"instId": "BTC-USDT-SWAP"} # 使用SWAP代表永续合约
# 还可以添加更多参数，例如sz（交易量）, last（最新成交价）, askPx（卖一价）, bidPx（买一价）

response = requests.get(url, params=params)

if response.status_code == 200:
data = .loads(response.text)
if data['code'] == '0': # 检查API返回的code是否为成功
print(.dumps(data, indent=4)) # 格式化输出JSON数据，方便查看
else:
print(f"API Error: {data['code']} - {data['msg']}") # 打印API返回的错误信息
else:
print(f"HTTP Error: {response.status_code} - {response.text}") # 打印HTTP错误信息

此代码演示了如何使用Python的 requests 库向欧易API发送GET请求，并使用 库解析返回的JSON数据。 instId 参数指定了交易对，这里我们使用了 BTC-USDT-SWAP 代表BTC-USDT永续合约。需要注意的是，对于需要身份验证的私有接口（例如下单、查询账户余额等），需要添加对应的header并进行签名计算。 签名过程通常涉及使用API Key、Secret Key和请求参数，通过特定的哈希算法（如HMAC SHA256）生成签名，并将其添加到请求头中。 欧易API文档详细描述了签名过程和所需的参数。 为了程序的健壮性，应该添加错误处理机制，例如重试机制和异常捕获，以应对网络波动或API故障。

安全性考虑

在使用欧易API进行交易和数据访问时，安全性是至关重要的，必须采取严密的措施来防止API Key泄露和其他潜在的安全风险。API Key一旦泄露，可能导致资金损失、数据泄露或其他不可预测的后果。以下是一些强化安全性的具体建议：

• 避免硬编码API Key： 绝对不要将API Key直接嵌入到源代码中。这会将您的密钥暴露给任何能够访问代码的人，包括恶意攻击者。代码仓库、公共论坛或本地文件中都不应存在明文的API Key。
• 利用环境变量和配置文件： 将API Key存储在环境变量或加密的配置文件中。环境变量只在运行时加载，不会直接暴露在代码中。对于配置文件，务必使用加密技术，例如使用密钥管理系统（KMS）进行加密存储，并设置适当的访问权限。
• 定期轮换API Key： 定期更换您的API Key，即使没有发生任何安全事件。这是一种预防措施，可以降低长期密钥泄露的风险。轮换周期可以根据安全需求和风险承受能力来确定，建议至少每季度或半年进行一次。
• 最小权限原则： 为API Key分配最小权限。只授予API Key执行其所需操作的权限。例如，如果API Key仅用于获取市场数据，则不要授予其交易或提款的权限。欧易API通常允许您自定义API Key的权限范围，务必仔细配置。
• 监控API使用情况： 实施API使用监控机制，以便及时检测异常活动。监控内容包括API请求频率、请求来源IP地址、请求的API端点等。设置警报阈值，当检测到异常活动时立即发出警报，以便快速响应潜在的安全威胁。
• IP白名单限制： 使用IP白名单来限制API访问来源。只允许特定的IP地址或IP地址范围访问API。这可以防止未经授权的访问，并降低API Key泄露带来的风险。在欧易API管理界面中，您可以配置IP白名单。
• 双因素认证（2FA）： 虽然双因素认证主要用于用户账户登录，但如果欧易平台允许，启用与API Key相关的账户的双因素认证也能增加一层额外的安全保障，防止账户被盗用后API Key被滥用。
• 使用HTTPS协议： 始终使用HTTPS协议来与欧易API进行通信。HTTPS协议对数据进行加密，防止数据在传输过程中被窃取。确保您的代码和客户端配置正确地使用了HTTPS。
• 代码审查： 定期进行代码审查，以查找潜在的安全漏洞。让其他开发人员检查您的代码，可以帮助您发现自己可能忽略的安全问题。
• 安全审计： 定期进行安全审计，以评估您的API安全措施的有效性。安全审计可以帮助您识别安全漏洞和风险，并制定相应的改进计划。