BigONE API接口使用指南：认证、签名与Python示例

日期： 栏目：解答 浏览：48

BigONE 网 API 接口使用方法

概述

BigONE 交易所提供了一套全面的应用程序编程接口 (API)，为开发者提供以编程方式访问其平台功能的强大途径。这些 API 接口允许开发者自动化交易策略、检索实时和历史市场数据、集成 BigONE 交易所到第三方应用程序以及高效地管理账户信息。本指南旨在帮助开发者深入理解并有效利用 BigONE 的 API 接口，从而充分发挥其在加密货币交易和数据分析方面的潜力。通过本文档，开发者可以了解如何利用 API 进行订单管理、数据抓取、以及账户自动化等操作。务必仔细阅读官方API文档，了解最新的接口变更和最佳实践。

API 认证

在使用 BigONE API 之前，必须创建并妥善管理 API 密钥。您可以在您的 BigONE 账户的“API 管理”或类似名称的设置页面中找到创建 API 密钥的选项。创建 API 密钥时，系统会生成一个公钥 (API Key) 和一个私钥 (Secret Key)。请务必妥善保管您的 API 密钥（包括公钥和私钥），绝对不要将其泄露给他人，也不要将其存储在不安全的地方。如果私钥泄露，立即撤销并重新生成新的 API 密钥。强烈建议启用双因素身份验证 (2FA) 来保护您的账户安全，进一步保障API密钥的安全。

BigONE API 使用 HMAC (Hash-based Message Authentication Code) 算法进行身份验证，确保请求的完整性和真实性。服务器通过验证请求中携带的签名来确认请求是否由授权用户发起，以及数据在传输过程中是否被篡改。HMAC 结合了密钥和消息摘要，即使攻击者截获了请求，也无法在不知道密钥的情况下伪造签名。

具体的签名方法如下：

  1. 构建请求字符串。请求字符串的格式取决于您要调用的 API 端点，不同的API接口可能需要不同的请求参数。一般来说，它包括请求方法（如 GET、POST、PUT、DELETE），API 端点路径（例如 `/api/v3/orders`）以及所有必要的请求参数。请求参数需要按照参数名称的字母顺序进行排列，并使用 URL 编码进行转义。例如，`symbol=BTCUSDT&side=BUY&type=LIMIT`。参数值也需要进行URL编码。对于 POST 和 PUT 请求，如果请求体中包含 JSON 数据，通常需要将 JSON 数据转换为字符串并包含在签名计算中。

  2. 使用您的 API 密钥中的私钥 (Secret Key) 作为密钥，对构建好的请求字符串进行 HMAC-SHA256 加密。HMAC-SHA256 是一种安全的哈希算法，它结合了密钥和消息，生成一个固定长度的哈希值，作为签名。密钥的安全性至关重要，直接关系到整个认证机制的可靠性。请注意，不同的编程语言和库在 HMAC-SHA256 的实现上可能存在细微差别，需要仔细检查文档和示例代码。

  3. 将加密后的结果（即 HMAC-SHA256 签名）转换为十六进制字符串，并将其作为 `X-API-SIGNATURE` 添加到请求头中。同时，将 API 公钥 (API Key) 作为 `X-API-KEY` 添加到请求头，并将时间戳 (Timestamp) 作为 `X-API-TIMESTAMP` 添加到请求头。时间戳用于防止重放攻击，服务器通常会拒绝时间戳过期过久的请求。正确设置 Content-Type 头也很重要，例如 `application/` 或 `application/x-www-form-urlencoded`，具体取决于请求的内容类型。

以下是一个 Python 代码示例，展示了如何对请求进行签名：

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

def generate_signature(secret_key, method, path, query_string):
""" 生成 HMAC-SHA256 签名。 

 Args:
 secret_key (str): API 私钥。
 method (str): HTTP 方法 (GET, POST, PUT, DELETE)。
 path (str): API 端点路径。
 query_string (str): 查询字符串（已排序）。

 Returns:
 str: HMAC-SHA256 签名。
 """
 message = method + path + query_string
 message = message.encode('utf-8')
 secret_key = secret_key.encode('utf-8')
 signature = hmac.new(secret_key, message, hashlib.sha256).hexdigest()
 return signature

def make_request(api_key, secret_key, method, url, params=None):
""" 发送经过身份验证的 API 请求。 

 Args:
 api_key (str): API 公钥。
 secret_key (str): API 私钥。
 method (str): HTTP 方法 (GET, POST, PUT, DELETE)。
 url (str): API 端点 URL。
 params (dict): 请求参数。

 Returns:
 dict: API 响应 JSON 数据。如果请求失败，则返回 None。
 """

 if params is None:
 params = {}

 # 构建查询字符串并按字母排序
 sorted_params = sorted(params.items())
 query_string = urllib.parse.urlencode(sorted_params)

 # 构建完整的 URL
 parsed_url = urllib.parse.urlparse(url)
 path = parsed_url.path
 if query_string:
 full_path = path + "?" + query_string
 else:
 full_path = path

 timestamp = str(int(time.time()))
 # 生成签名
 signature = generate_signature(secret_key, method, path, query_string)

 headers = {
 'Content-Type': 'application/',  # 建议根据实际情况设置Content-Type
 'X-API-KEY': api_key,
 'X-API-SIGNATURE': signature,
 'X-API-TIMESTAMP': timestamp
 }

 try:
 if method == 'GET':
 response = requests.get(url, headers=headers, params=params)
 elif method == 'POST':
 response = requests.post(url, headers=headers, =params) #  params 改为 ，并且使用 .dumps(params) 转换
 elif method == 'PUT':
 response = requests.put(url, headers=headers, =params) # params 改为 ，并且使用 .dumps(params) 转换
 elif method == 'DELETE':
 response = requests.delete(url, headers=headers, params=params)
 else:
 raise ValueError("Unsupported HTTP method")

 response.raise_for_status() # 检查 HTTP 状态码

 return response.()

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

