OKX API终极指南：玩转自动化交易，秒变量化大神！

指南 2025-03-08 102 次浏览

本教程全面讲解OKX API的集成和使用，涵盖API密钥的生成，接口认证，常用交易接口的调用方法，及常见问题解决。助你快速上手OKX API，实现交易自动化，并成为量化交易高手！

OKX API接口调用教程

1. 概述

本文档旨在提供一个全面的OKX API接口调用指南，旨在帮助开发者高效、安全地接入OKX交易平台，实现包括但不限于自动化交易、市场数据分析、账户管理等功能。我们将由浅入深地介绍API密钥的申请与管理、接口的多种认证方式（例如，签名认证），并详细阐述常用REST API接口和WebSocket API接口的调用方法，同时列举常见问题及其解决方案，力求使开发者能够快速上手并顺利使用OKX API。

OKX API接口提供了强大的功能，允许开发者通过程序化方式访问平台服务。理解其工作原理和最佳实践对于构建可靠的应用至关重要。本指南将涵盖HTTP请求的构建、响应数据的解析、错误处理机制以及风控措施，以确保交易安全和数据准确性。同时，我们将提供代码示例（建议使用Python等常用编程语言）来演示如何使用API进行下单、查询账户余额、获取实时行情等操作。

使用OKX API进行交易具有显著的优势，包括更高的交易效率、更低的交易成本以及更强的风控能力。然而，API的使用也需要一定的技术基础和安全意识。开发者需要严格遵守OKX的API使用规则，并采取必要的安全措施来保护API密钥和交易数据。例如，建议使用环境变量或加密文件存储API密钥，避免将其直接硬编码在代码中。同时，需要定期审查API密钥的使用情况，及时发现和处理潜在的安全风险。

2. 准备工作

2.1 注册OKX账号

要开始在OKX上进行加密货币交易，您需要注册一个OKX账号。如果您尚未拥有OKX账号，请访问OKX官方网站（请确保访问官方域名，谨防钓鱼网站），并按照注册流程进行操作。

注册过程中，您通常需要提供以下信息：

  • 邮箱地址或手机号码： 用于接收验证码和账户安全通知。建议使用常用的邮箱或手机号，并妥善保管，开启二次验证（2FA）。
  • 设置密码： 密码强度非常重要，应包含大小写字母、数字和特殊字符，长度至少8位以上，避免使用容易被猜测的密码，并定期更换密码。
  • 身份验证： 根据OKX的KYC（了解你的客户）政策，您可能需要提供身份证明文件（如身份证、护照或驾驶执照）以及居住地址证明，以便完成身份验证，提高账户交易限额，并符合监管要求。请务必提供真实有效的身份信息。

完成注册后，请务必开启两步验证（2FA），例如使用Google Authenticator或短信验证，以增强账户安全性。这是保护您的资金免受未经授权访问的重要措施。

2.2 创建API密钥

为了能够通过程序化方式访问和操作OKX交易所，你需要创建一个API密钥。创建API密钥的过程允许你精细地控制访问权限，从而提高账户的安全性。

登录你的OKX账户。在账户控制面板中，导航至API管理页面。通常，这个选项可以在账户设置或安全设置的子菜单中找到。进入API管理页面后，点击“创建API密钥”或类似按钮，开始创建流程。

在创建API密钥的过程中，你需要设置以下关键参数：

  • API名称： 为你的API密钥指定一个清晰且具有描述性的名称。这个名称应该能够让你轻易地识别出该密钥的用途，例如“交易机器人”、“数据分析”等。良好的命名习惯有助于管理多个API密钥。
  • 绑定IP地址： (可选，但强烈建议) 出于安全考虑，强烈建议将API密钥绑定到特定的IP地址。这意味着只有来自指定IP地址的请求才会被允许使用该密钥。如果你知道你的应用程序将从哪些IP地址发出请求（例如，你的服务器的IP地址），那么绑定IP地址可以显著降低密钥泄露带来的风险。如果你需要从多个IP地址访问API，你可以添加多个IP地址到白名单。
  • 交易权限： 仔细评估你的应用程序需要哪些权限，并仅授予必要的权限。OKX提供了多种权限选项，例如交易（允许买卖加密货币）、提现（允许转移资金）、查看账户信息（允许读取账户余额和交易历史）等。始终遵循最小权限原则：只授予API密钥完成其任务所需的最低权限。例如，如果你的应用程序只需要读取市场数据，那么你就不应该授予它交易或提现的权限。
  • 资金密码： 为了增强安全性，创建API密钥时，系统会要求你验证你的资金密码。这是确认你是账户所有者的重要步骤。

