BigONE API：开发者如何高效接入？全方位指南！

2025-03-06 16:41:46 72

BigONE 交易所 API 使用指南

BigONE 交易所提供了一套全面的 API，允许开发者以编程方式访问其平台上的各种功能，包括市场数据、交易执行和账户管理。 本文档旨在为开发者提供关于如何有效使用 BigONE API 的详细指南。

1. API 概览

BigONE API 提供了两种主要类型的接口，分别用于不同的目的：公开API和私有API。理解这两种API的区别以及它们的功能对于开发者至关重要。

  • 公开 API: 公开API，也称为公共API，主要用于访问无需用户身份验证的市场数据。这类数据包括各种交易对的详细信息，例如交易对的名称、交易量、最小交易数量等。更重要的是，公开API提供了实时的市场行情数据，包括最新成交价、最高价、最低价等，以及订单簿深度信息，这可以帮助开发者了解市场的买卖力量分布情况。通过公开API还可以获取历史交易数据，这些数据对于进行技术分析、回测交易策略等都非常有价值。由于这些API不需要身份验证，因此可以方便地被各种应用程序和网站使用，为用户提供实时的市场信息。
  • 私有 API: 私有API则专注于与用户账户相关的操作，因此需要进行身份验证。通过私有API，用户可以执行各种交易操作，包括下单、取消订单、修改订单等。私有API还允许用户管理自己的账户，例如查看账户余额、查询交易历史、进行资金划转等。更进一步，私有API还可以提供用户的个人信息，例如用户的注册时间、实名认证状态等。由于私有API涉及到用户的资金和个人信息安全，因此在使用前必须进行严格的身份验证，以确保只有授权的用户才能访问这些API。

2. 认证

使用BigONE交易所的私有API需要进行身份验证，这是确保账户安全和授权访问权限的关键步骤。身份验证通过API密钥实现。您可以通过登录BigONE交易所账户，在账户设置或API管理页面创建和管理您的API密钥。

API密钥由两部分组成： API Key 和 Secret Key 。 API Key ，也称为公钥，用于唯一标识您的身份，相当于您的用户名。请妥善保管您的 API Key ，但即使泄露，攻击者也无法直接利用它进行交易，因为它还需要对应的 Secret Key 才能签名请求。

Secret Key ，也称为私钥，是用于对API请求进行数字签名的密钥。每个API请求都需要使用 Secret Key 进行签名，以证明请求的真实性和完整性。切勿将 Secret Key 泄露给任何第三方，并采取必要的安全措施来保护它。如果 Secret Key 泄露，攻击者可以使用您的API Key和Secret Key来冒充您的身份进行交易，从而造成资金损失。建议定期更换您的Secret Key，以提高安全性。

在发送API请求时，您需要将 API Key 包含在请求头中，并将使用 Secret Key 生成的签名也包含在请求头或请求参数中，具体取决于API的规范。BigONE交易所的服务器会验证签名是否有效，如果签名有效，则允许请求通过，否则将拒绝请求。

2.1 请求签名