示例用法

以下代码展示了如何使用API密钥和密钥从BigONE API获取资产交易对信息。 请注意 if __name__ == '__main__': 语句确保代码仅在脚本直接运行时执行，而不是作为模块导入时执行。

if __name__ == '__main__':
api_key = "YOUR_API_KEY" # 替换为你的 API Key
secret_key = "YOUR_SECRET_KEY" # 替换为你的 Secret Key
base_url = "https://big.one/api/v3"
endpoint = "/asset_pairs" # 获取交易对信息的端点
url = base_url + endpoint

这段代码首先定义了必要的变量： api_key 、 secret_key 、 base_url 和 endpoint 。 api_key 和 secret_key 是你的身份验证凭据，务必妥善保管。 base_url 是BigONE API的基本URL， endpoint 指定要访问的特定API端点，此处为获取资产交易对信息。 将 base_url 和 endpoint 组合成完整的 url 。 

data = make_request(api_key, secret_key, 'GET', url)

if data:
    print(data)

这段代码调用 make_request 函数（未在此处定义，需要您自行实现）向BigONE API发起请求。 该函数接收API密钥、密钥、请求方法（'GET'）和URL作为参数，并返回API响应数据。 如果成功获取数据，则将其打印到控制台。 make_request 函数需要处理认证、签名和请求发送的逻辑，并能够解析返回的 JSON 数据。 它应该能够处理潜在的错误，例如网络问题和 API 返回的错误代码。 推荐使用安全的HTTPS连接。

请务必将示例代码中的 YOUR_API_KEY 和 YOUR_SECRET_KEY 替换为您自己的 API 密钥，并在安全的环境中存储你的密钥。 不要将它们直接暴露在代码库中或提交到公共版本控制系统中。 考虑使用环境变量或其他安全的方法来管理敏感信息。

常用 API 端点

BigONE 交易所提供了一系列功能强大的 API 端点，开发者可以利用这些端点访问市场数据、管理账户、进行交易等等。以下是一些常用的 API 端点，涵盖了交易、行情、账户等多个方面：

  • 市场行情数据 API： 用于获取各种交易对的实时行情数据，例如最新成交价、最高价、最低价、成交量等。这些数据对于量化交易策略和市场分析至关重要。包括但不限于：
    • 获取指定交易对的最新成交价
    • 获取指定交易对的深度数据（买单和卖单）
    • 获取指定交易对的历史成交记录
    • 获取所有交易对的汇总行情信息
  • 交易 API： 允许用户通过 API 进行下单、撤单、查询订单状态等交易操作。安全性和稳定性是此类 API 的关键要素，需要进行严格的权限控制和错误处理。包括但不限于：
    • 提交限价单和市价单
    • 撤销未成交的订单
    • 查询当前挂单列表
    • 查询历史成交记录
  • 账户 API： 用于查询账户余额、资产信息、交易记录等。为了保护用户隐私，此类 API 通常需要进行身份验证和授权。包括但不限于：
    • 查询各种币种的可用余额和冻结余额
    • 查询充值和提现记录
    • 查询交易手续费率
  • 公共数据 API： 提供一些公开可用的数据，例如交易所公告、系统状态等。此类 API 通常不需要身份验证。包括但不限于：
    • 获取交易所公告列表
    • 查询系统维护状态
    • 获取支持的交易对列表
