欧易OKX API接口：探索数字资产交易无限可能

欧易全球站API接口：探索数字资产交易的无限可能

1. 概述

欧易（OKX）全球站API接口为开发者提供一套功能完备且强大的程序化访问工具，以便于访问和操控欧易交易平台的各项核心功能，例如实时行情数据获取、自动化交易执行、全面的账户管理以及风险控制等。这套API接口涵盖了现货交易、合约交易、期权交易以及杠杆交易等多个业务场景，旨在满足不同类型开发者的需求。借助这些API接口，开发者能够高效构建高度定制化的交易机器人，实现自动化交易策略；搭建专业的数据分析平台，深入挖掘市场趋势；以及开发其他基于区块链技术的创新型金融应用，例如量化交易系统、套利机器人、以及自动跟单系统等。

本详细文档旨在为不同经验水平的开发者提供一份全面且深入的指南，力求帮助他们系统性地理解、高效地使用欧易全球站API接口。文档内容覆盖API接口的认证方式、请求参数详解、返回数据格式说明，以及常见问题的解答，旨在降低开发门槛，加速应用开发进程。通过本指南，开发者可以快速上手，充分利用欧易API接口的强大功能，提升交易效率，并拓展其在加密货币领域的应用范围。文档还会持续更新，以便跟进欧易API的最新特性和变更，确保开发者能够获得最新、最准确的信息。

2. API接口分类

欧易API接口根据其功能和访问权限，主要划分为以下几大类别，方便开发者根据自身需求选择合适的接口进行集成：

• 公共接口（Public API）： 此类接口提供无需身份验证即可访问的公开市场数据，是了解市场动态的基础。具体包括：
  • 行情数据： 提供实时和历史的交易价格、成交量、深度信息等，帮助开发者构建数据分析模型。
  • 交易对信息： 列出所有可交易的币种对，包括交易手续费率、最小交易数量等参数。
  • K线数据： 提供不同时间周期的K线图数据，用于技术分析和趋势预测。
  • 平台公告： 获取欧易官方发布的公告，了解平台最新动态和规则变更。
• 账户接口（Account API）： 用于查询和管理用户账户相关信息的接口，所有操作均需要进行身份验证，确保账户安全。具体功能包括：
  • 余额查询： 查询用户账户中各种币种的可用余额、冻结余额等。
  • 交易记录查询： 查询用户的历史交易记录，包括成交价格、成交数量、手续费等详细信息。
  • 账户资产查询： 查询用户账户的资产总值，包括法币估值等。
  • API权限查询： 查询当前API Key所拥有的权限，方便开发者进行权限管理。
• 交易接口（Trade API）： 用于执行各种交易操作的接口，是实现自动化交易和量化交易的核心。同样需要进行身份验证。具体操作包括：
  • 下单： 创建新的买单或卖单，可以选择市价单、限价单、止损单等多种订单类型。
  • 撤单： 取消尚未成交的订单。
  • 查询订单状态： 查询订单的当前状态，如待成交、部分成交、全部成交、已撤销等。
  • 批量下单/撤单： 一次性提交多个下单或撤单请求，提高交易效率。
  • 查询历史委托： 查询用户的历史委托记录，包括委托价格、委托数量等信息。
• 资金接口（Funding API）： 用于进行资金划转和管理操作的接口，涉及到用户资金安全，必须进行严格的身份验证。具体功能包括：
  • 充币： 获取用户的充币地址，方便用户将数字资产充值到欧易账户。
  • 提币： 将用户账户中的数字资产提取到指定的外部地址。
  • 资金划转： 在欧易的不同账户之间进行资金划转，如从交易账户划转到资金账户。
  • 查询充提币记录： 查询用户的充币和提币历史记录。
  • 余币宝操作： 将闲置资金存入或取出余币宝，赚取利息。

3. 身份验证

为了保障API接口的安全性，特别是对于涉及用户数据和交易操作的接口，身份验证机制至关重要。通常情况下，我们会采用API Key和Secret Key相结合的方式进行身份验证。

API Key： API Key的作用类似于用户名，它是一个公开的字符串，用于唯一标识您的用户身份或应用程序身份。每个注册用户或应用程序都会分配一个唯一的API Key，在每次调用API接口时，都需要携带该API Key，以便服务器识别请求的来源。

