Bigone API 接口使用教程

1. 简介

Bigone 交易所提供一套全面且强大的应用程序编程接口 (API)，它允许开发者通过编写代码的方式，自动化地访问和管理其在 Bigone 交易所的账户，从而实现更高效的交易和数据分析。通过 Bigone API，开发者能够实时获取市场数据，包括各种交易对的最新价格、交易量、深度信息以及历史数据。API 还支持执行多种交易指令，如限价单、市价单等，方便开发者构建自动化交易策略。开发者还能够管理账户信息，例如查询余额、充值提现等。本教程旨在为开发者提供详细的指导，帮助他们理解并有效利用 Bigone API。内容涵盖 API 的认证机制、常用接口的详细说明以及在使用过程中需要注意的关键事项。我们将深入探讨如何配置 API 密钥，如何构建 HTTP 请求，以及如何解析 API 返回的数据，以便开发者能够快速上手并构建自己的应用程序。

2. 准备工作

在使用 Bigone API 之前，需要完成以下几项准备工作，以便顺利地进行开发和数据交互：

• 注册 Bigone 账户： 如果尚未拥有 Bigone 账户，请访问 Bigone 官方网站（通常为 bigone.com 或类似域名）并按照注册流程创建一个新账户。 注册过程通常需要提供有效的电子邮件地址或手机号码，并设置安全的密码。完成注册后，可能需要进行身份验证，以便解锁全部功能。
• 创建 API Key： 成功登录 Bigone 账户后，导航至账户设置或个人资料中的 "API 管理" 或类似命名的页面。 在此页面，您可以创建一个新的 API Key 对。创建 API Key 时，系统会生成两个关键字符串：API Key（公钥）和 Secret Key（私钥）。 您需要仔细配置 API Key 的权限，例如 "只读"（仅允许获取市场数据）、"交易"（允许进行买卖操作）以及其他相关权限。 权限设置应根据您的实际需求进行，避免赋予不必要的权限，从而降低安全风险。请务必将 API Key 和 Secret Key 安全地存储在本地，切勿将其泄露给他人。Secret Key 用于签名请求，是访问 API 的关键凭证。建议使用加密存储等安全措施保护这些密钥。
• 熟悉 API 文档： Bigone 官方提供的 API 文档是使用 API 的重要参考资料。请认真阅读 API 文档，深入了解各个 API 接口的详细信息，包括接口的 URL 地址、请求方法（如 GET、POST、PUT、DELETE 等）、所需的请求参数（包括参数类型、是否必选等）、响应数据的格式（通常为 JSON 或 XML）以及可能的错误代码和错误信息。文档还会说明 API 的使用限制，例如请求频率限制（Rate Limit）等。 充分理解 API 文档能够帮助您正确地构建 API 请求，并有效地处理响应数据，提高开发效率和程序的稳定性。 不同 API 接口可能需要不同的身份验证方法，请根据文档说明正确地进行身份验证，例如使用 API Key 和 Secret Key 进行签名。

3. 认证方式

Bigone API 使用 API Key 和 Secret Key 进行身份验证。每个 API 请求都必须携带这两个关键参数，以确保请求的合法性和安全性。API Key 用于标识您的账户，而 Secret Key 则用于生成签名，验证请求的真实性。

Bigone API 的身份验证机制采用 HMAC SHA256 签名算法。 HMAC（Hash-based Message Authentication Code）是一种消息认证码算法，它结合了哈希函数和密钥，用于验证消息的完整性和真实性。具体实现步骤如下：

