OKX API怎么用？新手快速入门教程（2024最新版）

OKX API 接口详解

简介

OKX API 是一套功能强大的接口，专为开发者设计，旨在提供与 OKX 数字资产交易所进行程序化交互的全面解决方案。通过这一 API，开发者能够安全、高效地访问实时市场数据，例如最新的交易价格、交易量、订单簿深度等，从而为算法交易、市场分析和数据驱动型决策提供支持。

除了市场数据访问，OKX API 还允许开发者执行各种交易操作，包括创建、修改和取消订单。开发者可以利用 API 实现不同类型的订单，如限价单、市价单和止损单，以适应不同的交易策略和风险管理需求。更重要的是，API 提供了账户管理功能，使开发者能够查询账户余额、交易历史以及其他关键账户信息，从而实现对交易活动的全面监控。

更进一步地，OKX API 不仅限于基本的交易和账户管理功能，还涵盖了更广泛的加密货币交易相关任务。例如，开发者可以使用 API 进行资金划转，在不同账户之间转移数字资产。API 还支持衍生品交易，包括永续合约、交割合约和期权等，为高级交易者和机构投资者提供了丰富的交易选择。 通过深入理解并熟练运用 OKX API 的各项功能，开发者可以构建定制化的交易策略、自动化交易机器人以及创新的金融应用程序，从而在快速发展的数字资产市场中获得竞争优势。

API 认证

在使用 OKX API 之前，必须进行身份认证才能访问受保护的资源。身份认证的核心在于生成和使用 API 密钥，它由 API Key 和 Secret Key 组成。每个 API 请求都需要包含签名信息，用于验证请求的合法性和完整性。

• 获取 API 密钥： 开发者需要在 OKX 账户中创建和管理 API 密钥。在账户后台，可以创建多个 API 密钥，并为每个密钥分配不同的权限。这些权限可以细化到只读访问（获取市场数据）、交易权限（下单、取消订单）、提币权限等，从而实现精细化的权限控制。务必妥善保管 Secret Key，避免泄露，因为它用于生成签名，拥有 Secret Key 相当于拥有了对应 API 密钥的全部权限。
• 签名： 为了确保 API 请求的安全性，防止数据篡改和重放攻击，每个 API 请求都需要使用 Secret Key 进行签名。签名过程涉及将请求的关键信息，例如时间戳、请求方法（GET、POST、PUT、DELETE）、API 请求路径和请求体（JSON 字符串）组合在一起，形成一个待签名字符串。该字符串然后使用 HMAC-SHA256 算法进行加密，Secret Key 作为密钥。生成的签名被添加到请求头中，OKX 服务器接收到请求后，会使用相同的算法和 Secret Key 重新计算签名，并与请求头中的签名进行比较，以验证请求的真实性和完整性。时间戳的引入可以防止重放攻击，允许服务器拒绝过期请求。

以下是一个 Python 示例，展示如何生成 OKX API 请求签名：

import hmac import hashlib import time import base64

def generate_signature(timestamp, method, request_path, body, secret_key): """ 生成 OKX API 请求签名.

Args:
        timestamp: 当前时间戳 (秒).  通常使用 int(time.time()) 获取.
        method: 请求方法 (GET, POST, PUT, DELETE). 必须大写.
        request_path: API 请求路径 (例如, '/api/v5/account/balance'). 注意包含版本号.
        body: 请求体 (JSON 字符串). 如果是 GET 请求，body 通常为空字符串 "".
        secret_key: OKX Secret Key. 从 OKX 账户后台获取.

Returns:
        签名字符串. 用于添加到请求头中.
"""
message = str(timestamp) + str.upper(method) + request_path + body
hmac_key = secret_key.encode('utf-8')
message = message.encode('utf-8')
signature = hmac.new(hmac_key, message, hashlib.sha256).digest()
signature_b64 = base64.b64encode(signature).decode('utf-8')
return signature_b64

常用 API 接口

OKX API 提供了全面的交易功能，涵盖现货、合约、期权等交易类型。以下列举了一些常用的 API 接口，并详细说明其功能和使用方法：

