欧易(OKX)订单查询惊天秘籍：一键掌握交易数据！

2025-03-06 48

如何通过欧易API查询订单历史

对于加密货币交易者来说，了解过去的交易记录至关重要。无论是进行财务核算、策略回测，还是仅仅为了追踪个人交易表现，都需要访问完整的订单历史数据。 欧易(OKX) API 提供了一种便捷的方式来检索这些数据，允许开发者和交易者程序化地访问并分析其交易活动。本文将详细介绍如何利用欧易API查询订单历史，并提供代码示例，帮助您快速上手。

准备工作

在开始之前，您需要确保具备以下条件，以顺利进行欧易(OKX) API交易：

  • 欧易(OKX)账户: 您需要一个已注册并完成身份验证的欧易账户。身份验证是使用API进行交易的前提，确保符合交易所的KYC（了解你的客户）政策。 强烈建议开启谷歌验证器（Google Authenticator）或者其他双因素认证（2FA），提高账户安全性。
  • API 密钥: 您需要在欧易账户中创建API密钥。请务必启用"交易"权限，并仔细设置IP访问限制（如果OKX支持此功能），进一步提升密钥的安全性。务必妥善保管您的API密钥（Key）和私钥（Secret Key）。请不要将它们泄露给任何人，切勿将密钥上传到公共代码仓库，或通过非加密通道传输。 密钥泄露会导致资金损失。 请定期更换API密钥。
  • 编程环境: 您需要一个可以执行HTTP请求的编程环境，例如Python, JavaScript, Java等。不同的编程语言有不同的库和工具可以用于与API交互。 本文将以Python为例进行讲解，因为它易于学习和使用，并且拥有丰富的第三方库支持。
  • 相关库: 在Python中，您需要安装 requests 库来发送HTTP请求。可以使用 pip install requests 命令安装。 另外，您可能还需要 库来处理API返回的JSON格式数据，以及 hmac 和 hashlib 库来生成签名，确保请求的安全性。 使用 pip install requests hmac hashlib 命令安装这些库。 建议使用虚拟环境管理您的Python项目依赖，避免不同项目之间的依赖冲突。

API端点和参数

查询订单历史的欧易API端点是：

GET /api/v5/trade/orders-history

此端点提供全面的订单历史查询功能，并支持通过参数进行精细化筛选。以下是可用参数的详细说明：

  • instId (必选): 交易对ID，用于指定要查询的交易市场。务必提供有效的交易对，如现货交易对"BTC-USDT"、永续合约交易对"BTC-USD-SWAP"或交割合约交易对"BTC-USD-231229"。
  • ordType (可选): 订单类型。允许的值包括："market"（市价单）、"limit"（限价单）、"post_only"（只挂单）、"fok"（立即全部成交否则取消）、"ioc"（立即成交剩余取消）、"optimal_limit_ioc"（最优限价IOC单）、"mmp"（做市商保护订单）。留空则返回所有订单类型的记录。每种订单类型都代表着不同的交易策略，适用于不同的市场情况。
  • state (可选): 订单状态。支持的状态包括："canceled"（已取消）、"live"（未成交）、"filled"（已完全成交）、"partially_filled"（部分成交）。不指定状态则返回所有状态的订单。理解订单状态对于分析交易执行情况至关重要。
  • category (可选): 产品类型。可选值包括："spot"（现货）、"margin"（杠杆）、"swap"（永续合约）、"futures"（交割合约）、"option"（期权）。默认值为"spot"。正确选择产品类型能确保查询到对应市场的订单信息。
  • after (可选): 分页参数。指定一个 orderId ，API将返回晚于（即 orderId 值更大）此 orderId 的订单。此参数用于实现向后分页，避免一次性返回大量数据。
  • before (可选): 分页参数。指定一个 orderId ，API将返回早于（即 orderId 值更小）此 orderId 的订单。此参数用于实现向前分页，方便用户浏览较早的订单记录。
  • limit (可选): 返回订单的数量。取值范围为1到100，默认值为100。建议根据实际需求设置此参数，避免不必要的数据传输，提高API响应速度。

请求签名

