BigONE比特币API交易指南：新手也能快速上手！| 附Python代码示例

研究 33℃

BigONE 比特币交易 API 文档解析

本文档旨在解析 BigONE 交易所提供的比特币交易 API，帮助开发者理解并使用该 API 构建自己的交易策略和应用。我们将涵盖API的各个方面，包括认证，请求格式，响应结构以及常见的交易操作。

认证

在使用 BigONE API 之前，进行身份认证是必要的安全步骤。 BigONE 采用 API Key 和 Secret Key 机制来验证用户身份，确保只有授权用户才能访问其 API 服务。

API Key 和 Secret Key 是你访问 BigONE API 的凭证。 API Key 类似于你的用户名，用于标识你的身份； Secret Key 则相当于你的密码，用于对你的请求进行签名，防止篡改。 请务必妥善保管你的 Secret Key，切勿泄露给他人，以防资金损失。

你可以在你的 BigONE 账户的 API 管理页面生成 API Key 和 Secret Key。 在API 管理页面，你可以创建新的 API Key，并为其设置相应的权限，例如交易、查询等。 创建完成后，系统将显示你的 API Key 和 Secret Key。 请立即保存 Secret Key，因为它是唯一显示的机会。 如果丢失，你只能重新生成新的 API Key。

需要注意的是，为了账户安全，建议定期轮换 API Key 和 Secret Key。 你也可以根据实际需求，为不同的应用或服务创建不同的 API Key，并分配不同的权限，以实现更精细化的权限管理。

请求头

每个 API 请求必须包含特定的请求头，以便服务器能够正确地验证请求并处理数据。以下是必需的请求头：

  • Authorization : 此请求头用于身份验证和授权。它包含一个 JWT (JSON Web Token)，该 JWT 包含了 API Key 和用于验证请求完整性的签名信息。JWT 的格式通常为 Bearer ，其中 是实际的 JWT 字符串。服务器会使用 JWT 中的信息来验证请求者的身份，并确定其是否有权限访问所请求的资源。正确的配置和使用 Authorization 请求头对于 API 的安全性至关重要。
  • Content-Type : 此请求头用于指定请求体的 MIME 类型。当请求体包含 JSON 数据时，必须将其设置为 application/ 。这告诉服务器将请求体的内容解析为 JSON 格式。如果请求体包含其他格式的数据，例如 XML 或表单数据，则应相应地设置 Content-Type 请求头。例如，如果发送的是 XML 数据，则应设置为 application/xml ；如果发送的是表单数据，则应设置为 application/x-www-form-urlencoded 。不正确的 Content-Type 可能导致服务器无法正确解析请求体，从而导致请求失败。

签名生成

为了保障API请求的安全性和完整性，签名是必不可少的环节。签名利用您的 Secret Key 对请求的各个组成部分进行加密哈希运算，从而生成唯一的身份验证凭据。 具体步骤详解如下：

  1. 构建规范化的签名字符串： 签名字符串的构建是整个签名流程的关键。 确定请求方法（例如 GET 、 POST 、 PUT 、 DELETE ）。 获取请求的完整路径，包括任何前缀。 接着，处理查询参数：将所有查询参数按照其参数名进行字母升序排序，然后将排序后的参数名和参数值以 key=value 的形式拼接，多个参数之间用 & 符号连接。 如果请求包含请求体（例如，POST 和 PUT 请求通常包含JSON数据），则将请求体的内容也包含到签名字符串中。 将上述所有组成部分按照特定的格式连接起来形成最终的签名字符串。一种常见的格式是： 请求方法\n请求路径\n排序后的查询参数字符串\n请求体 。 每个部分之间用换行符分隔。
  2. 使用 SHA256 进行哈希运算： 构建好规范化的签名字符串后，使用 SHA256（安全哈希算法256位）算法对其进行哈希运算。 这一步需要使用您的 Secret Key 作为哈希算法的密钥。 将 Secret Key 与签名字符串一起传递给 SHA256 算法，以生成唯一的哈希值。 不同的编程语言或平台都有相应的 SHA256 库或函数可供使用。 确保选择安全可靠的哈希库，并正确处理 Secret Key，避免泄露。
  3. JWT（JSON Web Token）生成： 生成最终签名的方式是将 API Key，过期时间戳和哈希值作为 payload 数据，按照 JWT 标准格式生成。 API Key 用于标识您的身份，过期时间戳用于控制签名的有效期，哈希值则是对整个请求的签名，确保请求的完整性和真实性。 JWT 的 Header 通常指定加密算法和 token 类型。 Payload 包含声明（claims），其中包括 API Key、过期时间戳和哈希值。 Signature 部分使用 Secret Key 对 Header 和 Payload 进行签名，生成最终的 JWT 字符串。 将生成的 JWT 字符串作为请求头或其他指定方式发送给 API 服务器，用于身份验证和授权。 API 服务器收到请求后，会使用相同的 Secret Key 验证 JWT 签名的有效性，并检查 API Key 和过期时间戳，以确保请求的合法性。