Secret Key： Secret Key相当于密码，是一个保密的字符串，只有您和服务器知道。Secret Key用于生成签名，该签名可以验证请求的完整性和真实性，防止恶意篡改和伪造请求。请务必妥善保管您的Secret Key，切勿泄露给他人。

签名生成流程： 一般来说，签名生成的过程包括以下几个步骤：

1. 构建请求字符串： 将请求参数按照一定的规则（例如，按照参数名称的字母顺序）排序，然后拼接成一个字符串。通常需要包含时间戳、API Key以及其他必要的请求参数。
2. 使用 Secret Key 进行哈希： 使用 Secret Key 对构建好的请求字符串进行哈希运算，常见的哈希算法包括 HMAC-SHA256 或 MD5。
3. 将签名添加到请求头或请求参数中： 将生成的签名添加到HTTP请求的头部（例如， Authorization 字段）或作为请求参数传递给服务器。

服务器验证： 服务器收到请求后，会使用相同的算法和您的 Secret Key 重新计算签名，然后将计算出的签名与请求中携带的签名进行比较。如果两个签名一致，则说明请求是合法的，可以继续处理；否则，服务器会拒绝该请求。

通过这种方式，可以有效防止未经授权的访问和数据篡改，确保API接口的安全性和可靠性。

3.1 API Key 获取

用户若要通过编程方式访问欧易交易所，需要在欧易全球站的个人中心创建API Key。API Key 是应用程序编程接口 (API) 的访问凭证，允许用户在不直接登录账户的情况下，安全地自动化交易、获取市场数据等操作。

创建API Key时，必须谨慎设置权限，例如只读权限（仅用于获取数据）、交易权限（允许执行买卖操作）或提现权限（允许转移资产，需谨慎授予）。权限设置应遵循最小权限原则，即仅授予API Key 完成特定任务所需的最低权限集，降低潜在的安全风险。还可以设置IP白名单，限制API Key 只能从指定的IP地址访问，进一步提升安全性。

API Key 通常包含两个部分：API Key 本身（也称为 Public Key），用于标识用户；Secret Key（也称为 Private Key），用于对请求进行签名，验证请求的合法性。请务必以最高安全标准妥善保管API Key 和 Secret Key，切勿将其存储在不安全的位置或以任何方式泄露给他人。一旦泄露，恶意行为者可能会利用 API Key 访问或控制您的账户，造成不可挽回的损失。

建议定期更换 API Key，并启用双重验证 (2FA) 等安全措施，增强账户的安全性。同时，密切监控 API Key 的使用情况，及时发现并处理任何异常活动。如果怀疑 API Key 泄露，应立即撤销该 API Key 并创建新的 API Key。

3.2 签名生成

为了确保API请求的真实性和完整性，防止恶意篡改，签名机制至关重要。签名利用Secret Key对请求参数进行加密生成，服务端通过验证签名来确认请求的合法性。签名算法的具体步骤如下：

1. 参数排序： 将所有请求参数（包括查询参数和请求体中的参数，但不包括签名本身）按照其参数名的字母顺序进行升序排列。这是为了确保即使参数顺序不同，最终生成的签名结果也一致。
2. 字符串拼接： 将排序后的参数按照 key=value 的形式拼接成一个字符串。如果参数值本身包含特殊字符，需要进行URL编码。多个参数之间不使用任何分隔符直接连接。
3. HMAC-SHA256加密： 使用Secret Key作为密钥，对拼接后的字符串进行HMAC-SHA256加密。HMAC-SHA256是一种带有密钥的哈希算法，能够有效地防止消息被篡改。
4. Base64编码： 将HMAC-SHA256加密后的二进制结果转换为Base64编码。Base64是一种常用的编码方式，可以将二进制数据转换为可打印的ASCII字符，方便在网络上传输和存储。

以下是一个Python示例代码，演示如何生成签名：

import hmac import hashlib import base64

def generate_signature(secret_key, timestamp, method, request_path, body=None): """ 生成签名 :param secret_key: Secret Key，用于加密请求参数的密钥 :param timestamp: 时间戳（秒），表示请求发送的时间 :param method: HTTP方法 (GET, POST, PUT, DELETE)，请求的HTTP方法 :param request_path: 请求路径，API的请求路径 :param body: 请求体 (JSON格式的字符串)，POST或PUT请求时需要传递的请求体数据，默认为None :return: 签名字符串，生成的签名字符串 """ message = str(timestamp) + str.upper(method) + request_path if body: message += body message = bytes(message, 'utf-8') secret = bytes(secret_key, 'utf-8')

    hmac_obj = hmac.new(secret, message, digestmod=hashlib.sha256)
    signature = base64.b64encode(hmac_obj.digest()).decode('utf-8')
    return signature