1. 构造签名字符串： 需要创建一个签名字符串，该字符串包含了构建 API 请求的所有关键元素。这通常涉及将请求方法（例如 GET、POST、PUT、DELETE）、请求路径（例如 /orders , /trades ）以及所有请求参数（包括 API Key、时间戳，以及任何其他与请求相关的参数）按照 Bigone 官方文档指定的规则进行拼接。参数排序规则至关重要，必须严格遵守官方文档的说明，以保证签名的一致性。时间戳通常是 Unix 时间戳，代表自 Epoch 以来的秒数。
2. 计算签名： 使用您的 Secret Key 作为密钥，对上一步构造的签名字符串进行 HMAC SHA256 加密。HMAC SHA256 算法将 Secret Key 和签名字符串作为输入，生成一个唯一的哈希值，这个哈希值就是请求的签名结果。务必确保 Secret Key 的安全性，避免泄露，因为它能被用来伪造请求。
3. 添加签名到请求头： 将 API Key 和计算得到的签名结果添加到 HTTP 请求头中。通过请求头传递认证信息是一种常见的做法，它使得服务器能够验证请求的身份，而无需在请求体中暴露敏感信息。通常使用的请求头包括：
   • Authorization : Bearer : 。其中， 替换为您的实际 API Key， 替换为 HMAC SHA256 签名。 "Bearer" 是一种常见的授权方案，表明接下来的内容是持有者令牌。
   • Content-Type : application/ 。指定请求体的 MIME 类型为 JSON，表明您正在发送 JSON 格式的数据。这是 RESTful API 中常用的格式。
   • Accept : application/ 。指定客户端期望接收的响应体的 MIME 类型为 JSON。
   • X-BIGONE-TIMESTAMP : 。有些 API 可能需要将时间戳单独放置在自定义的请求头中，以增加安全性。 替换为当前 Unix 时间戳。

几乎所有流行的编程语言都提供了现成的 HMAC SHA256 加密库。例如，在 Python 中可以使用 hashlib 库，在 JavaScript 中可以使用 crypto 模块。选择与您的编程语言兼容的库，并参考其文档进行正确使用。除了标准库外，还有许多第三方库提供了更高级的加密功能和更便捷的 API 使用方式。

4. 常用 API 接口

以下介绍一些常用的 Bigone API 接口，开发者可以通过这些接口获取市场数据、管理账户信息以及进行交易操作。

• 获取账户信息：
  • GET /viewer/accounts ：获取用户的账户余额信息，包括各种资产的可用余额、冻结余额等详细数据。此接口需要携带有效的 API Key 和签名进行身份验证，确保账户安全。响应结果通常包含一个资产列表，每个资产对应一个账户对象，其中包含资产 ID、可用余额、冻结余额等属性。
  • GET /viewer/accounts/{asset_id} : 获取指定币种账户余额信息。通过指定 asset_id ，可以精确查询特定加密货币的账户余额情况。例如，查询 BTC 的余额，你需要知道 BTC 对应的 asset_id 。响应结果包含该资产的详细账户信息，方便开发者进行针对性的资产管理。
• 获取市场数据：
  • GET /asset_pairs ：获取所有交易对的信息，包括交易对名称（例如 BTC/USDT）、交易对 ID、基础币种（base asset）和报价币种（quote asset）等。该接口是了解 Bigone 平台支持哪些交易对的重要入口，返回数据通常包含一个交易对列表，每个交易对对象包含交易对名称、交易对 ID、基础币种 ID 和报价币种 ID 等属性。
  • GET /asset_pairs/{asset_pair_name}/depth ：获取指定交易对的深度数据（买单和卖单），也称为订单簿。可以指定深度数据的精度，例如返回的订单数量。深度数据对于分析市场供需关系、评估交易滑点至关重要。通过调整精度参数，开发者可以控制返回的订单簿深度，从而优化数据处理性能。
  • GET /asset_pairs/{asset_pair_name}/trades ：获取指定交易对的成交记录（历史交易数据）。可以指定成交记录的起始时间和结束时间，进行时间范围查询。该接口允许开发者回溯历史交易数据，进行趋势分析、量化交易策略的回测等。返回结果通常包含一个成交记录列表，每个记录包含成交时间、成交价格、成交数量、买卖方向等信息。
  • GET /asset_pairs/{asset_pair_name}/ticker ：获取指定交易对的最新成交价、最高价、最低价、成交量等信息，是快速了解市场行情的重要接口。Ticker 数据通常用于实时监控市场价格波动、触发交易信号等。返回结果通常包含最新成交价、最高价、最低价、成交量、24 小时涨跌幅等指标。
  • GET /asset_pairs/{asset_pair_name}/kline ：获取指定交易对的 K 线数据（蜡烛图数据）。可以指定 K 线的周期（例如 1 分钟、5 分钟、1 小时、1 天等）。K 线数据是技术分析的重要工具，用于识别市场趋势、支撑位和阻力位等。通过调整周期参数，开发者可以获取不同时间粒度的 K 线数据，满足不同的分析需求。