为了保障API请求的安全性，防止恶意篡改或重放攻击，所有需要身份验证的私有 API 请求都必须经过严格的签名验证。签名是对请求数据的一种数字指纹，可以验证请求的完整性和来源。以下是详细的签名生成和验证流程：

  1. 构造规范化的请求字符串:

    将所有参与签名的请求参数按照其参数名称的字母升序进行排序，然后将排序后的参数以 key=value 的形式连接成一个字符串。参数值需要进行URL编码，以确保特殊字符不会影响签名计算。例如，对于以下参数： 

    
    {
      "account_id": "XXX",
      "amount": "1",
      "instrument_id": "BTC-USDT",
      "price": "10000",
      "side": "buy"
    }

    排序并连接后的请求字符串应为： 

    account_id=XXX&amount=1&instrument_id=BTC-USDT&price=10000&side=buy

    注意：

    • 空值参数也必须包含在签名字符串中，其值为""。
    • 参数值必须为字符串类型。
    • 如果参数值本身包含特殊字符，需要进行URL编码，然后再进行签名。
  2. 使用 Secret Key 进行 HMAC-SHA256 加密:

    使用您的 Secret Key 作为密钥，对上一步构造的规范化请求字符串进行 HMAC-SHA256 加密。HMAC-SHA256 是一种消息认证码算法，它结合了哈希函数和密钥，可以有效地防止消息被篡改。大多数编程语言都提供了 HMAC-SHA256 的实现。

    例如，在Python中可以使用以下代码进行HMAC-SHA256加密： 

    
    import hmac
    import hashlib
    import urllib.parse

    secret_key = "YOUR_SECRET_KEY"  # 替换成你的 Secret Key
    request_string = "account_id=XXX&amount=1&instrument_id=BTC-USDT&price=10000&side=buy"

    hashed = hmac.new(secret_key.encode('utf-8'), request_string.encode('utf-8'), hashlib.sha256)
    signature = hashed.hexdigest()

    print(signature)
  3. 将签名添加到请求头:

    将生成的签名字符串添加到 HTTP 请求的 X-ONE-SIGN 请求头中。服务器端会使用相同的算法和密钥对请求进行签名验证，以确保请求的合法性。

    示例请求头： 

    
    X-ONE-SIGN: [生成的签名字符串]

    请确保在发送请求时，正确设置 X-ONE-SIGN 请求头。

2.2 示例代码 (Python)

该示例代码展示了如何使用 Python 通过 BigONE 交易所的 API 获取账户余额。它使用了 hashlib , hmac , time , urllib.parse 和 requests 库来生成签名并发送 HTTP 请求。

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

请务必替换以下变量为你自己的 API 密钥、私钥和账户 ID。API 密钥和私钥可在 BigONE 交易所的账户设置中找到，账户 ID 通常也在账户设置或相关API文档中提供。

API_KEY = "YOUR_API_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"
BASE_URL = "https://api.big.one/v3"

generate_signature(params) 函数负责生成 API 请求的数字签名。这个签名用于验证请求的完整性和身份。它使用 HMAC-SHA256 算法，将请求参数进行 URL 编码，然后使用你的私钥对编码后的字符串进行哈希运算。参数必须按照键的字母顺序排序，然后再进行URL编码。

def generate_signature(params):
"""生成签名"""
params_string = urllib.parse.urlencode(sorted(params.items()))
secret_key = SECRET_KEY.encode('utf-8')
params_string = params_string.encode('utf-8')
signature = hmac.new(secret_key, params_string, hashlib.sha256).hexdigest()
return signature

get_account_balance() 函数用于获取账户余额。它构造 API 端点 URL，添加时间戳参数，并生成签名。然后，它设置 HTTP 请求头，包括签名、时间戳和 API 密钥。它发送 GET 请求到 API 端点，并解析响应以获取账户余额。请注意，实际的账户余额数据结构可能需要根据 BigONE API 文档进行调整。使用try-except捕获网络请求异常可以增强代码的鲁棒性。

def get_account_balance():
"""获取账户余额"""
endpoint = "/accounts"
url = BASE_URL + endpoint
timestamp = str(int(time.time())) 

params = {
    "timestamp": timestamp,
    "account_id": "YOUR_ACCOUNT_ID" # 你的account_id，从账户设置中获得
}

signature = generate_signature(params)

headers = {
    "Content-Type": "application/",
    "X-ONE-SIGN": signature,
    "X-ONE-TIME": timestamp,
    "X-ONE-KEY": API_KEY,
}
try:
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()  # 检查请求是否成功，抛出异常 for bad status codes
    return response.() # 返回 JSON 格式的响应数据
except requests.exceptions.RequestException as e:
    print(f"请求出错: {e}")
    return None

if __name__ == '__main__': 代码块确保只有在直接运行脚本时才会执行以下代码。它调用 get_account_balance() 函数并打印账户余额，或者在获取账户余额失败时显示错误消息。

if __name__ == '__main__':
balance = get_account_balance()
if balance:
print("账户余额:", balance)
else:
print("获取账户余额失败。")

