OKEx API终极指南：3分钟搞定加密货币交易开发？

15 2025-03-07 00:01:29

欧易接口开发文档：深度解析与应用指南

本文档旨在为开发者提供欧易交易所API接口的全面深入指南，涵盖现货、合约、期权等多种交易类型，以及账户管理、市场数据获取等核心功能。它致力于帮助开发者构建高效、稳定、安全的加密货币交易应用程序及相关服务。

我们将详细剖析各项API接口的功能，包括但不限于：订单管理（下单、撤单、查询订单状态）、资金划转、持仓查询、历史成交记录、实时市场行情、K线数据等。对于每个接口，都将详细阐述其请求参数，包括参数类型、是否必填、取值范围及含义，并通过具体的代码示例进行说明，以确保开发者能够准确理解并正确使用。

文档还将深入解读响应数据的格式，详细解释每个字段的含义和可能的值，并提供错误码对照表，帮助开发者快速定位和解决问题。同时，还会针对高并发场景下的API调用策略、签名算法的实现、以及如何有效处理限流等问题提供专业的建议和最佳实践。

本指南力求全面覆盖欧易平台提供的丰富资源，并持续更新，以适应平台API的最新发展。我们希望通过这份详尽的文档，能够帮助开发者快速上手，充分利用欧易API，构建出满足各种业务需求的强大应用。

认证与授权

所有需要访问用户账户信息的应用程序接口 (API) 都必须经过严格的身份验证流程，以确保用户资产安全和数据隐私。欧易交易所采用 API 密钥 (API Key) 和密钥密码 (Secret Key) 结合的方式进行认证，这是一种常用的数字签名机制，用于验证请求的来源和完整性。

API 密钥 (API Key): 类似于用户名，用于标识您的身份。您可以将其视为公开信息，但务必妥善保管，避免泄露给未经授权的第三方。API Key 通常用于在请求中标识您的账户。

密钥密码 (Secret Key): 类似于密码，是只有您知道的私密信息。请务必极其谨慎地保管您的 Secret Key，切勿将其分享给任何人或将其存储在不安全的地方。Secret Key 用于生成数字签名，验证您的请求是否真实有效。

通过 API Key 和 Secret Key 的组合使用，欧易可以安全地验证每个 API 请求，并确保只有经过授权的应用程序才能访问您的账户信息和执行交易操作。请务必遵循欧易提供的安全最佳实践，以保护您的 API 密钥和密钥密码的安全。

1. API 密钥获取:

为了访问欧易交易所的API接口，您需要先登录您的欧易账户。登录后，导航至“API管理”页面。通常，该页面可以在您的账户设置或个人资料设置中找到。

在API管理页面，您可以创建新的API密钥对。每个API密钥对由一个API Key（公钥）和一个Secret Key（私钥）组成。API Key用于标识您的应用程序，而Secret Key用于对您的API请求进行签名，以确保请求的安全性。

在创建API密钥时，务必仔细选择所需的权限。欧易提供了多种权限选项，例如交易、提现、查看账户信息等。请仅勾选您的应用程序实际需要的权限。例如，如果您的应用程序只需要读取市场数据，则无需勾选交易或提现权限。最小化权限授予可以显著提高安全性，降低潜在风险。

强烈建议为每个应用程序创建独立的API密钥。这意味着如果您有多个应用程序需要访问欧易API，请为每个应用程序创建一个单独的API密钥对，而不是共享同一个密钥对。这有助于隔离不同应用程序之间的风险，并方便您追踪和管理API使用情况。

创建API密钥后，务必妥善保管您的Secret Key。切勿将Secret Key泄露给任何其他人，也不要将其存储在不安全的地方。如果您的Secret Key泄露，攻击者可能会利用您的API密钥进行恶意操作。您可以将Secret Key存储在加密的配置文件中，或者使用硬件安全模块（HSM）进行保护。

为了进一步提高安全性，您可以设置IP地址白名单。这意味着只有来自指定IP地址的请求才能使用您的API密钥。您可以将您的服务器IP地址添加到白名单中，以防止未经授权的访问。欧易的API管理页面通常提供IP地址白名单设置选项。

2. 请求签名:

为了保障交易请求的完整性和安全性，防止恶意篡改，所有需要授权的私有API接口都必须进行签名验证。这是一种标准的身份验证机制，用于确认请求确实来自授权用户，并且在传输过程中未被篡改。签名过程的详细步骤如下：