成功创建API密钥后，系统将生成三个关键信息： API Key （也称为公钥）、 Secret Key （也称为私钥）和 Passphrase 。 API Key 用于识别你的应用程序， Secret Key 用于对API请求进行签名， Passphrase 是在某些需要额外安全验证的API接口中使用的密码。务必采取以下措施来保护这些信息：

  • 安全存储： 将 API Key 、 Secret Key 和 Passphrase 存储在安全的地方。永远不要将它们硬编码到你的应用程序中，或者存储在公共代码仓库中。
  • 权限控制： 限制对存储这些信息的文件的访问权限。
  • 环境变量： 考虑使用环境变量来存储这些敏感信息。
  • 不要泄露： 绝对不要将 Secret Key 和 Passphrase 泄露给任何人。如果你的密钥泄露了，立即撤销该密钥并创建一个新的密钥。
  • 定期更换： 出于安全考虑，建议定期更换你的API密钥。

请注意，任何拥有你的 Secret Key 的人都可以模拟你的账户执行操作。因此，务必妥善保管这些信息，并定期审查你的API密钥权限。

重要提示: OKX API密钥具有很高的权限，泄露后可能导致资产损失。请务必采取安全措施保护API密钥的安全。

3. API认证

OKX API采用两种主要的认证机制，旨在保障用户数据的安全性和访问控制，确保只有授权的应用程序才能访问用户的账户信息和执行交易操作。

  • HTTP Header Authentication (HTTP头部认证): 这是OKX API中应用最广泛的认证方法。大多数API接口，特别是RESTful风格的接口，都要求通过HTTP请求的头部信息来提供认证凭证。 开发者需要在每个HTTP请求的头部中包含预先生成的API Key、Secret Key以及签名 (Signature)。 API Key用于标识开发者身份，Secret Key用于生成签名，签名则是对请求内容进行加密处理，以防止篡改。 OKX服务器会验证这些头部信息，确保请求的合法性和完整性。 这种认证方式能够有效地防止未经授权的访问，并确保数据在传输过程中的安全性。 开发者必须妥善保管自己的API Key和Secret Key，避免泄露，否则可能导致安全风险。
  • WebSocket Authentication (WebSocket认证): 针对WebSocket接口，OKX采用了不同的认证流程。 由于WebSocket连接是持久性的双向通信通道，认证需要在连接建立初期完成。 开发者通常需要在建立WebSocket连接后，发送一个包含认证信息的特殊消息 (Authentication Message) 到OKX服务器。 该消息中通常会包含API Key、时间戳 (Timestamp) 和签名 (Signature)。 服务器验证这些信息后，如果认证成功，则会保持WebSocket连接，允许应用程序进行实时数据订阅和交易操作。 WebSocket认证对于实时性要求高的应用程序至关重要，例如市场数据订阅和快速交易等。 通过建立持久的WebSocket连接，应用程序可以避免频繁地进行HTTP请求，从而提高响应速度和效率。 同样，开发者也需要保护好自己的API Key和Secret Key，以防止WebSocket连接被恶意利用。

3.1 HTTP Header Authentication

为了保障API接口的安全访问，在使用HTTP Header Authentication时，需要在每个请求的HTTP头部（Header）中添加身份验证信息。 这种方式为您的账户提供了一层额外的安全保障，确保只有经过授权的请求才能访问您的数据和执行操作。

以下是需要在HTTP Header中包含的关键信息：

  • OK-ACCESS-KEY : 您的API Key。这是一个公开的密钥，用于标识您的账户。 API Key 可以在您的账户设置中生成和管理。请妥善保管您的API Key，避免泄露。
  • OK-ACCESS-SIGN : 请求签名。这是一个通过使用您的 Secret Key 和请求参数生成的加密签名。服务器会使用相同的算法验证签名，以确保请求的完整性和真实性，防止请求被篡改。签名算法通常采用 HMAC-SHA256 或类似的安全哈希算法。
  • OK-ACCESS-TIMESTAMP : 当前Unix时间戳 (秒)。时间戳用于防止重放攻击。 服务器会检查时间戳，如果时间戳与服务器当前时间相差过大，请求将被拒绝。时间戳必须是自 Unix 纪元（1970 年 1 月 1 日 00:00:00 UTC）以来的秒数。
  • OK-ACCESS-PASSPHRASE : 您的Passphrase。Passphrase 是一个您设置的额外密码，用于增强安全性。类似于双重验证中的第二重因素。 它用于加密和解密敏感数据，进一步保护您的账户安全。请务必牢记您的Passphrase，并妥善保管。

请注意，所有Header参数均需正确设置，大小写敏感，且必须按照上述说明进行配置，否则API请求将会失败。 建议参考官方文档提供的示例代码和工具库，以确保正确生成签名和构建请求。

