欧易OKX API 自动化交易实战：快速入门教程！

日期：2025-03-06 栏目：文档浏览：48

如何利用欧易的交易 API 进行自动化交易

在快节奏的加密货币市场中，自动化交易的需求日益增长。通过使用欧易（OKX）的交易 API，交易者可以构建自己的交易策略并实现自动执行，从而提高效率，降低人为错误，并抓住市场机会。本文将深入探讨如何利用欧易的交易 API 进行自动化交易，包括 API 密钥的获取、API 的认证、常用 API 接口的使用以及示例代码。

1. 获取欧易 API 密钥

要使用欧易交易所的交易 API 进行程序化交易或数据分析，您首先需要在欧易平台上创建并管理 API 密钥。API 密钥是您与欧易服务器进行安全通信的凭证，允许您的应用程序代表您执行交易和其他账户操作。请按照以下详细步骤操作：

登录您的欧易账户： 使用您的账户凭据（用户名/邮箱/手机号和密码）登录欧易交易所官方网站或App。确保开启双重验证（2FA），以增强账户安全性。
导航至“API”页面： 成功登录后，在账户设置中寻找“API”或“API管理”入口。这通常位于用户中心的“安全设置”、“账户设置”或类似的标签下。具体位置可能因欧易平台更新而略有变化，请仔细查找。
创建 API 密钥： 在 API 管理页面，点击“创建 API”或类似的按钮。您可能需要阅读并同意相关的 API 使用条款。
填写 API 密钥信息： 在创建API密钥的表单中，填写以下信息：
- API 密钥名称： 为您的 API 密钥指定一个易于识别的名称，例如“量化交易机器人”、“数据分析脚本”等。良好的命名习惯有助于您管理和区分不同的 API 密钥。
- API 密钥描述： 简要描述该 API 密钥的用途，例如“用于 ETH/USDT 网格交易策略”。
设置 API 权限： 这是 API 密钥创建过程中最关键的一步。欧易提供多种 API 权限，允许您控制该 API 密钥可以执行的操作。对于交易相关的自动化程序，您必须启用“交易”权限。
- 交易权限： 允许 API 密钥进行现货交易、合约交易、期权交易等。请根据您的实际需求选择相应的交易权限。
- 只读权限： 如果您的应用仅需要获取市场数据或账户信息，而不需要执行交易，请仅赋予“只读”权限。
- 其他权限： 根据需要，您可能还需要授予其他权限，例如“提币”权限（如果您的应用需要自动提币）。但是，请务必谨慎授予“提币”权限，并严格控制提币地址，以防止资金被盗。
- 重要安全提示： 始终遵循最小权限原则。仅授予您的应用程序所需的最低权限。避免赋予过多的权限，以降低安全风险。
设置 IP 访问限制： 为了最大程度地保护您的 API 密钥，强烈建议您限制 API 密钥的访问 IP 地址。
- IP 白名单： 输入您服务器或运行交易程序的公网 IP 地址。只有来自这些 IP 地址的请求才会被允许访问 API。
- 多 IP 地址： 如果您的应用程序运行在多个服务器上，您可以添加多个 IP 地址到白名单中。使用逗号分隔多个 IP 地址。
- 安全警告： 切勿将 IP 限制设置为 0.0.0.0/0，这相当于允许所有 IP 地址访问您的 API，会带来极高的安全风险。
完成双重验证并提交： 按照欧易平台的提示，完成双重验证（例如 Google Authenticator 验证码、短信验证码或邮件验证码），以确认您的操作。然后，提交 API 密钥创建请求。

创建完成后，欧易平台将向您提供 API Key（也称为 Public Key）、Secret Key（也称为 Private Key）和 Passphrase。这些信息是访问欧易 API 的关键凭证。 请务必采取以下措施妥善保管这些信息：

