欧易OKX API接口指南：高效交易策略，新手快速入门！

2025-03-05 11:28:54 行业阅读 83

欧易API接口文档：交易、市场与账户管理

概述

欧易（OKX）API接口为开发者提供了一种强大的程序化访问平台核心功能的途径，涵盖交易、市场数据和账户管理等关键领域。通过API，开发者不仅可以构建高度定制化的自动化交易策略，还能实时监控市场动态，高效管理账户资产，并无缝集成欧易平台到现有的交易系统、量化分析工具或第三方应用程序中，从而提升交易效率和策略执行能力。

该API接口的设计目标是提供灵活、可靠且易于使用的编程接口，助力开发者充分利用欧易平台的各项功能。例如，开发者可以利用API自动执行订单，根据预设条件进行买卖操作；可以获取实时的市场行情数据，进行深度技术分析；还可以通过API查询账户余额、交易历史等信息，方便进行财务管理和风险控制。

本文档作为欧易API接口的中文使用指南，旨在帮助开发者快速上手并有效利用API接口。文档将详细介绍常用API接口的功能、请求方法、请求参数及其含义、响应格式，以及常见错误代码及其处理方法。还将提供代码示例，以帮助开发者更好地理解和应用API接口。通过阅读本文档，开发者可以更有效地利用欧易API接口，开发出满足自身需求的应用程序，并充分发挥欧易平台在数字资产交易领域的优势。

身份验证

要安全地访问受保护的API端点，身份验证是必不可少的步骤。它确保只有授权用户才能访问敏感数据和功能。身份验证过程的核心是生成并使用API密钥对，包括API Key（公钥）和Secret Key（私钥），以及在每个API请求的HTTP头部中包含根据请求内容生成的数字签名。

获取API密钥对： 登录您的欧易账户。然后，导航至账户设置中的API管理或API密钥管理页面。在该页面，您可以创建一个新的API密钥对。创建时，请务必仔细设置API密钥的权限，仅授予其访问所需的特定API端点的权限，以最小化潜在的安全风险。创建完成后，系统会生成API Key（公钥）和Secret Key（私钥）。务必妥善保管您的Secret Key，切勿以任何方式泄露给任何第三方。 Secret Key用于生成数字签名，泄露会导致账户安全风险。强烈建议启用两步验证 (2FA) 以增强账户的安全性。
生成签名： 为了验证请求的完整性和来源，每个API请求都需要一个数字签名。签名的生成过程涉及使用您的Secret Key对请求参数、请求路径和请求时间戳进行哈希运算。常用的哈希算法是HMAC SHA256。具体步骤如下：
1. 将所有请求参数按照字母顺序排序，并将其拼接成一个字符串。
2. 将请求方法（例如 GET, POST, PUT, DELETE）、请求路径和排序后的请求参数字符串拼接在一起。
3. 使用您的Secret Key作为密钥，对拼接后的字符串进行HMAC SHA256哈希运算。
4. 将哈希运算的结果作为签名。
请注意，签名必须在每次API请求时重新生成，并且必须与请求参数保持一致。
请求头参数： 在每个API请求的HTTP头部中，您需要包含以下参数，以便服务器验证您的身份和请求的有效性：
- OK-ACCESS-KEY : 您的API Key（公钥）。用于标识您的账户。
- OK-ACCESS-SIGN : 根据请求参数、请求方法、请求路径和时间戳生成的数字签名。用于验证请求的完整性和真实性。
- OK-ACCESS-TIMESTAMP : 请求的时间戳（UTC时间，精确到秒）。用于防止重放攻击。服务器会检查时间戳是否在有效的时间窗口内。
- OK-ACCESS-PASSPHRASE : 您的Passphrase (如果设置了Passphrase)。 Passphrase是您在创建API密钥时设置的额外安全密码。如果您设置了Passphrase，则必须将其包含在请求头中。 强烈建议设置Passphrase以提高账户安全性。
确保所有请求头参数都正确设置，否则API请求可能会失败。