示例 (伪代码):

本示例展示了如何使用 Python 生成符合 BigONE API 规范的签名和 JWT（JSON Web Token），用于进行身份验证和授权。代码中使用了 hashlib 、 hmac 和 jwt 等标准库，以及 time 模块来处理时间戳。请确保已安装 PyJWT 库 ( pip install PyJWT )。

import hashlib
import hmac
import jwt
import time

def generate_signature(secret_key, method, path, query_params=None, body=None):
"""生成 BigONE API 请求签名。签名过程包括构建消息字符串，然后使用 HMAC-SHA256 算法对消息进行哈希。"""
message = method + path 

    if query_params:

        sorted_params = sorted(query_params.items())

        query_string = '&'.join([f"{k}={v}" for k, v in sorted_params])

        message += '?' + query_string


    if body:

        message += body


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

    return hashed

def generate_jwt(api_key, secret_key, method, path, query_params=None, body=None):
"""生成 JWT。JWT 包含头部（header）、有效载荷（payload）和签名（signature）。本函数构建了包含 API 密钥、过期时间和请求签名的有效载荷，并使用 HS256 算法进行签名。"""
expiration_time = int(time.time()) + 60 # 设置过期时间为 60 秒。实际应用中，请根据安全需求调整过期时间。
signature = generate_signature(secret_key, method, path, query_params, body) 

    payload = {

        'uid': api_key,  # 用户ID，通常是 API 密钥

        'exp': expiration_time,  # 过期时间，Unix 时间戳格式

        'sig': signature  # 请求签名

    }


    jwt_token = jwt.encode(payload, secret_key, algorithm='HS256')

    return jwt_token

市场数据 API

市场数据 API 允许你获取关于各种加密货币交易对的实时和历史市场数据，这些数据对于理解市场趋势、进行技术分析和构建交易策略至关重要。通过此API，开发者可以访问详细的交易信息，包括但不限于：

  • 实时价格： 当前市场最新的买入和卖出价格。
  • 成交量： 指定时间段内的交易总量，反映市场活跃度。
  • 最高价和最低价： 一段时间内达到的最高和最低价格，用于评估价格波动范围。
  • 时间加权平均价格 (TWAP)： 在特定时期内，根据交易量加权计算的平均价格，提供更准确的价格衡量。
  • 开盘价和收盘价： 指定时间段开始和结束时的价格，用于确定价格趋势。
  • 深度数据： 买单和卖单的挂单数量和价格，反映市场供需关系。
  • 历史交易记录： 过去的交易详细信息，用于回溯测试和分析。

这些数据可以帮助开发者构建各种应用程序，例如：

  • 交易机器人： 自动执行交易的算法。
  • 投资组合跟踪器： 监控加密货币投资的表现。
  • 市场分析工具： 识别潜在的交易机会。
  • 数据可视化仪表板： 以图表形式呈现市场数据。

为了确保数据的准确性和可靠性，API通常会从多个交易所聚合数据，并提供数据质量指标。同时，API通常支持不同的时间粒度，例如分钟、小时、天等，以便开发者根据需要选择合适的数据。API还可能提供速率限制，以防止滥用并确保所有用户的公平访问。

获取交易对信息

  • Endpoint: /markets/{asset_pair_name}
  • Method: GET
  • Description: 获取指定交易对的详细信息。此接口返回关于特定交易对的关键数据，包括但不限于最新成交价格、24小时内的最高价、24小时内的最低价、24小时成交量、以及可能的交易对特定参数和状态信息。利用此接口，用户可以实时监控市场动态，进行交易决策。
  • 参数:
    • asset_pair_name (字符串): 交易对的名称，例如 "BTC-USDT"。此参数区分大小写，必须与平台支持的交易对名称完全一致。
  • 示例: /markets/BTC-USDT
  • 返回数据结构示例: 
    
    {
      "symbol": "BTC-USDT",
      "base_asset": "BTC",
      "quote_asset": "USDT",
      "last_price": "29500.00",
      "high_24h": "30000.00",
      "low_24h": "29000.00",
      "volume_24h": "1000",
      "timestamp": "1678886400",
      "additional_info": {
        "maker_fee": "0.001",
        "taker_fee": "0.002"
      }
    }
  • 注意事项:
    • 交易对名称必须有效且存在于平台。无效的交易对名称将导致错误响应。
    • 返回的时间戳通常为 Unix 时间戳，表示自 Epoch (1970-01-01 00:00:00 UTC) 以来的秒数。
    • additional_info 字段的内容可能因交易所而异，包含交易手续费率等平台特定信息。