安全存储： 将 API Key、Secret Key 和 Passphrase 存储在安全的地方，例如加密的数据库或密钥管理系统。
不要泄露： 切勿将这些信息泄露给任何人，包括欧易的客服人员。欧易官方不会主动向您索要这些信息。
定期更换： 定期更换 API 密钥，以降低安全风险。您可以在欧易 API 管理页面禁用或删除旧的 API 密钥，并创建新的 API 密钥。
Secret Key 的作用： Secret Key 用于对 API 请求进行签名。所有发送到欧易服务器的 API 请求都需要使用 Secret Key 进行签名，以验证请求的有效性和完整性。
Passphrase 的作用： Passphrase 用于加密您的账户信息，例如提币地址。如果您启用了某些需要加密的功能，您需要提供 Passphrase 才能使用这些功能。 Passphrase 类似于您的账户密码，但用于 API 相关的加密操作。

2. API 认证

在使用欧易 API 之前，必须对每个请求进行签名认证，以确保请求的合法性以及数据的完整性。未经过正确签名认证的请求将被服务器拒绝。认证流程详细如下：

准备请求数据： 包括但不限于以下关键信息：请求方法（ GET 、 POST 、 PUT 、 DELETE 等）、完整的请求路径（例如 /api/v5/trade/order ，必须包含版本号）、以及请求参数。对于 POST 、 PUT 等请求，请求参数通常以 JSON 格式编码，作为请求体发送。
创建签名字符串： 签名字符串是生成签名的核心要素。其格式为： timestamp + method + requestPath + requestBody 。各部分解释如下：
- timestamp ：是当前时间戳，精确到秒，必须是 Unix 时间戳。强烈建议使用服务器当前时间戳，以避免因时钟偏差导致的签名验证失败。
- method ：是请求方法，必须使用大写形式，例如 GET 、 POST 、 PUT 、 DELETE 。请务必与实际使用的 HTTP 方法保持一致。
- requestPath ：是请求路径，必须包含 API 版本号。例如 /api/v5/trade/order 。确保路径的准确性，包括斜杠和大小写。
- requestBody ：是请求体。对于 GET 请求， requestBody 为空字符串 "" 。对于 POST 、 PUT 等请求， requestBody 是 JSON 格式的字符串。如果请求体包含任何参数，必须将其序列化为 JSON 字符串。即使请求体为空，也需要使用空字符串。
使用 Secret Key 进行 HMAC SHA256 加密： 使用你的 Secret Key 对签名字符串进行 HMAC SHA256 加密，生成最终的签名值。HMAC (Hash-based Message Authentication Code) 是一种使用密钥的哈希算法，可以有效地验证消息的完整性和真实性。请确保你的 Secret Key 安全地存储，不要泄露给他人。
添加 HTTP Headers： 将以下 HTTP Headers 添加到你的请求中。这些 Headers 包含认证信息，服务器会使用这些信息验证请求的合法性：
- OK-ACCESS-KEY ：你的 API Key，用于标识你的身份。API Key 可以在欧易的 API 管理页面创建和管理。
- OK-SIGN ：上一步生成的签名值，用于验证请求的完整性和真实性。这是最重要的 Header，必须正确生成并添加到请求中。
- OK-TIMESTAMP ：当前时间戳（单位为秒），与签名字符串中使用的时间戳一致。
- OK-PASSPHRASE ：你的 Passphrase，用于增强安全性。如果你的 API Key 设置了 Passphrase，必须将其添加到请求中。如果未设置，则无需添加此 Header。
- Content-Type ：指定请求体的格式。对于大多数 API 请求，应设置为 application/ ，表明请求体是 JSON 格式的数据。

以下是一个 Python 示例，展示了如何生成签名：

import hashlib import hmac import time import

def generate_signature(timestamp, method, request_path, body, secret_key): """ 生成欧易 API 请求签名。

    Args:
        timestamp: 当前时间戳。
        method: 请求方法 (GET, POST, DELETE)。
        request_path: 请求路径。
        body: 请求体，JSON 字符串。
        secret_key: 你的 Secret Key.

    Returns:
        签名字符串。
    """
    message = str(timestamp) + method + request_path + body
    mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf8'), hashlib.sha256)
    d = mac.digest()
    return d.hex()

示例：生成数字签名