注意事项：

• 时间戳同步： 客户端和服务器的时间戳必须保持同步，误差不应超过允许的范围，否则签名验证将失败。通常建议使用网络时间协议（NTP）进行时间同步。
• Secret Key安全： Secret Key是保密的，应妥善保管，避免泄露。不要将Secret Key硬编码到客户端代码中，更不要将其提交到公共代码仓库。
• 编码一致性： 在进行字符串拼接和加密时，务必保持编码一致。示例代码中使用的是UTF-8编码，如果使用其他编码，可能会导致签名结果不一致。
• 参数完整性： 所有参与签名计算的参数都必须包含在请求中，否则签名验证将失败。
• URL编码： 如果参数值包含特殊字符，例如空格、加号、斜杠等，需要进行URL编码，以确保签名计算的正确性。

示例

为了确保API请求的安全，我们需要生成一个签名。以下示例展示了如何使用密钥、时间戳、HTTP方法和请求路径生成签名。

定义以下变量：

secret key = "YOUR SECRET_KEY" 你的私有密钥，用于签名。请妥善保管你的私有密钥，切勿泄露给他人。

timestamp = 1678886400 # 时间戳，秒 请求发起的时间戳，以秒为单位。时间戳必须是自Unix纪元（1970年1月1日 00:00:00 UTC）以来的秒数。确保时间戳的准确性，避免出现因时间偏差导致的签名验证失败。

method = "GET" HTTP请求方法，例如GET、POST、PUT或DELETE。 请务必使用与实际API请求一致的方法。

request_path = "/api/v5/account/balance" API请求的路径。 请求路径必须与你要访问的API端点完全匹配。路径通常不包含域名部分。

接下来，使用这些变量生成签名：

signature = generate signature(secret key, timestamp, method, request_path) 调用 generate_signature 函数，传入私钥、时间戳、HTTP方法和请求路径，生成签名。 generate_signature 函数的具体实现取决于所使用的签名算法，常见的算法包括HMAC-SHA256。

打印生成的签名：

print(signature) 输出生成的签名字符串。这个签名字符串将作为请求头的一部分发送到API服务器，用于验证请求的合法性。

3.3 请求头设置

在与交易所的API进行交互时，准确设置请求头至关重要，它能够确保请求的身份验证、数据完整性以及数据格式的正确解析。以下详细说明了在发送API请求时需要在请求头中包含的关键信息：

• OK-ACCESS-KEY : API Key。这是你在交易所注册后获得的唯一身份标识，类似于用户名，用于识别你的账户。请务必妥善保管你的API Key，避免泄露，因为它关系到你的资金安全。
• OK-ACCESS-SIGN : 签名。这是一个通过你的API Secret Key对请求内容进行加密生成的字符串，用于验证请求的真实性和完整性。签名算法通常涉及哈希函数（如SHA256）和你的API Secret Key。服务器会使用相同的算法和密钥来验证签名，以确保请求未被篡改。生成签名的具体方法请参考API文档中的签名算法说明。
• OK-ACCESS-TIMESTAMP : 时间戳（秒）。时间戳表示请求发送的时间，通常以Unix时间戳的形式表示，即自1970年1月1日以来经过的秒数。时间戳用于防止重放攻击。交易所通常会拒绝时间戳与服务器时间相差过大的请求，以防止恶意用户截获请求并重复发送。确保你的系统时间与交易所服务器时间同步。
• OK-ACCESS-PASSPHRASE : 资金密码（如果需要）。资金密码是在进行资金操作（如提币、划转等）时需要提供的密码，用于进一步验证你的身份。如果API请求涉及到敏感的资金操作，则必须在请求头中包含资金密码。并非所有API接口都需要资金密码。
• Content-Type : application/ (如果请求体是JSON格式)。 Content-Type 标头指定了请求体的MIME类型。当请求体包含JSON格式的数据时，必须将其设置为 application/ ，以便服务器正确解析请求体中的数据。如果请求体是其他格式（例如 application/x-www-form-urlencoded ），则需要相应地设置 Content-Type 标头。