3.1.1 生成签名

生成签名的过程对于保障API请求的安全性至关重要。以下算法详细描述了如何使用HMAC SHA256算法结合Base64编码，利用时间戳、请求方法、请求路径和请求体生成一个唯一的签名。

  1. 数据拼接: 将 timestamp （时间戳，通常以秒为单位）、 请求方法 （如GET, POST, PUT, DELETE等HTTP方法）、 请求路径 （例如：/api/v5/account/balance，指向特定的API端点）以及 请求体 （包含请求数据的JSON字符串）按照预定的顺序拼接成一个字符串。确保拼接顺序的正确性是生成有效签名的关键。
  2. HMAC SHA256加密: 使用您的 Secret Key （保密密钥）对拼接后的字符串进行HMAC SHA256加密。HMAC (Hash-based Message Authentication Code) 是一种使用加密哈希函数和密钥来生成消息摘要的算法，用于验证数据的完整性和真实性。SHA256是一种广泛使用的安全哈希算法，它生成一个256位的哈希值。
  3. Base64编码: 将HMAC SHA256加密后的二进制结果进行Base64编码。Base64是一种将二进制数据转换为ASCII字符串的编码方式，常用于在不支持直接传输二进制数据的协议中传输数据。Base64编码后的签名可以安全地包含在HTTP请求头中。

以下Python代码示例展示了如何实现上述签名生成算法： 