本示例演示如何使用时间戳、请求方法、请求路径、请求体和您的API密钥来生成数字签名，用于安全地与加密货币交易所的API进行交互。数字签名是验证请求来源和确保数据完整性的关键组成部分。

获取当前时间戳，并将其转换为字符串格式。时间戳代表自Unix纪元（1970年1月1日 00:00:00 UTC）以来的秒数。

timestamp = str(int(time.time()))

定义HTTP请求方法（例如 'POST'）、请求路径（例如 '/api/v5/trade/order'，表示交易下单API）和请求体。请求体是一个JSON字符串，包含交易所需的参数，如交易对（'instId': 'BTC-USDT'，表示比特币兑USDT）、交易方向（'side': 'buy'，表示买入）、订单类型（'ordType': 'market'，表示市价单）和交易数量（'sz': '0.001'，表示0.001个BTC）。

method = 'POST'
request_path = '/api/v5/trade/order'
body = .dumps({'instId': 'BTC-USDT', 'side': 'buy', 'ordType': 'market', 'sz': '0.001'})

接下来，设置您的 Secret Key。 请务必保管好您的Secret Key，不要泄露给他人。 您的Secret Key用于生成签名，是您身份验证的重要凭证。

secret_key = 'YOUR_SECRET_KEY'  # 替换为你的 Secret Key

然后，使用 generate_signature 函数生成签名。这个函数接收时间戳、请求方法、请求路径、请求体和您的Secret Key作为参数，并返回生成的签名。

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

打印生成的签名。您需要将此签名添加到您的API请求的header中，以便交易所验证您的身份。

print(f"签名: {signature}")

重要提示： 请务必将 YOUR_SECRET_KEY 替换为你自己的 Secret Key。切勿在代码中硬编码您的Secret Key，建议从环境变量或配置文件中读取。

为了保证安全性，请在客户端进行签名计算，避免在服务器端存储您的Secret Key。同时，注意定期更换您的API密钥，以降低安全风险。

3. 常用 API 接口

欧易 API 提供了一系列功能强大的接口，方便开发者获取实时市场数据、高效管理账户资产以及执行各类交易操作。以下列出了一些常用的 API 接口，并对其功能进行了详细说明：

获取市场行情： /api/v5/market/tickers - 该接口用于检索所有交易对的最新行情数据，包括但不限于最新成交价、最高价、最低价、成交量等关键指标，为用户提供全面的市场概览。
获取K线数据： /api/v5/market/candles - 该接口允许用户获取指定交易对在特定时间周期内的 K 线数据。用户可以通过调整时间周期参数（如 1 分钟、5 分钟、1 小时、1 天等）来获取不同粒度的历史价格信息，用于技术分析和趋势判断。
下单： /api/v5/trade/order - 该接口用于创建新的订单，允许用户指定交易对、买卖方向（买入或卖出）、订单类型（市价单、限价单等）、数量和价格等参数，实现灵活的交易策略。正确使用该接口需要理解欧易交易所的订单类型规则和手续费机制。
撤单： /api/v5/trade/cancel-order - 该接口用于取消尚未完全成交的订单。用户需要提供订单 ID 作为参数来指定需要取消的订单。撤单操作的成功与否可能受到市场流动性和网络延迟的影响。
获取订单详情： /api/v5/trade/order - 通过该接口，用户可以查询指定订单的详细信息，包括订单状态（已成交、未成交、部分成交、已撤销等）、成交数量、成交价格、下单时间等。订单 ID 是查询订单详情的必要参数。
获取账户余额： /api/v5/account/balance - 该接口用于查询账户中各种币种的可用余额、冻结余额和总余额，为用户提供全面的资产视图。使用该接口需要注意账户权限和 API 密钥的配置。
获取历史成交记录： /api/v5/trade/fills - 通过该接口，用户可以获取历史成交记录，包括成交时间、成交价格、成交数量、手续费等信息。该接口对于追踪交易历史、计算盈亏和进行风险管理至关重要。