4. 公共接口示例：获取交易对信息

以下示例演示如何使用公共接口获取交易对信息，以便于用户了解市场动态和交易规则。

在加密货币交易所中，交易对信息至关重要，它包含了该交易对的详细参数，例如：交易对的名称（如BTC/USDT）、基础货币和报价货币、价格精度、最小交易量、最大交易量以及交易状态等关键数据。这些信息帮助交易者制定交易策略，避免因不了解规则而造成损失。

通过调用交易所提供的公共API接口，开发者可以程序化地获取这些信息。通常，这些接口采用RESTful风格，并返回JSON格式的数据。开发者可以使用各种编程语言（如Python、Java、JavaScript等）编写代码，解析JSON数据，并将其用于各种应用场景，例如：构建交易机器人、开发行情分析工具、监控市场价格波动等。

获取交易对信息通常不需要身份验证，任何用户都可以访问。交易所会提供详细的API文档，说明接口的URL、请求方法、请求参数以及返回数据的结构。开发者需要仔细阅读API文档，并按照文档的要求构建HTTP请求，才能成功获取所需的数据。

交易所可能会限制API的调用频率，以防止滥用。开发者需要合理地设计程序，避免频繁地调用API，以免被交易所屏蔽。可以使用缓存技术，将获取到的交易对信息缓存起来，减少API的调用次数。

请求URL: https://www.okx.com/api/v5/public/instruments?instType=SPOT 请求方法: GET

请求参数:

• instType : 交易对类型，指定您希望检索信息的交易品种类型。例如：
  • SPOT : 现货交易对，表示直接买卖加密货币的交易市场，例如 BTC/USDT。
  • FUTURES : 永续合约交易对，代表一种没有到期日的合约，允许交易者以杠杆方式推测加密货币的价格走势，例如 BTC-USD-SWAP。需要注意的是，不同交易所的永续合约代码格式可能略有不同。
  • SWAP : 另一种永续合约的表示方式，与 FUTURES 类似，但有些平台使用 SWAP 来明确区分永续合约。
  • OPTION : 期权交易对，允许交易者购买或出售在未来某个日期以特定价格买入或卖出加密货币的权利，例如 BTC-USD-240628-70000-C，表示行权日为2024年6月28日，行权价为70000美元的看涨期权。
  • MARGIN : 杠杆现货交易对，允许交易者借入资金进行现货交易，从而放大收益和风险。
  选择正确的 instType 对于获取准确的交易信息至关重要，因为不同类型的交易对对应不同的市场深度、交易规则和风险特征。错误的类型选择可能导致API返回错误或不相关的数据。

响应示例:

以下JSON格式的响应示例展示了交易所提供的交易对信息，以便开发者理解数据结构。

{ "code": "0", "msg": "", "data": [ { "instType": "SPOT", "instId": "BTC-USDT", "uly": "BTC", "baseCcy": "BTC", "quoteCcy": "USDT", "settleCcy": null, "ctVal": null, "ctMult": null, "ctValCcy": null, "optType": null, "stk": null, "listTime": "1566873600000", "expTime": null, "lever": null, "tickSz": "0.01", "lotSz": "0.0001", "minSz": "0.0001", "ctType": null, "alias": null, "state": "live" }, { "instType": "SPOT", "instId": "ETH-USDT", "uly": "ETH", "baseCcy": "ETH", "quoteCcy": "USDT", "settleCcy": null, "ctVal": null, "ctMult": null, "ctValCcy": null, "optType": null, "stk": null, "listTime": "1566873600000", "expTime": null, "lever": null, "tickSz": "0.01", "lotSz": "0.0001", "minSz": "0.0001", "ctType": null, "alias": null, "state": "live" } ] }

字段解释:

• code: 返回码，"0" 通常表示成功。其他值可能表示错误，具体含义请参考API文档。
• msg: 错误信息，成功时为空字符串。
• data: 包含交易对信息的数组。
• instType: 交易工具类型，例如 "SPOT" (现货)。其他可能的值包括 "FUTURES" (期货), "SWAP" (永续合约), "OPTION" (期权)。
• instId: 交易工具ID，例如 "BTC-USDT"。这是用于在交易API中指定交易对的唯一标识符。
• uly: 标的资产，例如 "BTC"。 对于衍生品合约，比如期货和永续合约，`uly`表示基础资产的symbol。
• baseCcy: 基础货币，例如 "BTC"。在BTC-USDT交易对中，BTC是基础货币。
• quoteCcy: 计价货币，例如 "USDT"。在BTC-USDT交易对中，USDT是计价货币。
• settleCcy: 结算货币。 对于交割合约和永续合约，指定结算时使用的货币。对于现货，此字段通常为 null。
• ctVal: 合约面值。仅适用于合约交易。
• ctMult: 合约乘数。仅适用于合约交易。
• ctValCcy: 合约面值计价货币。仅适用于合约交易。
• optType: 期权类型。仅适用于期权交易，可能的值有“C”（看涨期权）和“P”（看跌期权）。
• stk: 标的指数。 仅适用于指数期权合约。
• listTime: 上市时间，Unix时间戳（毫秒）。
• expTime: 到期时间，Unix时间戳（毫秒）。 仅适用于交割合约和期权合约。
• lever: 杠杆倍数。
• tickSz: 最小价格变动单位。例如，"0.01" 表示价格最小变动0.01 USDT。
• lotSz: 最小交易数量单位。例如，"0.0001" 表示最小交易0.0001 BTC。
• minSz: 最小下单数量。
• ctType: 合约类型。仅适用于合约交易。 例如，"linear"（线性合约）。
• alias: 合约别名。 仅适用于交割合约和永续合约，例如 "this_week" (当周), "next_week" (次周), "quarter" (当季), "next_quarter" (下季), null (永续合约)。
• state: 交易对状态，"live" 表示正常交易。其他可能的状态包括 "halt" (暂停交易), "preopen" (预开放)。

开发者可以根据这些信息来构建交易策略，显示市场数据等。务必查阅交易所的官方API文档以获取最准确和最新的信息。

5. 账户接口示例：查询账户余额

以下示例演示如何通过API接口查询指定账户的可用余额，该功能是账户管理的基础组成部分，允许用户或应用程序实时了解资金状况。

示例场景： 假设您正在开发一个加密货币交易机器人，需要定期检查账户余额，以便根据可用资金执行交易策略。或者，您可能正在构建一个钱包应用程序，需要向用户显示其当前的账户余额。

实现方式： 通常，查询账户余额会涉及到向交易所或钱包服务提供商发送一个API请求。该请求需要包含您的API密钥和账户标识符。服务器会验证您的身份，然后返回一个JSON格式的响应，其中包含账户余额信息。余额信息通常包括可用余额、冻结余额和总余额。

安全提示： 在使用API密钥时，务必妥善保管，避免泄露。建议将API密钥存储在安全的地方，例如环境变量或密钥管理系统中。还应限制API密钥的权限，使其只能访问必要的资源。

请求URL: https://www.okx.com/api/v5/account/balance 请求方法: GET 请求参数: 无

请求头:

• OK-ACCESS-KEY : YOUR_API_KEY。 此请求头用于提供您的API密钥，该密钥是您访问OKX API的身份凭证。请务必妥善保管您的API密钥，避免泄露，防止未经授权的访问。
• OK-ACCESS-SIGN : YOUR_SIGNATURE。 此请求头用于提供您的签名，该签名用于验证请求的完整性和真实性。签名是通过将请求参数、请求体（如果存在）和您的私钥结合使用特定签名算法生成的。确保您的签名算法与OKX API文档中指定的算法一致。
• OK-ACCESS-TIMESTAMP : YOUR_TIMESTAMP。 此请求头用于提供请求的时间戳，以防止重放攻击。时间戳必须是Unix时间戳，单位为秒。时间戳与服务器时间的偏差应在允许的范围内，否则请求将被拒绝。强烈建议使用服务器时间同步客户端来确保时间戳的准确性。

响应示例:

以下JSON响应展示了一个账户资产快照，它提供了关于特定加密货币（本例中为USDT）余额的详细信息。

{
   "code":  "0",
  "msg": "",
   "data":  [
    {
          "ccy": "USDT",
          "eq": "1000.00",
       "cashBal": "1000.00",
       "isoEq": "0",
        "availBal": "1000.00",
         "ordFrozen": "0.00"
     }
  ]
}

字段解释：

