想玩欧易合约？3分钟教你用Python API搞定！

日期： 栏目：知识 浏览：148

欧易智能合约 API

本文档旨在详细介绍欧易交易所提供的智能合约 API，帮助开发者快速接入并利用 API 构建自己的交易策略、监控市场数据、以及执行相关智能合约操作。

概述

欧易智能合约 API 提供了一整套全面的接口，旨在赋能开发者和机构用户，使其能够通过编程方式无缝访问和管理他们在欧易平台上持有的智能合约账户。借助这些API，用户可以执行包括但不限于以下关键操作：高效查询账户的详细信息，例如余额、已部署合约的地址以及其他相关账户属性；精确提交交易订单，涵盖合约部署、函数调用以及资产转移等操作；实时获取准确的市场数据，为交易决策提供有力支持，包括合约交易对的价格、成交量和订单簿信息；以及执行与智能合约交互相关的各种其他操作，从而实现自动化交易策略和定制化应用开发。

为了确保易用性和广泛的兼容性，欧易智能合约 API 严格遵循 RESTful 架构风格，这使得API的集成过程变得简单直接，降低了开发门槛。API 还提供对多种主流编程语言的支持，例如 Python、Java 和 JavaScript 等，从而满足不同开发者的偏好和技术栈需求。通过详细的文档、示例代码和强大的技术支持，欧易致力于为用户提供流畅、高效的智能合约 API 使用体验，助力其在快速发展的去中心化金融（DeFi）领域取得成功。

认证

为了保障账户的安全性和交易的合规性，所有发送至欧易智能合约API的请求都必须经过严格的身份验证流程。 欧易智能合约API采用基于API密钥对的身份验证机制，确保只有授权用户才能访问和操作相关资源。API密钥对由公钥（API Key）和私钥（Secret Key）组成，类似于银行卡号和密码，是您访问API的唯一凭证。

您需要在欧易平台上创建API密钥对。请务必妥善保管您的Secret Key，切勿泄露给任何第三方，因为它用于生成签名，任何持有您的Secret Key的人都可以伪造您的请求。 API Key则可以公开使用，用于标识您的身份。创建API密钥时，您可以设置API密钥的权限，例如交易、查询等，以及IP访问限制，进一步增强账户的安全性。

在每个API请求的头部（Header）中，您需要包含以下信息：您的API Key，用于标识您的身份；时间戳（Timestamp），表明请求发送的时间；以及基于请求参数和您的Secret Key生成的数字签名（Signature），用于验证请求的完整性和真实性。服务器将根据这些信息验证请求的合法性，并决定是否允许访问。

签名生成的具体步骤如下：

  1. 将所有请求参数（包括URL参数和请求体中的参数）按照字母顺序排序，并将参数名和参数值用等号连接，形成字符串。
  2. 将时间戳添加到排序后的字符串中。
  3. 使用您的Secret Key对该字符串进行哈希运算，通常使用HMAC-SHA256算法。
  4. 将哈希运算的结果转换为十六进制字符串，作为您的签名。

请参考欧易官方文档，了解更详细的签名算法和代码示例，以便正确地生成签名并成功通过身份验证。

API 密钥对生成

为了安全地访问和管理您的欧易账户，您需要生成一对 API 密钥，包括公钥（API Key）和私钥（Secret Key）。API 密钥允许您在无需直接登录账户的情况下，通过编程方式与欧易交易所进行交互，例如进行交易、查询账户余额或获取市场数据。

  1. 登录您的欧易账户： 请使用您的用户名和密码（或通过其他身份验证方式）登录您的欧易官方网站。请务必确认您正在访问的是官方且安全的欧易网站，以防止遭受钓鱼攻击。
  2. 访问 "API 管理" 页面： 成功登录后，导航至您的账户设置或个人中心。在该区域，您应该能找到 "API 管理" 或类似的选项。点击进入该页面，开始创建您的 API 密钥。
  3. 创建新的 API 密钥对： 在 API 管理页面，您需要创建一个新的 API 密钥对。您可能需要为您的 API 密钥设置一个名称或标签，以便于识别和管理不同的密钥。同时，您需要仔细设置API的权限。欧易通常会提供多种权限选项，例如只读权限（用于获取市场数据）或交易权限（用于执行交易）。请根据您的需求谨慎选择相应的权限，并确保仅授予必要的权限，以最大限度地降低安全风险。
  4. 务必安全保存您的私钥（Secret Key），该密钥用于生成签名： 生成 API 密钥对后，您将获得一个公钥（API Key）和一个私钥（Secret Key）。 请务必安全地保存您的私钥。 私钥就像是您账户的密码，拥有它的人可以代表您执行操作。欧易 强烈建议您将私钥保存在安全的地方，例如使用密码管理器或离线存储。切勿将您的私钥泄露给任何第三方。 公钥（API Key）可以公开使用，用于标识您的身份，而私钥则用于生成交易签名，以验证交易请求的有效性。每次通过 API 发送交易请求时，都需要使用私钥对请求进行签名。

请注意，API 密钥的管理至关重要。定期审查和更新您的 API 密钥，可以提高账户的安全性。如果您怀疑您的 API 密钥可能已泄露，请立即撤销该密钥并生成新的密钥对。

请求签名

