CEX.IO API 调用指南：开发者快速入门与实战 | 最新教程

2025-03-05 13:40:10 8

CEX.IO API 接口如何调用

CEX.IO 是一家老牌的加密货币交易所，提供各种加密货币交易服务。对于开发者来说，CEX.IO 的 API 接口提供了访问其平台各种功能的强大途径，例如获取市场数据、进行交易以及管理账户。 本文将介绍如何调用 CEX.IO 的 API 接口。

1. API 概览与认证

CEX.IO 提供两种主要的 API 接口类型，以满足不同的应用场景：REST API 和 WebSocket API。REST API 采用请求/响应模式，适用于执行诸如下单、查询账户余额、获取交易对信息等操作。其优势在于简单易用，易于集成。而 WebSocket API 则是一种基于长连接的实时通信协议，特别适用于需要持续接收市场数据更新的应用，例如实时行情数据、深度图变化等。WebSocket 允许服务器主动向客户端推送数据，避免了频繁轮询，从而降低延迟并减少资源消耗。

在使用 CEX.IO 的 API 之前，必须先在 CEX.IO 平台注册一个账户，并通过账户安全设置创建 API 密钥。API 密钥由两部分组成： key （公钥） 和 secret （私钥）。 key 类似于用户名，用于标识你的身份； secret 则类似于密码，用于对请求进行签名验证。务必采取必要的安全措施来保护 secret ，防止泄露。泄露的 secret 可能被用于恶意操作你的账户，造成资金损失。

API 认证是确保请求安全的关键环节。CEX.IO 的 API 认证主要通过在 HTTP 请求头部中添加认证信息来实现。为了验证请求的合法性，需要在请求头中包含以下三个关键字段：

  • key : 你的 API key (公钥)。用于标识发送请求的用户。
  • signature : 请求的数字签名。它使用你的 secret (私钥) 对请求内容进行加密生成，用于验证请求的完整性和真实性，防止请求被篡改。签名算法通常是 HMAC-SHA256 或其他安全哈希算法。
  • timestamp : 请求的时间戳 (Unix 时间戳)，表示请求发送的时间。时间戳用于防止重放攻击，即攻击者截获并重新发送之前的有效请求。服务器会验证时间戳的有效性，通常会设置一个时间窗口，超出该时间窗口的请求将被拒绝。

更具体地说， signature 的生成通常涉及以下步骤：将请求参数（包括请求方法、请求路径和请求体等）按照一定规则排序并拼接成字符串，然后使用你的 secret 作为密钥，通过 HMAC-SHA256 算法对该字符串进行哈希运算，得到最终的签名。生成的签名需要进行 Base64 编码，以便在 HTTP 请求头中传输。务必参考 CEX.IO 的官方 API 文档，了解具体的签名算法和参数要求，以确保正确生成签名。

2. 生成请求签名

请求签名是保障 API 请求安全的关键环节。 CEX.IO 采用 HMAC-SHA256 算法对每个 API 请求进行签名验证，确保请求的完整性和来源可靠性，防止中间人攻击或其他恶意篡改。理解并正确生成请求签名对于成功调用 CEX.IO API 至关重要。

  1. 构造签名字符串： 签名字符串的构建方式依赖于具体的 API 端点和 HTTP 请求方法。通常情况下，你需要将请求的 URI 路径、当前时间戳以及请求体（如果存在，例如 POST 或 PUT 请求）按照特定规则拼接成一个字符串。务必查阅 CEX.IO 的官方 API 文档，仔细了解每个端点所需的签名字符串格式。常见的组合方式包括将时间戳作为前缀或后缀添加到 URI 之后，再拼接请求体。
  2. 使用 HMAC-SHA256 算法进行哈希运算： 使用你的 API secret 密钥（由 CEX.IO 提供）作为密钥，对构造好的签名字符串进行 HMAC-SHA256 哈希运算。HMAC-SHA256 是一种带密钥的哈希算法，确保只有拥有正确密钥的人才能生成有效的签名。这一步是确保请求安全性的核心。
  3. 将哈希结果转换为 Base64 编码字符串： 将 HMAC-SHA256 哈希运算的结果（二进制数据）转换为 Base64 编码的字符串。Base64 编码是一种将二进制数据转换为 ASCII 字符串的常用方法，方便在 HTTP 头部或其他文本协议中传输。生成的 Base64 编码字符串即为最终的请求签名，需要将其包含在 API 请求的头部信息中。

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