获取交易深度

  • 端点 (Endpoint): /markets/{asset_pair_name}/depth
  • 方法 (Method): GET
  • 参数 (Parameters):
    • limit : (可选) 返回的买单和卖单的数量。 该参数用于限制返回的订单簿深度，帮助用户控制数据量。 默认值为 20，允许的最大值为 200。 如果未提供此参数，服务器将默认返回 20 个最佳买单和 20 个最佳卖单。
  • 描述 (Description): 获取指定交易对的交易深度信息。 交易深度信息包含了订单簿上的买单（bid）和卖单（ask）的价格和数量，展示了市场在不同价格水平上的流动性。 该接口允许开发者获取实时的市场供需情况，有助于制定更精准的交易策略。买单代表了市场中愿意以某个价格买入该资产的订单，而卖单则代表了愿意以某个价格卖出该资产的订单。
  • 示例 (Example): /markets/BTC-USDT/depth?limit=50
    • 该示例请求获取 BTC-USDT 交易对的交易深度信息，并限制返回 50 个最佳买单和 50 个最佳卖单。 响应数据将包含深度数据，按照价格排序，并显示每个价格上的可用数量。 开发者可以利用这些数据构建订单簿的可视化图表，或者进行更高级的量化分析。

获取历史成交记录

  • Endpoint: /markets/{asset_pair_name}/trades
  • Method: GET
  • Parameters:
    • limit : (可选) 指定返回的成交记录数量。默认情况下，返回最近的 20 条成交记录。该参数允许自定义返回结果的数量，但最大值被限制为 200。超出此范围的请求将自动截断至最大允许值。 旨在优化数据传输效率，避免服务器资源过度消耗。
    • timestamp : (可选) 以Unix时间戳格式表示。 筛选并返回时间戳小于指定值的成交记录。 采用该参数进行分页查询，允许用户按时间顺序浏览历史成交数据。每次查询都使用前一次查询结果的最小时间戳作为参数，从而实现逐页浏览。
  • Description: 获取指定交易对的历史成交记录。该接口提供对特定交易市场中发生的交易事件的详细数据访问。返回的数据通常包括成交价格、成交数量、成交时间等关键信息。这些数据对于市场分析、交易策略制定和风险管理具有重要价值。
  • 示例: /markets/BTC-USDT/trades?limit=100&timestamp=1678886400

    此示例展示了如何获取 BTC-USDT 交易对的历史成交记录。请求中设置了 limit 参数为 100，表示希望获取 100 条成交记录。同时， timestamp 参数被设置为 1678886400，这意味着返回的成交记录的时间戳将小于此值。通过调整这两个参数，可以灵活地查询特定时间段内特定数量的成交记录。

交易 API

交易 API 允许你安全高效地执行比特币等加密货币的买卖操作，并实时查询您的账户余额、交易历史和订单状态等关键信息。通过此API，您可以自动化交易策略，集成交易功能到您的应用程序或平台中，实现更加灵活和便捷的数字资产管理。

API 提供了多种交易类型，包括市价单（Market Order）、限价单（Limit Order）和止损单（Stop-Loss Order），满足您不同的交易需求。市价单以当前最佳可用价格立即执行，限价单允许您指定买入或卖出的价格，止损单则用于在价格达到特定水平时自动触发交易，从而帮助您管理风险。API还支持不同的交易对，如BTC/USD，ETH/BTC等，您可以根据市场行情选择合适的交易对。

除了交易功能，API还提供了强大的账户管理功能。您可以查询账户余额，包括可用余额和已冻结余额；查看交易历史，了解过去的交易记录；获取订单状态，监控当前订单的执行情况。这些信息对于跟踪您的投资组合表现和优化交易策略至关重要。

为了确保交易的安全性和可靠性，API 采用多重安全措施，包括API密钥认证、数据加密和访问控制。建议您妥善保管API密钥，并采取必要的安全措施，以防止未经授权的访问。同时，我们也建议您在使用API之前仔细阅读API文档，了解API的使用方法和注意事项。

创建订单

  • Endpoint: /orders
  • Method: POST
  • Request Body:

提交订单需要符合特定格式的JSON请求体，以下是具体的字段说明： 