注意：

  • 请务必将代码中的占位符 YOUR_API_KEY 、 YOUR_SECRET_KEY 和 YOUR_ACCOUNT_ID 替换为您在交易所或API服务提供商处获得的真实凭证。 YOUR_API_KEY 用于识别您的身份， YOUR_SECRET_KEY 用于生成签名以验证请求的完整性， YOUR_ACCOUNT_ID 则指定您要操作的特定账户。 请妥善保管这些凭证，避免泄露，以防资金损失或其他安全问题。
  • 时间戳 timestamp 在请求中至关重要，它必须是标准的 Unix 时间戳，表示自 Unix 纪元（1970年1月1日 00:00:00 UTC）以来的秒数。可以使用编程语言内置的时间函数或在线工具生成。确保时间戳的准确性对于避免重放攻击和保证请求的有效性至关重要。
  • 请求头中的 Content-Type 字段必须明确设置为 application/ 或 application/x-www-form-urlencoded ，具体取决于您发送的数据格式。如果发送的是JSON数据，则设置为 application/ ，如果发送的是表单数据，则设置为 application/x-www-form-urlencoded 。错误的 Content-Type 可能导致服务器无法正确解析您的请求数据。
  • 由于签名验证通常依赖于时间戳，因此请务必确保您的系统时钟与服务器时间精确同步。即使是几秒钟的偏差也可能导致签名验证失败，从而导致请求被拒绝。可以使用网络时间协议 (NTP) 服务来自动同步系统时钟，或者手动调整时钟以确保其准确性。对于高频交易或对时间敏感的应用，时间同步尤为重要。

3. 公开 API

公开 API 提供对交易所市场数据的访问，是开发者和交易者获取实时和历史信息的关键接口。通过这些API，用户可以监控市场动态、分析交易行为以及构建自动化交易策略。 常用的 API 端点包括：

  • /markets : 获取交易所所有交易对的详细信息。此端点返回的数据通常包含交易对的交易代码、基础货币和报价货币、交易状态（例如是否可交易）、最小交易数量、价格精度以及其他相关的交易规则和参数。
  • /markets/{market_id}/depth : 获取指定交易对的深度数据（订单簿）。深度数据反映了市场上买单和卖单的分布情况，帮助交易者了解当前市场的供需关系和潜在的价格支撑/阻力位。通常，深度数据会提供不同价格水平的买单和卖单数量，以及相应的订单总量。
  • /markets/{market_id}/trades : 获取指定交易对的最新成交记录。成交记录包含了每一笔成功交易的价格、交易数量、买卖方向（买入或卖出）以及交易时间戳。通过分析成交记录，交易者可以追踪市场价格的波动情况，识别交易趋势，并评估市场活跃度。
  • /markets/{market_id}/candles : 获取指定交易对的 K 线数据（也称为 OHLC 数据，即开盘价、最高价、最低价和收盘价）。K 线数据是技术分析的基础，可以帮助交易者识别价格模式、趋势反转信号以及支撑/阻力位。常见的 K 线周期包括 1 分钟、5 分钟、15 分钟、30 分钟、1 小时、4 小时、1 天、1 周和 1 月，用户可以根据自己的交易策略选择合适的 K 线周期。

3.1 示例代码 (Python)

import requests

BASE_URL = "https://api.big.one/v3"

def get_market_depth(market_id="BTC-USDT"): """ 获取指定交易对的市场深度数据。 Args: market_id (str, 可选): 交易对ID，例如 "BTC-USDT"。默认为 "BTC-USDT"。 Returns: dict: 包含市场深度数据的字典，如果请求成功。如果请求失败，则返回 None。 """ endpoint = f"/markets/{market_id}/depth" url = BASE_URL + endpoint 

try:
    response = requests.get(url)
    response.raise_for_status()  # 检查 HTTP 响应状态码，如果不是 200，则抛出异常
    return response.()
except requests.exceptions.RequestException as e:
    print(f"请求出错: {e}")
    return None

if __name__ == '__main__': depth = get_market_depth() if depth: print("市场深度:", depth) else: print("获取市场深度失败。")