每个 API 请求都需要包含一个数字签名，这是验证请求是否来自授权方的关键机制，保证了数据的完整性和安全性。 签名过程涉及多个步骤，旨在防止恶意篡改和未经授权的访问。

  1. 构建签名字符串: 签名字符串是构建签名的基础，它包含了请求的关键信息。你需要将以下元素按照特定顺序拼接成一个字符串：
    • HTTP 方法: 使用大写的 HTTP 方法，例如 GET , POST , PUT , 或 DELETE 。
    • 请求路径: 这是 API 的具体端点，例如 /api/v1/orders 。确保包含前导斜杠。
    • 请求参数: 将所有请求参数按照字母顺序（区分大小写）排序，并将其转换为查询字符串格式（例如 param1=value1&param2=value2 ）。如果参数值本身包含特殊字符，务必进行 URL 编码。
    • 请求时间戳: 使用 UTC 时间戳，通常以 Unix 时间（自 1970 年 1 月 1 日 00:00:00 UTC 以来的秒数）表示。时间戳必须在服务器允许的时间窗口内，以防止重放攻击。
    将以上各部分按照顺序连接起来，形成最终的签名字符串。例如： POST/api/v1/ordersparam1=value1&param2=value21678886400 。
  2. 使用私钥进行哈希: 使用您的私钥（Secret Key）对签名字符串进行加密哈希运算。强烈建议使用 HMAC-SHA256 算法，因为它能提供强大的安全保障。
    • HMAC-SHA256: HMAC（Hash-based Message Authentication Code）是一种消息认证码算法，它使用哈希函数和密钥来生成消息摘要。SHA256 是一个广泛使用的安全哈希算法。
    • 使用您的 Secret Key 作为 HMAC-SHA256 算法的密钥，对签名字符串进行哈希计算。这会产生一个固定长度的哈希值，作为您的签名。
  3. 将签名添加到请求头: 将生成的签名以 Base64 编码后的形式添加到请求头的 OK-ACCESS-SIGN 字段中。
    • Base64 编码: Base64 是一种将二进制数据转换为 ASCII 字符串的编码方法，以便在 HTTP 头部中传输。
    • 将 HMAC-SHA256 哈希值进行 Base64 编码，确保它可以安全地包含在 HTTP 头部中。
    • 将编码后的签名添加到 OK-ACCESS-SIGN 请求头中，例如 OK-ACCESS-SIGN: your_base64_encoded_signature 。
    服务器将使用相同的步骤验证签名，确保请求的有效性。

示例 (Python):

以下 Python 代码展示了如何生成用于加密货币交易平台 API 调用的签名。签名用于验证请求的真实性和完整性，防止恶意篡改。

import hashlib
import hmac
import time
import urllib.parse
import requests
import base64

导入必要的 Python 模块：

  • hashlib : 提供多种哈希算法，用于生成消息摘要。
  • hmac : 实现基于哈希的消息认证码 (HMAC)，用于签名生成。
  • time : 获取当前时间戳，通常作为签名的一部分。
  • urllib.parse : 用于 URL 编码，处理请求参数。
  • requests : 发送 HTTP 请求。虽然此处未直接使用，但通常与签名一起使用来发送 API 请求。
  • base64 : 用于将二进制数据编码为 Base64 字符串，便于传输。

def generate_signature(timestamp, method, request_path, body, secret_key):

定义 generate_signature 函数，该函数接收以下参数：

  • timestamp : 请求的时间戳 (Unix 时间戳)。
  • method : HTTP 请求方法 (例如：GET, POST, PUT, DELETE)。
  • request_path : API 请求的路径 (例如：/api/v1/orders)。
  • body : 请求体 (JSON 格式的字符串)。 如果请求没有 body，则传入空字符串。
  • secret_key : 与 API 密钥关联的密钥，用于生成签名，必须保密。

message = str(timestamp) + method + request_path + body

构建用于签名的消息。将时间戳、HTTP 方法、请求路径和请求体连接成一个字符串。消息的顺序必须与 API 文档中指定的一致，否则签名验证将失败。

mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), hashlib.sha256)

使用 HMAC-SHA256 算法创建 HMAC 对象。

  • bytes(secret_key, encoding='utf8') : 将密钥从字符串编码为 UTF-8 字节串。 密钥必须始终安全存储，切勿在客户端代码中硬编码。
  • bytes(message, encoding='utf-8') : 将消息从字符串编码为 UTF-8 字节串。
  • hashlib.sha256 : 指定使用 SHA256 哈希算法。

d = mac.digest()

计算消息的摘要，返回字节串格式的哈希值。

return base64.b64encode(d)

将二进制摘要数据编码为 Base64 字符串，并返回。Base64 编码后的字符串通常用于 HTTP 请求头中传递签名信息。

您的 API 密钥和私钥

在进行加密货币交易或访问交易所数据时，API 密钥和私钥是至关重要的凭证。它们允许您的应用程序安全地与交易所进行交互，执行诸如下单、查询账户余额和获取市场数据等操作。

api_key = "YOUR_API_KEY"

API 密钥（ api_key ）是一个公开的标识符，用于识别您的应用程序或账户。请妥善保管您的 API 密钥，但需要注意的是，API 密钥本身不具备执行交易的权限，它仅仅是用于初步验证您的身份。

secret_key = "YOUR_SECRET_KEY"

私钥（ secret_key ）是一个高度敏感的密钥，必须严格保密。私钥用于对您的请求进行签名，证明您有权执行特定的操作。 泄露私钥可能会导致您的账户被盗用，资金遭受损失。请务必采取一切必要的安全措施来保护您的私钥，例如将其存储在加密的环境中，并避免在不安全的网络或计算机上使用。