• 获取账户余额： GET /api/v5/account/balance

  此接口用于查询用户的账户资产信息。开发者通过指定 ccy 参数，可以获取特定币种的余额详情。返回数据包含总余额 ( totalEq )、可用余额 ( availableBal ) 和冻结余额 ( frozenBal )。还可以通过 GET /api/v5/account/positions 获取仓位信息，了解持仓情况。

• 获取市场行情： GET /api/v5/market/tickers

  通过此接口，可以实时获取指定交易对（ instId ）的市场行情数据。返回数据包含最新成交价 ( last )、24 小时最高价 ( high24h )、24 小时最低价 ( low24h )、24 小时成交量 ( vol24h ) 和最新成交量 ( volCcy24h )等关键信息。开发者可以利用这些数据构建量化交易模型、进行风险评估以及捕捉市场机会。还可以使用 GET /api/v5/market/candles 获取K线数据。

• 下单： POST /api/v5/trade/order

  此接口用于提交交易订单。通过指定交易对 ( instId )、交易方向 ( side - 买入 buy 或卖出 sell )、订单类型 ( ordType - 限价单 limit 、市价单 market 、止盈止损单 stop_limit 等)、订单数量 ( sz ) 和价格 ( px ，仅限价单需要) 等参数，可以实现多种交易策略。高级选项包括指定交易模式 ( tdMode - 现货 cash 、杠杆 margin 、模拟盘 simulated ) 和保证金币种 ( mgnCcy )。订单提交成功后，会返回订单 ID ( orderId )。

• 撤单： POST /api/v5/trade/cancel-order

  此接口用于撤销尚未完全成交的订单。开发者需要提供要撤销订单的订单 ID ( orderId ) 和交易对 ( instId )。成功撤单后，冻结的资金或资产将被释放。 还提供了批量撤单的接口 POST /api/v5/trade/cancel-batch-orders ， 允许一次撤销多个订单。

• 获取订单历史： GET /api/v5/trade/orders-history

  此接口用于查询用户的历史订单记录。可以根据时间范围 ( begin 和 end ，Unix 时间戳)，交易对 ( instId ) 和订单状态 ( state - live , canceled , filled , partially_filled ) 进行筛选。返回数据包含订单的详细信息，包括订单类型、价格、数量、成交量等。可以使用分页参数 limit 和 after 进行分页查询。

• 获取成交明细： GET /api/v5/trade/fills

  此接口用于查询用户的成交记录。 开发者可以根据时间范围 ( begin 和 end ，Unix 时间戳)，交易对 ( instId ) 和订单 ID ( orderId ) 进行筛选。返回数据包含成交价格、成交数量、手续费等详细信息。成交明细对于交易分析和税务计算非常重要。同样可以使用分页参数 limit 和 after 进行分页查询。

订单类型

OKX API 提供丰富的订单类型，旨在满足交易者多样化的交易策略和风险管理需求。理解并合理运用这些订单类型，对于提升交易效率、控制交易风险至关重要。

• 限价单 (Limit Order)： 允许交易者指定期望的买入或卖出价格及数量。 只有当市场价格达到或优于设定的限价时，订单才会被执行。 限价单的优势在于能够以理想的价格成交，但缺点是可能无法立即成交，需要等待市场价格到达指定水平。
• 市价单 (Market Order)： 以当前市场上最优的价格立即执行买入或卖出操作。 市价单保证订单的快速成交，适用于需要立即进入或退出市场的场景。 然而，由于市场价格的波动性，市价单的最终成交价格可能与下单时的预期价格略有偏差，尤其是在市场波动剧烈时。
• 止损单 (Stop Order)： 是一种条件订单，当市场价格触及预先设定的止损价格时，订单会被触发，并通常以市价单的形式提交到市场进行执行。 止损单的主要目的是限制潜在的损失，当市场走势不利时，止损单可以帮助交易者及时止损离场，避免更大的损失。
• 跟踪委托单 (Trailing Stop Order)： 是一种动态调整止损价格的订单类型。 止损价格会随着市场价格的有利变动而自动调整，始终保持一个预设的回调比例或固定价差。 跟踪委托单特别适用于在趋势行情中锁定利润，它可以在市场价格上涨时跟随上涨，并在价格回调时触发止损，从而保留一部分利润。
• 冰山委托 (Iceberg Order)： 是一种将大额订单拆分成多个较小订单的策略性订单。 冰山订单会将部分订单显示在订单簿上，而剩余的订单则隐藏起来，当显示的订单成交后，系统会自动补充新的小额订单，直到整个大额订单完全成交。 冰山委托的主要目的是减少大额订单对市场价格的冲击，避免引起市场的剧烈波动。
• 时间加权平均价格委托 (TWAP Order)： 将一个较大的订单在一段时间内均匀地拆分成多个小订单并执行。 系统会根据设定的时间间隔和订单总量，自动计算出每个小订单的交易量，并在指定的时间段内逐步执行。 TWAP 订单旨在降低交易对市场的影响，减少因一次性大额交易而导致的价格波动，适用于需要执行大额交易且不希望对市场造成明显冲击的场景。