签名生成示例 (Python)

以下代码展示了如何使用Python生成用于欧易API请求的签名。该签名用于验证请求的完整性和真实性，防止恶意篡改。

import hashlib
import hmac
import base64
import time

引入必要的Python库： hashlib 提供哈希算法， hmac 用于生成哈希消息认证码， base64 用于进行Base64编码， time 获取时间戳。

def generate_signature(timestamp, method, request_path, body, secret_key):
"""生成欧易API签名"""
message = timestamp + method.upper() + request_path + body
mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod=hashlib.sha256)
d = mac.digest()
return base64.b64encode(d)

generate_signature 函数接收五个参数：

timestamp : 当前时间戳，通常以秒为单位。
method : HTTP请求方法，例如 GET 或 POST 。务必转换为大写。
request_path : API请求的路径，例如 /api/v5/account/balance 。
body : 请求体的内容，如果为 GET 请求，则为空字符串。
secret_key : 您的API密钥对应的密钥。

该函数按照以下步骤生成签名：

将时间戳、大写的请求方法、请求路径和请求体连接成一个字符串。
使用HMAC-SHA256算法，以您的密钥作为密钥，对上述字符串进行哈希运算。
对哈希运算的结果进行Base64编码。
返回Base64编码后的字符串，即生成的签名。

重要提示：

确保时间戳的准确性，服务器通常会对时间戳进行验证，偏差过大的请求会被拒绝。
请勿泄露您的密钥。
不同API接口的签名要求可能略有不同，请务必参考欧易API的官方文档。

示例用法

进行API调用前，请务必替换以下占位符为你实际的API密钥、密钥和密码短语（如果适用）。API密钥和密钥用于认证你的身份，密码短语是额外的安全措施。保护好你的密钥和密码短语至关重要，切勿泄露给他人。

api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE" # 如果有
timestamp = str(int(time.time()))
method = "GET"
request_path = "/api/v5/account/balance" # 替换为实际API路径
body = "" # 适用于GET请求

时间戳是自Unix纪元以来的秒数，用于防止重放攻击。确保你的系统时间是准确的。请求方法通常是GET、POST、PUT或DELETE。请求路径是API端点的相对路径。对于GET请求，请求体通常为空。

signature = generate_signature(timestamp, method, request_path, body, secret_key)

使用你的密钥、时间戳、请求方法、请求路径和请求体生成签名。签名用于验证请求的完整性和真实性。不同的交易所可能有不同的签名生成算法，请参考交易所的API文档。