每个 API 接口都有其特定的请求参数、请求方式（GET 或 POST）、响应格式（JSON）以及错误代码。开发者在使用这些 API 接口时，必须仔细阅读并理解欧易官方 API 文档，了解详细的接口规范、参数说明、频率限制和错误处理机制，以确保 API 调用的正确性和稳定性，避免不必要的错误和损失。务必注意API Key的安全性，避免泄露。

4. 示例代码：下单

以下是一个 Python 示例，展示了如何使用欧易 API 进行交易下单操作。此代码片段演示了如何构建请求、签名并发送到欧易服务器。请注意，在实际使用前，请务必替换代码中的占位符，例如 API 密钥、密钥、交易对和下单参数。

import requests
import time
import hashlib
import hmac

此段代码首先导入了必要的Python库。 requests 库用于发送HTTP请求， time 库用于生成时间戳， hashlib 和 hmac 库用于消息签名，以确保请求的安全性。在与任何加密货币交易所的API交互时，消息签名至关重要，可以防止未经授权的访问和数据篡改。

API 密钥

api_key = 'YOUR_API_KEY' # 替换为你的 API Key。API Key 是访问交易所 API 的凭证，用于标识你的身份并授权访问权限。请妥善保管你的 API Key，避免泄露给他人，否则可能导致资金损失或数据泄露。在交易所的账户设置中可以生成和管理 API Key。通常，API Key 具有特定的权限，例如交易、查询余额等。请根据你的需求配置 API Key 的权限，避免赋予不必要的权限。

secret_key = 'YOUR_SECRET_KEY' # 替换为你的 Secret Key。Secret Key 与 API Key 配对使用，用于对 API 请求进行签名，确保请求的完整性和真实性。Secret Key 必须严格保密，绝对不能泄露给任何人。如果 Secret Key 泄露，攻击者可以伪造你的 API 请求，从而造成严重损失。如同 API Key 一样，Secret Key 也是在交易所的账户设置中生成和管理。

passphrase = 'YOUR_PASSPHRASE' # 替换为你的 Passphrase (如果适用)。Passphrase 是一个额外的安全层，用于加密你的 Secret Key 或其他敏感信息。并非所有交易所都要求 Passphrase，但如果你的交易所需要，请务必设置一个强密码，并妥善保管。Passphrase 可以在交易所账户的安全设置中找到相关选项。如果忘记 Passphrase，可能需要重置 API Key，这将导致之前的 API 连接失效。请仔细阅读交易所的文档，了解如何正确使用和管理 Passphrase。

API 接口 (API Endpoint)

base_url = 'https://www.okx.com' ：指定了欧易交易所API的基础URL。所有API请求都将以此URL为起点构建。务必确认此URL的正确性，尤其是在测试环境或未来版本中可能发生变化。

order_endpoint = '/api/v5/trade/order' ：定义了用于创建订单的特定API端点。该路径附加到 base_url 后，构成完整的订单创建API地址。v5表示API的版本号，选择正确版本非常重要。

以下是 create_order 函数的详细说明，用于通过欧易API创建交易订单。