错误处理

在使用 OKX API 时，开发者可能会遇到各种类型的错误。为了帮助开发者调试和诊断问题，OKX API 使用标准的 HTTP 状态码以及自定义的错误代码来指示错误类型。正确理解和处理这些错误信息对于构建稳定可靠的应用程序至关重要。

• HTTP 状态码： HTTP 状态码是服务器返回的三个数字代码，用于表示请求的结果。常见的状态码包括：
  • 200 (成功)： 表示请求已成功处理。
  • 400 (请求错误)： 指示客户端发送的请求存在问题，例如参数错误、格式错误等。需要检查请求参数是否符合 API 规范。
  • 401 (未授权)： 表示请求需要身份验证。通常是由于缺少有效的 API 密钥或密钥权限不足引起的。
  • 403 (禁止访问)： 表示服务器拒绝执行请求。即使提供了有效的身份验证，也可能由于权限限制导致无法访问。
  • 429 (请求过多)： 表示客户端在短时间内发送了过多的请求，触发了 API 的速率限制。开发者应该实施速率限制策略，例如使用指数退避算法重试请求。
  • 500 (服务器错误)： 表示服务器在处理请求时遇到了内部错误。这种错误通常是由于服务器端的问题引起的，开发者可以稍后重试请求或联系 OKX 技术支持。
• 错误代码： OKX API 定义了详细的错误代码，这些代码以 JSON 格式返回，用于描述特定错误的详细信息。 每个错误代码都对应着一种特定的错误情况，例如余额不足、订单不存在等。开发者可以参考 OKX 官方 API 文档，查阅错误代码列表及其详细解释，以便更好地理解错误的含义和采取相应的处理措施。文档通常会提供错误代码的含义、可能的原因以及建议的解决方法。

开发者应该建立完善的错误处理机制，以便在 API 调用失败时能够及时发现问题并采取适当的措施。有效的错误处理策略包括：

• 重试请求： 对于由于网络问题或临时服务器故障引起的错误，可以尝试重试请求。为了避免过度请求，应该使用指数退避算法来控制重试的频率。
• 记录错误日志： 将 API 错误信息（包括 HTTP 状态码、错误代码、请求参数等）记录到日志文件中，以便进行问题分析和调试。
• 通知用户： 对于影响用户体验的错误，应该及时通知用户，并提供相应的解决方案或建议。
• 监控 API 性能： 监控 API 的响应时间和错误率，以便及时发现潜在的问题。

REST API 与 WebSocket API

OKX 提供了两种主要的应用程序编程接口 (API)：REST API 和 WebSocket API，以满足不同类型的数据访问和交易需求。

• REST API： REST (Representational State Transfer) API 基于标准的 HTTP 协议，遵循请求-响应模式。客户端发起 HTTP 请求，服务器返回相应的响应数据。这种API适用于执行同步操作，例如获取历史交易数据、提交或取消交易订单、查询账户余额和管理账户信息等场景。由于其基于 HTTP 协议，易于理解和集成，被广泛应用于各种编程语言和平台。REST API 通常返回 JSON 格式的数据，方便解析和处理。 REST API支持多种HTTP方法，如GET（获取资源）、POST（创建资源）、PUT（更新资源）和DELETE（删除资源），以实现对资源的完整操作。
• WebSocket API： WebSocket API 基于 WebSocket 协议，是一种全双工通信协议，可以在客户端和服务器之间建立持久连接。与 REST API 的请求-响应模式不同，WebSocket API 允许服务器主动向客户端推送实时数据。这种特性使其非常适合需要实时更新数据的应用场景，例如获取实时市场行情（价格、成交量等）、订阅订单状态更新、监控账户活动和接收交易警报。WebSocket 连接建立后，数据可以在客户端和服务器之间双向传输，而无需客户端重复发送请求。 WebSocket 协议通过减少HTTP握手的开销，降低了延迟，提高了数据传输效率。