构造签名字符串（Sign String Construction）： 签名字符串是基于请求的多个关键因素构建的。这包括：
- 请求方法 (HTTP Method): 明确指出使用的HTTP方法，例如 GET 或 POST 。请求方法必须全部大写。
- 请求路径 (Request Path): API端点的路径，不包含域名部分。例如： /api/v5/trade/order 。
- 请求参数 (Request Parameters): 所有请求参数必须按照其字母顺序进行排列。这确保了相同的参数集总是产生相同的签名字符串。注意：如果参数值本身是JSON对象，也需要对其内部的键值对进行排序。
- 时间戳 (Timestamp): Unix时间戳，精确到秒或毫秒级别，表示请求发送的时间。时间戳是防止重放攻击的关键要素。
将这些元素按照顺序拼接成一个字符串。例如： POST/api/v5/trade/order?instrument_id=BTC-USD&size=1&side=buy&type=market1678886400 。
HMAC-SHA256 加密 (HMAC-SHA256 Encryption): 使用您的 Secret Key (API密钥创建时生成的密钥) 作为密钥，对构造的签名字符串进行HMAC-SHA256加密。 HMAC-SHA256 是一种密码学散列函数，结合了哈希算法和密钥，能提供更强的安全性。不同的编程语言提供了相应的库来实现HMAC-SHA256加密。请确保正确地编码签名字符串和密钥，通常使用UTF-8编码。
添加请求头 (Request Header Injection): 将加密后的签名值、API Key和时间戳添加到HTTP请求头中，以便服务器验证。
- OK-ACCESS-SIGN : 包含HMAC-SHA256加密后的签名字符串。这是服务器验证请求来源的关键。
- OK-ACCESS-KEY : 您的API Key，用于标识您的账户。
- OK-ACCESS-TIMESTAMP : 发送请求时的时间戳。服务器会使用此时间戳来防止重放攻击。
- OK-ACCESS-PASSPHRASE : 在创建API密钥时设置的密钥密码（Passphrase）。这是额外的安全措施，进一步验证您的身份。如果创建API密钥时没有设置，则不需要添加此请求头。
示例请求头：
```
        OK-ACCESS-KEY: YOUR_API_KEY
        OK-ACCESS-SIGN: SIGNATURE_VALUE
        OK-ACCESS-TIMESTAMP: 1678886400
        OK-ACCESS-PASSPHRASE: YOUR_PASSPHRASE
        
```

示例 (Python):

import hashlib import hmac import base64 import time

def generate_signature(timestamp, method, request_path, body, secret_key): """ 生成签名。该函数使用 HMAC-SHA256 算法基于给定的时间戳、HTTP 方法、请求路径、请求体以及密钥来生成签名。生成的签名用于验证请求的完整性和身份。 """ message = str(timestamp) + str.upper(method) + request_path + body # 将所有元素拼接成一个字符串，作为待签名消息。 # 时间戳确保签名的时效性，防止重放攻击。 # HTTP 方法（如 GET、POST、PUT 等）需要大写。 # 请求路径是 API 的 endpoint。 # 请求体包含请求的具体数据。 mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf8'), hashlib.sha256) # 创建一个 HMAC 对象，使用 secret_key 作为密钥，sha256 作为哈希算法。 # secret_key 必须安全地保存，并且只在客户端和服务器端之间共享。 d = mac.digest() # 计算消息的 HMAC-SHA256 摘要。 return base64.b64encode(d) # 将摘要进行 Base64 编码，以便在 HTTP 请求头中传输。 # Base64 编码将二进制数据转换为 ASCII 字符串。

示例数据

用于访问加密货币交易所API的身份验证信息。 api_key , secret_key , 和 passphrase 是您从交易所获得的凭据，务必妥善保管，切勿泄露。 API密钥（ api_key ）用于标识您的账户。密钥（ secret_key ）用于签名请求，确保请求的完整性和真实性。短语（ passphrase ）作为额外的安全层，某些交易所需要此项。
api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

timestamp = str(int(time.time()))
时间戳（ timestamp ）是当前时间的 Unix 时间戳，精确到秒。它用于防止重放攻击，确保请求的时效性。在Python中，可以使用 time.time() 函数获取当前时间戳，并将其转换为整数和字符串格式。
method = "GET"
HTTP方法（ method ）指定请求的类型。常见的有 GET、POST、PUT 和 DELETE。 GET 方法用于从服务器检索数据。
request_path = "/api/v5/account/balance"
请求路径（ request_path ）指定API的端点，表示您要访问的资源。例如， /api/v5/account/balance 表示获取账户余额的API端点。
body = "" # GET 请求通常没有 body
请求体（ body ）包含要发送到服务器的数据。对于 GET 请求，通常没有请求体，因此为空字符串。 POST, PUT 等方法常常需要传递请求体。

生成签名

在加密货币交易和API交互中，生成签名是一个至关重要的步骤，用于验证请求的真实性和完整性，防止恶意篡改。签名本质上是对请求数据进行加密处理后得到的一串字符串，接收方使用相同的密钥和算法验证签名，以此确认请求来源的合法性。

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

上述代码片段描述了签名生成的通用过程，其中每个参数的含义如下：

timestamp ：时间戳，表示请求发送的时间，通常以Unix时间戳（自1970年1月1日以来的秒数）表示。时间戳的主要作用是防止重放攻击，即攻击者截获有效的请求并重复发送。接收方会验证时间戳是否在可接受的时间范围内，例如前后几分钟，超出范围的请求将被拒绝。
method ：HTTP请求方法，例如 GET 、 POST 、 PUT 、 DELETE 等。不同的请求方法表明了不同的操作意图，签名中包含请求方法可以确保请求没有被篡改为其他类型的操作。
request_path ：请求路径，即API端点的URL路径，例如 /api/v1/orders 。请求路径指定了请求访问的资源或执行的操作，签名中包含请求路径可以防止请求被重定向到其他未经授权的端点。
body ：请求体，包含请求的具体数据，例如JSON格式的参数。请求体是请求的核心内容，签名中包含请求体可以确保请求数据没有被篡改。对于 GET 请求，通常没有请求体，可以传入空字符串或 null 。
secret_key ：密钥，只有请求发送方和接收方知道的私密字符串，用于生成和验证签名。密钥必须安全保存，防止泄露，否则攻击者可以伪造签名。

generate_signature 函数内部通常会进行以下操作：