• 交易相关接口：
  • POST /orders ：创建一个新的订单。可以指定交易对、交易方向（买入或卖出，通常用 bid 或 ask 表示）、订单类型（限价单、市价单等）、价格和数量。这是进行交易的核心接口，开发者可以通过该接口实现自动化交易策略。订单类型参数允许开发者选择不同的交易方式，例如限价单允许指定成交价格，市价单则以当前市场最优价格立即成交。
  • GET /orders/{order_id} ：获取指定订单的详细信息，包括订单状态、成交数量、平均成交价格等。通过订单 ID 查询订单详情，方便开发者跟踪订单执行情况、进行盈亏分析等。
  • DELETE /orders/{order_id} ：取消指定订单。只有未成交的订单才能被取消。取消订单是风险管理的重要手段，允许开发者及时终止错误的交易决策。
  • GET /orders ：获取用户的订单列表。可以指定交易对、订单状态（未成交、已成交、已取消等）和时间范围进行筛选。该接口方便开发者查看历史订单记录、分析交易行为等。通过指定不同的筛选条件，开发者可以获取特定类型的订单列表，例如只查看未成交的 BTC/USDT 订单。

5. 错误处理

在使用 Bigone API 时，开发者可能会遇到各种预期或非预期的错误。 Bigone API 采用标准 HTTP 状态码以及详细的 JSON 格式错误信息来清晰地反馈 API 调用结果，帮助开发者快速定位和解决问题。

• HTTP 状态码： 常见的 HTTP 状态码及其含义如下：
  • 200 OK ：请求已成功处理并返回结果。
  • 400 Bad Request ：客户端请求参数错误。这通常意味着请求中缺少必要的参数，或者参数格式不正确，例如数据类型错误、超出范围的值等。仔细检查请求参数和 API 文档以确保符合要求。
  • 401 Unauthorized ：身份验证失败。 常见的错误原因包括：提供的 API Key 或 Secret Key 不正确、未激活 API 权限、API Key 与调用的 endpoint 不匹配、或签名验证失败。请务必检查 API 密钥是否正确配置，并确保签名算法实现无误。
  • 403 Forbidden ：客户端没有权限访问该接口或资源。这可能是由于账户权限不足，或者尝试访问受限的 API endpoint。检查您的账户权限设置，并确保拥有调用该 API 所需的访问权限。
  • 404 Not Found ：请求的资源不存在。 可能是由于 API endpoint 的 URL 地址不正确，或者请求的资源 ID 不存在。请检查 API endpoint 的 URL 地址以及资源 ID 是否正确。
  • 429 Too Many Requests ：由于请求频率过高，触发了 API 的速率限制。为了维护 API 的稳定性和可用性，Bigone 对 API 的调用频率进行了限制。请降低您的请求频率，并考虑使用批量请求或缓存机制来减少 API 调用次数。 查阅API文档以获取关于速率限制的详细信息。
  • 500 Internal Server Error ：服务器内部错误。 这通常是由于 Bigone 服务器端的未知错误导致的。如果遇到此错误，请稍后重试，如果问题仍然存在，请联系 Bigone 技术支持。
• JSON 格式的错误信息： 当 HTTP 状态码指示错误（通常是非 200 状态码）时，响应体通常会包含 JSON 格式的错误信息，提供更详细的错误描述，方便开发者进行调试和排错。例如：

  {
         "code": "invalid_parameter",
         "message": "Invalid parameter: price"
      }

  在上面的例子中， code 字段表示错误的类型（ invalid_parameter 表示无效参数）， message 字段提供了关于错误的更详细描述（ Invalid parameter: price 表示价格参数无效）。开发者可以根据这些信息来诊断和解决问题。

在编写程序时，务必对这些错误进行适当的、健壮的处理。 推荐的错误处理策略包括：使用 try-catch 块捕获异常、根据 HTTP 状态码和 JSON 错误信息进行判断、实现重试机制（特别是对于间歇性错误）、记录详细的错误日志以便于问题追踪、以及在必要时向用户提供友好的错误提示信息，优化用户体验。

6. 请求频率限制

为了保障 Bigone API 服务的稳定性和安全性，防止恶意请求和资源滥用，Bigone 实施了请求频率限制（Rate Limiting）机制。不同 API 接口，根据其资源消耗和重要性，会配置不同的请求频率限制策略。开发者必须严格遵守这些限制，否则可能会导致请求被拒绝。

当您的应用程序超过了预设的请求频率限制时，Bigone API 将会返回 429 Too Many Requests HTTP 状态码。收到此错误代码表明您需要暂停发送请求，并等待一段冷却时间后才能再次尝试。 具体等待时间长度取决于您违反的频率限制策略以及 Bigone 的服务器配置。强烈建议开发者在收到 429 错误后，采用指数退避算法进行重试，避免立即再次触发频率限制。