4. 私有 API

私有 API 是加密货币交易所或交易平台为授权用户提供的专属接口，用于执行交易、管理账户信息以及访问更敏感的数据。这些 API 通常需要身份验证，例如 API 密钥和签名，以确保只有账户所有者才能访问和操作相关功能。

常用的 API 端点包括：

  • /orders : 此端点允许用户创建、修改、取消订单，并查询订单状态及历史记录。用户可以通过指定交易对、订单类型（限价单、市价单等）、价格和数量来下达新的订单。同时，也可以使用订单 ID 来撤销未成交的订单。查询功能则提供订单的详细信息，如订单状态、成交价格、成交数量、下单时间等。
  • /accounts : 通过此端点，用户可以获取账户的各种加密货币和法币余额。除了总余额之外，还可以查询可用余额、冻结余额等，从而了解资金的使用情况。更高级的实现可能提供更细粒度的账户信息，例如不同账户类型（现货账户、合约账户）的余额。
  • /deposits : 此端点用于查询用户在交易所的充值记录。可以按照时间范围、充值币种等条件进行过滤，方便用户核对充值情况。交易所通常会返回充值的时间、金额、交易哈希等关键信息。
  • /withdrawals : 用户可以通过此端点查询提现记录，了解提现申请的状态（例如：已提交、处理中、已完成、已取消等）。交易所会提供提现的时间、金额、提现地址、手续费以及交易哈希等详细信息。

4.1 下单

使用 /orders API端点可以下达买入或卖出订单，参与加密货币交易。 该端点允许你指定交易的各种参数，以满足你的交易策略需求。准确指定参数至关重要，确保订单能够按照预期执行。

下订单时，需要提供以下关键参数：

  • instrument_id : 交易对 ID，明确指定要交易的资产对。例如， BTC-USDT 表示比特币与泰达币之间的交易对。 正确的交易对ID对于确保交易在正确的市场上执行至关重要。
  • side : 订单方向，定义你是想买入还是卖出指定资产。 可选值为 buy (买入) 或 sell (卖出)。 选择正确的订单方向是交易的基础。
  • type : 订单类型，指定订单的执行方式。 可选值为 limit (限价单) 或 market (市价单)。 限价单允许你指定订单执行的价格，而市价单会以当前市场最佳价格立即执行。
  • price : 价格，指定限价订单的执行价格。 只有当订单类型为 limit 时才需要提供此参数。 设定的价格决定了订单的执行条件。
  • amount : 数量，指定要买入或卖出的资产数量。 数量的单位取决于交易对，例如， BTC-USDT 中数量的单位通常是比特币（BTC）。 准确的数量至关重要，它决定了交易的规模。

请务必仔细检查所有参数，尤其是在提交订单之前。错误的参数可能导致意外的交易结果。 不同的交易所或交易平台可能对参数的格式和取值范围有特定的要求，因此请参考平台的官方文档。

4.2 撤单

在加密货币交易中，撤单是指取消先前提交的订单请求的操作。这允许交易者在订单尚未成交的情况下，改变交易策略或应对市场变化。通过 /orders/{order_id} 端点，你可以撤销指定 ID 的订单。 order_id 是指交易所分配给该订单的唯一标识符，用于精确指定要取消的订单。请务必确认 order_id 的正确性，避免误撤其他订单。

要成功撤销订单，通常需要满足一些条件，例如订单尚未完全成交，并且交易所允许在特定状态下撤单。具体的撤单规则会因交易所而异，因此建议在使用 API 撤单前，仔细阅读交易所的 API 文档，了解其撤单机制和限制。例如，某些交易所可能不允许撤销已部分成交的订单，或者在市场波动剧烈时暂停撤单功能。高频交易或API使用不当可能会触发交易所的风控系统，导致撤单失败甚至账户受限，所以要合理使用API，并关注交易所的相关公告。

4.3 查询订单

使用 /orders/{order_id} 端点能够检索特定 ID 的订单信息，包括订单状态、创建时间、交易详情等。 该接口通过在URL中包含唯一的 order_id 来实现对目标订单的精准定位和查询。