import hashlib
import hmac
import base64
import time

def generate_signature(api_secret, timestamp, request_uri, request_body=None):
    """
    为 CEX.IO API 请求生成签名.

    Args:
        api_secret: 你的 CEX.IO API secret 密钥.
        timestamp: 请求的时间戳 (Unix 时间戳).
        request_uri: API 端点的 URI (例如, "/api/place_order").
        request_body: 请求体 (如果有, 字符串格式).

    Returns:
        生成的签名 (Base64 编码).
    """
    message = str(timestamp) + request_uri  # 时间戳必须转换为字符串
    if request_body:
        message += request_body

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

示例用法

api_secret = "YOUR_API_SECRET" # 替换为你的 API secret 。 这是你在交易所或其他加密货币服务提供商处获得的私密密钥，务必妥善保管，切勿泄露。它用于生成签名，验证请求的合法性。

timestamp = str(int(time.time())) 。时间戳是请求发送的时间，通常以 Unix 时间戳的形式表示（即自 1970 年 1 月 1 日以来经过的秒数）。它用于防止重放攻击，确保请求的时效性。

request_uri = "/api/place_order" 。 这是你想要访问的 API 端点，例如，在此示例中，它代表“下单”的API接口。不同API对应不同的URI，请务必参照相关API文档。

request_body = .dumps({"pair1": "BTC", "pair2": "USD", "type": "buy", "amount": 0.01, "price": 20000}) 。 请求体是你要发送给 API 的数据，通常以 JSON 格式编码。在这个例子中，请求体包含交易对（BTC/USD），交易类型（买入），数量（0.01 BTC）和价格（20000 USD）。不同的API对请求体的格式和内容要求不同，必须按照API文档构造请求体。

signature = generate_signature(api_secret, timestamp, request_uri, request_body) 。 使用 API secret、时间戳、请求 URI 和请求体生成签名。签名算法通常是 HMAC-SHA256 或其他加密算法，具体取决于 API 的要求。签名用于验证请求的完整性和真实性，确保请求没有被篡改，并且来自合法的用户。

print(f"Timestamp: {timestamp}") print(f"Signature: {signature}") 。 打印生成的时间戳和签名，以便在发送 API 请求时使用。这些信息通常会作为 HTTP 头部或请求体的一部分发送给 API 服务器。

3. 发送 API 请求

在成功生成包含有效签名的请求后，即可向API端点发送请求。 为了进行数据交互，你需要构造一个符合API规范的HTTP请求，并将签名信息添加到请求头或请求体中（具体取决于API的设计）。 可以使用各种编程语言和相应的HTTP客户端库来实现此功能，例如 Python 的 requests 库，Java 的 Apache HttpClient，或者 JavaScript 的 Fetch API。

以下是一个 Python 示例，展示如何使用 requests 库发送一个包含签名的 POST 请求。 请注意，此示例仅作为演示，你需要根据具体的API文档调整请求的URL、请求头、请求体以及签名生成方式。

import requests

替换为你的 API Key 和 API Secret

在进行加密货币交易或访问相关数据时，API Key 和 API Secret 是至关重要的身份验证凭据。它们类似于用户名和密码，但专为应用程序（而非人类用户）设计，用于安全地访问交易所或服务提供商的 API（应用程序编程接口）。务必妥善保管你的 API Key 和 API Secret，切勿与他人分享，以防止未经授权的访问和潜在的资金损失。