参数拼接： 将 timestamp 、 method 、 request_path 和 body 按照一定的规则拼接成一个字符串。拼接顺序和格式必须与接收方保持一致。
哈希运算： 使用哈希算法（例如SHA256、HMAC-SHA256）对拼接后的字符串进行哈希运算，生成哈希值。
密钥加密： 使用 secret_key 对哈希值进行加密，生成最终的签名。常用的加密算法包括HMAC（Hash-based Message Authentication Code）。
编码： 将生成的签名进行Base64编码，方便在HTTP请求头或查询参数中传递。

示例（使用HMAC-SHA256算法）：


import hashlib
import hmac
import base64

def generate_signature(timestamp, method, request_path, body, secret_key):
  message = f"{timestamp}{method}{request_path}{body}".encode('utf-8')
  secret_key_bytes = secret_key.encode('utf-8')
  hashed = hmac.new(secret_key_bytes, message, hashlib.sha256).digest()
  signature = base64.b64encode(hashed).decode('utf-8')
  return signature

在实际应用中，需要根据具体的API文档和安全要求选择合适的签名算法和参数传递方式。

构建请求头

在与OKX交易所API交互时，构建正确的HTTP请求头至关重要，它包含了认证信息，确保您的请求被服务器正确识别和授权。以下是一个包含必要字段的Python字典示例，用于构建符合OKX API安全要求的请求头：

headers = {
    "OK-ACCESS-KEY": api_key,
    "OK-ACCESS-SIGN": signature,
    "OK-ACCESS-TIMESTAMP": timestamp,
    "OK-ACCESS-PASSPHRASE": passphrase
}

字段详解：

OK-ACCESS-KEY : 您的API密钥，用于标识您的账户。请务必妥善保管，切勿泄露给他人。这是从OKX官方申请的API Key，具有调用API接口的权限。
OK-ACCESS-SIGN : 数字签名，通过使用您的私钥对请求内容进行哈希计算生成。这是验证请求完整性和身份的关键，防止请求被篡改。生成签名的算法需要严格按照OKX官方文档的指导进行，通常涉及将请求参数、时间戳和私钥组合后进行加密哈希运算（例如，HMAC-SHA256）。
OK-ACCESS-TIMESTAMP : 时间戳，表示请求发送的时间。用于防止重放攻击，确保请求的新鲜度。时间戳通常以UTC时间表示，精确到秒或毫秒，并需要与服务器时间保持合理的同步，避免因时间偏差导致认证失败。单位为秒或者毫秒。
OK-ACCESS-PASSPHRASE : 您的账户密码短语，作为额外的安全层。如果您在创建API密钥时设置了密码短语，则必须将其包含在请求头中。这是可选的，取决于您账户的安全设置。务必牢记此短语，丢失将可能导致API调用失败。

构建完成后，可以使用以下代码打印请求头，以便调试和验证其内容：

print(headers)

注意事项：

API密钥和密码短语是敏感信息，请勿硬编码在代码中，建议使用环境变量或其他安全的方式存储和管理。
签名生成过程必须严格按照OKX官方文档的要求进行，确保签名的正确性。
时间戳的精度和同步性对认证的成功至关重要，请确保您的系统时间与UTC时间同步。
不同的API接口可能需要不同的请求头参数，请仔细阅读OKX官方文档，了解每个接口的具体要求。
除了以上必须的header之外，根据具体API接口的要求，可能还需要添加Content-Type，例如：application/

账户接口

账户接口提供了一系列功能，旨在安全、便捷地访问和管理用户在平台上的账户信息。这些功能涵盖了账户余额查询、交易历史记录检索、账户设置修改，以及其他与账户相关的操作。

通过账户接口，用户可以实时查看其账户中的各种加密货币余额，例如比特币（BTC）、以太坊（ETH）等。接口通常支持多种货币单位显示，方便用户根据自身需求进行查看。

该接口还允许用户查询详细的交易历史记录，包括每一笔交易的交易时间、交易类型（如充值、提现、交易）、交易金额、手续费等信息。这些信息有助于用户追踪资金流向，进行财务管理。

账户接口通常还提供账户设置修改的功能，例如修改登录密码、绑定/解绑手机号码、启用/禁用双重身份验证（2FA）等。这些功能旨在提高账户的安全性，防止账户被盗。

为了确保用户数据的安全，账户接口通常采用严格的安全措施，例如API密钥认证、数据加密传输、访问控制等。开发者需要正确使用这些安全措施，以防止未经授权的访问。

1. 获取账户余额 (GET /api/v5/account/balance):

该接口提供了一种查询用户账户中各种加密货币资产余额的途径，包括可用余额、冻结余额以及总余额，从而允许用户全面了解其资产状况。