重要提示：

  • 切勿将您的 API 密钥和私钥泄露给任何人。
  • 不要将您的私钥存储在代码库中。
  • 定期轮换您的 API 密钥和私钥。
  • 启用双因素身份验证（2FA）以增强账户安全性。
  • 使用强密码并定期更改密码。

请务必认真对待 API 密钥和私钥的安全问题，以确保您的加密货币资产安全。

请求参数

timestamp = str(int(time.time())) 。 时间戳是发起 API 请求的关键组成部分，它用于确保请求的时效性，防止重放攻击。 此处的时间戳应为自 Unix 纪元（1970 年 1 月 1 日 00:00:00 UTC）以来经过的秒数的整数表示的字符串。 强烈建议使用服务器端时间生成时间戳，以避免因客户端时间不准确导致的问题。 在 Python 中，可以使用 time.time() 函数获取当前时间戳，并将其转换为整数和字符串。

method = "GET" 。 HTTP 请求方法指定了对给定资源执行的操作。 GET 方法用于从服务器检索数据，通常用于查询账户余额等信息。 其他常用的 HTTP 方法包括 POST (用于创建新资源)、 PUT (用于更新现有资源) 和 DELETE (用于删除资源)。 根据 API 的设计，选择合适的 HTTP 方法至关重要。

request_path = "/api/v5/account/balance" 。 请求路径是 API 端点的 URL 路径，指示要访问的特定资源或功能。 在此示例中， "/api/v5/account/balance" 指示请求获取账户余额信息。 不同的 API 端点对应于不同的功能，例如交易、订单管理、市场数据等。 务必查阅 API 文档以获取正确的请求路径。

body = "" 。 对于 GET 请求，通常不包含请求体 ( body )。 请求体用于向服务器发送数据，通常用于 POST 、 PUT 和 PATCH 请求。 GET 请求的数据通常通过 URL 参数传递。 因此，在此示例中， body 设置为空字符串。

生成签名

在构建安全的API请求时，生成签名至关重要。签名用于验证请求的来源，确保数据在传输过程中未被篡改。签名生成过程通常涉及以下步骤：

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

上述代码展示了一个通用的签名生成函数，该函数接受以下参数：

  • timestamp : 时间戳，表示请求发送的时间。时间戳应采用协调世界时（UTC），并以秒或毫秒为单位。时间戳用于防止重放攻击，服务器通常会拒绝过期的请求。
  • method : HTTP请求方法，例如 GET 、 POST 、 PUT 或 DELETE 。 请求方法必须大写。
  • request_path : 请求路径，不包含域名或查询参数。例如，对于URL https://api.example.com/v1/users?page=2 ， request_path 应为 /v1/users 。
  • body : 请求体，包含要发送的数据。对于 GET 请求， body 通常为空。对于 POST 或 PUT 请求， body 包含JSON、XML或其他格式的数据。需要注意的是， body 的格式必须与 Content-Type 头中指定的格式一致。
  • secret_key : 密钥，只有客户端和服务器知道。密钥用于对签名进行加密，防止第三方伪造请求。密钥必须保密，不能泄露给任何人。

签名生成函数的具体实现方式取决于所使用的加密算法。常见的加密算法包括：

  • HMAC-SHA256: 一种基于哈希的消息认证码算法。HMAC-SHA256是目前最常用的签名算法之一，因为它安全、高效且易于实现。
  • RSA: 一种非对称加密算法。RSA签名需要使用私钥进行签名，使用公钥进行验证。RSA签名通常用于需要高安全性的场景。
  • ECDSA: 一种基于椭圆曲线密码学的数字签名算法。ECDSA签名具有较短的签名长度，适用于移动设备和嵌入式系统。

为了提高安全性，建议对时间戳、请求方法、请求路径和请求体进行规范化处理，然后再进行签名。例如，可以按照字典顺序对请求参数进行排序，然后将排序后的参数拼接成一个字符串。规范化处理可以防止因参数顺序不同而导致签名不一致的问题。

生成的签名通常会添加到HTTP请求头中，例如 Authorization 头。服务器收到请求后，会使用相同的算法和密钥重新生成签名，然后与请求头中的签名进行比较。如果签名一致，则认为请求是合法的，否则拒绝请求。

构建请求头

在与交易所API交互时，构建正确的请求头至关重要，它包含了认证信息，允许交易所验证您的身份和授权您的请求。 以下是构建请求头的关键组成部分：

OK-ACCESS-KEY ：您的API密钥，这是交易所分配给您的唯一标识符，类似于您的用户名。 它用于识别您的账户，必须妥善保管，避免泄露。

OK-ACCESS-SIGN ：数字签名，使用您的私钥对请求内容（例如请求路径、请求参数和时间戳）进行加密哈希运算生成。 这个签名用于验证请求的完整性和真实性，防止请求被篡改。 生成签名的过程通常涉及以下步骤：

  1. 将请求参数按照字母顺序排序并拼接成字符串。
  2. 将拼接后的字符串与时间戳和您的私钥组合。
  3. 使用加密哈希算法（例如HMAC-SHA256）对组合后的字符串进行哈希运算。
  4. 将哈希结果进行Base64编码。

生成的签名必须与请求的其他部分一起发送到交易所，以便进行验证。 请务必使用正确的编码方式（例如UTF-8）对签名进行编码，以确保签名可以正确验证。 signature.decode('utf-8') 示例代码展示了使用UTF-8解码签名。