{
    "asset_pair_name": "交易对名称，例如：BTC-USDT",
    "side": "订单方向，'bid' 表示买入（做多），'ask' 表示卖出（做空）",
    "type": "订单类型，'limit' 表示限价单，'market' 表示市价单",
    "price": "委托价格，仅当订单类型为 'limit' 时有效，表示期望成交的价格",
    "amount": "委托数量，表示希望交易的标的数量"
}
  • Description: 创建一个限价或市价订单。 side 参数用于指定订单的方向， bid 代表买入订单，即希望以更低的价格买入资产； ask 代表卖出订单，即希望以更高的价格卖出资产。 type 参数定义订单的执行方式， limit 表示限价单，只有当市场价格达到或优于指定价格时才会执行； market 表示市价单，会立即以当前市场最优价格执行。
  • 示例:

以下是一个创建限价买入订单的示例，交易对为 BTC-USDT，买入价格为 27000 USDT，买入数量为 0.01 BTC： 


{
    "asset_pair_name": "BTC-USDT",
    "side": "bid",
    "type": "limit",
    "price": "27000",
    "amount": "0.01"
}

取消订单

  • Endpoint: /orders/{order_id}
  • Method: DELETE
  • Description: 取消指定 ID 的订单。此操作将从系统中移除指定的订单，并可能触发相关的状态更新和资源释放。请注意，取消订单可能存在时间窗口限制，一旦订单进入特定的处理阶段（如已发货），可能无法取消。在调用此接口前，请务必确认订单状态是否允许取消操作，并考虑潜在的退款或补偿策略。成功取消订单后，服务器应返回适当的状态码，例如 204 No Content，表示操作成功且无需返回额外内容。
  • 示例: /orders/1234567890
  • 请求参数：
    • order_id (路径参数, 字符串): 必需。要取消的订单的唯一标识符。此 ID 通常由系统在创建订单时生成。
  • 请求头：
    • Authorization (字符串): 推荐。用于身份验证的令牌，通常是 JWT 或 API 密钥。
  • 响应状态码：
    • 204 No Content : 订单已成功取消，并且没有内容需要返回。
    • 400 Bad Request : 请求无效。例如， order_id 格式不正确或缺少必需的参数。
    • 401 Unauthorized : 未提供身份验证凭据或凭据无效。
    • 403 Forbidden : 身份验证成功，但用户没有权限取消此订单。
    • 404 Not Found : 找不到具有指定 order_id 的订单。
    • 409 Conflict : 订单当前状态不允许取消操作。例如，订单已经发货或已完成。
    • 500 Internal Server Error : 服务器内部错误。
  • 注意事项：
    • 取消订单是一个敏感操作，应该在前端提供足够的提示和确认，以避免用户误操作。
    • 在实际应用中，可能需要在取消订单后执行额外的操作，例如退款处理、库存调整、发送通知等。
    • 建议记录所有取消订单的操作日志，以便进行审计和问题追踪。
    • API 设计应考虑到幂等性，即使重复调用取消订单接口，也应确保最终状态一致。

获取订单信息

  • Endpoint: /orders/{order_id}
  • Method: GET
  • Description: 获取指定 ID 的订单的详细信息。该接口允许开发者通过提供唯一的订单 ID 来检索特定订单的完整数据。返回的信息包括但不限于订单创建时间、订单状态（例如：已创建、已支付、已发货、已完成、已取消）、订单总金额、订单包含的商品列表、收货人信息、支付方式、以及其他与订单相关的关键信息。
  • 示例: /orders/1234567890 。 这意味着要获取订单号为 "1234567890" 的订单详细信息，你需要向服务器发送一个 GET 请求，URL 为 /orders/1234567890 。 请注意，此处的 "1234567890" 仅仅是一个示例，你需要替换为你实际想要查询的订单 ID。如果订单 ID 不存在，服务器通常会返回一个错误代码（例如：404 Not Found）以及相应的错误信息。