请求参数:
- ccy (可选): 指定需要查询的币种代码，例如 "BTC" 代表比特币，"ETH" 代表以太坊。如果不指定此参数，接口将返回用户账户中所有币种的余额信息。明确指定币种可以提高查询效率，并减少返回的数据量。
响应示例:
成功调用该接口后，服务器将返回一个 JSON 格式的响应，其中包含了账户余额的详细信息。
```
{
    "code": "0",
    "msg": "",
    "data": [
        {
            "ccy": "BTC",
            "bal": "1.00000000",
            "frozen": "0.00000000",
            "availBal": "1.00000000"
        },
        {
            "ccy": "ETH",
            "bal": "5.00000000",
            "frozen": "0.00000000",
            "availBal": "5.00000000"
        }
    ]
}
    
```
字段说明：
- code : 返回码，"0" 代表请求成功。其他数值代表不同的错误代码。
- msg : 返回信息，通常为空字符串，除非出现错误。
- data : 一个数组，包含账户中各个币种的余额信息。
- ccy : 币种代码，如 "BTC"、"ETH"。
- bal : 总余额，包括可用余额和冻结余额的总和。
- frozen : 冻结余额，指暂时无法使用的余额，例如在挂单交易中被锁定的资金。
- availBal : 可用余额，指可以立即用于交易或提现的余额。
用户可以通过解析 data 数组中的信息，获得每个币种的详细余额情况，从而进行资产管理和交易决策。需要注意的是，余额的精度取决于交易所的具体设置，示例中的小数点后8位只是一种常见的精度展示。

2. 获取账户持仓信息 (GET /api/v5/account/positions):

该接口允许用户查询其在OKX账户中的具体持仓信息，涵盖持仓数量、平均持仓价格、未实现盈亏等关键指标。通过此接口，用户可以全面了解其风险敞口和投资组合表现。

请求参数:

instType : 必选。指定需要查询的交易产品类型。支持的类型包括现货 ( SPOT )、永续合约 ( SWAP )、交割合约 ( FUTURES ) 和期权 ( OPTION )。选择合适的 instType 至关重要，它决定了返回数据的范围。
instId : 可选。交易对ID，用于精确定位特定交易对的持仓信息。例如，"BTC-USDT" 代表比特币对USDT的现货交易对，"ETH-USDT-SWAP" 代表以太坊对USDT的永续合约交易对。若不提供此参数，接口将返回所有满足指定 instType 的交易对的持仓数据。

响应示例:

该JSON示例展示了成功调用接口后返回的数据结构。各个字段提供了关于持仓状态的详细信息。


{
  "code": "0",
  "msg": "",
  "data": [
    {
      "instId": "BTC-USDT-SWAP",
      "posSide": "long",
      "pos": "10",
      "avgPx": "20000",
      "upl": "100",
      "uplRatio": "0.005"
    }
  ]
}

字段说明：

code : 返回码，"0" 表示请求成功。
msg : 返回消息，通常为空字符串，除非发生错误。
data : 包含持仓信息的数组。数组中的每个对象代表一个交易对的持仓信息。
instId : 交易对ID，例如 "BTC-USDT-SWAP"。
posSide : 持仓方向，"long" 表示多头持仓，"short" 表示空头持仓。
pos : 持仓数量，例如 "10"。
avgPx : 平均持仓价格，例如 "20000"。
upl : 未实现盈亏，例如 "100"。
uplRatio : 未实现盈亏比例，例如 "0.005" (0.5%)。

注意事项：

持仓数量 ( pos ) 的单位取决于对应的交易产品类型。例如，对于永续合约，它可能代表合约张数。
未实现盈亏 ( upl ) 以计价货币（例如 USDT）表示。
未实现盈亏比例 ( uplRatio ) 的计算方式为：(当前价格 - 平均持仓价格) / 平均持仓价格。
如果没有持仓， data 字段可能返回一个空数组。

交易接口

交易接口是连接加密货币交易平台与用户交易策略的关键桥梁，允许用户通过编程方式自动执行交易操作。它主要用于执行以下核心功能：

下单： 通过交易接口，用户可以提交买入或卖出加密货币的订单。下单请求通常需要指定交易对（例如，BTC/USD）、订单类型（例如，市价单、限价单）、交易数量和价格（如果是限价单）。
撤单： 用户可以通过交易接口取消尚未成交的订单。撤单操作通常需要提供订单ID，以便交易所识别需要取消的订单。高效的撤单功能对于风险管理至关重要，尤其是在市场波动剧烈时。
查询订单信息： 交易接口提供查询订单状态的功能，允许用户获取订单的详细信息，包括订单是否已成交、部分成交的数量、订单状态（例如，挂单中、已成交、已取消）以及成交价格等。这对于监控交易执行情况和进行交易策略分析至关重要。

更进一步，交易接口通常支持多种订单类型，以满足不同的交易需求。除了常见的市价单和限价单外，还可能包括：

止损单： 当市场价格达到预设的止损价格时，自动触发的市价单或限价单，用于限制潜在的损失。
止损限价单： 与止损单类似，但在触发时提交的是限价单，可以更好地控制成交价格。
跟踪止损单： 止损价格会随着市场价格的上涨而自动调整，从而锁定利润并限制回撤。
冰山订单（或隐藏订单）： 将大额订单拆分成多个小额订单，以减少对市场价格的影响。

为了安全地使用交易接口，通常需要进行身份验证，例如使用API密钥和密钥。密钥需要妥善保管，避免泄露，以防止未经授权的交易。在使用交易接口时，务必仔细阅读交易所的API文档，了解接口的使用方法、请求频率限制以及其他相关规定，以确保交易的顺利进行和避免不必要的错误。

1. 下单 (POST /api/v5/trade/order):

该接口用于提交新的订单至欧易交易所。通过此接口，用户可以创建市价单、限价单以及其他类型的订单，执行买入或卖出操作。