import hashlib
import hmac
import base64
import time

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

    :param timestamp: 当前时间戳(秒)，例如：int(time.time())
    :param method: 请求方法 (GET, POST, PUT, DELETE)，必须大写
    :param request_path: 请求路径 (例如: /api/v5/account/balance)，包含斜杠
    :param body: 请求体 (JSON字符串)，如果无请求体则为空字符串 ""
    :param secret_key: 你的Secret Key，从你的API密钥管理页面获取
    :return: 签名字符串
    """
    message = str(timestamp) + method + request_path + body
    mac = hmac.new(secret_key.encode('utf-8'), message.encode('utf-8'), hashlib.sha256)
    d = mac.digest()
    return base64.b64encode(d).decode('utf-8')

代码解释：

  • timestamp : 务必使用当前时间戳，通常以秒为单位。与服务器时间偏差过大可能导致签名验证失败。
  • method : 请求方法必须为大写，例如 "GET"、"POST"。
  • request_path : 请求路径必须包含斜杠，并且与API文档中定义的路径完全一致。
  • body : 如果请求没有请求体，则 body 参数应为空字符串 "" 。
  • secret_key : Secret Key 必须妥善保管，切勿泄露。
  • hmac.new(secret_key.encode('utf-8'), message.encode('utf-8'), hashlib.sha256) : 使用 UTF-8 编码对 secret_key 和 message 进行编码，以确保字符串的正确处理。
  • base64.b64encode(d).decode('utf-8') : 将加密后的二进制数据进行Base64编码，并将结果解码为UTF-8字符串，以便于在HTTP头中传输。

示例

时间戳 (timestamp) 是一个至关重要的参数，用于确保API请求的时效性，防止重放攻击。通常，它表示自 Unix 纪元（1970 年 1 月 1 日 00:00:00 UTC）以来经过的秒数。你可以使用编程语言内置的时间函数获取当前时间戳，并将其转换为字符串类型。 timestamp = str(int(time.time())) 方法 (method) 定义了HTTP请求的类型。常见的类型包括 GET（用于检索数据）、POST（用于创建数据）、PUT（用于更新数据）和 DELETE（用于删除数据）。根据 API 的设计，选择合适的 HTTP 方法。 method = 'GET' 请求路径 (request_path) 是 API 端点的 URL 路径部分，它指定了要访问的特定资源。例如， /api/v5/account/balance 表示获取账户余额信息的 API 端点。 request_path = '/api/v5/account/balance' 请求体 (body) 包含了要发送到 API 服务器的数据。对于 GET 请求，通常没有请求体，因此将其设置为空字符串。而 POST、PUT 等请求则可能包含 JSON、XML 等格式的数据。 body = '' # GET请求通常没有body

API 密钥 (api_key) 是用于标识您的身份的公开密钥。它类似于用户名，用于告诉 API 服务器您是谁。请务必妥善保管您的 API 密钥，不要将其泄露给他人。 api_key = 'YOUR_API_KEY' 私钥 (secret_key) 是用于生成签名的秘密密钥。它类似于密码，用于验证您的身份和确保请求的完整性。私钥必须严格保密，绝对不能泄露给任何人。一旦私钥泄露，您的账户将面临风险。 secret_key = 'YOUR_SECRET_KEY' 口令 (passphrase) 是一些API中可选的安全措施，用于增加安全性，对私钥进行加密。它是一个额外的密码，用于保护您的账户安全。 passphrase = 'YOUR_PASSPHRASE'

签名 (signature) 是通过使用时间戳、HTTP 方法、请求路径、请求体和私钥等参数生成的加密字符串。它用于验证请求的合法性和完整性。签名算法通常使用哈希函数（如 SHA256）和消息认证码（MAC）算法（如 HMAC）。正确生成签名是成功调用 API 的关键。 signature = generate_signature(timestamp, method, request_path, body, secret_key)

为了调试和验证签名是否正确生成，可以将时间戳和签名打印出来。 print(f"Timestamp: {timestamp}") print(f"Signature: {signature}")

3.1.2 发送HTTP请求

在区块链应用开发中，与外部API或服务交互经常需要发送HTTP请求。Python的 requests 库是一个强大且易于使用的工具，能够简化发送各种类型的HTTP请求，例如GET、POST等。

以下是一个使用Python requests 库发送HTTP GET请求的示例： 

import requests

# 定义目标URL
url = "https://api.example.com/data"

# 发送GET请求
try:
    response = requests.get(url)

    # 检查响应状态码
    response.raise_for_status()  # 如果状态码不是200，则抛出HTTPError异常

    # 解析JSON响应
    data = response.()

    # 打印响应数据
    print(data)

except requests.exceptions.RequestException as e:
    print(f"发生错误: {e}")

上述代码首先导入 requests 库。然后，定义要访问的API的URL。使用 requests.get() 函数发送GET请求，并将响应保存在 response 变量中。 response.raise_for_status() 方法用于检查HTTP响应状态码，如果状态码表示错误（例如404或500），则会抛出一个异常，从而便于错误处理。如果请求成功，可以使用 response.() 方法将响应内容解析为JSON格式，方便后续处理。 代码段中添加了异常处理，使用了`try...except`块来捕获可能发生的 requests.exceptions.RequestException 异常，例如网络连接错误或超时。 这使得代码更加健壮，能够处理各种潜在的错误情况。

替换成你的API密钥、Secret Key和Passphrase

为了成功访问和操作OKX交易所的API，你需要替换以下占位符为你自己的有效凭证。这些凭证对于你的账户安全至关重要，请妥善保管，切勿泄露给他人。

api_key = 'YOUR_API_KEY'

api_key 代表你的API密钥，它是用于识别你的账户并授权访问API的关键凭证。通过OKX交易所账户生成，每个密钥与特定的权限集关联，谨慎设置权限以符合你的应用需求。

secret_key = 'YOUR_SECRET_KEY'

secret_key 是与你的API密钥配对的私密密钥。它用于对你的API请求进行签名，确保请求的真实性和完整性。类似于密码，绝对不能共享给任何人。遗失Secret Key需要重新生成API Key。

passphrase = 'YOUR_PASSPHRASE'

passphrase 是你在创建API密钥时设置的密码短语。它增加了额外的安全层，用于加密和解密你的API请求。必须牢记此短语，并在每次使用API密钥时提供。

请将以上代码块中的 'YOUR_API_KEY' 、 'YOUR_SECRET_KEY' 和 'YOUR_PASSPHRASE' 替换成你从OKX交易所获得的实际值。

base_url = 'https://www.okx.com'

base_url 定义了OKX API的根URL。 https://www.okx.com 指向OKX交易所的正式生产环境。请注意，在开发和测试阶段，OKX也提供沙箱环境（模拟交易环境），但正式交易务必使用生产环境URL，以免造成不必要的损失。

base_url = 'https://www.okx.com' # OKX API 根域名，用于模拟环境 (仅供测试和开发使用，正式环境请确认)

定义 API 端点 endpoint = '/api/v5/account/balance' ，该端点用于获取账户余额信息。 API 请求方法设定为 method = 'GET' ，表示这是一个获取数据的请求。获取当前时间戳 timestamp = str(int(time.time())) ，时间戳是生成签名的关键要素，必须是整数且转换为字符串格式。由于是 GET 请求，请求体 body = '' 为空。

通过调用 generate_signature(timestamp, method, endpoint, body, secret_key) 函数生成签名。此签名用于验证请求的合法性，防止未经授权的访问。其中， secret_key 必须妥善保管。

构建 HTTP 请求头 headers ，包含以下字段：

  • 'OK-ACCESS-KEY': api_key ：您的 API 密钥，用于标识您的身份。
  • 'OK-ACCESS-SIGN': signature ：生成的签名，用于验证请求的完整性和合法性。
  • 'OK-ACCESS-TIMESTAMP': timestamp ：请求的时间戳，防止重放攻击。
  • 'OK-ACCESS-PASSPHRASE': passphrase ：您的 passphrase，用于增强安全性。

构造完整的 API 请求 URL： url = base_url + endpoint ，将根域名和端点拼接在一起。

使用 try...except 块处理请求，以捕获可能发生的异常。

发起 GET 请求： response = requests.get(url, headers=headers) ，将 URL 和请求头传递给 requests.get() 函数。

使用 response.raise_for_status() 检查 HTTP 状态码。如果状态码表示错误（例如 400、401、500），则会引发异常。 

print(response.())

捕获请求过程中可能发生的异常： except requests.exceptions.RequestException as e: 。打印错误信息： print(f"请求失败: {e}") ，方便调试和问题排查。

3.2 WebSocket 认证

WebSocket 的认证过程相较于简单的 HTTP 认证而言，更为复杂，需要建立持续连接并进行双向数据传输。客户端需要构建一个特定的认证请求，并通过 WebSocket 连接将其发送到服务器。服务器收到请求后，会验证客户端的身份，并决定是否允许建立连接。

认证请求通常采用 JSON 格式，包含操作类型、参数等关键信息。下面是一个典型的认证请求示例： 

{
  "op": "login",
  "args": [
    {
      "apiKey": "YOUR_API_KEY",
      "timestamp": "CURRENT_TIMESTAMP",
      "sign": "SIGNATURE"
    }
  ]
}

其中， apiKey 代表您的 API 密钥，用于标识您的身份。 timestamp 是当前 Unix 时间戳，精确到秒，用于防止重放攻击。 sign 是签名，用于验证请求的完整性和真实性，防止篡改。 这三个参数是必不可少的。

签名的生成方式与 HTTP Header Authentication 类似，但拼接的字符串有所区别。WebSocket 认证使用的签名字符串通常包含时间戳、HTTP 方法、请求路径等要素。具体如下：

timestamp + 'GET' + '/users/self/verify' + ''

将上述字符串按照顺序拼接后，使用您的 Secret Key 进行 HMAC SHA256 加密，并对结果进行 Base64 编码。HMAC SHA256 确保数据的完整性和认证性，Base64 编码则将二进制数据转换为文本格式，方便传输。

以下是一个使用 Python 的 websocket-client 库进行 WebSocket 认证的示例代码。该示例展示了如何生成签名，并构建认证请求： 

import websocket
import hmac
import hashlib
import time
import base64

def generate_websocket_signature(timestamp, secret_key):
    """
    生成 OKX WebSocket 签名
    """
    message = str(timestamp) + 'GET' + '/users/self/verify' + ''
    mac = hmac.new(secret_key.encode('utf-8'), message.encode('utf-8'), hashlib.sha256)
    d = mac.digest()
    return base64.b64encode(d).decode('utf-8')

替换成你的API密钥和Secret Key

在访问加密货币交易所的API时，身份验证至关重要。你需要将以下代码中的'YOUR_API_KEY'和'YOUR_SECRET_KEY'替换为你从交易所获得的实际API密钥和Secret Key。 API密钥用于识别你的账户，而Secret Key用于生成签名，以确保请求的安全性。 

api_key = 'YOUR_API_KEY'
secret_key = 'YOUR_SECRET_KEY'

时间戳是自Unix纪元（1970年1月1日00:00:00 UTC）以来经过的秒数，它在API请求中扮演着重要的角色，通常用于防止重放攻击。以下代码展示如何生成时间戳，并使用Secret Key对其进行签名，从而创建一个安全的身份验证令牌。 

timestamp = str(int(time.time()))
signature = generate_websocket_signature(timestamp, secret_key)

为了成功连接到交易所的WebSocket API，你需要构建一个包含必要身份验证参数的登录参数对象。这个对象通常包括你的API密钥、生成的时间戳以及使用Secret Key创建的签名。以下代码展示了如何构建这样的登录参数对象，以便你可以安全地连接到WebSocket API。 

login_params = {
   "op": "login",
   "args": [
      {
        "apiKey": api_key,
        "timestamp": timestamp,
       "sign": signature
     }
   ]
}

一旦你有了API密钥、Secret Key、时间戳和签名，你就可以使用这些信息来建立与交易所WebSocket服务器的连接。下面的代码展示了如何使用Python的 websocket 库连接到OKX交易所的公共频道。请注意，不同的交易所可能使用不同的WebSocket URL，务必根据交易所提供的文档进行调整。公共频道提供市场数据，无需额外权限即可访问。 

ws = websocket.create_connection("wss://ws.okx.com:8443/ws/v5/public")  # 公共频道

ws = websocket.create_connection("wss://ws.okx.com:8443/ws/v5/private") # 私有频道，需要登录

此代码段展示了如何使用Python的`websocket-client`库与OKX交易所建立WebSocket连接，访问其私有频道。需要注意的是，私有频道需要进行身份验证才能访问。`wss://ws.okx.com:8443/ws/v5/private` 是OKX WebSocket API的私有频道端点，`websocket.create_connection()` 函数用于创建到该端点的WebSocket连接。确保已安装 `websocket-client` 库，可以通过 `pip install websocket-client` 命令进行安装。

ws.send(.dumps(login_params))

建立连接后，需要发送包含身份验证信息的`login_params`到服务器。这些参数通常包括API密钥、签名和其他安全凭证，用于验证用户的身份和授权。`.dumps()` 函数将Python字典对象转换为JSON字符串，以便通过WebSocket发送。`login_params` 变量需要根据OKX的API文档进行配置，包含正确的身份验证信息。 务必妥善保管您的API密钥，避免泄露。

result = ws.recv() print(result)

发送身份验证信息后，使用 `ws.recv()` 函数接收来自服务器的响应。该响应通常包含身份验证结果，指示登录是否成功。接收到的数据以字符串形式存储在 `result` 变量中。`print(result)` 用于将接收到的响应打印到控制台，以便查看身份验证结果和后续的数据流。 根据返回的 `result` 可以判断登录是否成功，以及是否需要重试或检查 `login_params` 是否正确。

订阅示例 (公共频道)

为了接收特定交易对的实时市场数据，你需要构建一个订阅消息。以下是一个订阅公共频道 "tickers" 的示例，它将推送 BTC-USDT 交易对的最新成交价、成交量和其他相关信息。

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

在这个JSON对象中， op 字段指定操作类型为 "subscribe"，表示订阅。 args 字段是一个列表，其中包含一个或多个需要订阅的频道和交易对信息。 channel 字段指定要订阅的频道，这里是 "tickers"，用于获取实时价格更新。 instId 字段指定具体的交易对，例如 "BTC-USDT"，代表比特币兑泰达币。

ws.send(.dumps(subscribe_params))

使用WebSocket连接( ws )，将 subscribe_params 对象转换为JSON字符串，并通过 send() 方法发送到服务器。 .dumps() 函数用于将Python字典转换为JSON格式的字符串，以便通过网络传输。

while True:
result = ws.recv()
print(result)

这段代码建立了一个无限循环，用于持续接收服务器推送的数据。 ws.recv() 方法会阻塞，直到接收到一条新的消息。接收到的消息（通常也是JSON格式的字符串）会被赋值给 result 变量，然后通过 print(result) 语句打印到控制台。 你可以使用 .loads() 方法将接收到的JSON字符串转换回Python字典，以便更方便地访问和处理数据。

ws.close()

在不再需要接收数据时，务必调用 ws.close() 方法关闭WebSocket连接，释放资源。如果不关闭连接，可能会导致资源浪费或连接泄漏。

4. 常用接口调用

4.1 获取账户余额

  • 接口地址: /api/v5/account/balance
  • 请求方法: GET
  • 描述: 此接口用于查询指定或所有币种的账户余额信息。如果未指定币种，将返回所有可用币种的余额信息。
  • 请求参数:
    • ccy : 币种 (可选)。例如： BTC ， ETH ， USDT 。留空则返回所有币种的账户余额。支持多币种查询，多个币种间用逗号分隔，例如： BTC,ETH,USDT 。
  • 返回数据: 账户余额信息。返回结果包含可用余额、冻结余额和总余额等详细信息，具体字段定义请参考API文档中的账户余额数据结构。
  • 返回示例: 
            
        {
            "code": "0",
            "msg": "",
            "data": [
                {
                    "ccy": "BTC",
                    "bal": "1.00000000",
                    "frozenBal": "0.10000000",
                    "availBal": "0.90000000"
                },
                {
                    "ccy": "ETH",
                    "bal": "10.00000000",
                    "frozenBal": "1.00000000",
                    "availBal": "9.00000000"
                }
            ]
        }

    字段说明:

    • code : 返回码。 "0" 表示成功，其他值表示失败。
    • msg : 错误信息。
    • data : 账户余额数据数组。
      • ccy : 币种。
      • bal : 总余额。
      • frozenBal : 冻结余额。
      • availBal : 可用余额。
  • 注意事项:
    • 请注意频率限制，避免频繁调用接口。
    • 请务必处理好返回码，根据返回码判断请求是否成功。
    • 在进行交易前，请务必确认账户余额充足。

4.2 下单

  • 接口地址: /api/v5/trade/order
  • 请求方法: POST
  • 请求参数:
    • instId : 交易对。指定进行交易的加密货币对，例如 BTC-USDT 表示比特币兑USDT的交易对。务必确保交易对的准确性。
    • tdMode : 交易模式。定义交易的类型和风险承担方式。支持以下几种模式：
      • cash : 币币交易，即现货交易，直接使用账户中的可用余额进行买卖。
      • cross : 全仓杠杆交易，账户中的所有可用资金都可作为保证金，风险较高，收益潜力也较大。
      • isolated : 逐仓杠杆交易，为每个仓位设置独立的保证金，风险相对可控。
      选择合适的交易模式需要根据个人的风险承受能力和交易策略进行权衡。
    • side : 订单方向。指明订单的买卖方向。
      • buy : 买入，即做多，预期价格上涨。
      • sell : 卖出，即做空，预期价格下跌。
    • ordType : 订单类型。决定订单的执行方式。
      • market : 市价单，以当前市场最优价格立即成交。无需指定价格，但成交价格可能与预期价格存在偏差，尤其是在市场波动较大时。
      • limit : 限价单，指定订单的成交价格。只有当市场价格达到或超过指定价格时，订单才会成交。
      • post_only : 只挂单，确保订单不会立即成交，而是以挂单的形式进入市场。如果订单会立即成交，则会被取消。常用于 maker 策略，以获取手续费优惠。
      • fok : 全部成交或立即取消 (Fill or Kill)，订单必须全部立即成交，否则将被立即取消。
      • ioc : 立即成交并取消剩余 (Immediate or Cancel)，订单尽可能以当前市场最优价格立即成交，未成交的部分将被立即取消。
    • sz : 数量。指定交易的数量，例如购买或出售的 BTC 数量。
    • px : 价格。仅在限价单 ( limit ) 中需要指定，表示期望的成交价格。如果订单类型为市价单，则无需提供此参数。
  • 返回数据: 订单ID等信息。提交订单后，API 将返回包含订单 ID 等信息的 JSON 响应。可以利用此 ID 查询订单状态或进行后续操作。

4.3 取消订单

  • 接口地址: /api/v5/trade/cancel-order
  • 请求方法: POST
  • 接口描述: 用于取消已提交但尚未完全成交的订单。该接口允许用户撤销指定交易对的特定订单。
  • 请求参数:
    • instId : 交易对 (Instrument ID)。 指定要取消订单的交易对，例如 "BTC-USD-SWAP" 或 "ETH-USDT"。 交易对 ID 是交易所内唯一标识交易品种的字符串。
    • ordId : 订单ID (Order ID)。 要取消的订单的唯一标识符。该ID由交易所生成，并在订单创建时返回给用户。确保提供的订单 ID 正确无误。
  • 请求示例:

    例如，要取消交易对为 'BTC-USDT'，订单ID为 '123456789' 的订单，请求体应如下： 

    
{
  "instId": "BTC-USDT",
  "ordId": "123456789"
}
  • 返回数据: 取消结果。 返回数据包含取消操作的状态信息，包括是否成功取消，以及可能出现的错误代码和错误信息。 需要根据交易所的具体API文档解析返回数据，以确定取消操作的结果。成功取消通常会返回一个确认消息，失败则会返回相应的错误代码。
  • 错误处理:

    取消订单可能会因多种原因失败，包括：

    • 订单已完全成交。
    • 订单已被取消。
    • 订单ID无效。
    • 账户余额不足。
    • 系统错误。

    在调用接口后，务必检查返回的状态码和错误信息，以便及时处理各种异常情况。

  • 注意事项:
    • 频繁取消订单可能会受到交易所的限制，建议合理使用取消订单功能。
    • 取消订单请求需要在订单未完全成交之前发起。
    • 不同交易所的API接口可能略有不同，请务必参考具体的API文档。

4.4 获取订单详情

  • 接口地址: /api/v5/trade/order
  • 接口描述: 通过该接口，您可以获取指定订单的详细信息，包括订单状态、成交价格、成交数量、手续费等。
  • 请求方法: GET
  • 请求参数:
    • instId (必填): 交易对。例如：BTC-USDT，ETH-USDT。指定您要查询订单的交易对。
    • ordId (必填): 订单ID。您需要提供要查询的订单的唯一标识符。
  • 请求示例:

    假设您要查询交易对为 BTC-USDT，订单 ID 为 1234567890 的订单详情，请求 URL 可能如下所示： 

    /api/v5/trade/order?instId=BTC-USDT&ordId=1234567890
  • 返回数据: 订单详细信息。返回数据是一个 JSON 对象，包含了订单的所有相关信息。具体字段包括：
    • ordId : 订单ID。
    • instId : 交易对。
    • clOrdId : 客户自定义订单ID。
    • px : 订单价格。
    • sz : 订单数量。
    • ordType : 订单类型（如：市价单、限价单）。
    • side : 订单方向（买/卖）。
    • ordState : 订单状态（如：等待成交、部分成交、完全成交、已撤销）。
    • avgPx : 平均成交价格。
    • fillSz : 已成交数量。
    • fee : 手续费。
    • feeCcy : 手续费币种。
    • Rebate : 返佣金额。
    • RebateCcy : 返佣币种。
    • createdTime : 订单创建时间。
    • updatedTime : 订单更新时间。
  • 错误处理: 如果请求失败，服务器将返回一个包含错误代码和错误信息的 JSON 对象。常见的错误包括：
    • 订单不存在（无效的 ordId ）。
    • 交易对不存在（无效的 instId ）。
    • 服务器内部错误。

5. 常见问题

  • API请求频率限制: OKX API为了保障系统的稳定性和公平性，对每个用户的API请求频率进行了限制。具体的限制规则，包括每分钟或每秒钟允许的最大请求次数，会根据不同的API接口和用户的VIP等级有所不同。您务必详细参考OKX官方API文档中关于频率限制的说明，合理控制您的请求频率，避免触发限制。违反频率限制可能导致您的API访问被暂时或永久阻止。您可以采用诸如请求队列、批量请求等技术手段来优化您的API使用，降低频率超限的风险。同时，关注OKX官方发布的关于频率限制调整的公告。
  • HTTP状态码: HTTP状态码是服务器响应客户端请求时返回的三位数代码，用于指示请求的处理结果。了解HTTP状态码对于诊断和解决API调用问题至关重要。 200 OK 表示请求已成功处理。 400 Bad Request 表示请求包含错误，例如参数缺失或格式错误。 401 Unauthorized 表示未授权访问，通常是因为API密钥无效或缺失。 403 Forbidden 表示服务器拒绝请求，可能是由于权限不足。 429 Too Many Requests 表示请求频率过高，超过了API的限制。 500 Internal Server Error 表示服务器内部错误，这通常不是客户端的问题。请仔细检查您收到的HTTP状态码，并根据其含义采取相应的措施。
  • 错误码: 如果API请求失败，OKX API会返回一个特定的错误码以及相应的错误信息，以便您了解失败的原因。不同的错误码对应着不同的问题，例如，订单不存在、余额不足、参数无效等等。请务必仔细阅读OKX官方API文档中关于错误码的说明，了解每个错误码的具体含义和解决方法。通过分析错误码和错误信息，您可以快速定位问题，并采取正确的措施进行修复。一些常见的错误码可能与交易参数错误、账户状态异常或系统维护有关。
  • 签名错误: API签名是用于验证请求的完整性和身份的重要机制。签名错误通常是由于以下几个原因导致的：时间戳不正确，确保您的客户端时间与服务器时间同步，并使用当前时间戳生成签名；Secret Key错误，请仔细检查您的Secret Key是否正确，并妥善保管，避免泄露；请求体拼接错误，请确保您按照API文档的要求正确拼接请求体，包括参数名称、参数顺序和参数值；签名算法错误，请使用正确的签名算法（通常是HMAC-SHA256）生成签名。仔细检查您的签名算法和参数，确保生成的签名与服务器期望的签名一致。
  • 权限不足: OKX API提供了不同权限级别的API密钥，例如，只读权限、交易权限、提现权限等等。如果您的API密钥没有相应的权限，您将无法执行某些操作。请检查您的API密钥的权限设置，确保它具有执行您所需操作的权限。您可以在OKX账户管理页面中查看和修改API密钥的权限。例如，如果您想进行交易，您的API密钥必须具有交易权限。

6. 其他

为了更全面地掌握OKX API的使用，请务必深入阅读OKX官方API文档。官方文档提供了最详细的API接口说明、请求参数定义、返回数据格式、错误代码解释以及示例代码，能够帮助您更好地理解和运用OKX API。请密切关注文档中关于API变更的通知，以便及时调整您的程序代码，避免因API升级而产生的问题。

OKX API官方文档地址： OKX API官方文档（中文）

OKX API官方文档地址： OKX API官方文档（英文）

强烈建议开发者定期查阅API文档的更新日志，掌握最新的API功能和优化，确保应用程序与OKX平台保持同步。同时，OKX可能会根据市场变化和技术发展，对API接口进行调整和优化，及时了解这些变更对于构建稳定可靠的交易系统至关重要。