• code : 响应代码。 "0" 通常表示成功，非零值表示错误。应根据API文档检查具体的错误代码定义。
• msg : 与响应代码相关的消息。如果 code 不是 "0"，则此字段应包含错误消息，以便诊断问题。如果 code 是"0"，则为空字符串。
• data : 包含资产信息的数组。在此示例中，数组只包含一个元素，即USDT的余额信息。
• ccy : 货币类型，此处为USDT (Tether)。代表账户中持有的稳定币种类。
• eq : 等值余额。 表示该币种的总等值余额，这里是1000.00 USDT。
• cashBal : 现金余额。 这是账户中可用于交易的实际现金数量，这里是1000.00 USDT。
• isoEq : 逐仓保证金等值余额。 仅在账户使用逐仓保证金模式时相关，表示逐仓仓位的等值余额。 如果不使用，则为0。
• availBal : 可用余额。 这是可以立即用于交易或提款的余额，这里是1000.00 USDT。
• ordFrozen : 订单冻结金额。 这是由于未完成的订单而被冻结的金额，这里是0.00 USDT。 表示没有资金因挂单而被占用。

重要提示： 实际应用中， data 数组可能包含多个元素，代表账户中持有的不同加密货币的余额信息。请务必查阅API文档以了解所有可能的响应字段和数据类型。

6. 交易接口示例：下单

以下示例演示如何使用交易接口进行下单操作，涵盖了常见的下单参数和注意事项，以便开发者能够更好地理解和使用交易接口。

在进行下单之前，需要确保已经完成了身份验证和权限申请，并且了解了交易平台的交易规则和手续费标准。不同的交易平台可能采用不同的API规范和认证方式，因此需要仔细阅读平台的API文档。

下单操作通常需要指定以下参数：

• 交易对 (Symbol): 明确指定需要交易的加密货币对，例如 BTC/USDT 或 ETH/BTC。必须确保交易对在交易所是有效且可交易的。
• 方向 (Side): 指定交易方向，买入 (Buy) 或卖出 (Sell)。买入表示购买基础货币，卖出表示出售基础货币。
• 类型 (Type): 指定订单类型，常见的订单类型包括市价单 (Market Order) 和限价单 (Limit Order)。市价单会立即以当前市场最优价格成交，而限价单则会在指定的价格或更好的价格成交。
• 数量 (Quantity): 指定交易的数量，即买入或卖出的加密货币数量。需要注意最小交易单位和精度要求。
• 价格 (Price): 如果订单类型是限价单，则需要指定限价。该价格是您愿意买入或卖出的最高或最低价格。
• 时间有效性 (Time In Force, TIF): 指定订单的有效时间，常见的 TIF 包括：GTC (Good-Til-Canceled，直到取消)，IOC (Immediate-Or-Cancel，立即成交或取消)，FOK (Fill-Or-Kill，全部成交或取消)。
• 高级选项 (Optional Parameters): 一些平台还提供高级选项，例如止损单 (Stop-Loss Order) 和止盈单 (Take-Profit Order)，允许用户设置触发价格和委托价格，以实现自动化的风险管理。

以下是一个简化的下单请求示例 (以伪代码形式展示，实际API请求格式可能因交易所而异):

{
  "symbol": "BTC/USDT",
  "side": "BUY",
  "type": "LIMIT",
  "quantity": 0.1,
  "price": 28000.0,
  "timeInForce": "GTC"
}

在发送下单请求后，交易平台会返回一个订单ID (Order ID)。您可以使用该订单ID来查询订单状态，例如是否已成交、部分成交或已取消。请务必处理好各种可能的返回状态和错误代码，并采取相应的措施，例如重试下单或取消订单。

请求URL: https://www.okx.com/api/v5/trade/order 请求方法: POST

请求体:

此JSON请求体用于向交易所提交交易订单，以下是各字段的详细解释：

{
  "instId": "BTC-USDT",
  "tdMode": "cash",
  "side":  "buy",
  "ordType": "market",
  "sz":  "0.001"
}

字段说明：

• instId (交易对): "BTC-USDT" 指定了要交易的交易对。在此例中，代表比特币 (BTC) 兑美元泰达币 (USDT) 的交易对。交易所使用此参数确定要交易的资产。

• tdMode (交易模式): "cash" 表示现货交易模式。也可能存在其他模式，例如"isolated"（逐仓杠杆）或 "cross"（全仓杠杆），具体取决于交易所支持的交易类型。现货交易意味使用账户中实际拥有的资产进行交易，不涉及借贷。