请求参数:
- instId : 必选，交易对 ID。这是指你想交易的加密货币对，例如 "BTC-USDT" 表示比特币兑 USDT 的交易对。务必确保输入正确的交易对 ID。
- tdMode : 必选，交易模式。指定交易的保证金模式。"cash" 代表现货交易，"cross" 代表全仓保证金交易，"isolated" 代表逐仓保证金交易。选择适合你风险偏好的交易模式。
- side : 必选，买卖方向。指定订单的类型。"buy" 代表买入，"sell" 代表卖出。根据你的交易意图选择正确的方向。
- ordType : 必选，订单类型。定义订单的执行方式。"market" 代表市价单，以当前市场最优价格立即成交；"limit" 代表限价单，只有当市场价格达到或超过指定价格时才会成交； "post_only" 代表只挂单，如果订单会立即成交，则会被取消；"fok" 代表立即全部成交或立即取消 (Fill or Kill)，如果订单不能立即全部成交，则会被立即取消；"ioc" 代表立即成交剩余取消 (Immediate or Cancel)，订单会尽可能以当前市场最优价格成交，未成交部分会被立即取消。根据你的交易策略选择合适的订单类型。
- sz : 必选，下单数量。指定你想要买入或卖出的加密货币数量。数量必须大于交易所规定的最小交易单位。
- px : 可选，价格 (仅限价单需要)。如果订单类型为限价单 ("limit")，则必须指定价格。该价格是你希望成交的价格。市价单则不需要此参数。
- tag : 可选，订单标签。允许你为订单添加自定义标签，以便更好地跟踪和管理你的订单。该标签不会影响订单的执行。
- clOrdId : 可选，客户自定义ID。允许你为订单添加自定义订单ID，用于和自己系统关联。
- reduceOnly : 可选，只减仓。仅适用于具有仓位的交易对，设为true时只能减仓。
- tgtCcy : 可选 , 标的币种。市价单买入时，可以使用 quote_ccy 或 base_ccy。
响应示例:
以下是下单成功后返回的 JSON 响应示例。你需要解析此响应以确认订单是否已成功提交，并获取订单 ID。
```
{
  "code": "0",
  "msg": "",
  "data": [
    {
      "ordId": "3333333333333333",
      "clOrdId": "xxxxxxxxxxxxxxxxxxxxxxxxx",
      "tag": ""
    }
  ]
}
```
- code : "0" 表示请求成功，其他值表示错误。
- msg : 错误信息，如果 code 不为 "0"，则会包含错误描述。
- data : 包含订单信息的数组。
  - ordId : 订单 ID，由欧易交易所生成。
  - clOrdId : 客户端自定义订单 ID，如果请求中包含此参数，则会在此处返回。
  - tag : 订单标签，如果请求中包含此参数，则会在此处返回。

2. 撤单 (POST /api/v5/trade/cancel-order):

该接口用于撤销在交易平台上尚未完全成交的订单。通过此接口，用户可以主动取消挂单，从而灵活管理其交易策略。

请求参数:

instId : 必选，交易对 ID。用于指定要撤销订单的交易市场。例如，"BTC-USDT" 代表比特币与 USDT 的交易对。该参数必须准确，否则撤单请求将失败。
ordId : 必选，订单 ID。平台为每笔订单分配的唯一标识符。通过 ordId 可以精确定位需要撤销的订单。如果同时指定 ordId 和 clOrdId ，系统将优先使用 ordId 进行订单查找和撤销。
clOrdId : 可选，客户端订单 ID。用户自定义的订单标识符，方便用户在自己的系统中跟踪订单状态。如果只提供 clOrdId ，系统将根据此 ID 查找并撤销相应的订单。如果同时指定 ordId 和 clOrdId ，则 ordId 具有更高的优先级。

响应示例:

成功撤销订单后，服务器将返回包含撤单信息的 JSON 对象。 code 为 "0" 表示撤单成功。 msg 字段通常为空字符串，表示没有错误信息。 data 数组包含撤销订单的详细信息，例如平台订单 ID 和客户端订单 ID。

JSON 响应示例：


{
  "code": "0",
   "msg":  "",
  "data":  [
     {
        "ordId": "3333333333333333",
        "clOrdId": "xxxxxxxxxxxxxxxxxxxxxxxxx"
     }
   ]
}

字段说明：

code : 返回码。 "0" 表示成功，其他值表示失败。
msg : 错误信息。如果撤单失败，此字段将包含相应的错误描述。
data : 数据数组。包含撤销订单的详细信息。

ordId : 平台订单 ID。被撤销订单的平台唯一标识符。
clOrdId : 客户端订单 ID。被撤销订单的客户端自定义标识符。

注意事项：

如果订单已经成交或正在被处理，撤单请求可能会失败。
请务必验证返回的 code 值，以确认撤单是否成功。
在高并发场景下，撤单请求可能会受到延迟影响。

3. 获取订单详情 (GET /api/v5/trade/order):

该接口用于查询特定订单的完整详细信息，允许用户检索与其交易活动相关的关键数据。通过提供订单 ID 或客户端订单 ID，您可以获取关于该订单的执行状态、价格、数量和其他相关属性的全面信息。

请求参数:

instId : 必选，合约或交易对 ID，用于指定您想要查询的交易市场。例如，"BTC-USDT" 代表比特币与 USDT 的交易对， "ETH-USDT" 代表以太坊与泰达币的交易对。确保提供的交易对 ID 与您实际交易的标的物相符。
ordId : 必选，平台生成的唯一订单 ID，用于标识特定的交易指令。每个成功的订单创建都会生成一个唯一的 ordId ，这是检索订单信息的主要方式。
clOrdId : 可选，客户端自定义的订单 ID，允许用户使用易于识别的标识符来跟踪订单。如果同时提供 ordId 和 clOrdId ，系统将优先使用 ordId 进行订单查询。这使得用户可以使用自己的内部订单管理系统与交易所的 API 进行集成。客户端订单ID通常用于方便用户跟踪和管理自己的订单，对于交易所而言， ordId 才是唯一的订单标识符。