以下代码展示了如何将你的 API Key 和 API Secret 赋值给变量，以便在后续的代码中使用。请将 "YOUR_API_KEY" 替换为你实际的 API Key，并将 "YOUR_API_SECRET" 替换为你实际的 API Secret。

api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"

API Key： 你的 API Key 是一个公开的标识符，用于识别你的应用程序或账户。它可以被视为你的用户名，但本身并不足以授权访问。

API Secret： 你的 API Secret 是一个私密的密钥，类似于你的密码。它与 API Key 结合使用，用于对你的请求进行签名，从而验证你的身份并授权访问。API Secret 必须保密，泄露将导致安全风险。

安全提示：

  • 不要将 API Key 和 API Secret 硬编码到你的应用程序中： 这会将它们暴露给潜在的攻击者。建议使用环境变量或配置文件来存储这些敏感信息。
  • 不要将 API Key 和 API Secret 提交到公共代码仓库（例如 GitHub）： 在提交代码之前，请务必检查并删除任何包含 API Key 和 API Secret 的代码。
  • 定期轮换 API Key 和 API Secret： 许多交易所和服务提供商允许你生成新的 API Key 和 API Secret。定期轮换这些凭据可以降低因泄露造成的风险。
  • 启用双因素身份验证（2FA）： 如果你的交易所或服务提供商支持 2FA，请务必启用它，以增加额外的安全层。
  • 监控你的 API 使用情况： 密切关注你的 API 请求，以检测任何异常活动。

API 端点

在与 CEX.IO 交易所进行程序化交易时，您将主要使用其提供的 API 端点。 其中，用于提交订单的关键端点是 api_url = "https://cex.io/api/place_order" 。 通过向该 URL 发送带有特定参数的 HTTP 请求，您可以实现自动化的买入或卖出操作。 需要注意的是，实际使用过程中还需要考虑身份验证、请求频率限制等因素，具体参数的格式和要求请参考CEX.IO官方API文档。 为了保证数据安全，建议使用HTTPS协议进行通信。

请求参数

构建交易请求时，需要提供以下参数。这些参数将被序列化为 JSON 格式并作为请求体发送到交易服务器。

payload 是一个 Python 字典，包含了交易所需的关键信息：

  • pair1 : 指定交易对的第一种资产，例如 "BTC" (比特币)。这是你想买入或卖出的资产。

  • pair2 : 指定交易对的第二种资产，例如 "USD" (美元)。这是你用来购买或出售第一种资产的计价货币。

  • type : 指定交易类型，可以是 "buy" (买入) 或 "sell" (卖出)。"buy" 表示用 pair2 购买 pair1 ， "sell" 表示用 pair1 换取 pair2 。

  • amount : 指定交易数量。对于 "buy" 类型，表示要购买的 pair1 的数量；对于 "sell" 类型，表示要出售的 pair1 的数量。 在此示例中， amount 为 0.01，表示购买或出售 0.01 个比特币。

  • price : 指定交易价格。对于 "buy" 类型，表示你愿意为每个 pair1 支付的最高 pair2 价格（限价买单）；对于 "sell" 类型，表示你愿意接受的每个 pair1 的最低 pair2 价格（限价卖单）。在此示例中， price 为 20000，表示你愿意以每个比特币 20000 美元的价格进行交易。

示例：

payload = {"pair1": "BTC", "pair2": "USD", "type": "buy", "amount": 0.01, "price": 20000}

request_body = .dumps(payload) 。 这行代码使用 Python 的 .dumps() 方法将 payload 字典转换为 JSON 字符串。 这个 JSON 字符串将被作为 HTTP 请求体发送到服务器。

生成时间戳和签名

时间戳（timestamp）在加密货币交易API中扮演着至关重要的角色，它用于确保请求的新鲜度和防止重放攻击。通常，时间戳表示为自Unix纪元（1970年1月1日00:00:00 UTC）以来的秒数。生成时间戳的代码如下： 

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

此代码段使用Python的 time.time() 函数获取当前时间，该函数返回一个浮点数，代表自Unix纪元以来的秒数。然后，使用 int() 函数将其转换为整数，并使用 str() 函数将其转换为字符串，以便在API请求中使用。