为了确保交易和数据安全，欧易API要求所有请求都必须经过签名验证。签名是验证请求来源和确保数据完整性的关键机制，防止恶意篡改和未经授权的访问。签名过程涉及一系列加密操作，确保只有拥有正确密钥的用户才能发起有效请求。

  1. 创建请求字符串: 将请求的关键组成部分组合成一个统一的字符串，作为签名的基础。这些组成部分包括：时间戳(timestamp，精确到毫秒，防止重放攻击)，HTTP请求方法(method，如GET、POST、PUT或DELETE，必须大写)，API请求路径(requestPath，例如 /api/v5/trade/orders，区分大小写)，以及请求体(requestBody，如果是GET请求，则为空字符串，POST、PUT等请求则包含JSON格式的请求数据)。按照时间戳 + method + requestPath + body 的顺序拼接，顺序至关重要。
  2. 计算HMAC-SHA256哈希: 使用您的私钥(secret key，由欧易提供)对请求字符串进行HMAC-SHA256哈希运算。HMAC-SHA256是一种消息认证码算法，结合了哈希函数和密钥，可以有效防止消息被篡改。私钥必须妥善保管，切勿泄露。
  3. 进行Base64编码: 将HMAC-SHA256哈希运算的结果进行Base64编码。Base64是一种将二进制数据转换为ASCII字符串的编码方式，便于在HTTP头中传输。

以下是一个Python函数，用于生成欧易API请求签名：

import hashlib import hmac import base64 import time

def generate_signature(timestamp, method, request_path, body, secret_key): """ 生成欧易API请求签名。此函数接收时间戳、HTTP方法、请求路径、请求体和私钥作为输入，并返回签名字符串。为了确保安全性，所有参数都应进行适当的验证和编码。 

Args:
     timestamp:  时间戳 (Unix timestamp)，以秒为单位，通常使用time.time()获取，建议使用毫秒级时间戳，避免重放攻击。
    method: HTTP请求方法 (GET, POST, PUT, DELETE)，必须为大写字符串。
      request_path: API请求路径 (例如:  /api/v5/trade/orders-history)，包含版本号，区分大小写。确保路径正确无误。
     body: 请求体 (如果是GET请求，则为空字符串 ""，而不是 None 或 null。对于POST、PUT等请求，应为JSON字符串，使用.dumps()进行序列化)。
    secret_key: 您的私钥 (由欧易提供，务必妥善保管，避免泄露)。

Returns:
    签名字符串 (Base64编码后的字符串，用于添加到HTTP请求头中)。
"""
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()

Python代码示例

以下是一个使用Python查询欧易交易所订单历史的示例代码，该代码示例展示了如何通过欧易的API接口获取您的交易记录。您需要先在欧易交易所创建API密钥，并确保拥有读取交易历史的权限。

import requests
import time
import hmac
import hashlib

这段代码导入了必要的Python库。 requests 库用于发送HTTP请求； time 库用于获取时间戳，这对于生成API签名至关重要； hmac 和 hashlib 库用于创建安全哈希消息认证码，确保API请求的安全性。

替换为您的API密钥信息

API KEY = "YOUR API KEY" 用于身份验证的API密钥，请在您的交易所账户中获取。

SECRET KEY = "YOUR SECRET_KEY" 用于生成签名的密钥，务必妥善保管。

PASSPHRASE = "YOUR_PASSPHRASE" # 如果设置了passphrase，用于进一步保护您的账户。

BASE_URL = "https://www.okx.com" # 替换为您的环境URL，例如"https://www.okx.com"，如果您使用模拟盘，请替换为模拟盘对应的URL，比如"https://www.okx.com"

def get order history(inst id, ord type=None, state=None, category=None, after=None, before=None, limit=100): """ 查询欧易交易所的订单历史记录。 

Args:
    inst_id: 交易对ID，指定您要查询的交易对，例如 "BTC-USDT", "ETH-USDT" 等。
    ord_type: 订单类型，用于筛选特定类型的订单，例如 "market" (市价单), "limit" (限价单), "post_only" (只挂单)等 (可选)。
    state: 订单状态，用于筛选特定状态的订单，例如 "live" (未成交), "filled" (已成交), "canceled" (已撤销), "partially_filled" (部分成交)等 (可选)。
    category: 产品类型，指定交易产品类别，例如 "spot" (现货), "futures" (交割合约), "swap" (永续合约), "option" (期权)等 (可选，默认为"spot")。
    after: 分页参数，用于获取指定订单ID之后的订单记录，实现分页查询 (可选)。
    before:  分页参数，用于获取指定订单ID之前的订单记录，实现分页查询 (可选)。
    limit: 返回订单数量，指定每次API调用返回的订单记录数量，最大值为100 (可选，默认为交易所默认值)。

Returns:
    包含订单历史数据的JSON对象，如果请求失败则返回 None。请检查返回的JSON对象，确保包含预期的订单数据。
"""

timestamp = str(int(time.time()))
method = "GET"
request_path = "/api/v5/trade/orders-history"
body  = ""   # GET请求通常没有请求体