def create_order(inst_id, side, ord_type, sz, price=None):
    """
    使用欧易 API 创建一个订单。

    Args:
        inst_id (str): 交易对，例如 'BTC-USDT'。指定交易的市场。正确的交易对格式是关键，需要参照欧易官方文档。
        side (str): 交易方向，'buy' (买入) 或 'sell' (卖出)。区分大小写，必须完全匹配API的要求。
        ord_type (str): 订单类型，'market' (市价单) 或 'limit' (限价单)。 市价单会立即以当前市场最优价格成交，而限价单只有当市场价格达到指定价格时才会成交。
        sz (str or float): 交易数量。表示要买入或卖出的标的数量。 对于某些交易对，最小交易数量有限制，需要注意。
        price (str or float, optional): 仅在 ord_type 为 'limit' 时需要。 指定限价单的价格。如果未提供，并且 ord_type 为 'limit'，函数会抛出异常。

    Returns:
        dict: 如果成功，返回包含订单信息的字典；否则返回包含错误信息的字典。 订单信息通常包括订单ID、成交价格、成交数量等。 错误信息会包含错误代码和错误描述，有助于调试。

    Raises:
        ValueError: 如果 ord_type 为 'limit' 且 price 未提供，则抛出此异常。

    """
    import time
    import requests
    import 
    import hashlib

    # 确保 price 在限价单中被提供
    if ord_type == 'limit' and price is None:
        raise ValueError("使用限价单时必须提供价格。")

    timestamp = str(int(time.time())) # 获取当前时间戳，用于生成签名
    method = 'POST' # 指定HTTP请求方法为 POST
    request_path = order_endpoint # 使用预定义的订单API端点
    body_data = {'instId': inst_id, 'side': side, 'ordType': ord_type, 'sz': sz} # 订单请求体
    if price is not None:
        body_data['px'] = str(price)  # 添加价格到请求体中，需要将价格转换为字符串

    body = .dumps(body_data) # 将Python字典转换为JSON字符串，准备发送到API

    # 生成签名
    def generate_signature(timestamp, method, request_path, body, secret_key):
        message = timestamp + method + request_path + body
        mac = hashlib.sha256(message.encode('utf-8')).hexdigest()
        signature = hmac.new(secret_key.encode('utf-8'), mac.encode('utf-8'), hashlib.sha256).digest().hex()
        return signature

    # 假设 api_key, secret_key, passphrase 已经在其他地方定义
    # api_key = 'YOUR_API_KEY'
    # secret_key = 'YOUR_SECRET_KEY'
    # passphrase = 'YOUR_PASSPHRASE'

    signature = generate_signature(timestamp, method, request_path, body, secret_key) # 使用密钥生成签名

    headers = {
        'OK-ACCESS-KEY': api_key, # API Key, 用于身份验证
        'OK-SIGN': signature, #  请求签名，用于验证请求的完整性和身份
        'OK-TIMESTAMP': timestamp, #  时间戳，防止重放攻击
        'OK-PASSPHRASE': passphrase, #  Passphrase, 用于增强安全性
        'Content-Type': 'application/' #  指定请求体的格式为JSON
    }

    url = base_url + order_endpoint # 构造完整的API URL
    response = requests.post(url, headers=headers, data=body) # 发送POST请求

    if response.status_code == 200:
        return response.() #  如果请求成功，解析JSON响应并返回
    else:
        return {'error': f'请求失败，状态码：{response.status_code}, 响应：{response.text}'} #  如果请求失败，返回包含错误信息的字典

示例：市价买入 0.001 BTC

该示例展示了如何使用市价单购买 0.001 BTC。市价单将以当前市场上最优的价格立即执行。

使用 create_order 函数提交市价买单，相关参数设置如下：

inst_id='BTC-USDT' : 指定交易的币对为 BTC/USDT。这意味着您将使用 USDT 购买 BTC。
side='buy' : 指示这是一个买入订单。
ord_type='market' : 设定订单类型为市价单。
sz='0.001' : 指定购买的 BTC 数量为 0.001 个。

代码示例如下：

order result = create order(inst id='BTC-USDT', side='buy', ord type='market', sz='0.001')

订单提交后，通过 print(order_result) 打印订单结果，可以查看订单的详细信息，例如订单ID、成交价格、手续费等。

print(order_result)

安全提示： 在运行代码之前，请务必将 YOUR_API_KEY , YOUR_SECRET_KEY , 和 YOUR_PASSPHRASE 替换为您自己在交易所注册获得的真实 API 密钥信息。妥善保管您的 API 密钥，避免泄露，防止资产损失。

5. 风险管理

自动化交易系统虽然能够显著提升交易效率和执行速度，但同时也引入了新的风险因素。因此，一套完善的风险管理体系对于保障资金安全和策略稳定运行至关重要。以下是一些关键的风险管理建议，旨在帮助用户更好地应对潜在挑战：