• side (交易方向): "buy" 指示交易方向为买入。 另一个常见值是 "sell" ，表示卖出。 此参数告知交易所用户希望买入或卖出指定的资产。

• ordType (订单类型): "market" 指定订单类型为市价单。 市价单会以当前市场上最佳可用价格立即执行。其他常见的订单类型包括 "limit" (限价单)，允许用户指定订单执行的价格。

• sz (交易数量): "0.001" 表示交易数量。 在此例中，表示买入 0.001 个比特币。 交易数量的单位取决于交易对中基础资产的单位。此参数定义用户希望交易的资产数量。

重要提示：

• 提交交易请求前，务必仔细核对 instId 、 side 和 sz 等参数，确保订单符合预期。
• 使用市价单时，成交价格可能与下单时的价格略有差异，这是由于市场波动造成的。
• 实际的请求体可能包含更多字段，例如 clOrdId (客户端自定义订单ID)，用于唯一标识订单。请参考具体的交易所API文档。

请求头:

• OK-ACCESS-KEY : YOUR_API_KEY

  您的API密钥，用于身份验证。请确保妥善保管您的API密钥，避免泄露。每个用户都有唯一的API密钥，通过此密钥来识别您的账户并授权访问API资源。

• OK-ACCESS-SIGN : YOUR_SIGNATURE

  您的签名，通过特定的签名算法生成。签名用于验证请求的完整性和真实性，防止篡改。 签名算法通常涉及您的API密钥、请求参数和时间戳等信息。 正确的签名对于成功调用API至关重要。

• OK-ACCESS-TIMESTAMP : YOUR_TIMESTAMP

  时间戳，表示请求发送的时间。时间戳用于防止重放攻击。通常以Unix时间戳（从1970年1月1日0时0分0秒UTC起至现在的总秒数）表示。 时间戳应该与服务器时间保持同步，避免因时间偏差导致请求失败。

• Content-Type : application/

  指定请求体的MIME类型为JSON。 说明您发送的数据格式为JSON。 这是API常用的数据格式，易于解析和处理。 确保您的请求体符合JSON格式规范，否则服务器可能无法正确解析。

请求参数:

• instId : 交易对ID (Instrument ID) ，用于指定交易的市场。例如， BTC-USDT 表示比特币兑美元泰达币的交易对。务必使用交易所支持的正确交易对ID。
• tdMode : 交易模式 (Trade Mode) ，指示交易类型。例如， cash 代表现货交易，允许直接买卖加密货币。其他模式可能包括杠杆交易（ margin ）或模拟交易（ demo ），具体取决于交易所支持的模式。
• side : 交易方向 (Side) ，定义交易是买入还是卖出。 buy 表示买入，用于以指定价格或市场价格购买加密货币。 sell 表示卖出，用于以指定价格或市场价格出售持有的加密货币。
• ordType : 订单类型 (Order Type) ，指定订单的执行方式。 market 表示市价单，将以当前市场最优价格立即执行。 limit 表示限价单，只有当市场价格达到或超过指定价格时才会执行。其他订单类型可能包括止损单（ stop ）或跟踪止损单（ trailing_stop ），具体取决于交易所支持的订单类型。
• sz : 交易数量 (Size) ，表示要交易的加密货币数量。数量单位通常是交易对中基础货币的数量。例如，在 BTC-USDT 交易对中， sz 为 1 表示交易 1 个比特币。 请注意，交易数量应符合交易所规定的最小交易数量限制。

响应示例:

以下 JSON 响应示例展示了订单操作执行后的服务器反馈。 code 字段表示操作结果的状态码， msg 字段提供关于操作结果的详细信息， data 字段包含一个数组，数组中的每个元素代表一个订单操作的结果。

{
"code": "0",
"msg": "",
"data": [
{
"ordId": "1234567890",
"clOrdId": "",
"tag": "",
"sCode": "0",
"sMsg": ""
}
]
}

字段解释：