#  构建请求参数
params  =  {
    "instId":  inst_id,
    "limit": limit
}

if  ord_type:
    params["ordType"] = ord_type
if state:
    params["state"] = state
if category:
    params["category"] = category
if after:
    params["after"] = after
if  before:
    params["before"] = before


#  生成签名，使用您的SECRET_KEY和时间戳等信息对请求进行签名，确保请求的安全性。
signature = generate_signature(timestamp, method, request_path,  body, SECRET_KEY)

#  构建请求头，将API_KEY，签名，时间戳和Passphrase添加到请求头中。
headers = {
    "OK-ACCESS-KEY": API_KEY,
    "OK-ACCESS-SIGN": signature,
    "OK-ACCESS-TIMESTAMP": timestamp,
    "OK-ACCESS-PASSPHRASE": PASSPHRASE,   #  如果设置了passphrase
    "Content-Type": "application/" #  设置Content-Type为application/
}

#  发送HTTP GET请求，使用requests库发送GET请求，并将headers和params传递给请求。
url = BASE_URL +  request_path
response = requests.get(url,  headers=headers, params=params)

# 检查响应状态码，确保请求成功。如果状态码不是200，则打印错误信息。
if response.status_code  == 200:
    return response.() # 使用response.()解析JSON响应
else:
    print(f"请求失败: 状态码 {response.status_code},  错误信息: {response.text}")
    return None

示例用法

以下代码展示了如何使用 get_order_history 函数获取指定交易对的历史订单记录。 在Python脚本中，你可以通过检查 __name__ 变量是否等于 "__main__" 来确定脚本是否作为主程序运行。如果是，则执行相应的代码块。 以下示例代码演示了如何调用 get_order_history 函数，并打印返回的订单历史记录。

例如:

if name == " main ": instrument_id = "BTC-USDT" order_history = get_order_history(instrument_id)

这段代码首先定义了交易对 instrument_id 为 "BTC-USDT"，代表比特币兑 USDT 的交易对。 然后，它调用 get_order_history 函数，并将 instrument_id 作为参数传递给该函数，以获取该交易对的历史订单记录。 函数返回的订单历史记录将存储在 order_history 变量中。 

if order_history:
      print(.dumps(order_history, indent=4))

接下来，代码检查 order_history 变量是否为空。如果 order_history 包含有效的订单历史记录，则使用 .dumps 函数将其格式化为 JSON 字符串，并使用 indent=4 参数进行美化输出，使其更易于阅读。 .dumps 函数用于将 Python 对象编码成 JSON 字符串。 indent 参数指定了缩进的空格数，用于美化 JSON 输出。 如果 order_history 为空（例如，没有找到任何历史订单记录），则不会执行任何操作。

代码解释

  1. 导入库: 导入必要的Python库，包括 requests 用于发送HTTP请求， 用于处理JSON数据，以及 time 库用于生成时间戳。 这些库是脚本运行的基础。
  2. 设置API密钥: 务必将示例代码中的 YOUR_API_KEY , YOUR_SECRET_KEY 和 YOUR_PASSPHRASE 替换为您在欧易（OKX）交易所申请的真实API密钥信息。 API密钥用于身份验证，确保您有权访问您的账户数据和执行交易操作。 正确设置这些密钥至关重要，否则API调用将会失败。Passphrase 是一个额外的安全层，如果你的账户设置了 Passphrase，则必须提供。
  3. get_order_history 函数:
    • 此函数接受交易对ID ( inst_id )，例如 "BTC-USDT"，作为必要参数。 该参数指定您要查询的交易对。该函数还可以接受其他可选参数，例如订单类型、开始时间和结束时间等，以进一步筛选订单历史记录。
    • 构建请求参数字典 params 。 此字典包含了您要传递给欧易API的所有查询参数，例如订单状态、分页信息等。 这些参数将以URL查询字符串的形式附加到API请求中。
    • 生成时间戳 timestamp 。 时间戳是一个重要的安全元素，用于防止重放攻击。 它表示API请求发送的时间，并且必须与服务器时间保持同步。 时间戳通常以Unix时间（自1970年1月1日以来的秒数）的形式表示。
    • 生成签名 signature 。 signature 是使用您的私钥 ( YOUR_SECRET_KEY ) 和请求参数（包括时间戳）生成的加密签名。 签名用于验证请求的完整性和来源，确保请求未被篡改且来自授权用户。生成签名的具体算法取决于交易所的要求，通常涉及HMAC-SHA256等哈希函数。 具体可以参考欧易API的官方文档。
    • 构建请求头 headers ，包含API密钥 ( OK-ACCESS-KEY )、签名 ( OK-ACCESS-SIGN )、时间戳 ( OK-ACCESS-TIMESTAMP ) 和 Passphrase ( OK-ACCESS-PASSPHRASE ，如果设置了)。 请求头是HTTP请求的一部分，用于传递元数据。 在此上下文中，请求头包含了API身份验证所需的所有信息，以便欧易服务器可以验证请求的有效性。
    • 发送GET请求到欧易API端点。 使用 requests 库向欧易API的订单历史记录端点发送GET请求。GET请求用于从服务器检索数据。 API端点的URL取决于交易所的API版本和具体功能。 例如，订单历史记录端点的URL可能类似于 https://www.okx.com/api/v5/trade/orders-history 。
    • 检查响应状态码。 如果API请求成功，欧易服务器将返回一个200状态码。 如果状态码不是200，则表示发生了错误。 常见的错误包括无效的API密钥、错误的签名、请求参数错误等。 如果状态码为200，则将响应数据解析为JSON格式并返回。否则，打印详细的错误信息，帮助用户诊断问题。
  4. 示例用法:
    • 设置 instrument_id 为 "BTC-USDT"。 这指定了您要查询的交易对为比特币兑USDT。 您可以将其更改为任何其他有效的交易对，例如 "ETH-USDT" 或 "LTC-BTC"。
    • 调用 get_order_history 函数获取订单历史数据。 调用该函数会向欧易API发送请求，并返回包含订单历史记录的JSON数据。您可以根据需要传递额外的参数来筛选订单。
    • 如果成功获取数据，则使用 .dumps 格式化并打印JSON数据。 .dumps 函数将Python字典或列表转换为格式化的JSON字符串，使其更易于阅读和调试。 indent=4 参数指定缩进级别，使JSON数据更具可读性。