通过访问 /orders 端点，可以查询满足特定条件的多个订单。此接口支持使用查询参数进行过滤和排序，例如按时间范围、订单状态、交易金额等进行筛选。 通过灵活运用查询参数，用户可以高效地检索所需的订单列表，便于数据分析和管理。

5. 错误处理

BigONE API 使用标准的 HTTP 状态码来清晰地指示请求处理的结果。开发者可以通过这些状态码快速了解请求是否成功，并根据不同的状态码采取相应的措施。

  • 200 OK : 请求成功。表示服务器已成功处理请求，并返回了预期的结果。
  • 400 Bad Request : 请求参数错误。这意味着客户端发送的请求包含了无效的参数、缺少必要的参数或者参数格式不正确。开发者应仔细检查请求参数，确保其符合API的要求。常见原因包括：参数类型错误、参数范围超出限制、缺少必填参数等。
  • 401 Unauthorized : 身份验证失败。表明客户端未提供有效的身份验证凭据，或者提供的凭据已过期或无效。开发者应检查API密钥、签名是否正确，以及API密钥是否拥有访问所需资源的权限。
  • 404 Not Found : 资源不存在。表示服务器无法找到与请求URL匹配的资源。这可能是由于URL拼写错误、资源已被删除或资源访问权限发生变更。
  • 429 Too Many Requests : 超过请求频率限制。为了保护API服务的稳定性，BigONE API对请求频率进行了限制。当客户端在短时间内发送过多请求时，服务器会返回此状态码。开发者应实现请求频率限制逻辑，例如使用指数退避算法重试请求。
  • 500 Internal Server Error : 服务器内部错误。表示服务器在处理请求时遇到了未知的内部错误。这通常是服务器端的问题，开发者可以尝试稍后重试请求。如果问题持续存在，应联系BigONE技术支持。

当请求失败时，响应正文通常会包含JSON格式的错误消息，提供关于错误原因的详细信息，帮助开发者更快速地定位和解决问题。错误消息通常包含错误代码、错误描述等字段，开发者应根据这些信息进行调试。

6. 速率限制

为确保系统稳定性和公平性，防止恶意滥用，BigONE API 实施了多层速率限制机制。速率限制的具体数值由多个因素决定，包括但不限于：您请求的 API 端点类型、您的账户等级，以及当前的系统负载情况。不同类型的API接口，例如交易接口、行情接口和账户信息接口，可能具有不同的速率限制。

当您的请求频率超过允许的速率限制时，服务器将返回 HTTP 状态码 429 Too Many Requests 错误。该错误表示您的请求已被暂时拒绝。为了避免对您的应用造成影响，您需要等待一段时间后才能再次发送请求。具体等待时间会在响应头中说明。

我们强烈建议您在应用程序的代码中实现健壮的重试机制，以便自动处理速率限制错误。理想的重试机制应包括以下特性：指数退避（Exponential Backoff），即每次重试之间的等待时间逐渐增加；抖动（Jitter），即在等待时间上增加一个随机的小数值，以避免多个客户端同时重试，从而进一步加剧拥塞；最大重试次数限制，以防止无限循环。

您可以通过查看 HTTP 响应头中的 X-RateLimit-Remaining 和 X-RateLimit-Reset 字段来实时监控当前的速率限制使用情况。 X-RateLimit-Remaining 表示在当前时间窗口内您还可以发送的请求数量。 X-RateLimit-Reset 表示到下一个时间窗口重置的剩余秒数（通常以 Unix 时间戳表示）。通过合理利用这些信息，您可以动态调整您的请求频率，从而避免触发速率限制。

另外，请注意，BigONE可能会根据实际情况调整速率限制策略，恕不另行通知。开发者应定期查阅BigONE API文档，以获取最新的速率限制信息。建议您设计您的应用程序时考虑到未来的速率限制变化，采用灵活的架构，以便快速适应新的策略。

7. WebSocket API (实时数据流接口)