签名（signature）是用于验证API请求完整性和真实性的加密哈希值。它通过使用API密钥（api_secret）、时间戳（timestamp）、API端点（"/api/place order"）和请求体（request body）作为输入，利用加密哈希算法（例如HMAC-SHA256）生成。不同的交易所或API提供商可能采用不同的签名算法和参数组合，因此务必参考其官方文档。

生成签名的示例代码如下（假设使用HMAC-SHA256算法）： 

signature = generate_signature(api_secret, timestamp, "/api/place_order", request_body)

generate_signature 函数的具体实现取决于所使用的编程语言和加密库。一般来说，它会按照API文档指定的顺序将所有输入参数连接成一个字符串，然后使用HMAC-SHA256算法对该字符串进行哈希处理，并使用API密钥作为密钥。最终生成的哈希值通常需要进行Base64编码，以便在HTTP请求头中安全传输。

请务必妥善保管您的API密钥，避免泄露，因为它相当于您的账户密码。泄漏的API密钥可能导致您的账户被盗用。

设置请求头

在进行与加密货币交易所或其他加密货币相关服务的API交互时，设置正确的请求头至关重要。请求头包含了身份验证信息和其他元数据，服务器可以使用这些信息来验证请求的来源并正确处理请求。

以下是一个示例，展示了如何构建一个包含API密钥、签名、时间戳和内容类型的请求头： 

headers = {
    "key": api_key,
    "signature": signature,
    "timestamp": timestamp,
    "Content-Type": "application/"
}

key : API密钥是用于识别您的账户的唯一标识符。交易所会使用此密钥来验证您是否有权访问其API。务必妥善保管您的API密钥，不要将其泄露给他人，因为这可能会导致您的账户被盗用。

signature : 签名是一种加密哈希值，用于验证请求的完整性和真实性。通常，签名是使用您的API密钥和一些请求参数（例如时间戳和请求正文）生成的。服务器会使用相同的算法和您的API密钥重新计算签名，并将其与您在请求头中提供的签名进行比较。如果两个签名匹配，则表示请求未被篡改并且来自授权用户。

timestamp : 时间戳表示请求发送的时间。许多交易所使用时间戳来防止重放攻击。重放攻击是指攻击者截获并重新发送合法的请求。为了防止此类攻击，交易所可能会拒绝时间戳与当前时间相差太远的请求。时间戳通常以Unix时间格式表示，即自1970年1月1日UTC以来的秒数。

Content-Type : Content-Type 指定了请求正文的数据格式。常见的 Content-Type 值包括 application/ （用于JSON数据）和 application/x-www-form-urlencoded （用于表单数据）。确保您的 Content-Type 与您发送的数据格式匹配，否则服务器可能无法正确解析您的请求。

通常，加密货币交易所的 API 文档会详细说明如何构造请求头，包括需要哪些参数以及如何生成签名。请务必仔细阅读 API 文档并按照说明进行操作，以确保您的请求能够被正确处理。

发送 POST 请求

在使用 Python 的 requests 库发送 POST 请求时，需要构造请求体 (request body) 并设置合适的 headers。以下代码展示了如何发送包含 JSON 数据的 POST 请求： 

try:
    # 定义 API 端点 URL
    api_url = "https://api.example.com/resource"

    # 定义请求头，指定内容类型为 JSON
    headers = {'Content-Type': 'application/'}

    # 定义请求体，通常为 JSON 格式的数据
    request_body = {
        "key1": "value1",
        "key2": 123,
        "key3": True
    }

    # 使用 requests.post() 方法发送 POST 请求
    response = requests.post(api_url, headers=headers, =request_body)

    # 检查响应状态码
    response.raise_for_status()  # 如果状态码不是 2xx，则抛出 HTTPError 异常，指示请求失败

    # 解析 JSON 响应
    response_data = response.()  # 将响应内容解析为 Python 字典或列表
    print(response_data)