注意事项

  • 错误处理: 在实际应用中，健壮的错误处理至关重要。 除了基本的网络连接错误，还应考虑处理API返回的各种错误代码。 欧易API定义了详细的错误代码体系，通过捕获和分析这些错误代码，您可以实现更精细的错误诊断和恢复机制。 例如，可以针对不同的错误代码采取不同的重试策略，或者记录详细的错误日志以便于后续排查问题。 还可以添加熔断机制，防止因API服务不稳定而导致整个应用崩溃。
  • 速率限制: 欧易API为了保障服务质量和防止滥用，实施了速率限制。 请求过于频繁会导致API访问被限制，影响程序的正常运行。 需要仔细研究欧易API文档中关于速率限制的详细规则，包括每分钟、每秒的请求次数限制，以及不同API接口的限制差异。 可以采用令牌桶算法或漏桶算法等技术，控制请求的发送速率。 建议在代码中实现自动重试机制，当遇到速率限制错误时，自动暂停一段时间后重试。 同时，建议在API请求头中包含必要的身份验证信息，以便欧易能够准确地识别您的应用并应用正确的速率限制策略。
  • 分页处理: 当您的交易数据量非常大时，一次性获取所有订单历史记录可能会导致性能问题。 欧易API提供了分页功能，可以通过`after`和`before`参数指定查询的起始位置。 `after`参数用于获取指定ID之后的订单，`before`参数用于获取指定ID之前的订单。 使用分页查询时，需要循环调用API接口，每次获取一部分数据，直到获取到所有需要的订单。 务必处理好分页查询的边界条件，例如没有更多数据时的判断逻辑，以及`after`和`before`参数的正确使用。 还可以考虑使用缓存机制，将已经获取的数据缓存起来，避免重复查询。
  • 安全: API密钥和私钥是访问欧易API的凭证，必须妥善保管，严防泄露。 切勿将API密钥和私钥硬编码在代码中，这会带来极高的安全风险。 推荐使用环境变量来存储API密钥和私钥。 环境变量可以从操作系统或配置文件中读取，避免将敏感信息暴露在代码中。 还可以使用专门的密钥管理服务，例如HashiCorp Vault，来安全地存储和管理API密钥和私钥。 还可以限制API密钥的权限，只授予必要的权限，减少安全风险。 定期轮换API密钥也是一项重要的安全措施。

通过本文的介绍，您应该能够利用欧易API查询您的订单历史。 请务必仔细阅读欧易API文档，并根据您的实际需求进行调整和扩展。 同时，请关注欧易API的更新和变化，及时调整您的代码以适应新的API版本。

上一篇： Gate.io实名认证攻略：极速提升交易权限与账户安全！
下一篇： 还在犹豫？OKX狗狗币交易，是机会还是陷阱？