OK-ACCESS-TIMESTAMP ：时间戳，表示请求发送的时间。 时间戳用于防止重放攻击，即攻击者截获您的请求并重复发送。 交易所通常会验证时间戳是否在可接受的范围内（例如，在当前时间前后几分钟内）。 如果时间戳超出范围，则请求将被拒绝。 时间戳通常以Unix时间（自1970年1月1日以来经过的秒数）表示。

OK-ACCESS-PASSPHRASE ：资金密码，是您在交易所设置的安全密码，用于保护您的资金。 如果您启用了资金密码，则必须将其包含在请求头中。 交易所会验证资金密码是否正确，以确保只有您才能执行涉及资金操作的请求。 请注意，并非所有API请求都需要资金密码，只有涉及提款、转账等敏感操作才需要。 如果未启用资金密码，则可以省略此头部。

示例代码： 


headers = {
    "OK-ACCESS-KEY": api_key,
    "OK-ACCESS-SIGN": signature.decode('utf-8'),
    "OK-ACCESS-TIMESTAMP": timestamp,
    "OK-ACCESS-PASSPHRASE": "YOUR_PASSPHRASE"  # 如果启用了资金密码，则需要
}

请务必仔细阅读交易所的API文档，了解构建请求头的具体要求，例如所需的头部字段、签名算法和时间戳格式。 错误的请求头会导致请求被拒绝，并可能导致安全问题。

发送HTTP请求

为了与OKX交易所的API进行交互，你需要构造并发送HTTP请求。以下代码展示了如何使用Python的 requests 库发送一个GET请求，并包含了构建URL和设置请求头的关键步骤。

你需要拼接完整的API URL。这通常包括交易所的基础URL（例如： "https://www.okx.com" ）和特定的请求路径（ request_path ），该路径决定了你所请求的具体API端点。 例如，如果你要请求账户信息，`request_path` 可能是 `"/api/v5/account/balance"`。

url = "https://www.okx.com" + request_path

接下来，设置请求头（ headers ）至关重要，因为某些API端点可能需要特定的认证信息或其他元数据。常见的请求头包括 "Content-Type" （指定请求体的MIME类型，通常为 "application/" ）和 "OK-ACCESS-KEY" 、 "OK-ACCESS-SIGN" 、 "OK-ACCESS-TIMESTAMP" 、 "OK-ACCESS-PASSPHRASE" 等身份验证相关的头部字段。这些头部字段用于验证你的身份，确保你有权限访问特定的API端点。

使用 requests.get() 函数发送GET请求。GET请求通常用于获取数据。 headers=headers 参数将你设置的请求头添加到请求中。

response = requests.get(url, headers=headers)

发送请求后， response 对象包含了服务器的响应。你可以通过检查 response.status_code 来确认请求是否成功（例如，200表示成功）。然后，使用 response.() 方法将响应体解析为JSON格式，以便进一步处理和使用返回的数据。

例如，你可以通过以下方式检查响应状态码和解析JSON数据： 


if response.status_code == 200:
  data = response.()
  # 处理返回的数据
else:
  print(f"请求失败，状态码: {response.status_code}")

打印响应

print(response.())

注意: 请将 YOUR_API_KEY, YOUR_SECRET_KEY 和 YOUR_PASSPHRASE 替换为您自己的 API 密钥、私钥和资金密码（如果已启用）。

接口说明

以下是一些常用的欧易（OKX）智能合约 API 接口，这些接口允许开发者与欧易交易所的智能合约系统进行交互，实现自动化的交易、数据查询等功能。掌握这些接口对于构建基于欧易的量化交易系统、风险管理工具或数据分析平台至关重要。

  • 合约信息查询 (GET /api/swap/v3/instruments/{instrument_id})

    该接口用于获取特定合约的详细信息，包括合约代码、标的资产、合约乘数、tick size（最小变动单位）等。通过此接口，你可以了解合约的交易规则和属性，为交易决策提供基础数据。

    参数： instrument_id (字符串, 必选): 合约 ID，例如 BTC-USD-SWAP。

    返回值： 包含合约信息的 JSON 对象。

  • 市场行情 (GET /api/swap/v3/instruments/{instrument_id}/ticker)

    此接口提供特定合约的实时行情数据，包括最新成交价、最高价、最低价、成交量等。这是进行高频交易和监控市场动态的关键接口。

    参数： instrument_id (字符串, 必选): 合约 ID，例如 BTC-USD-SWAP。

    返回值： 包含行情数据的 JSON 对象，例如最新成交价、买一价、卖一价等。

  • 深度数据 (GET /api/swap/v3/instruments/{instrument_id}/depth)

    获取特定合约的深度数据，也就是买单和卖单的挂单价格和数量。深度数据对于分析市场供需关系、预测价格走势非常有用。不同深度档位的数据可以帮助你评估市场流动性。

    参数： instrument_id (字符串, 必选): 合约 ID，例如 BTC-USD-SWAP。

    参数： size (整数, 可选, 默认值：200): 返回的深度档位数量，最大为 200。

    返回值： 包含买单和卖单价格、数量的 JSON 对象。

  • 历史K线数据 (GET /api/swap/v3/instruments/{instrument_id}/candles)

    获取特定合约的历史 K 线数据，例如 1 分钟、5 分钟、1 小时等时间周期的开盘价、最高价、最低价、收盘价和成交量。K 线数据是技术分析的基础，可以用于识别趋势、支撑位和阻力位。

    参数： instrument_id (字符串, 必选): 合约 ID，例如 BTC-USD-SWAP。

    参数： granularity (字符串, 必选): K 线周期，例如 60 (1 分钟), 300 (5 分钟), 3600 (1 小时) 等，单位为秒。

    参数： start (字符串, 可选): 起始时间戳 (Unix 时间戳，单位秒)。

    参数： end (字符串, 可选): 结束时间戳 (Unix 时间戳，单位秒)。

    返回值： 包含 K 线数据的 JSON 数组。

  • 下单 (POST /api/swap/v3/order)

    使用此接口可以创建新的合约订单，包括开多、开空、平多、平空等操作。下单时需要指定合约 ID、交易方向、委托价格、委托数量等参数。务必谨慎使用此接口，确保参数设置正确，避免意外损失。

    参数： instrument_id (字符串, 必选): 合约 ID，例如 BTC-USD-SWAP。

    参数： side (字符串, 必选): 交易方向，例如 buy（开多）, sell（开空）。

    参数： type (字符串, 必选): 订单类型，例如 limit（限价单）, market（市价单）。

    参数： size (整数, 必选): 委托数量。

    参数： price (字符串, 可选): 委托价格 (仅限价单需要)。

    返回值： 包含订单信息的 JSON 对象，例如订单 ID。

  • 撤单 (POST /api/swap/v3/cancel_order)

    撤销尚未成交的合约订单。撤单需要提供订单 ID。在市场波动剧烈时，撤单可以帮助你减少潜在的损失。

    参数： instrument_id (字符串, 必选): 合约 ID，例如 BTC-USD-SWAP。

    参数： order_id (字符串, 必选): 订单 ID。

    返回值： 包含撤单结果的 JSON 对象。

  • 账户信息 (GET /api/swap/v3/accounts)

    查询你的合约账户信息，包括账户余额、可用保证金、已用保证金等。了解账户状况是进行风险管理的基础。

    返回值： 包含账户信息的 JSON 对象。