响应示例:

以下是一个 JSON 格式的响应示例，展示了订单详情接口返回的数据结构。响应包含了订单的状态、价格、数量、交易方向等关键信息。

{ "code": "0", "msg": "", "data": [ { "instId": "BTC-USDT", "ordId": "3333333333333333", "clOrdId": "xxxxxxxxxxxxxxxxxxxxxxxxx", "px": "20000", "sz": "1", "side": "buy", "ordType": "limit", "state": "filled", "avgPx": "20000", "fillSz": "1", "fillTime": "1678886400000" } ] }

字段解释：

code : 返回码，"0" 表示请求成功。非零值表示发生错误。
msg : 错误信息，当 code 不为 "0" 时，此字段包含错误的详细描述。
data : 包含订单详情的数组。通常，数组中只有一个元素，即请求的订单的信息。
instId : 交易对 ID，与请求参数中的 instId 对应。
ordId : 订单 ID，与请求参数中的 ordId 对应。
clOrdId : 客户端订单 ID，与请求参数中的 clOrdId 对应。
px : 订单的下单价格。
sz : 订单的下单数量。
side : 订单的交易方向，例如 "buy" (买入) 或 "sell" (卖出)。
ordType : 订单类型，例如 "limit" (限价单), "market" (市价单)。
state : 订单状态，例如 "open" (未成交), "filled" (已成交), "canceled" (已取消)。
avgPx : 平均成交价格，仅在订单已成交时有效。
fillSz : 已成交的数量，仅在订单已成交时有效。
fillTime : 最后一次成交的时间戳（毫秒）。

市场数据接口

市场数据接口提供实时的市场行情数据，这些数据对于算法交易、风险管理、市场分析至关重要。通过该接口，用户可以获取加密货币的价格、成交量、买卖盘深度等关键信息。精确的数据更新频率，例如每秒更新多次，能够保证用户掌握最新的市场动态，及时调整交易策略。

具体来说，价格数据包括最新成交价、最高价、最低价、开盘价等。成交量数据反映了市场的活跃程度，可以帮助用户判断趋势的强弱。深度数据，也称为订单簿数据，展示了市场上买单和卖单的分布情况，有助于用户了解市场的供需关系，评估价格的支撑位和阻力位。深度数据通常以不同价格档位的买卖单量来呈现，例如买一价、买二价、卖一价、卖二价等，以及对应的挂单量。一些高级的市场数据接口还会提供历史成交数据，供用户进行回溯测试和统计分析。

部分市场数据接口还提供聚合数据，例如VWAP（成交量加权平均价），用于更准确地反映一段时间内的平均交易价格。为了方便用户进行程序化交易，这些接口通常支持多种数据格式，如JSON、CSV等，并提供各种编程语言的SDK（软件开发工具包）。

1. 获取行情信息 (GET /api/v5/market/ticker):

此接口提供特定交易对的实时行情数据快照，是了解市场动态的关键入口。通过此接口，用户可以获取交易对的最新成交价格、买卖盘口信息及成交量等关键指标，从而辅助交易决策。

请求参数:
- instId : 必选。交易对ID，用于指定需要查询的交易市场。例如，"BTC-USDT" 代表比特币与USDT的交易对。准确的交易对ID是成功获取数据的必要条件。请注意大小写和分隔符，确保与交易所的规范一致。
响应示例:
接口返回JSON格式的数据，包含交易状态码、消息以及实际的行情数据。以下是一个示例：
```
{
   "code": "0",
   "msg": "",
   "data": [
     {
       "instId": "BTC-USDT",
       "last": "20000",
       "askPx": "20001",
       "bidPx": "19999",
       "askSz": "1",
       "bidSz": "1",
       "vol24h": "1000"
    }
  ]
}
```
字段解释:
- code : 返回码，"0" 通常表示请求成功。非 "0" 值表示发生错误，需要根据 msg 字段排查问题。
- msg : 返回消息，提供关于请求状态的详细信息。如果 code 不是 "0"，该字段会包含错误描述。
- data : 包含实际行情数据的数组。通常，该数组只包含一个元素，对应于请求的交易对。

2. 获取深度数据 (GET /api/v5/market/depth):

该接口用于获取指定交易对的实时深度数据，即买卖盘口信息。深度数据反映了市场上买方和卖方的挂单情况，是进行交易决策的重要参考依据。