小额测试（Paper Trading & Backtesting）： 在正式部署自动化交易策略之前，务必进行充分的测试。这包括使用模拟账户（Paper Trading）进行实时市场环境下的仿真交易，以及利用历史数据进行回测（Backtesting）。小额资金测试能够帮助评估策略在不同市场条件下的表现，识别潜在缺陷和不足，确保策略的有效性和稳定性。重点关注回测期间的滑点模拟，真实复现交易成本。
设置止损（Stop-Loss Orders）： 止损订单是风险管理的核心组成部分。通过预先设定止损价格，可以有效地限制单笔交易的最大亏损。止损设置应根据策略特性、市场波动性和个人风险承受能力综合考虑。同时，也要注意止损价格的合理性，避免因市场短期波动而被错误触发。根据波动率调整动态止损，例如使用ATR指标。
持续监控（Continuous Monitoring）： 自动化交易系统并非一劳永逸，需要持续的监控和维护。监控内容包括系统运行状态、交易执行情况、账户资金状况等。利用日志记录和报警机制及时发现并解决潜在问题，例如网络连接中断、API密钥失效、交易异常等。关注交易所API的稳定性，避免交易中断。
风控参数优化（Risk Parameter Optimization）： 精心设置和优化风控参数是降低交易风险的重要手段。这些参数包括但不限于：最大持仓量（控制总风险敞口）、单笔交易最大亏损（限制单笔交易风险）、最大回撤比例（控制策略整体亏损）。风控参数的设定应结合策略特性和市场环境，并定期进行调整和优化，以适应不断变化的市场情况。考虑使用夏普比率等指标评估风险调整后的收益。
API 权限最小化（API Key Permission Restriction）： API密钥是连接交易账户和自动化交易系统的桥梁。为了防止API密钥被滥用，务必确保其权限仅限于必要的交易操作，例如下单、撤单、查询账户余额等。避免授予提现权限，以防止资金被盗。定期更换API密钥，并将其安全存储，防止泄露。

6. 其他注意事项

API 文档： 务必详尽阅读欧易官方 API 文档。文档中包含了所有可用接口的完整描述、请求参数说明、响应格式示例以及错误代码解释。深入理解每个接口的功能、适用场景和限制条件，能够帮助你更高效、准确地使用 API 进行开发。注意 API 文档的版本更新，及时了解最新的接口变更和功能增强。
速率限制： 欧易 API 实施了速率限制机制，旨在保护系统稳定性和公平性。开发者应严格遵守这些限制，避免因过于频繁的请求而导致 IP 地址被临时或永久封禁。为了防止超出速率限制，建议采用以下策略：实施请求队列，控制并发请求数量；根据接口的重要性设置不同的延迟策略，降低高频接口的请求频率；监控 API 响应头中的速率限制相关信息，例如剩余请求次数和重置时间，动态调整请求频率。
错误处理： 构建健壮的错误处理机制对于保证应用程序的稳定运行至关重要。在 API 调用过程中，可能会出现各种错误，例如网络连接问题、参数验证失败、权限不足等。开发者应捕获这些错误，并采取相应的处理措施，例如重试请求、记录错误日志、通知用户等。为了方便调试和问题排查，建议在错误日志中包含详细的错误信息，例如错误代码、错误描述、请求参数等。
安全： API 密钥是访问欧易 API 的凭证，必须妥善保管，避免泄露给未经授权的第三方。密钥泄露可能导致账户资金被盗、交易数据泄露等严重安全问题。建议采取以下措施来保护 API 密钥的安全：将密钥存储在安全的地方，例如加密的配置文件、密钥管理系统等；避免将密钥硬编码到应用程序代码中；定期轮换密钥，降低密钥泄露带来的风险；启用 IP 白名单功能，限制只有指定的 IP 地址才能访问 API。
时间同步： 欧易 API 使用时间戳进行身份验证，因此客户端时间必须与服务器时间保持同步。如果客户端时间与服务器时间存在较大偏差，会导致认证失败。为了确保时间同步，建议使用网络时间协议 (NTP) 服务。NTP 客户端可以定期与 NTP 服务器进行同步，校正本地时间。常用的 NTP 服务器包括 pool.ntp.org 等。还可以使用编程语言提供的时间同步库，例如 Python 的 ntplib 库。在关键操作前，先进行一次时间同步，可以有效避免时间戳误差导致的认证问题。