except requests.exceptions.RequestException as e:
    # 捕获请求过程中的异常，例如网络连接错误、超时等
    print(f"请求出错: {e}")
except .JSONDecodeError as e:
    # 捕获 JSON 解析错误，例如响应内容不是有效的 JSON 格式
    print(f"JSON 解析错误: {e}")

代码解释：

  • api_url : API 接口的 URL 地址，需要替换为实际的 API 端点。
  • headers : HTTP 请求头， Content-Type: application/ 表示请求体是 JSON 格式的数据。
  • request_body : 要发送到服务器的数据，以 Python 字典的形式表示， requests 库会自动将其转换为 JSON 格式。
  • requests.post(api_url, headers=headers, =request_body) : 发送 POST 请求到指定的 URL，并附带请求头和 JSON 数据。 使用 =request_body 参数可以自动将 Python 字典转换为 JSON 字符串，并正确设置 Content-Type 请求头。
  • response.raise_for_status() : 检查响应状态码。如果状态码在 400-599 范围内，则抛出一个 HTTPError 异常，表示请求失败。
  • response.() : 将服务器返回的 JSON 响应解析为 Python 字典或列表。
  • 异常处理：使用 try...except 块来捕获可能发生的异常，包括网络请求异常（ requests.exceptions.RequestException ）和 JSON 解析异常（ .JSONDecodeError ），并打印错误信息。

注意事项：

  • 确保 requests 库已正确安装（ pip install requests ）。
  • 根据 API 的要求设置正确的请求头，例如 Content-Type 、 Authorization 等。
  • 根据 API 的要求构造正确的请求体，可以是 JSON、表单数据或其他格式。
  • 根据实际情况处理不同类型的异常，例如网络连接错误、服务器错误、权限错误等。
  • 在使用 response.() 前，确保响应内容确实是有效的 JSON 格式。

4. 常用 API 端点

CEX.IO API 提供了全面的 REST API 接口，允许开发者访问和管理其交易平台上的各种功能。以下是一些常用的端点，并附带更详细的说明：

  • /api/tickers/{pair1}/{pair2} : 获取指定交易对的实时 ticker 信息。Ticker 信息包括最新成交价格、最高价、最低价、成交量、交易对信息等。 pair1 和 pair2 代表交易对中的两种加密货币或法定货币。例如： /api/tickers/BTC/USD 将返回比特币 (BTC) 与美元 (USD) 交易对的实时数据，包括 24 小时内的价格变动统计。此端点对于监控市场动态和构建实时数据应用程序至关重要。
  • /api/order_book/{pair1}/{pair2} : 获取指定交易对的订单簿信息。订单簿是买单和卖单的集合，按照价格排序。通过此端点，您可以获取不同价格级别的订单深度，了解市场供需情况。例如： /api/order_book/BTC/USD 将返回 BTC/USD 交易对的买单和卖单列表。此端点返回的数据通常包含价格和数量，可以用来分析市场深度和预测价格走势。
  • /api/place_order : 用于提交新的交易订单。该端点需要身份验证和订单参数，例如交易对、订单类型（市价单或限价单）、买卖方向、数量和价格（如果适用）。成功调用此端点将会在订单簿中创建一个新的订单。
  • /api/cancel_order : 用于取消已提交的订单。需要提供要取消的订单的唯一标识符（订单 ID）。成功调用此端点将从订单簿中移除指定的订单。取消订单通常需要遵守交易所的规则，例如，某些订单可能无法在特定状态下取消。
  • /api/open_orders : 获取当前账户中所有未成交的订单列表。该端点需要身份验证，并返回一个包含所有未成交订单的详细信息的列表。这些信息包括订单 ID、交易对、订单类型、买卖方向、数量、价格和提交时间。此端点对于跟踪您的交易活动和管理您的未结头寸至关重要。
  • /api/balance : 获取当前账户的资金余额信息。该端点需要身份验证，并返回一个包含各种加密货币和法定货币余额的列表。余额信息通常包括可用余额、冻结余额和总余额。可用余额是可以立即用于交易的资金，冻结余额是被锁定在未成交订单中的资金。