在使用这些 API 接口之前，请务必阅读欧易的官方 API 文档，了解接口的详细参数、返回值和使用限制。同时，请注意保护你的 API 密钥，避免泄露，并采取必要的安全措施，防止 API 被恶意利用。交易所的API更新频繁，请务必以官方文档为准。

账户相关

  • /api/v5/account/balance : 获取账户余额。此接口用于查询用户在平台上的资金状况，包括可用余额、冻结金额等。
    • 请求方法: GET
    • 参数: ccy (可选): 币种，例如 BTC 、 ETH 等。不指定此参数时，将返回所有币种的账户余额信息。 建议明确指定币种，以减少数据传输量并提高响应速度。
  • /api/v5/account/positions : 获取持仓信息。该接口允许用户查询当前持有的合约仓位信息，包括多仓和空仓的数量、开仓均价、保证金等。
    • 请求方法: GET
    • 参数: instId (可选): 合约 ID，例如 BTC-USD-SWAP 、 ETH-USDT-SWAP 等。 不指定此参数时，将返回所有合约的持仓信息。推荐指定合约ID，便于针对特定合约进行分析。
    • 参数: posId (可选): 持仓 ID。 如果需要查询特定持仓的详细信息，可以使用此参数。 通常情况下，无需指定此参数即可获取所有持仓的概览。
  • /api/v5/account/bills : 获取账单流水。 通过此接口，用户可以查询账户历史交易记录，包括充值、提现、交易、手续费等详细信息，便于财务核对和交易分析。
    • 请求方法: GET
    • 参数: instId (可选): 合约 ID。用于筛选特定合约的账单流水。
    • 参数: ccy (可选): 币种。用于筛选特定币种的账单流水。
    • 参数: type (可选): 账单类型。例如 "trade" (交易), "transfer" (资金划转), "deposit" (充值), "withdrawal" (提现) 等。具体类型请参考API文档。
    • 参数: after (可选): 分页参数，用于获取指定ID之后的账单数据。 通常用于滚动加载更多数据，需要传入上次请求返回的最后一条数据的 ID。
    • 参数: before (可选): 分页参数，用于获取指定ID之前的账单数据。 通常用于滚动加载更早的数据，需要传入上次请求返回的第一条数据的 ID。
    • 参数: limit (可选): 每页返回的数据条数，最大值为 100。 用于控制每次请求返回的数据量，合理设置可以提高响应速度和减少数据传输量。建议根据实际需求调整。