headers = { "OK-ACCESS-KEY": api_key, "OK-ACCESS-SIGN": signature.decode('utf-8'), "OK-ACCESS-TIMESTAMP": timestamp, "OK-ACCESS-PASSPHRASE": passphrase # 如果有 }

构建包含认证信息的HTTP头部。 OK-ACCESS-KEY 包含你的API密钥。 OK-ACCESS-SIGN 包含生成的签名，并且要确保将其解码为UTF-8字符串。 OK-ACCESS-TIMESTAMP 包含时间戳。 OK-ACCESS-PASSPHRASE 包含密码短语（如果需要）。

print(headers)

打印HTTP头部，以检查其内容。下一步是使用这些头部发送API请求。使用适当的HTTP客户端库，例如Python中的 requests 库。请务必仔细阅读交易所的API文档，了解速率限制、错误处理和其他重要细节。

常用API接口

以下是一些常用的欧易API接口，并附有简要说明。这些接口允许开发者以编程方式访问欧易交易所的数据和功能，方便构建交易机器人、数据分析工具等应用。

市场数据API (Market Data API)

获取交易对信息： 允许查询所有或特定交易对的详细信息，例如交易对名称、最小交易数量、价格精度等。这是了解市场交易规则的基础。
获取最新成交价： 提供交易对的最新成交价格，用于快速获取市场行情。通常会提供多个交易所的行情数据，便于比较和套利。
获取深度数据： 返回交易对的买单和卖单的挂单信息，用于分析市场深度和流动性。深度数据对高频交易和量化策略至关重要。
获取K线数据： 提供历史K线数据，包括开盘价、收盘价、最高价、最低价和交易量。 K线数据是技术分析的基础，可用于预测价格趋势。

交易API (Trading API)

下单接口： 用于创建买单或卖单。支持多种订单类型，如限价单、市价单、止损单等。下单需要身份验证和资金账户权限。
撤单接口： 用于取消未成交的订单。及时撤单是风险管理的重要手段。
查询订单状态： 允许查询特定订单的详细状态，如已成交数量、平均成交价格等。订单状态查询对于监控交易执行情况至关重要。
获取账户信息： 提供用户的账户余额、持仓信息等。账户信息是交易决策的基础。

账户API (Account API)

获取账户余额： 查询账户中各种加密货币的可用余额和冻结余额。
获取充提币记录： 查询账户的充值和提现历史记录。
资金划转： 允许在不同的账户类型之间划转资金，例如从交易账户划转到资金账户。

使用API时，请务必阅读欧易的API文档，了解接口的具体参数、返回值和使用限制。请注意保护您的API密钥，避免泄露，并采取必要的安全措施，防止API被滥用。

账户相关

/api/v5/account/balance : 获取账户余额信息。此接口用于检索用户账户中所有或指定加密货币的可用余额、冻结余额和总余额。通过此接口，可以清晰了解账户资产状况，便于进行投资决策和风险管理。
- 请求方法: GET
- 参数: ccy (可选) - 指定要查询的币种。接受单个币种代码，例如 BTC , ETH 。如果未提供此参数，接口将返回所有币种的余额信息。不区分大小写。
/api/v5/account/positions : 获取持仓信息。此接口提供当前账户在不同产品类型下的持仓详情，包括多仓和空仓的数量、平均开仓价格、未实现盈亏等关键信息。有效监控仓位变动，及时调整交易策略。
- 请求方法: GET
- 参数:
  - instType : 产品类型，枚举值包括 SPOT (现货), MARGIN (杠杆), SWAP (永续合约), FUTURES (交割合约), OPTION (期权)。必须指定产品类型，以便筛选特定市场的持仓数据。
  - instId (可选): 产品ID，例如： BTC-USD-SWAP 。用于进一步筛选指定合约的持仓信息。如果省略此参数，接口将返回指定产品类型下的所有合约持仓。请注意合约的命名规则。
  - posId (可选): 仓位ID。用于查询特定仓位的详细信息。通常用于追踪特定交易的盈亏情况和持仓历史。
/api/v5/account/bills : 获取账单明细。此接口提供用户账户的交易历史记录，包括交易、充值、提现、手续费等详细信息。账单数据是财务审计、税务申报和交易分析的重要依据。
- 请求方法: GET
- 参数:
  - instType (可选): 产品类型，与 /api/v5/account/positions 接口中的定义相同。用于筛选特定产品类型的账单记录。
  - ccy (可选): 币种，例如： BTC , ETH 。指定需要查询的币种，仅返回与该币种相关的账单记录。
  - billType (可选): 账单类型。用于筛选特定类型的账单，例如： trade (交易), deposit (充值), withdrawal (提现), fee (手续费), interest (利息) 等。如果不指定，则返回所有类型的账单。
  - after (可选): 分页参数，返回在此ID之后的账单记录。用于实现分页查询，通常需要配合 limit 参数使用。提供大于0的账单ID。
  - before (可选): 分页参数，返回在此ID之前的账单记录。与 after 参数类似，用于分页查询，但返回的是更早的记录。提供大于0的账单ID。
  - limit (可选): 每页返回的记录数量，范围为 1 到 100。默认为100，建议根据实际需求合理设置，避免数据量过大导致响应缓慢。

交易相关

/api/v5/trade/order : 下单。此接口允许您在欧易平台进行交易下单，创建买入或卖出指令。
- 请求方法: POST
- 参数:
  - instId : 产品ID，指定交易的合约或币对。例如： BTC-USD-SWAP 代表比特币美元永续合约交易。确保该ID与您希望交易的标的物一致。
  - tdMode : 交易模式，决定保证金的使用方式。 cash 表示现货交易，无需保证金； cross 表示全仓保证金模式，所有仓位共享保证金； isolated 表示逐仓保证金模式，每个仓位独立计算保证金。选择正确的模式对风险管理至关重要。
  - side : 买卖方向，指示您希望执行的操作。 buy 表示买入，用于做多或平空仓位； sell 表示卖出，用于做空或平多仓位。
  - ordType : 订单类型，定义订单的执行方式。
    - market (市价单): 立即以当前市场最优价格成交，保证成交，但不保证成交价格。
    - limit (限价单): 只有当市场价格达到或优于指定价格时才会成交，可以控制成交价格，但不保证立即成交。
    - post_only (只挂单): 确保订单只会被挂在盘口上，而不会立即成交，避免成为taker，从而享受maker手续费优惠。
    - fok (立即全部成交否则撤销): 订单必须立即全部成交，否则会被立即撤销，适用于追求立即成交的场景。
    - ioc (立即成交剩余撤销): 订单会立即尽可能多地成交，剩余未成交的部分会被立即撤销，适用于快速成交部分仓位的场景。
    - mkt_to_limit (市价转限价): 当市价单未能完全成交时，剩余部分会自动转换为限价单，以避免订单完全失败。
  - sz : 数量，指定您希望交易的合约数量或币的数量。务必仔细核对数量，避免交易错误。
  - px (可选): 价格，仅限价单需要。指定您希望成交的价格。该参数决定了限价单的成交条件。
  - tpTriggerPx (可选): 止盈触发价格，仅止盈止损单需要。当市场价格达到此价格时，止盈订单会被触发。
  - tpOrdPx (可选): 止盈委托价格，仅止盈止损单需要。止盈订单被触发后，会以该价格提交一个限价单。
  - slTriggerPx (可选): 止损触发价格，仅止盈止损单需要。当市场价格达到此价格时，止损订单会被触发。
  - slOrdPx (可选): 止损委托价格，仅止盈止损单需要。止损订单被触发后，会以该价格提交一个限价单。
/api/v5/trade/cancel-order : 撤销订单。此接口允许您撤销尚未成交的订单，取消未成交的挂单。
- 请求方法: POST
- 参数:
  - instId : 产品ID，指定要撤销订单的合约或币对。例如： BTC-USD-SWAP 。必须与下单时的产品ID一致。
  - ordId : 订单ID，要撤销的订单的唯一标识符。可以通过获取未成交订单列表接口获取。
/api/v5/trade/orders-pending : 获取未成交订单列表。此接口返回您尚未完全成交的订单，即当前仍然挂在市场上的订单。
- 请求方法: GET
- 参数:
  - instType : 产品类型，指定要查询的订单类型，例如： SPOT (现货), MARGIN (杠杆), SWAP (永续合约), FUTURES (交割合约), OPTION (期权)。
  - instId (可选): 产品ID，指定要查询的合约或币对，例如： BTC-USD-SWAP 。如果未指定，则返回该产品类型的所有未成交订单。
  - after (可选): 分页参数，返回在此ID之后的订单。用于分页查询，避免一次性返回大量数据。
  - before (可选): 分页参数，返回在此ID之前的订单。用于分页查询。
  - limit (可选): 每页返回的记录数量，最大100。用于控制每次请求返回的数据量。
/api/v5/trade/orders-history : 获取历史订单列表。此接口返回您的历史订单，包括已成交和已撤销的订单。
- 请求方法: GET
- 参数:
  - instType : 产品类型，指定要查询的订单类型，例如： SPOT (现货), MARGIN (杠杆), SWAP (永续合约), FUTURES (交割合约), OPTION (期权)。
  - instId (可选): 产品ID，指定要查询的合约或币对，例如： BTC-USD-SWAP 。如果未指定，则返回该产品类型的所有历史订单。
  - after (可选): 分页参数，返回在此ID之后的订单。用于分页查询。
  - before (可选): 分页参数，返回在此ID之前的订单。用于分页查询。
  - limit (可选): 每页返回的记录数量，最大100。用于控制每次请求返回的数据量。

市场数据相关

/api/v5/market/tickers : 获取所有产品行情信息，用于监控市场整体表现。此接口返回欧易交易所支持的所有交易产品（包括现货、杠杆、永续合约、交割合约和期权）的最新行情快照数据。
- 请求方法: GET
- 参数: instType (必需): 产品类型，定义了不同类型的交易工具。
  - SPOT : 现货交易，代表直接买卖数字资产。
  - MARGIN : 杠杆交易，允许用户借入资金进行交易，放大收益和风险。
  - SWAP : 永续合约，一种没有到期日的合约，追踪标的资产的价格。
  - FUTURES : 交割合约，一种有到期日的合约，到期时需要进行交割。
  - OPTION : 期权，一种赋予持有者在未来某个时间以特定价格买卖标的资产权利的合约。
  选择合适的 instType 可筛选所需的产品类型行情。
/api/v5/market/ticker : 获取单个产品行情信息，用于深入分析特定交易对。此接口返回指定产品的详细行情数据，例如最新成交价、24小时涨跌幅、成交量等。
- 请求方法: GET
- 参数: instId (必需): 产品ID，唯一标识一个交易产品。例如， BTC-USD-SWAP 代表比特币兑美元的永续合约。使用正确的 instId 可以精确获取目标产品的行情信息。
/api/v5/market/candles : 获取K线数据，用于技术分析和趋势预测。此接口返回指定产品的K线图数据，包含开盘价、收盘价、最高价、最低价和成交量等信息。
- 请求方法: GET
- 参数:
  - instId (必需): 产品ID，例如： BTC-USD-SWAP 。指定要获取K线数据的产品。
  - bar (可选): K线周期，定义了每根K线的时间跨度。例如：
    - 1m : 1分钟K线
    - 5m : 5分钟K线
    - 15m : 15分钟K线
    - 30m : 30分钟K线
    - 1H : 1小时K线
    - 4H : 4小时K线
    - 1D : 1天K线
    - 1W : 1周K线
    - 1M : 1月K线
    默认值为 1m 。选择不同的周期可以观察不同时间尺度的价格变动。
  - after (可选): 分页参数，用于获取指定时间戳之后的K线数据。用于浏览历史数据。
  - before (可选): 分页参数，用于获取指定时间戳之前的K线数据。用于浏览历史数据。
  - limit (可选): 每页返回的记录数量，最大100。用于控制每次请求返回的数据量，避免数据过大。

错误处理

欧易API采用标准HTTP状态码来标识请求处理的结果。通过检查这些状态码，开发者能够快速了解请求是否成功，或者出现了哪种类型的错误。常见的HTTP状态码及其含义如下：

200 OK : 这是一个成功的标志。表示请求已成功被服务器接收、处理，并返回了期望的结果。
400 Bad Request : 客户端发出的请求存在问题，例如，请求体格式错误、缺少必要的参数、参数值不符合预期等。开发者需要仔细检查请求的各个方面，确保符合API的规范。
401 Unauthorized : 表明客户端尝试访问受保护的资源，但提供的身份验证信息无效。这通常意味着API密钥不正确、过期，或者签名计算错误。请务必检查API密钥是否正确配置，以及签名算法是否按照欧易的文档正确实现。
403 Forbidden : 客户端通过了身份验证，但没有足够的权限访问请求的资源。这可能是由于用户账户的权限设置限制了对特定API接口的访问。
429 Too Many Requests : 客户端在短时间内发送了过多的请求，触发了欧易的速率限制。为了避免此错误，开发者应该实施速率限制策略，例如使用队列或令牌桶算法来控制请求的发送频率。
500 Internal Server Error : 服务器在处理请求时遇到了意外的错误。这通常是服务器端的问题，开发者可以稍后重试。如果问题持续存在，请联系欧易的技术支持团队。

除了HTTP状态码之外，欧易API的响应通常还包含一个 code 字段和一个 msg 字段，用于提供更加详细和具体的错误信息。 code 字段是一个数字代码，用于标识特定的错误类型，而 msg 字段则包含了人类可读的错误描述。开发者应该仔细分析 code 和 msg 的内容，以便准确判断错误的性质，并采取相应的应对措施。例如，根据不同的 code 值，可以采取不同的重试策略、调整请求参数，或者记录错误日志以便后续分析。

Rate Limit (速率限制)

欧易API为了保障系统稳定性和公平性，对所有用户的请求频率都设置了速率限制。如果您的请求超过了设定的速率限制，API将返回HTTP状态码 429 Too Many Requests ，表示请求过多。因此，开发者需要合理控制API请求的频率，以避免触发速率限制，影响程序的正常运行。

您可以通过查看响应头中的 X-RateLimit-Limit 、 X-RateLimit-Remaining 和 X-RateLimit-Reset 等字段来获取当前的速率限制信息，这些信息能帮助您更好地管理您的请求行为。

示例响应头信息：

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1

X-RateLimit-Limit : 在一个时间窗口内允许的最大请求次数。例如，上面的例子表示在某个时间段内最多允许120次请求。
X-RateLimit-Remaining : 在当前时间窗口内剩余的可用请求次数。该数值会随着您的请求而递减。
X-RateLimit-Reset : 指示速率限制重置的时间，以Unix时间戳表示。在此时间戳之后， X-RateLimit-Remaining 将会重置为 X-RateLimit-Limit 的值。

为了优雅地处理速率限制，强烈建议采用指数退避算法。该算法的核心思想是：当收到 429 错误时，程序暂停一段时间后重试。每次重试前，等待时间都应该比上一次更长。例如，第一次等待1秒，第二次等待2秒，第三次等待4秒，以此类推。这种策略有助于避免持续过载API，从而更快地恢复正常请求。

请务必仔细阅读欧易API的官方文档，了解针对不同API接口的具体速率限制策略，因为不同的API接口可能具有不同的速率限制。遵守这些规则对于维护应用程序的稳定性和可靠性至关重要。

欧易OKX API接口指南：高效交易策略，新手快速入门！

欧易API接口文档：交易、市场与账户管理

概述

身份验证

签名生成示例 (Python)

示例用法

常用API接口

账户相关

交易相关

市场数据相关

错误处理

Rate Limit (速率限制)

更多信息

Bitget奖励多久到账？注册、邀请、交易奖励领取全攻略！

OKX 存款取款指南：新手 5 分钟学会？操作步骤详解！

相关推荐

欧易币安互通？揭秘加密货币交易平台的未来之路！

欧易(OKX)加密货币税务攻略：新手必看指南！

欧易OKX限价单攻略：低价抄底以太坊？这样做！

新手必看：如何在欧易OKX上轻松购买瑞波币XRP？

币安API密钥设置指南：新手也能轻松上手，交易快人一步！

欧易(OKEx)提币SHIB币指南：新手必看，避免资产丢失！

欧易超级返佣：不交易就亏了？揭秘交易界的“薅羊毛”！

欧易账户安全大作战：6招教你安全验证，告别盗号风险！

欧易(OKX)收益怎么算？2024最全计算公式详解！

欧易OKX交易BCH：新手指南！避坑技巧与安全保障详解