5. 错误处理

在与 CEX.IO API 交互时，务必重视错误处理机制。CEX.IO API 会通过 HTTP 状态码和 JSON 格式的错误信息来反馈请求的处理结果，告知开发者请求是否成功执行。 开发者需要理解并正确处理这些错误信息，以确保应用程序的稳定性和可靠性。 例如，网络连接不稳定或服务器故障也可能导致API调用失败，需要进行适当的重试策略。

  • 400 Bad Request : 此状态码表示客户端发送的请求存在语法错误或缺少必要的参数。开发者需要仔细检查请求参数，确保它们符合 API 文档的要求。 常见的错误包括参数类型错误、参数值超出范围或缺少必填参数。
  • 401 Unauthorized : 此状态码表示客户端未经过身份验证或提供的身份验证信息无效。这通常是因为 API 密钥 (API key) 未提供、密钥不正确或者签名计算错误。 开发者需要检查 API 密钥是否已正确设置，并确保签名算法的实现正确无误。 同时，也需要检查API Key是否具有足够的权限访问该接口。
  • 429 Too Many Requests : 此状态码表示客户端在短时间内发送了过多的请求，超过了 API 的速率限制。 为了避免被服务器限制，开发者需要实施请求频率限制策略，例如使用队列来控制请求的发送速度，或者采用指数退避算法进行重试。 详细的速率限制信息通常可以在 API 文档中找到。
  • 500 Internal Server Error : 此状态码表示服务器在处理请求时遇到了内部错误。 这通常是服务器端的问题，开发者无法直接解决。 在这种情况下，建议稍后重试请求，或者联系 CEX.IO 的技术支持团队寻求帮助。 在重试之前，可以检查 API 的状态页面，以确认是否存在已知的问题。

针对不同的错误类型，应该采取相应的处理措施。 例如，对于 400 Bad Request 错误，需要仔细检查并更正请求参数；对于 401 Unauthorized 错误，需要验证 API 密钥和签名是否正确；对于 429 Too Many Requests 错误，需要降低请求频率或实现重试机制；对于 500 Internal Server Error 错误，可以稍后重试请求。 还可以记录错误日志，以便于调试和分析问题。 为了提高应用程序的健壮性，建议使用 try-catch 块来捕获潜在的异常，并进行适当的错误处理。

6. WebSocket API：实时数据流的通道

除了传统的 REST API，CEX.IO 还精心打造了 WebSocket API，为开发者提供近乎零延迟的实时数据推送服务。相较于 REST API 的轮询模式，WebSocket API 采用全双工通信，能够即时传递市场动态、订单簿变化和账户信息更新等关键数据，让您的交易决策更加敏捷高效。

要充分利用 WebSocket API 的强大功能，您需要先与 CEX.IO 建立稳定的 WebSocket 连接。连接建立后，通过发送特定的订阅消息，您可以精确地选择需要接收的数据类型。例如，您可以订阅特定交易对的实时行情、深度订单簿的动态变化，或是个人账户的资金变动通知。CEX.IO 提供了详尽的 WebSocket API 文档，其中包含了连接方法、消息格式、订阅参数等详细说明，帮助您快速上手并构建强大的实时交易应用。

掌握 CEX.IO API 接口的基本调用方法和注意事项是构建高效交易应用的关键。CEX.IO 官方文档是您最可靠的参考资料，其中详细列出了所有可用的 API 端点、请求参数、响应格式以及错误代码说明。通过 API 接口，您可以无缝访问 CEX.IO 平台的各项核心功能，包括下单、查询余额、获取历史数据等，从而构建自动化交易策略、风险管理系统以及其他定制化的交易工具。开发者可以根据自身需求，灵活组合不同的 API 接口，打造满足特定需求的交易解决方案。

The End

发布于：2025-03-05，除非注明，否则均为数新知原创文章，转载请注明出处。