交易相关

  • /api/v5/trade/order: 下单。此接口用于提交新的交易订单到交易系统。
    • 请求方法: POST
    • 参数: instId (必须): 合约 ID。指定交易的合约标的，例如"BTC-USD-SWAP"。
    • 参数: tdMode (必须): 交易模式。 cross 代表全仓保证金模式，适用于风险承受能力较高且需要灵活资金管理的交易者； isolated 代表逐仓保证金模式，便于控制单笔交易的风险。
    • 参数: side (必须): 买卖方向。 buy 表示买入开多或买入平空， sell 表示卖出开空或卖出平多。
    • 参数: ordType (必须): 订单类型。 market 代表市价单，以当前市场最优价格立即成交； limit 代表限价单，只有当市场价格达到或优于指定价格时才会成交。
    • 参数: sz (必须): 交易数量。代表您想要买入或卖出的合约数量，单位通常为张。
    • 参数: px (可选): 价格。仅在订单类型为限价单（ limit ）时需要填写，指定您希望成交的价格。
    • 参数: tag (可选): 用户自定义标签。用于标记订单，方便用户进行订单管理和策略跟踪。
  • /api/v5/trade/cancel-order: 撤销订单。此接口用于取消尚未成交的挂单。
    • 请求方法: POST
    • 参数: instId (必须): 合约 ID。需要撤销订单所属的合约。
    • 参数: ordId (必须): 订单 ID。要撤销的订单的唯一标识符，由系统生成。
    • 参数: clOrdId (可选): 用户自定义订单 ID。如果下单时指定了自定义订单ID，也可以使用该ID进行撤单。如果同时提供 ordId 和 clOrdId ，系统优先使用 ordId 。
  • /api/v5/trade/orders-pending: 获取未成交订单列表。此接口用于查询当前账户中所有未完全成交的订单。
    • 请求方法: GET
    • 参数: instId (可选): 合约 ID。指定要查询的合约，留空则返回所有合约的未成交订单。
    • 参数: ordType (可选): 订单类型。筛选特定类型的订单，例如只查询限价单。
    • 参数: after (可选): 分页参数。用于获取指定订单ID之后的订单列表，实现分页查询。
    • 参数: before (可选): 分页参数。用于获取指定订单ID之前的订单列表，实现分页查询。
    • 参数: limit (可选): 每页返回的数据条数。用于限制每次请求返回的订单数量，最大值通常有限制。
  • /api/v5/trade/order: 获取订单详情。此接口用于查询特定订单的详细信息，包括订单状态、成交价格、成交数量等。
    • 请求方法: GET
    • 参数: instId (必须): 合约 ID。订单所属的合约。
    • 参数: ordId (可选): 订单 ID。要查询的订单的唯一标识符。
    • 参数: clOrdId (可选): 用户自定义订单 ID。如果下单时指定了自定义订单ID，也可以使用该ID进行查询。优先使用 ordId 。

市场数据相关

  • /api/v5/market/tickers: 获取所有交易对的行情数据。该接口提供指定产品类型下所有交易对的实时行情快照，包括最新成交价、24小时涨跌幅、24小时成交量等关键指标。
    • 请求方法: GET
    • 参数: instType (必须): 产品类型。用于指定需要查询的交易对类型，支持以下选项：
      • SPOT : 币币交易
      • MARGIN : 杠杆币币
      • FUTURES : 永续合约
      • SWAP : 交割合约
      • OPTION : 期权合约
  • /api/v5/market/ticker: 获取单个交易对的行情数据。该接口提供指定交易对的实时行情快照，包括最新成交价、最高价、最低价、开盘价、成交量、买一价、卖一价等详细信息。
    • 请求方法: GET
    • 参数: instId (必须): 合约 ID。例如： BTC-USD-SWAP (BTCUSD永续合约), BTC-USDT (BTCUSDT 币币交易)。
  • /api/v5/market/candles: 获取 K 线数据。该接口提供指定交易对和时间周期的K线数据，可用于技术分析。支持不同时间粒度的K线，并提供分页功能方便获取历史数据。
    • 请求方法: GET
    • 参数: instId (必须): 合约 ID。例如： BTC-USD-SWAP 。
    • 参数: bar (必须): K 线周期。用于指定K线的时间粒度，支持以下选项：
      • 1m : 1分钟
      • 3m : 3分钟
      • 5m : 5分钟
      • 15m : 15分钟
      • 30m : 30分钟
      • 1h : 1小时
      • 2h : 2小时
      • 4h : 4小时
      • 6h : 6小时
      • 8h : 8小时
      • 12h : 12小时
      • 1d : 1天
      • 1w : 1周
      • 1M : 1月
      • 3M : 3个月
      • 6M : 6个月
      • 1Y : 1年
    • 参数: after (可选): 分页参数。用于指定起始时间戳，返回该时间戳之后的数据，以毫秒为单位。
    • 参数: before (可选): 分页参数。用于指定结束时间戳，返回该时间戳之前的数据，以毫秒为单位。
    • 参数: limit (可选): 每页返回的数据条数。 默认值为 100，最大值为 100。

错误处理

与 API 的交互并非总是顺利，客户端发起的请求可能因各种原因遭遇失败。当请求无法成功处理时，API 将返回包含错误信息的响应，以便开发者诊断和解决问题。

错误信息的核心组成部分是 code 和 msg 字段。 code 字段通常是一个数字或字符串，代表特定的错误类型。 每个 code 对应一个明确的错误场景，便于程序进行自动化处理。 msg 字段则提供人类可读的错误描述，旨在帮助开发者理解错误的具体原因，例如 "无效的API密钥" 或 "参数缺失"。建议在日志中记录 msg 内容，以便后续排查。

开发者在构建应用程序时，务必考虑到各种可能的错误情况，并根据 code 值实现相应的错误处理逻辑。 例如，如果 code 指示权限不足，应用程序应向用户显示授权提示；如果 code 指示请求参数无效，应用程序应提示用户检查输入。 处理方式应根据具体的业务场景和用户体验进行优化。 除了 code 和 msg 之外，某些 API 还会返回额外的错误信息，例如可以重试的时间，或修复错误的具体步骤。开发者应仔细阅读 API 文档，以充分利用这些信息。

频率限制

为了保障欧易智能合约 API 服务的稳定性和公平性，防止恶意攻击和资源滥用，我们对 API 的请求频率实施了严格的限制策略。 不同的 API 接口，例如交易接口、查询接口、以及市场数据接口，可能由于其资源消耗和重要性不同，而具有不同的频率限制阈值。开发者在使用 API 时，必须仔细查阅欧易官方文档，了解每个接口的具体频率限制规则。