获取交易对信息：/asset_pairs - 获取所有可用的交易对信息，包括交易对的名称、基础货币、报价货币、价格精度等。
  • 获取市场行情：/markets/{assetpairname}/depth - 获取特定交易对的深度数据（买单和卖单）。
  • 获取历史K线数据：/markets/{assetpairname}/candles - 获取特定交易对的历史K线数据，可以指定时间范围和K线周期。
  • 下单：/orders - 在特定交易对上下单，可以指定订单类型（市价单、限价单）、方向（买入、卖出）、数量和价格。
  • 取消订单：/orders/{order_id} - 取消指定 ID 的订单。
  • 获取订单信息：/orders/{order_id} - 获取指定 ID 的订单信息。
  • 获取账户余额：/accounts - 获取您的账户余额信息，包括各种币种的可用余额和冻结余额。

    • 错误处理

    当与 BigONE API 的交互出现问题，例如请求格式错误、服务器内部错误或身份验证失败时，API 会返回一个 JSON 格式的错误响应。该响应包含详细的错误信息，帮助开发者诊断和解决问题。错误信息的核心组成部分通常包括一个明确的错误代码和一个描述性的错误消息。开发者应仔细解析这些信息，准确判断错误的具体类型，并根据错误类型采取相应的补救或处理措施，确保应用程序的稳定性和可靠性。

    以下列出了一些在与 BigONE API 交互时可能遇到的常见错误代码及其含义，这些错误代码遵循标准的 HTTP 状态码规范：

    • 400 Bad Request ：此错误表明客户端发出的请求存在问题。常见原因包括请求参数缺失、参数格式不正确、参数值超出有效范围等。开发者应仔细检查请求的有效负载，确保所有必需参数都已提供，且参数类型和格式符合 API 的规范要求。详细的错误消息通常会指出具体哪个参数存在问题。

    • 401 Unauthorized ：此错误表示客户端未经授权尝试访问受保护的资源。通常发生在未提供有效的 API 密钥或提供的密钥已过期、被禁用时。开发者需要检查 API 密钥是否已正确配置，并且拥有访问所需端点的权限。确保在请求头中正确包含了身份验证信息，例如 API 密钥和签名。

    • 403 Forbidden ：此错误表明客户端已通过身份验证，但没有足够的权限访问请求的资源。这可能是由于用户的账户权限不足，或者 API 端点要求特定的角色或权限。开发者应检查用户的权限设置，确认其是否拥有访问该资源的权限。如果需要更高权限，请联系 BigONE 的支持团队。

    • 404 Not Found ：此错误表示请求的资源在服务器上不存在。这可能是由于 URL 地址错误、资源已被删除或移动等原因导致。开发者应仔细检查请求的 URL 地址是否正确，确保其指向有效的 API 端点。检查 API 文档，确认端点是否存在以及是否已正确拼写。

    • 429 Too Many Requests ：此错误表示客户端在短时间内发送了过多的请求，超过了 API 的速率限制。BigONE 为了保护服务器资源，会限制每个 API 密钥的请求频率。开发者应实现速率限制机制，例如使用指数退避算法，在收到此错误后暂停一段时间再重试。查看 API 文档，了解具体的速率限制策略。

    • 500 Internal Server Error ：此错误表示服务器在处理请求时遇到了未知的内部错误。这通常是服务器端的问题，与客户端的请求无关。开发者可以稍后重试请求，或者联系 BigONE 的技术支持团队报告此问题。服务器日志中可能包含有关错误的更多详细信息，以便进行故障排除。

    为了有效地处理 BigONE API 返回的错误，开发者应采取以下步骤：仔细检查发出的 API 请求，确认所有请求参数都符合 API 文档的规范，包括参数类型、格式和取值范围。如果参数正确，但仍然遇到错误，则需要验证 API 密钥的有效性，确保其未过期或被禁用，并确认该密钥是否拥有访问目标 API 端点的足够权限。如果问题仍然存在，建议查阅 BigONE 的官方 API 文档，查找与错误代码相关的详细解释和解决方案。如果以上步骤都无法解决问题，及时联系 BigONE 的技术支持团队，提供详细的错误信息和请求日志，以便他们能够更好地帮助你诊断和解决问题。详细的问题描述能够加速问题解决过程。

    速率限制

    为保障 BigONE API 的稳定性和高性能运行，同时防止恶意攻击和滥用，BigONE 实施了严格的速率限制策略。这意味着对用户在特定时间段内可以发起的 API 请求数量进行了约束。有关速率限制的具体参数，例如每个端点的请求次数限制、时间窗口大小以及重置机制等，请务必查阅 BigONE 官方 API 文档中的“速率限制”或“请求限制”章节，获取最新和最准确的信息。

    当您的应用程序在短时间内发送过多的 API 请求，超过了 BigONE 设定的速率限制阈值时，API 将返回一个 HTTP 状态码 429 Too Many Requests 错误。该错误表明您暂时无法继续发送请求，直到速率限制窗口重置。HTTP 响应头中通常会包含 Retry-After 字段，指示客户端需要等待的秒数，才能再次发送请求。忽略此信息并继续发送请求可能会导致更长时间的阻塞。

    为了避免触发速率限制，确保应用程序的稳定性和可靠性，建议实施以下策略：

    使用指数退避算法： 如果收到 429 错误，不要立即重试。而是等待一段时间，然后再重试。每次重试都增加等待时间（例如，等待时间翻倍），直到达到最大等待时间。
  • 批量请求： 某些 API 允许您在单个请求中获取多个数据。使用此功能可以减少请求的总数量。
  • WebSocket 连接： 对于实时数据，例如市场行情，可以考虑使用 WebSocket 连接，而不是定期轮询 API。WebSocket 连接可以提供更高效的数据传输，并减少 API 请求的数量。
  • 缓存数据： 对于不经常变化的数据，可以考虑将数据缓存到本地，并定期更新缓存。这样可以避免重复请求 API。

    • 在使用 BigONE API 时，务必仔细阅读 API 文档，了解速率限制的详细信息，并采取相应的措施来避免达到速率限制。

    相关推荐