请求参数:
- instId : 必选，交易对 ID，用于指定需要查询的交易对。例如，"BTC-USDT" 表示比特币对美元的交易对。"ETH-BTC"表示以太坊对比特币的交易对。务必确保提供的交易对 ID 正确且存在于交易所中。
- limit : 可选，深度数量，表示返回的买卖盘口深度档位数量。默认为 20 档，最大允许设置为 400 档。设置较大的 limit 值可以获取更详细的深度信息，但也可能增加数据传输量和处理时间。根据实际需求调整该参数，在深度和性能之间取得平衡。
响应示例:
以下 JSON 示例展示了深度数据接口返回的数据结构。其中， asks 数组表示卖盘挂单， bids 数组表示买盘挂单。每个挂单包含价格和数量信息。
```
        
{
    "code": "0",
    "msg": "",
    "data": [
        {
            "asks": [
                [
                    "20001",  // 卖一价：价格为 20001
                    "1",      // 卖一量：数量为 1
                    "1"       // 订单数量，部分交易所会提供
                ],
                [
                    "20002",  // 卖二价：价格为 20002
                    "2",      // 卖二量：数量为 2
                    "1"       // 订单数量
                ]
            ],
            "bids": [
                [
                    "19999",  // 买一价：价格为 19999
                    "1",      // 买一量：数量为 1
                    "1"       // 订单数量
                ],
                [
                    "19998",  // 买二价：价格为 19998
                    "2",      // 买二量：数量为 2
                    "1"       // 订单数量
                ]
            ]
        }
    ]
}
        
    
```
字段解释：
- code : 返回码，"0" 表示请求成功。
- msg : 错误信息，当请求失败时会包含错误描述。
- data : 包含深度数据的数组，通常只包含一个元素。
- asks : 卖盘挂单数组，每个元素是一个数组，包含价格、数量和订单数量。价格按从低到高排序。
- bids : 买盘挂单数组，每个元素是一个数组，包含价格、数量和订单数量。价格按从高到低排序。
数据使用注意事项：
- 深度数据是市场瞬时状态的快照，会随市场变化而快速更新。
- 需要根据具体的交易策略和风险承受能力，合理利用深度数据进行交易决策。
- 部分交易所可能会对深度数据的访问频率进行限制，需要遵守交易所的 API 使用规则。
- 在进行高频交易或算法交易时，应考虑深度数据的延迟和更新频率。

WebSockets API

欧易交易所提供强大的 WebSockets API，专为需要高速、低延迟实时数据访问的用户而设计。此 API 允许开发者建立双向持久连接，通过单个 TCP 连接实时接收高度动态的市场数据和账户信息流，从而显著降低延迟并提高应用程序性能。WebSockets API 有效地消除了传统 HTTP 轮询带来的开销，数据更新将以推送模式实时发送到客户端，无需客户端主动请求，极大提升了数据获取效率。

通过 WebSockets API，开发者可以实时获取各种市场数据，包括但不限于：实时交易价格、订单簿更新、交易量统计、K 线数据（包括各种时间周期）、指数价格等。对于账户信息，WebSockets API 允许用户实时监控账户余额变动、订单状态更新、仓位变化等关键信息，从而实现快速响应市场变化，优化交易策略。

使用 WebSockets API 需要先进行身份验证。身份验证过程通常涉及生成 API 密钥和签名，并将其包含在连接请求中。欧易的官方文档提供了详细的身份验证流程和代码示例，方便开发者快速上手。

WebSockets API 支持多种编程语言和平台，开发者可以使用任何支持 WebSocket 协议的客户端库来连接和使用 API。流行的编程语言如 Python、JavaScript、Java 和 C++ 都有相应的 WebSocket 库可供选择。开发者可以根据自己的技术栈和项目需求选择合适的库。

为了确保最佳性能和稳定性，欧易建议开发者仔细阅读 API 文档，了解 API 的使用限制和最佳实践，例如连接频率限制、数据订阅策略、错误处理机制等。合理地使用 API 可以有效地避免潜在的问题，并充分发挥 WebSockets API 的优势。

1. 连接:

与OKX WebSocket API建立连接至关重要，它允许您实时接收市场数据和账户信息。连接地址根据您需要访问的数据类型而有所不同。对于公共频道，用于获取市场行情、交易对信息、深度数据等公开信息，您需要连接到以下地址： wss://ws.okx.com:8443/ws/v5/public 。公共频道允许未经验证的用户访问。

若要访问私有频道，例如进行交易、查询账户余额、获取订单状态等需要身份验证的信息，您需要连接到以下地址： wss://ws.okx.com:8443/ws/v5/private 。私有频道需要用户通过API密钥进行身份验证，确保只有授权用户才能访问其账户信息和执行操作。在连接私有频道之前，请务必参考OKX官方文档，了解身份验证的具体流程和签名方法，以确保连接安全可靠。正确的身份验证能够保障您的交易安全和账户隐私。

请注意，根据网络状况和服务器负载，连接可能会出现波动。建议您在应用程序中实现自动重连机制，以确保数据流的稳定性。同时，定期检查您的连接状态，并根据OKX官方公告及时调整连接参数，以获得最佳的API体验。

2. 订阅频道：

通过发送符合规范的 JSON 格式消息来订阅特定的频道，从而接收实时数据更新。订阅操作允许客户端指定感兴趣的数据类型，例如市场行情、订单簿更新或交易信息。

以下示例展示了如何订阅 BTC-USDT 交易对的行情信息（tickers）：

{
  "op": "subscribe",
  "args": [
     {
       "channel": "tickers",
       "instId": "BTC-USDT"
      }
   ]
}

参数解释：

op : 操作类型，此处为 "subscribe"，表示订阅。
args : 一个数组，包含一个或多个订阅参数对象。每个对象定义了要订阅的频道和相关实例 ID。
channel : 指定要订阅的频道名称，例如 "tickers" (行情信息)、"orderbook" (订单簿)、"trades" (交易信息) 等。不同的交易所支持的频道名称可能有所不同，请参考具体的API文档。
instId : 指定要订阅的实例 ID，通常是交易对的名称，例如 "BTC-USDT" (比特币/USDT)、"ETH-BTC" (以太坊/比特币) 等。实例 ID 的格式也可能因交易所而异。