• code ：字符串类型，表示响应状态码。"0" 通常表示操作成功，其他非 "0" 的值可能表示错误或异常情况，需要参考具体的 API 文档来确定错误类型。
• msg ：字符串类型，提供关于操作结果的文本描述。如果 code 为 "0"，则 msg 通常为空字符串，否则 msg 会包含详细的错误信息。
• data ：数组类型，包含订单操作的结果列表。每个元素都是一个 JSON 对象，描述单个订单操作的状态。
• ordId ：字符串类型，表示服务器生成的唯一订单 ID。这是一个重要的标识符，用于跟踪订单状态。示例值 "1234567890" 仅为示例，实际值会根据交易所的规则生成。
• clOrdId ：字符串类型，表示客户端提供的订单 ID。如果客户端在创建订单时指定了 clOrdId ，则服务器会在响应中返回该值，方便客户端进行订单匹配和管理。如果客户端未指定 clOrdId ，则该字段可能为空字符串。
• tag ：字符串类型，用于存储与订单相关的自定义标签或元数据。这个字段允许客户端将额外的信息与订单关联，方便后续的分析和处理。
• sCode ：字符串类型，表示订单操作的子状态码。即使 code 为 "0" 表示操作总体成功， sCode 也可能包含更详细的状态信息，例如部分成交或挂单等。
• sMsg ：字符串类型，提供关于订单操作子状态的文本描述。与 sCode 配合使用，可以更精确地了解订单的执行情况。

请注意，上述示例和字段解释仅供参考。实际的响应格式和字段可能会因交易所、API 版本和具体操作而异。开发者需要仔细阅读 API 文档，并根据实际情况进行解析和处理。

7. 错误处理

API接口的响应数据结构中，关键在于 code 字段，它承担着指示请求处理状态的重要职责。当 code 字段的值为 "0" 时，这明确表明API请求已成功执行，并返回了期望的结果。反之，任何非 "0" 的 code 值均表示请求过程中出现了某种错误或异常情况。

为了帮助开发者更有效地诊断和解决潜在问题，API在请求失败时会提供额外的错误信息。这些信息通常包含在响应的 msg 字段中。 msg 字段的内容可能包括错误的具体类型、错误发生的原因，以及可能的解决方案建议。开发者应仔细分析 code 和 msg 字段，以便准确定位问题并采取适当的措施进行错误处理。

在实际开发中，针对不同的 code 值，开发者应制定相应的错误处理策略。例如，可以根据 code 值进行条件判断，针对不同的错误类型执行不同的处理逻辑。这可能包括重新发送请求、记录错误日志、向用户显示错误信息，或采取其他必要的措施以保证应用程序的稳定性和可靠性。建议开发者建立完善的错误监控和告警机制，以便及时发现和处理潜在的问题。

8. 频率限制

为了确保欧易全球站API平台的稳定性和可用性，我们实施了严格的频率限制策略。这些限制旨在防止恶意攻击、滥用行为，以及避免服务器过载，从而保障所有用户的公平访问体验。不同的API接口，由于其功能复杂性和资源消耗程度不同，因此对应不同的频率限制标准。

开发者在使用欧易全球站API时，务必仔细查阅官方文档中关于各个接口频率限制的具体规定。例如，某些查询市场数据的接口可能允许更高的请求频率，而交易相关的接口则会受到更严格的限制。开发者应密切关注其应用程序的请求速率，并采取必要的措施来有效控制请求频率，从而避免触发频率限制。

当应用程序的请求频率超过了API接口设定的限制时，API服务器将会返回一个HTTP状态码 "429 Too Many Requests" 以及相关的错误信息。这意味着您的应用程序已被暂时阻止访问该接口。为了避免这种情况，我们建议开发者实施以下策略：

• 实施重试机制： 当收到 "429" 错误码时，暂停发送新的请求，并等待一段预设的时间后，再尝试重新发送之前的请求。这个等待时间应该采用指数退避策略，即每次重试时都增加等待时间，以避免在短时间内再次触发频率限制。
• 使用请求队列： 将所有需要发送的API请求放入一个队列中，并按照预定的速率从队列中取出请求进行发送。这样可以平滑请求流量，避免突发性的请求峰值。
• 缓存数据： 对于一些不经常变化的数据，例如交易对信息或静态的市场数据，可以将这些数据缓存在本地。这样可以减少对API接口的请求次数，从而降低触发频率限制的风险。
• 优化代码逻辑： 审查应用程序的代码逻辑，确保只在必要时才发送API请求。避免不必要的轮询或重复请求。

请注意，如果您持续违反频率限制策略，您的API密钥可能会被暂时或永久禁用。因此，请务必认真对待频率限制问题，并采取必要的措施来确保您的应用程序符合我们的要求。欧易全球站致力于为所有开发者提供稳定、可靠的API服务，并希望您能理解和支持我们的频率限制策略。