当请求频率超过规定的限制时，API 将返回包含特定错误代码的错误响应，例如 HTTP 429 Too Many Requests，表明请求已被服务器限流。 开发者应仔细处理这些错误，并采取必要的措施来调整请求频率，避免持续触发频率限制。频繁触发频率限制可能会导致 IP 地址被暂时或永久封禁。

我们强烈建议开发者在设计和开发应用程序时，充分考虑频率限制因素，并采取以下措施来优化 API 请求：

  • 合理控制请求频率： 根据实际需求调整请求频率，避免不必要的请求。可以使用延迟、退避算法等技术来平滑请求流量。
  • 批量请求： 对于支持批量操作的 API 接口，尽可能使用批量请求来减少请求次数。
  • 数据缓存： 将不经常变化的数据缓存在本地，减少对 API 的重复请求。
  • 使用 WebSocket 订阅： 对于市场行情数据，强烈建议使用 WebSocket 订阅方式，而不是轮询 API。WebSocket 可以实时推送数据，极大地减少了 API 请求次数，降低延迟，提高效率。 欧易智能合约 API 提供了丰富的 WebSocket 订阅频道，涵盖了各种市场数据和交易事件。

通过以上优化措施，开发者可以有效地控制 API 请求频率，避免触发频率限制，确保应用程序的稳定性和可靠性。 请务必仔细阅读欧易智能合约 API 的官方文档，了解最新的频率限制规则和最佳实践。

安全建议

  • 务必安全保存您的 API 密钥和私钥，切勿泄露给任何第三方。 API 密钥和私钥是访问您账户和执行交易的关键凭证，一旦泄露可能导致资金损失或数据泄露。建议使用密码管理器等安全工具妥善保管，并定期备份。
  • 绝对不要在客户端代码（如浏览器端 JavaScript 或移动应用）中直接存储 API 密钥和私钥。 客户端代码容易被反编译或审查，将密钥直接嵌入其中会暴露您的凭证，使攻击者能够轻易获取并滥用。应将密钥存储在服务器端，并通过安全的 API 接口进行调用。
  • 强制使用 HTTPS 协议进行所有 API 请求，以确保数据在传输过程中的安全性。 HTTPS 使用 SSL/TLS 加密传输的数据，防止中间人攻击，确保数据的完整性和机密性。请验证您使用的 API 端点是否支持 HTTPS，并确保所有请求都通过 HTTPS 发送。
  • 定期轮换您的 API 密钥对，降低密钥泄露后的潜在风险。 即使采取了所有安全措施，密钥仍然存在泄露的风险。定期更换 API 密钥可以限制泄露密钥的有效期，减少潜在的损失。建议至少每三个月轮换一次密钥。
  • 强烈建议开启双重验证 (2FA) 以增强账户安全性。 双重验证需要在登录时提供除密码之外的另一种验证方式，例如手机验证码或身份验证器生成的代码。即使攻击者获取了您的密码，也无法轻易登录您的账户。请在所有支持 2FA 的平台上启用此功能。

WebSocket API

除了 RESTful API，欧易还提供了 WebSocket API，以便用户能够实时订阅市场数据和账户信息。相较于传统的 RESTful API，WebSocket API 通过建立持久的双向通信连接，显著降低了延迟，并提高了数据传输的效率。这种实时性对于需要快速响应市场变化的应用程序至关重要，例如高频交易机器人和实时行情监控系统。

WebSocket API 允许客户端与服务器之间进行全双工通信，这意味着数据可以同时双向流动，无需像 RESTful API 那样频繁地建立和断开连接。这种机制减少了握手开销，实现了更快的响应速度。通过订阅特定的频道，用户可以接收到特定交易对的最新价格、成交量、深度图以及其他相关市场数据。

WebSocket API 还可以用于实时获取账户信息，例如账户余额、持仓情况、交易历史等。这使得用户能够及时了解自己的账户状态，并做出相应的交易决策。

使用欧易 WebSocket API 需要一定的编程基础，通常涉及使用 WebSocket 客户端库连接到欧易服务器，并发送订阅和取消订阅消息。具体的技术细节、认证流程、消息格式以及频道列表，请务必参考欧易官方文档，以确保正确高效地使用该 API。官方文档会详细说明如何处理连接错误、数据解析以及其他潜在的问题。