BigONE 提供 WebSocket API，这是一个强大的实时数据流接口，允许用户以极低的延迟订阅并接收市场数据和账户信息。 相较于传统的 REST API 轮询方式，WebSocket 采用全双工通信模式，服务器可以主动向客户端推送数据，无需客户端频繁发起请求，从而显著减少延迟，提高交易效率，特别适用于高频交易和量化交易策略。

通过 WebSocket API，用户可以实时获取以下信息：

  • 市场行情： 包括最新成交价、最高价、最低价、成交量、买一价/卖一价、深度数据等。
  • 账户信息： 包括账户余额、持仓情况、订单状态更新（如挂单、成交、撤单）等。

使用 WebSocket API 前，需要建立 WebSocket 连接，并订阅感兴趣的数据频道。 BigONE 官方文档详细描述了 WebSocket 连接的建立方法、数据频道列表、数据格式以及错误处理机制。 建议开发者仔细阅读官方文档，并参考示例代码，以便正确使用 WebSocket API。

请务必注意，使用 WebSocket API 需要具备一定的编程基础，并了解 WebSocket 协议。 对于不熟悉 WebSocket 技术的用户，建议先使用 REST API 进行交易，然后再逐步学习 WebSocket API。 BigONE 官方文档中也提供了常见问题的解答和技术支持渠道，帮助用户更好地使用 WebSocket API。

8. 安全注意事项

  • 密钥安全至关重要： 务必妥善保管您的 API 密钥。切勿通过任何渠道，包括但不限于电子邮件、聊天应用、公共代码仓库或文档等，泄露给任何人。API 密钥一旦泄露，可能导致未经授权的访问，从而造成数据泄露、资金损失或其他严重安全问题。
  • 避免客户端存储密钥： 绝对不要将 API 密钥硬编码或以任何形式存储在客户端代码（例如，浏览器端 JavaScript 代码、移动应用代码）中。客户端代码容易被反编译和破解，导致密钥泄露风险极高。应将 API 密钥存储在安全的服务器端环境中，并通过安全的方式进行访问。
  • 强制使用 HTTPS： 始终使用 HTTPS 协议进行所有与 API 相关的通信。HTTPS 通过 TLS/SSL 加密传输的数据，防止中间人攻击，确保数据传输的机密性和完整性。确保您的服务器和客户端都配置为强制使用 HTTPS。
  • 定期轮换密钥： 定期更换您的 API 密钥是降低安全风险的有效措施。即使密钥在某个时间点泄露，也能最大限度地缩短其有效时间，减少潜在损失。建议根据您的安全策略和风险评估结果，设置合理的密钥轮换周期。
  • 账户活动监控： 密切监控您的账户活动，特别是 API 使用情况。定期检查 API 请求日志、交易记录等，及时发现任何异常行为，例如未经授权的请求、异常的交易量或来源不明的 IP 地址。建立完善的监控和告警机制，以便在出现安全事件时能够迅速响应。

9. 官方文档

要深入了解 BigONE API 的全面功能和使用方法，请务必查阅 BigONE 官方文档。该文档是理解 API 工作原理、可用端点和请求参数的关键资源。其中包含了对每个 API 端点的详细说明，包括请求方法（如 GET、POST）、所需的请求头、请求体格式以及可能的响应代码和数据结构。

官方文档还提供了丰富的示例代码，涵盖多种编程语言，例如 Python、JavaScript 和 Java。这些示例能够帮助开发者快速上手，了解如何构建 API 请求、处理响应数据以及实现各种交易策略。文档通常会包含关于速率限制、身份验证、错误处理以及其他重要 API 使用方面的最佳实践指南。通过遵循这些最佳实践，开发者可以构建更稳定、更高效的应用，并避免常见的陷阱。

请务必将 BigONE 官方文档作为首要参考资源，因为它包含了最准确、最新的信息。BigONE 团队会定期更新文档，以反映 API 的最新变化、新增功能和修复的错误。因此，定期查阅文档，确保您的应用与最新的 API 版本兼容，并能充分利用 API 的所有功能。

The End

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