重要提示：

成功发送订阅消息后，服务器将开始向客户端推送相关数据更新。
订阅多个频道和实例 ID 可以通过在 args 数组中包含多个参数对象来实现。
取消订阅可以使用 "unsubscribe" 操作，格式与订阅类似，只需将 op 的值更改为 "unsubscribe" 即可。
不同的加密货币交易所可能使用不同的 API 格式和参数。在实际应用中，请务必参考交易所的官方 API 文档，以确保订阅请求的正确性。

3. 认证:

为了确保只有授权用户才能访问私有频道的数据，订阅私有频道需要进行严格的身份验证过程。这意味着您需要提供您的API密钥、密码、时间戳以及基于这些信息生成的签名。

您需要发送一个特定格式的 JSON 消息来进行认证。以下 JSON 结构展示了如何构建您的认证请求：


{
   "op": "login",
  "args": [
      {
         "apiKey": "YOUR_API_KEY",
       "passphrase":  "YOUR_PASSPHRASE",
       "timestamp": "YOUR_TIMESTAMP",
       "sign": "YOUR_SIGNATURE"
    }
  ]
}

参数说明：

apiKey : 您的API密钥。它用于识别您的账户，并且是您访问API的凭证之一。请务必妥善保管您的API密钥，避免泄露。
passphrase : 您的密码短语。这是为了增强安全性而设置的，您可以将它理解为API密钥的补充密码。与API密钥一样，请务必保管好您的密码短语。
timestamp : 时间戳。这是一个Unix时间戳，表示请求发送的时间。时间戳有助于防止重放攻击，即攻击者截获并重用有效的请求。您需要确保您的时间戳在合理的时间范围内，通常是几分钟内。
sign : 签名。这是使用您的API密钥、密码短语、时间戳以及其他请求参数生成的数字签名。签名用于验证请求的完整性和真实性，确保请求没有被篡改，并且确实来自您。签名的生成算法通常是 HMAC-SHA256，具体算法细节请参考API文档。

重要提示：

请将 YOUR_API_KEY 、 YOUR_PASSPHRASE 、 YOUR_TIMESTAMP 和 YOUR_SIGNATURE 替换为您的实际值。
签名算法和具体参数的顺序可能因交易所而异，请务必参考您所使用的交易所的API文档。
请注意保护您的API密钥和密码短语，避免泄露，否则可能导致您的账户被盗用。
如果认证失败，请检查您的API密钥、密码短语、时间戳和签名是否正确。同时，也要检查您的网络连接是否正常。

错误处理

欧易 API 通过 HTTP 状态码和 JSON 格式的响应来明确指示请求过程中出现的错误。通过分析这些错误信息，开发者可以有效地诊断和解决问题。常见的 HTTP 状态码及其含义包括：

400 Bad Request : 此状态码表示客户端提交的请求存在错误，例如请求参数缺失、格式不正确或者参数值超出允许范围。开发者需要仔细检查请求的参数，确保符合 API 文档的要求。
401 Unauthorized : 表明客户端尝试访问需要身份验证的资源，但未提供有效的身份验证凭据。这通常意味着缺少 API 密钥或提供的密钥不正确。开发者应确保已正确配置 API 密钥并已将其包含在请求头中。
403 Forbidden : 与 401 类似， 403 也与权限相关，但意味着客户端已通过身份验证，但仍然没有足够的权限访问请求的资源。这可能是由于账户权限不足或 API 使用限制。开发者需要检查账户的权限设置，并确保其拥有访问所需资源的权限。
429 Too Many Requests : 表示客户端在短时间内发送了过多的请求，触发了 API 的限流机制。为了维护系统的稳定性，API 会对请求频率进行限制。开发者应实施速率限制策略，例如使用指数退避算法，以避免触发此错误。
500 Internal Server Error : 指示服务器在处理请求时遇到了意外错误。这通常是服务器端的问题，例如程序错误、数据库连接问题或其他内部故障。开发者可以稍后重试请求，或者联系欧易的技术支持团队寻求帮助。

当 API 返回错误时，响应的 JSON 格式数据通常包含 code 和 msg 两个关键字段。 code 字段提供了一个数字或字符串形式的错误代码，用于唯一标识特定类型的错误。 msg 字段则包含了更详细的错误信息，用自然语言描述了错误的具体原因。开发者应该解析这些字段，并根据错误代码采取相应的处理措施。举例来说：

以下是一个示例 JSON 响应，展示了 API 如何报告请求参数错误：

{
   "code": "60001",
   "msg":  "Invalid parameter"
}

在这个例子中， code 字段的值为 "60001" ，表示一个无效参数错误。 msg 字段的值为 "Invalid parameter" ，更详细地说明了错误的性质。开发者可以通过检查 code 字段的值，来判断是否发生了无效参数错误，并根据 msg 字段中的信息来确定哪个参数无效，然后进行相应的调整。

为确保应用程序的健壮性和可靠性，开发者应仔细阅读欧易 API 的官方文档，深入了解每个 API 接口可能返回的错误代码以及对应的错误信息。通过全面理解这些信息，开发者可以编写更完善的错误处理逻辑，从而有效地诊断和解决问题，提升用户体验。

欧易加密资产多元化：稳健投资，抓住机遇！

100 2025-03-09