常见问题

  • 如何处理 API 错误? 查看 API 响应中的 code 和 msg 字段，它们分别代表错误码和错误信息。根据具体的错误码进行相应的处理，例如，对于无效参数的错误码，需要检查并修正请求参数；对于权限不足的错误码，需要检查 API 密钥是否正确配置并拥有相应的权限。 部分API平台会提供详细的错误码文档，建议参考文档进行排错。可以记录每次API调用的请求参数和响应信息，方便后续问题追踪和调试。
  • 如何避免频率限制? 为了保证API服务的稳定性和公平性，交易所通常会设置频率限制。合理控制API请求的频率是避免触发频率限制的关键。可以采用以下策略：1. 批量处理：将多个操作合并到一个API请求中。 2. 延时：在每次API请求之间增加适当的延时。 3. 使用WebSocket订阅市场数据：对于需要实时获取市场数据的应用，使用WebSocket协议可以避免频繁轮询API接口，降低请求频率。 4. 了解并遵守交易所的频率限制规则：仔细阅读API文档，了解不同API接口的频率限制，并根据规则进行调整。 一些交易所会提供不同等级的API密钥，拥有不同的频率限制，根据业务需求选择合适的密钥等级。
  • 如何保证 API 请求的安全性? API 密钥和私钥是访问API接口的凭证，务必安全保存，防止泄露。切勿将密钥硬编码在代码中或提交到公共代码仓库。 使用环境变量或配置文件等方式管理密钥。 API通信必须使用 HTTPS 协议，确保数据在传输过程中的加密和安全。 定期更换API密钥，降低密钥泄露的风险。 开启IP白名单，限制API请求的来源IP，防止未经授权的访问。 同时，关注交易所的安全公告，及时了解最新的安全风险和防范措施。
  • 为什么订单没有成交? 订单没有成交可能有多种原因：1. 价格不合理：订单价格与市场价格偏差过大，导致无法成交。 检查买单价格是否高于当前卖一价，卖单价格是否低于当前买一价。2. 市场深度不足：市场上的买单或卖单数量不足，无法满足订单的需求。 可以尝试调整订单价格或等待市场深度增加。3. 账户余额不足：账户余额不足以支付订单所需的资金或手续费。 检查账户余额是否足够。4. 订单类型错误：选择了错误的订单类型，例如，市价单在市场波动剧烈时可能无法成交。 5. 订单参数错误：订单数量或价格精度不符合交易所的规则。 仔细检查订单参数，确保符合交易所的要求。

示例代码 (Python)

以下示例代码演示了如何使用 Python 语言，通过 OKX API 获取账户余额。代码展示了构建 API 请求所需的签名过程，确保数据安全传输和身份验证。

import hashlib import hmac import time import base64 import requests import

def get_account_balance(api_key, secret_key, passphrase): """ 使用 OKX API 获取账户余额。 Args: api_key (str): 您的 API 密钥。 secret_key (str): 您的 API 密钥。 passphrase (str): 您的 passphrase. Returns: dict: 包含账户余额信息的字典。如果请求失败，则返回 None。 """ timestamp = str(int(time.time())) method = "GET" request_path = "/api/v5/account/balance" body = "" 

    message = str(timestamp) + method + request_path + body
    mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), hashlib.sha256)
    d = mac.digest()
    sign = base64.b64encode(d).decode()

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

    url = "https://www.okx.com" + request_path
    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()  # 检查是否有 HTTP 错误

        return response.()
    except requests.exceptions.RequestException as e:
        print(f"API 请求失败: {e}")
        return None

代码详解:

  1. 导入必要的库: hashlib 用于哈希计算， hmac 用于生成 HMAC 签名, time 获取当前时间戳, base64 用于base64编码, requests 用于发送 HTTP 请求, 用于处理 API 返回的 JSON 数据.
  2. get_account_balance 函数: 接受 API 密钥、密钥和口令作为输入，并返回账户余额。
  3. 时间戳: 获取当前时间戳，用于生成签名。
  4. 请求方法和路径: 定义 HTTP 请求方法 (GET) 和 API 路径。
  5. 构建消息: 将时间戳、方法和请求路径连接成一个字符串，用于生成签名。
  6. 生成签名: 使用 HMAC-SHA256 算法，用密钥对消息进行哈希运算，然后进行 Base64 编码。
  7. 设置 Header: 构造 HTTP Header，包含 API 密钥、签名、时间戳和口令。这些 Header 用于身份验证。
  8. 发送请求: 使用 requests 库发送 GET 请求到 OKX API。
  9. 处理响应: 解析 JSON 响应，返回账户余额信息。同时添加异常处理，捕获请求错误并返回 None 。
  10. 异常处理： 使用try...except块来捕获并处理可能发生的 requests.exceptions.RequestException 异常，提高代码的健壮性。
  11. 完整的URL构建： 更清晰地展示了API请求URL的构建过程。

注意事项:

  • 替换示例代码中的 api_key , secret_key , 和 passphrase 为您自己的 API 凭据。
  • 请务必妥善保管您的 API 密钥和密钥，避免泄露。
  • 在使用 API 之前，请阅读 OKX 官方 API 文档，了解 API 的使用限制和频率限制。
  • 为了安全，请使用 HTTPS 连接。

替换为您的 API 密钥、私钥和资金密码

在开始交易之前，您需要将以下变量替换为您的实际凭据。 这些凭据用于验证您的身份并允许您访问交易所的 API。 

api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

api_key 是您的 API 密钥，由交易所提供。 secret_key 是您的私钥，也由交易所提供，务必妥善保管。 passphrase 是您的资金密码，用于保护您的账户资金安全。

获取账户余额的示例代码： 

balance = get_account_balance(api_key, secret_key, passphrase)
print(balance)

请务必将代码中的 YOUR_API_KEY 、 YOUR_SECRET_KEY 和 YOUR_PASSPHRASE 替换为您真实的值。 这些值通常可以在您的交易所账户的 API 管理页面找到。 特别强调，私钥（ secret_key ）必须严格保密，切勿泄露给任何人。泄露私钥会导致您的资产面临风险。

在使用代码之前，请确保您已经安装了 requests 库，这是一个常用的 Python HTTP 库，用于与 API 交互。 您可以使用以下命令安装该库： 

pip install requests

另外，某些交易所的API调用可能需要额外的依赖库，请根据交易所的API文档进行安装。 在进行任何交易操作之前，建议您先在测试环境（Testnet）中进行模拟交易，以确保您的代码能够正确运行，并避免在真实交易环境中出现意外损失。

相关推荐