为了有效地避免因超出请求频率限制而导致应用程序中断或性能下降，您可以采取以下优化措施：

• 本地数据缓存： 对于那些更新频率较低、但需要频繁访问的数据，例如交易对信息、账户资产快照等，建议在应用程序本地建立缓存机制。通过缓存，可以显著减少对 API 的重复请求，降低服务器负载，提升应用响应速度。缓存数据时，务必设置合理的过期时间，以确保数据的准确性和时效性。
• 批量请求策略： 充分利用 Bigone API 提供的批量请求功能。某些接口允许开发者在单个请求中提交多个操作，例如批量下单、批量查询订单状态等。通过将多个操作合并为一个请求，可以有效减少总的请求次数，从而降低触发频率限制的风险。在设计应用程序时，优先考虑使用批量请求接口。
• WebSocket 实时订阅： 对于需要实时更新的数据流，例如市场行情、订单簿深度、交易执行情况等，强烈建议使用 Bigone 提供的 WebSocket 实时数据流服务。通过建立持久的 WebSocket 连接，您可以实时接收数据更新，无需频繁轮询 API，极大地降低了服务器压力，并保证了数据的实时性。避免使用低效的轮询方式获取实时数据，这会迅速耗尽您的请求配额。
• 监控与日志： 在您的应用程序中集成监控和日志功能，以便实时跟踪 API 请求的频率和响应情况。通过监控，您可以及时发现潜在的频率限制问题，并采取相应的优化措施。详细的日志记录可以帮助您分析请求模式，找出需要改进的地方。
• API Key 权限控制： Bigone 可能会提供不同权限级别的 API Key，例如只读权限、交易权限等。根据您的应用程序的需求，选择合适的 API Key 权限级别，避免使用具有过多权限的 API Key。这可以降低因意外操作而触发频率限制的风险。

7. 代码示例 (Python)

以下是一个使用 Python 语言调用 Bigone API 获取账户信息的示例。这个示例展示了如何进行身份验证、构建请求以及处理来自Bigone交易所的响应数据。请注意，在使用此代码之前，务必安装必要的Python库，例如 requests ，可以通过 pip install requests 命令进行安装。

import hashlib
import hmac
import time
import requests
import 

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

def generate_signature(method, path, params):
    """
    生成符合 Bigone API 规范的签名。
    签名过程包括：
    1. 添加时间戳和 API Key 到参数字典。
    2. 对参数字典进行排序。
    3. 构建查询字符串。
    4. 使用 HMAC-SHA256 算法对消息进行哈希处理。
    """
    params["timestamp"] = str(int(time.time()))
    params["access_key"] = API_KEY
    sorted_params = sorted(params.items())
    query_string = "&".join([f"{k}={v}" for k, v in sorted_params])
    message = method.upper() + path + "?" + query_string
    signature = hmac.new(
        SECRET_KEY.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return signature, params["timestamp"]

def get_account_info():
    """
    获取 Bigone 账户信息。
    此函数演示了如何构建带签名的 GET 请求，并处理 API 的响应。
    """
    method = "GET"
    path = "/viewer/accounts"
    params = {}
    signature, timestamp = generate_signature(method, path, params)

    headers = {
        "Content-Type": "application/",
        "Authorization": f"Bearer {API_KEY}:{signature}"
    }

    # 从 URL 中排除 access_key 和 timestamp 参数，因为它们已包含在签名中。
    url = BASE_URL + path + "?" + "&".join([f"{k}={v}" for k, v in params.items() if k != "access_key" and k != "timestamp"])

    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()  # 抛出 HTTPError 异常，以便处理非 200 状态码
        print(.dumps(response.(), indent=4))
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    get_account_info()

请务必将 YOUR_API_KEY 和 YOUR_SECRET_KEY 替换为您从 Bigone 交易所获得的真实 API Key 和 Secret Key。请妥善保管您的Secret Key，避免泄露。

这个示例展示了如何生成API请求签名、发送带有身份验证信息的API请求以及处理API返回的响应数据。您可以根据您的具体需求修改这个示例，从而调用Bigone API的其他接口，例如交易下单、查询订单信息等。在进行任何实际交易操作之前，强烈建议您先在Bigone的测试环境或模拟盘上进行测试，确保您的代码逻辑正确无误。