获取所有订单

  • Endpoint: /orders
  • Method: GET
  • Parameters:
    • asset_pair_name : (可选) 交易对名称，用于筛选指定交易对的订单，例如 BTC-USDT 表示比特币与USDT的交易对。如果未指定，则返回所有交易对的订单。
    • state : (可选) 订单状态，用于筛选特定状态的订单。允许的值包括： open （未成交的挂单）, filled （完全成交）, canceled （已取消）, partially_filled （部分成交）。如果未指定，则返回所有状态的订单。 理解订单状态对于监控交易活动至关重要。
    • limit : (可选) 返回的订单数量限制。 默认值为 20 ，最大值为 200 。 此参数用于控制单次API请求返回的订单数量，避免一次性返回过多数据导致性能问题。
    • before : (可选) 分页参数，返回 order_id 小于此值的订单。 用于实现向后分页查询，获取更早的订单记录。 需要提供一个有效的 order_id 作为参考点。
    • after : (可选) 分页参数，返回 order_id 大于此值的订单。 用于实现向前分页查询，获取较新的订单记录。 需要提供一个有效的 order_id 作为参考点。
  • Description: 获取所有订单的信息。 API允许通过交易对名称、订单状态和分页参数进行灵活过滤，以便用户根据特定条件检索订单数据。 分页参数 before 和 after 可用于高效地浏览大量的订单历史记录。
  • 示例: /orders?asset_pair_name=BTC-USDT&state=open&limit=50
    此示例展示了如何获取 BTC-USDT 交易对中所有未成交（open）的订单，并且限制返回的订单数量为 50。 这对于快速监控特定交易对的挂单情况非常有用。

获取账户信息

  • Endpoint: /accounts
  • Method: GET
  • Description: 获取你的账户信息，包括账户的可用余额和已冻结余额。通过此接口，你可以实时掌握账户资金状况，为交易决策提供数据支持。可用余额是指账户中可以立即用于交易或提现的资金，而已冻结余额通常是由于挂单、提现申请或其他操作而暂时无法使用的资金。务必注意，不同交易所或平台对“冻结”的定义可能略有差异，建议查阅相关平台的具体文档说明。例如，某些平台可能会区分“挂单冻结”和“提现冻结”，并分别在不同的字段中显示。正确理解这些余额信息对于资金管理至关重要。

错误处理

BigONE API 使用标准的 HTTP 状态码来指示请求的处理结果。通过 HTTP 状态码，开发者可以快速了解请求是否成功，并根据不同的状态码采取相应的措施。 以下是一些常见的 HTTP 状态码及其在 BigONE API 上下文中的具体含义：

  • 200 OK : 请求成功。 这表示API请求已被服务器成功接收、处理并返回了期望的结果。这是最理想的状态码。
  • 400 Bad Request : 客户端发出的请求格式错误或包含无效参数。 这可能是由于缺少必要的参数、参数类型错误、参数值超出范围或其他类似的客户端错误导致。请仔细检查请求参数是否符合API文档的要求。
  • 401 Unauthorized : 客户端未提供有效的身份验证凭据，或提供的凭据无效。 通常是由于 API Key 缺失、API Key 不正确或签名验证失败导致。请确保你的 API Key 已正确配置，并且用于生成签名的密钥是正确的。同时，请检查签名算法和签名过程是否符合 BigONE API 的规范。
  • 404 Not Found : 请求的资源在服务器上不存在。 这可能意味着你尝试访问的API端点不存在、请求的交易对不存在或请求的其他特定资源不存在。请检查API端点URL是否正确，并确认请求的资源是否存在。
  • 500 Internal Server Error : 服务器在尝试处理请求时遇到了意外错误。 这通常是服务器端的Bug或配置问题，与客户端请求无关。如果遇到此错误，请稍后重试，或联系 BigONE 的技术支持团队。

除了 HTTP 状态码，BigONE API 响应体通常包含一个 code 字段和一个 message 字段，用于提供更详细的错误信息。 code 字段是一个数字或字符串，用于标识特定的错误类型。 message 字段是一个人类可读的字符串，用于描述错误的具体原因。通过结合 HTTP 状态码、 code 字段和 message 字段，开发者可以更精确地定位和解决API调用中出现的问题。

速率限制

为了确保BigONE API 平台的高度稳定性和持续可用性，我们采取了速率限制措施。这些限制根据您调用的具体 API 接口以及您的 API Key 权限级别而有所不同。 详细的速率限制策略旨在防止API滥用，保障所有用户的服务质量。当您的请求频率超过允许的速率限制时，API 服务器将返回一个 429 Too Many Requests 错误状态码。为应对这种情况，我们强烈建议您在应用程序中实施稳健的重试机制，以便在遇到速率限制时能够自动重试请求，而不会中断您的业务流程。您可以通过检查 API 响应头中的相关信息来监控您的速率限制使用情况，例如 X-RateLimit-Remaining 标头显示剩余的可用请求数量， X-RateLimit-Reset 标头指示速率限制重置的 Unix 时间戳，让您更好地管理 API 调用。

上一篇

Bigone大额提现省钱攻略：手续费全解析，避坑指南！

下一篇

欧易 vs 币安：手续费深度对比，哪个更划算？

相关推荐