开发者应根据应用程序的具体需求选择最合适的 API 类型。 如果应用需要实时、低延迟的数据更新，例如构建实时交易平台或市场监控工具，那么 WebSocket API 通常是更优的选择。 反之，如果应用主要涉及历史数据查询、订单提交等非实时操作，则 REST API 可能更合适。在实际应用中，开发者也可以结合使用这两种 API，利用 REST API 进行账户管理和历史数据查询，同时使用 WebSocket API 获取实时市场数据和订单状态更新，以实现更全面和高效的应用功能。

安全注意事项

在使用 OKX API 时，保障账户和数据的安全至关重要。请务必遵循以下安全最佳实践，以降低潜在风险：

• 保护 API 密钥： API 密钥是访问您 OKX 账户的凭证，务必妥善保管。切勿将 API 密钥泄露给任何第三方，包括通过电子邮件、公共代码仓库或任何不安全的渠道分享。如果怀疑密钥已泄露，立即撤销并重新生成新的密钥。
• 限制 API 密钥权限： 为每个 API 密钥分配合适且最小化的权限集。避免授予不必要的权限，例如，如果只需要读取市场数据，则不要授予交易权限。只授予完成特定任务所需的最低权限，降低密钥泄露可能造成的损失。细粒度的权限控制是安全的关键。
• 使用 HTTPS 协议： 强制所有 API 请求通过 HTTPS (HTTP Secure) 协议进行加密传输。HTTPS 使用 SSL/TLS 协议对数据进行加密，防止数据在传输过程中被窃听或篡改。确保您的应用程序或脚本始终使用 https:// 开头的 API 端点 URL。
• 验证服务器证书： 在建立 HTTPS 连接时，验证 OKX 服务器的 SSL/TLS 证书，确保您正在与合法的 OKX 服务器通信，而不是受到中间人攻击。使用受信任的证书颁发机构 (CA) 签发的证书进行验证，可以有效防止恶意第三方伪造服务器身份。
• 限制请求频率： OKX API 对请求频率有限制，旨在防止滥用和维护系统稳定。过度频繁地请求 API 可能会触发频率限制，导致请求被拒绝。请合理控制 API 请求的频率，并实施适当的重试机制，以应对偶发的请求失败。考虑使用批量请求或 WebSocket 连接以优化数据获取效率。
• 监控 API 使用情况： 定期监控 API 请求的成功率和错误率，以及 API 密钥的使用情况。及时发现任何异常活动，例如未授权的访问、异常交易或频率限制错误。设置警报机制，以便在检测到可疑行为时立即收到通知。日志分析和审计是识别潜在安全问题的有效手段。

API 文档

OKX 提供了全面而详细的 API 文档，旨在帮助开发者充分利用其交易平台的功能。该文档完整收录了所有可用 API 接口的详细说明，包括但不限于：REST API 和 WebSocket API。针对每个接口，文档提供了精确的参数定义，明确了每个参数的数据类型、取值范围以及是否为必填项。同时，文档还包括了各种编程语言的示例代码，例如Python、Java、JavaScript等，方便开发者快速上手并集成API。文档还详尽列出了可能出现的错误代码及其对应的含义和解决方案，帮助开发者快速定位和解决集成过程中遇到的问题。

开发者可以参考 API 文档来深入了解每个 API 的具体使用方法，包括请求的构建、身份验证、数据格式、速率限制等。正确理解和使用 API 文档是成功开发基于 OKX 平台的应用程序的关键。API 文档会定期更新，以反映平台功能的更新和改进。

OKX API 文档地址为： OKX API Documentation . 我们强烈建议开发者在开始 API 集成之前，仔细阅读并理解最新的文档内容。