BigONE API终极指南：快速上手，玩转数字货币交易！

BigONE API 说明

概述

BigONE 提供了一套全面的应用程序编程接口 (API)，赋予开发者访问 BigONE 数字资产交易平台的能力。通过这些 API，开发者能够便捷地获取实时行情数据，高效执行交易下单操作，并安全地管理其 BigONE 账户信息。本文档旨在为开发者提供详尽的 BigONE API 使用指南，涵盖接口功能、参数说明、返回数据格式，以及必要的安全注意事项，确保开发者能够充分利用 BigONE API 构建稳定可靠的应用。

BigONE API 提供了 RESTful 风格的接口，方便开发者使用各种编程语言进行调用。API 密钥管理和权限控制机制确保用户资产安全。API 文档将涵盖速率限制、错误代码处理以及签名验证等关键方面，助力开发者快速上手并有效解决开发过程中可能遇到的问题。

API 接口规范

所有 BigONE API 请求均采用 HTTPS 协议，通过加密方式保障用户数据在传输过程中的安全性，有效防止中间人攻击和数据篡改。HTTPS 协议使用 TLS/SSL 协议对通信进行加密，确保数据在客户端和服务器之间的安全传输。

请求方法： 支持 GET 和 POST 两种请求方法。 请求头： 必须包含 Content-Type: application/。

请求参数：

• 公共参数：
  • access_token ：用户身份验证令牌，用于识别用户并授权访问受保护的资源。该令牌通常在用户成功登录后颁发，并在后续的 API 请求中携带，服务器会验证 access_token 的有效性，确保请求的合法性。请妥善保管，避免泄露。
  • timestamp ：请求的时间戳，以 Unix 纪元时间（1970 年 1 月 1 日 00:00:00 UTC）起经过的毫秒数表示。用于防止重放攻击，服务器会验证时间戳的有效性，如果时间戳与服务器当前时间相差过大，则拒绝请求。确保客户端和服务器的时间同步至关重要。
  • signature ：请求签名，是使用加密算法对请求参数进行计算得出的唯一字符串，用于验证请求的完整性和真实性，防止请求被篡改。签名的生成过程通常包括以下步骤：
    1. 将所有请求参数（包括公共参数和接口特定参数）按照字母顺序排序。
    2. 将排序后的参数名和参数值拼接成一个字符串。
    3. 使用预共享密钥（Secret Key）对拼接后的字符串进行哈希运算（如 SHA256）。
    4. 将哈希运算的结果转换为十六进制字符串，作为请求签名。
    签名生成方法将在后续章节详细介绍，并提供示例代码。
• 接口特定参数：每个接口都有特定的请求参数，用于指定接口要执行的具体操作。这些参数的名称、类型和取值范围，具体参数请参考各个接口的详细说明文档。每个接口的参数定义都应该清晰明确，以便开发者能够正确地调用 API。

响应格式：

API 响应统一采用 JSON (JavaScript Object Notation) 格式，便于解析和处理。JSON 是一种轻量级的数据交换格式，易于人阅读和编写，同时也易于机器解析和生成。响应内容主要包含以下关键字段，以确保客户端能够准确地理解 API 的执行结果：

• code : 状态码，用于指示 API 请求的处理结果。 0 (零) 表示请求成功，API 执行完成并返回预期数据。任何非 0 的数值均表示请求失败，通常对应于不同的错误类型，方便客户端进行错误处理。具体错误码的定义应参考 API 文档。
• message : 错误信息，提供关于错误的详细描述。仅当 code 不为 0 时，此字段才会被填充。 message 字段旨在提供可读性强的错误描述，帮助开发者快速定位问题原因。错误信息应该足够详细，包含必要的问题上下文。
• data : 响应数据，用于承载 API 成功执行后返回的实际数据。只有当 code 为 0 时，该字段才包含有效数据。数据格式根据不同的 API 接口而有所不同，具体结构和字段应参考对应 API 的文档说明。如果API接口无需返回数据，该字段可能为空对象或者null。

错误处理：

当 API 请求执行过程中遇到问题时，服务器会通过返回特定的错误码和错误信息来告知客户端。 code 字段包含一个非零整数，用于标识具体的错误类型。 message 字段则提供关于该错误的更详细描述，以便开发者更好地理解问题所在。 开发者应该仔细分析错误码和错误信息，并据此采取适当的措施来处理异常情况。

常见的错误码及其含义如下，开发者应根据实际情况进行处理：

• 1000 : 参数错误。 这表示 API 请求中提供的参数不符合规范或缺少必要参数。 开发者需要检查请求参数的类型、格式、范围和必填性，确保所有参数都符合 API 文档的要求。 例如，检查时间戳格式是否正确，数字类型是否超出范围，字符串长度是否符合要求等。
• 1001 : 签名错误。 这通常意味着请求的签名验证失败，表明请求可能被篡改或使用了错误的密钥。 开发者需要仔细检查签名算法的实现，确认使用的密钥是正确的，并且签名计算过程中使用的参数和顺序与 API 文档的要求一致。 检查是否存在空格、大小写错误或编码问题。
• 1002 : Token 无效。 这表明用于身份验证的 Token 已经过期、被撤销或根本不存在。 开发者需要重新获取有效的 Token，并确保在每次 API 请求中使用最新的 Token。 可以检查 Token 的有效期，以及用户是否被禁用或已注销。
• 1003 : 权限不足。 这意味着当前用户没有足够的权限执行该操作。 开发者需要检查用户的角色和权限设置，确保用户拥有执行该 API 请求所需的权限。 不同的 API 接口可能需要不同的权限级别，开发者应根据 API 文档的要求进行权限控制。
• 2000 : 服务器内部错误。 这表示服务器在处理请求时发生了未知的内部错误。 这通常是由于服务器端的代码错误、配置问题或资源不足引起的。 开发者可以稍后重试该请求，或者联系 API 提供商获取技术支持。 服务器内部错误通常需要 API 提供商进行排查和修复。
• 3000 : 账户余额不足。 这表明执行该操作所需的账户余额不足。 开发者需要检查账户余额是否足够支付交易费用或满足其他要求。 可以提示用户充值或选择其他支付方式。 这通常发生在进行交易、转账或购买服务时。
• 4000 : 交易失败。 这表示交易未能成功执行。 这可能是由于多种原因引起的，例如市场波动剧烈、交易量不足或订单价格不合理。 开发者需要检查交易参数是否正确，并根据错误信息进行调整。 可以尝试重新提交订单，或者选择其他交易策略。

签名生成

为了保障 API 请求的安全性与完整性，BigONE API 采用了严谨的签名机制。开发者必须遵循既定步骤，确保生成的签名能够通过验证，从而成功发起 API 请求。

1. 构建规范化的参数字符串： 将所有参与签名的请求参数，包括所有公共参数（如 timestamp, nonce 等）以及特定于 API 接口的参数，按照参数名称的 ASCII 码进行升序排列。对参数值进行 URL 编码，确保特殊字符被正确处理。将排序后的参数名和参数值使用等号 = 连接，形成键值对；然后，将各个键值对之间用与符号 & 连接，最终形成一个规范化的参数字符串。 例如： access_key=YOUR_ACCESS_KEY&nonce=RANDOM_NUMBER&timestamp=CURRENT_TIMESTAMP&param1=value1&param2=value2 。
2. 附加密钥： 在上一步骤中生成的规范化参数字符串的末尾，直接追加用户的 Secret Key。 请注意，Secret Key 不参与参数排序和 URL 编码。 形成的字符串将作为后续 SHA256 加密的输入。例如： access_key=YOUR_ACCESS_KEY&nonce=RANDOM_NUMBER&timestamp=CURRENT_TIMESTAMP&param1=value1&param2=value2YOUR_SECRET_KEY 。
3. SHA256 哈希运算： 使用 SHA256 算法对第二步中拼接形成的字符串进行哈希运算。SHA256 是一种广泛应用的密码学哈希函数，能够生成固定长度的哈希值，用于验证数据的完整性。确保使用正确的字符编码（通常是 UTF-8）进行哈希计算，防止因编码差异导致签名验证失败。
4. 签名传递： 将第三步生成的 SHA256 哈希值（签名字符串）作为名为 signature 的参数，添加到 API 请求的参数列表中。此 signature 参数与其他请求参数一同发送至 BigONE API 服务器。 服务器收到请求后，会使用相同的步骤重新生成签名，并与接收到的 signature 参数进行比对，以验证请求的合法性。

示例 (使用 Python):

本示例演示如何使用 Python 生成 API 请求的签名，该签名常用于验证请求的完整性和真实性。使用的库包括 hashlib ，用于 SHA256 哈希计算； urllib.parse ，用于 URL 编码；以及 time ，虽然在本示例中未直接使用，但在实际应用中常用于加入时间戳以防止重放攻击。

import hashlib import urllib.parse import time

定义一个名为 generate_signature 的函数，该函数接收两个参数： params (一个字典，包含 API 请求的所有参数) 和 secret_key (API 密钥，用于生成签名)。

def generate_signature(params, secret_key): """ 生成 API 请求签名。 """

对请求参数进行排序。这一步至关重要，因为参数的顺序会影响最终生成的签名。使用 sorted(params.items()) 对参数字典的键值对进行排序，得到一个排序后的列表。

# 1. 拼接请求参数 sorted_params = sorted(params.items()) query_string = urllib.parse.urlencode(sorted_params)

然后，使用 urllib.parse.urlencode() 将排序后的参数列表编码成 URL 查询字符串。URL 编码确保参数值中的特殊字符被正确处理，避免签名错误。

# 2. 拼接密钥
string_to_sign = query_string + secret_key

# 3. 进行 SHA256 加密
signature = hashlib.sha256(string_to_sign.encode('utf-8')).hexdigest()

return signature

接下来，将 URL 编码后的查询字符串与密钥 secret_key 拼接在一起。密钥必须保密，泄露会导致安全风险。拼接后的字符串将用于生成签名。

使用 hashlib.sha256() 函数对拼接后的字符串进行 SHA256 哈希计算。 encode('utf-8') 确保字符串以 UTF-8 编码进行处理，避免编码问题导致的签名错误。 hexdigest() 将哈希结果转换为十六进制字符串，作为最终的 API 请求签名返回。

示例参数

params 字典包含了发起交易请求所需的关键参数。请注意，实际使用时需要替换示例值。

params = {
'access_token': 'your_access_token',
// 用于身份验证的访问令牌，务必妥善保管。
'timestamp': int(time.time() * 1000),
// 请求发送的时间戳，以毫秒为单位。使用当前时间能确保请求的有效性，防止重放攻击。
'symbol': 'BTC-USDT',
// 交易对，例如比特币兑泰达币。需根据交易所支持的交易对进行设置。
'side': 'BUY',
// 交易方向，买入或卖出。可选值为 'BUY' 或 'SELL' 。
'type': 'LIMIT',
// 订单类型。 'LIMIT' 表示限价单， 'MARKET' 表示市价单。不同的订单类型需要不同的参数。
'price': '10000',
// 限价单的价格。只有当市场价格达到或优于此价格时，订单才会被执行。仅在 type 为 'LIMIT' 时需要。
'amount': '0.01'
// 交易数量，例如买入或卖出的比特币数量。需根据交易所的最小交易单位进行调整。
}

注意： access_token 的获取方式和有效期由交易所决定。请务必参考交易所的API文档。

重要： 提交请求时，请仔细检查所有参数，尤其是价格和数量，避免造成不必要的损失。

用户的 Secret Key

Secret Key，亦称为私钥，是访问和管理加密货币资产的根本凭证。它是一个由字母和数字组成的复杂字符串，用于对交易进行数字签名，证明交易发起者的身份和授权。拥有私钥就相当于拥有对该地址上加密货币的完全控制权。因此，务必安全地保管私钥，防止泄露或丢失。丢失私钥意味着永久失去对相应加密货币资产的访问权限。常见的私钥存储方式包括硬件钱包、软件钱包、纸钱包和脑钱包，选择哪种方式取决于安全需求和便捷性之间的权衡。

secret_key = 'your_secret_key'

上述代码示例展示了一个Secret Key的声明。在实际应用中， your_secret_key 应该被替换成一个真正随机且保密的字符串。请勿使用示例中的字符串作为真实的私钥，因为它已被公开，不再安全。生成安全私钥的方法包括使用专门的密钥生成工具或依赖于可信的钱包应用程序。始终将私钥视为高度敏感的信息，并采取一切必要的措施来保护它。

生成签名

在加密货币交易和API交互中，生成签名是确保数据完整性和身份验证的关键步骤。 签名本质上是对请求参数进行加密处理后得到的唯一字符串，用以验证请求的真实性，防止篡改。

signature = generate_signature(params, secret_key)

上述代码片段展示了生成签名的基本方式。 generate_signature 是一个函数，它接受两个参数： params 和 secret_key 。

params ：通常是一个包含所有请求参数的字典或键值对集合。这些参数包括但不限于交易金额、接收地址、时间戳、API密钥等。参数的具体内容取决于所使用的加密货币交易所或API的具体规范。在生成签名之前，通常需要对这些参数按照特定的规则进行排序，例如按照字母顺序排列，以便确保签名的一致性。

secret_key ：这是一个保密的密钥，由API提供方提供给用户。 必须妥善保管，绝对不能泄露。 secret_key 用于对参数进行加密，生成最终的签名。 不同的API可能使用不同的签名算法，例如HMAC-SHA256、RSA等。签名算法的选择取决于API的安全要求。

生成签名的过程通常包括以下几个步骤：

1. 参数预处理： 对请求参数进行清洗和格式化，确保所有参数都符合API的要求。
2. 参数排序： 按照API的要求对参数进行排序。
3. 参数拼接： 将排序后的参数按照特定的格式拼接成一个字符串。
4. 签名计算： 使用 secret_key 和指定的签名算法对拼接后的字符串进行加密，生成签名。
5. 编码： 将生成的签名进行编码，例如使用Base64编码，以便在HTTP请求中传输。

正确的签名生成和验证能够有效防止中间人攻击和数据篡改，保障加密货币交易的安全。

将签名添加到请求参数中

在构建加密货币交易或API请求时，安全性至关重要。为了确保请求的完整性和真实性，通常需要对请求参数进行签名。签名本质上是使用私钥对请求参数的哈希值进行加密，接收方可以使用相应的公钥验证签名的有效性，从而确认请求未被篡改，并且确实来自授权方。

你需要准备好包含所有必要参数的字典或对象，例如 params 。接下来，你需要计算这些参数的签名。具体的签名算法取决于你所使用的加密货币交易所或API的具体要求，常见的算法包括HMAC-SHA256、RSA等。签名过程通常涉及以下步骤：

• 参数排序： 按照API文档的要求，对参数进行排序（通常是按照字母顺序）。
• 参数编码： 将参数编码成字符串，这通常涉及将参数名和参数值用特定的分隔符（例如 & 和 = ）连接起来。
• 计算哈希： 使用哈希函数（例如SHA-256）计算编码后的字符串的哈希值。
• 使用私钥签名： 使用你的私钥对哈希值进行加密，生成签名。

计算得到签名后，下一步是将签名添加到请求参数中。按照以下方式将签名添加到 params 字典中：

params['signature'] = signature

现在， params 字典包含了所有原始请求参数以及新生成的签名。你可以使用 print(params) 语句来查看包含签名的完整参数集，以便确认签名已正确添加到参数列表中。

print(params)

确保在发送请求之前，仔细检查 params 字典的内容。这可以帮助你调试潜在的问题，例如参数顺序错误或签名计算错误。一些API可能要求签名作为HTTP Header的一部分发送，而不是作为URL参数的一部分。请务必参考API文档，了解正确的签名传递方式，以确保你的请求能够被成功验证。

常用 API 接口

以下列出一些常用的 BigONE API 接口，这些接口允许开发者访问市场数据、执行交易和管理账户：

• 获取行情数据

  • /markets : 获取所有交易对的行情快照，包含最新成交价、24小时涨跌幅、交易量等统计信息，适用于构建市场概览或行情看板。
  • /markets/{symbol} : 获取指定交易对的详细行情数据，例如 BTC-USDT，可以获取该交易对的实时价格、最高价、最低价、成交量等。
  • /markets/{symbol}/depth : 获取指定交易对的深度数据（订单簿），包含买单和卖单的价格和数量，用于分析市场买卖力量和流动性。深度数据通常分为不同的档位，例如前10档、前20档等。
  • /markets/{symbol}/trades : 获取指定交易对的最新成交记录，包含成交时间、价格和数量，用于追踪市场交易活动和价格波动。
  • /tickers : 获取所有交易对的最新成交价，适用于快速了解市场整体价格走势。

• 交易下单

  • /orders : 创建订单。支持多种订单类型，包括市价单（以当前市场最优价格立即成交）和限价单（指定价格挂单，等待市场价格达到指定价格时成交）。创建订单需要指定交易对、订单类型、买卖方向、数量和价格（限价单）。

• 账户信息管理

  • /accounts : 获取账户余额，包含可用余额、冻结余额等。不同币种的余额会分别显示。
  • /orders : 获取订单列表，可以根据订单状态（例如未成交、已成交、已取消）进行筛选。
  • /orders/{id} : 获取指定订单的详细信息，包含订单创建时间、订单类型、状态、成交价格和数量等。
  • /orders/{id}/cancel : 取消指定订单。只有未成交的订单才能被取消。

• 资金划转

  • /withdrawals : 提交提现申请，需要指定提现币种、提现地址和提现数量。通常需要进行身份验证和安全验证。
  • /deposits : 查询充值记录，可以查看充值币种、充值数量和充值状态。

获取行情数据 (示例):

请求方法: GET

请求路径: /markets/BTC-USDT

描述: 此接口用于获取特定交易对的实时行情数据。在本例中， BTC-USDT 代表比特币 (BTC) 兑美元泰达币 (USDT) 的交易对。您可以通过更改交易对标识符来查询其他交易对的行情信息。例如， /markets/ETH-USDT 将返回以太坊 (ETH) 兑美元泰达币 (USDT) 的行情数据。

返回数据: 该接口将返回JSON格式的数据，包含以下关键信息 (示例):

• price : 最新成交价。
• volume : 24小时成交量。
• high : 24小时最高价。
• low : 24小时最低价。
• timestamp : 数据更新的时间戳。

请求示例:

GET /markets/BTC-USDT HTTP/1.1
Host: your-exchange-api.com

响应示例 (JSON):

{
  "price": 27000.50,
  "volume": 15000,
    "high": 27500.00,
    "low": 26800.00,
  "timestamp": 1678886400
}

注意事项:

• 请替换 your-exchange-api.com 为实际的API域名。
• 不同的交易所可能返回不同的数据结构和字段。请参考交易所的API文档。
• 为了避免频繁请求，建议使用 WebSocket 订阅行情更新。

请求参数： 无

响应示例：

以下JSON格式的响应示例展示了加密货币交易平台可能返回的数据结构，用于提供特定交易对的实时或历史市场信息。

{ "code": 0, "message": "success", "data": { "symbol": "BTC-USDT", "open": "28000", "high": "29000", "low": "27000", "close": "28500", "volume": "1000", "quote_volume": "28500000" } }

字段解释：

• code : 整数类型，表示API请求的状态码。 0 通常表示请求成功，其他非零值可能表示错误。
• message : 字符串类型，提供更详细的请求结果描述。 "success" 表明请求已成功处理。
• data : JSON对象，包含实际的市场数据。

data 对象中的字段：

• symbol : 字符串类型，表示交易对。 "BTC-USDT" 代表比特币兑泰达币的交易对。
• open : 字符串类型，表示该时间段（如一天）的开盘价。这里是 "28000" 。
• high : 字符串类型，表示该时间段的最高价。这里是 "29000" 。
• low : 字符串类型，表示该时间段的最低价。这里是 "27000" 。
• close : 字符串类型，表示该时间段的收盘价。这里是 "28500" 。
• volume : 字符串类型，表示交易量，通常以基础货币（例如BTC）的数量表示。这里是 "1000" 。
• quote_volume : 字符串类型，表示以计价货币（例如USDT）计算的总交易额。这里是 "28500000" ，计算方式为收盘价乘以交易量。

注意： 价格和交易量数据通常以字符串形式返回，以避免浮点数精度问题。应用程序可能需要将这些字符串转换为数值类型以进行计算。

创建订单 (示例):

在加密货币交易中，创建订单是启动买卖流程的关键步骤。通过向交易所的API发送POST请求至 /orders 端点，用户可以指示交易所按照特定参数执行交易。以下详细阐述了创建订单请求的各个方面。

请求方法: POST

此请求方法用于向服务器提交数据，在本例中，即订单信息，以便服务器创建新的订单记录。

端点: /orders

该端点是交易所API中负责处理订单创建请求的特定URL。不同的交易所可能会有不同的端点结构，但核心功能保持一致。

请求体 (Request Body):

POST请求的关键在于其请求体，其中包含了订单的所有必要信息。这些信息通常以JSON格式编码，包括:

• 交易对 (Symbol/Pair): 指定要交易的加密货币对，例如 BTC/USD 或 ETH/BTC 。
• 订单类型 (Order Type): 指示订单的执行方式，常见的类型包括：
  • 市价单 (Market Order): 以当前市场最优价格立即执行。
  • 限价单 (Limit Order): 只有当市场价格达到或优于指定价格时才执行。
  • 止损单 (Stop Order): 当市场价格达到指定止损价格时，触发市价单或限价单。
  • 止损限价单 (Stop-Limit Order): 当市场价格达到指定止损价格时，触发一个限价单。
• 订单方向 (Side): 指定是买入 ( buy ) 还是卖出 ( sell )。
• 数量 (Quantity/Amount): 要买入或卖出的加密货币数量。
• 价格 (Price): 对于限价单，指定期望的买入或卖出价格。
• 时间有效期 (Time in Force/TIF): 定义订单在交易所系统中的有效时间，常见的选项包括：
  • GTC (Good Till Cancelled): 订单持续有效，直到被执行或取消。
  • IOC (Immediate or Cancel): 订单必须立即全部或部分执行，否则立即取消。
  • FOK (Fill or Kill): 订单必须立即全部执行，否则立即取消。
• 客户端订单ID (Client Order ID): 用户自定义的订单ID，用于跟踪和识别订单。

示例JSON请求体:

{
  "symbol": "BTC/USD",
  "type": "limit",
  "side": "buy",
  "quantity": 0.1,
  "price": 50000,
  "time_in_force": "GTC",
  "client_order_id": "my_unique_order_123"
}

响应 (Response):

交易所会返回一个HTTP响应，其中包含订单创建的结果。成功的响应通常包含以下信息:

• 订单ID (Order ID): 交易所分配的唯一订单标识符。
• 订单状态 (Order Status): 指示订单的当前状态，例如 open (未成交), partially_filled (部分成交), filled (完全成交), cancelled (已取消)。
• 成交均价 (Average Fill Price): 订单的平均成交价格。
• 成交数量 (Filled Quantity): 已经成交的加密货币数量。

错误处理:

创建订单请求可能会失败，例如由于无效的参数、账户余额不足或市场波动过大。交易所会返回包含错误代码和错误信息的响应，以便用户进行调试和处理。

安全注意事项:

在创建订单时，务必采取安全措施，例如使用HTTPS协议、验证交易所的证书以及妥善保管API密钥。还应仔细检查订单参数，以避免意外的交易损失。

请求参数：

以下JSON对象详细描述了API请求所需的参数，用于提交加密货币交易订单。务必确保所有参数均按照指定的数据类型和格式正确填写。

{
"access_token": "your_access_token",
// 身份验证令牌。替换为您的有效访问令牌，用于验证请求的身份。该令牌通常由身份验证流程获得，并具有一定的有效期。确保令牌未过期，并具有执行交易的权限。
"timestamp": 1678886400000,
// 时间戳。表示请求发送的时间，以Unix时间戳格式（毫秒）表示。用于防止重放攻击，确保请求的新鲜度。时间戳必须在服务器允许的合理时间范围内。可以使用 Date.now() 获取当前时间戳。
"symbol": "BTC-USDT",
// 交易对。指定要交易的加密货币对。例如，"BTC-USDT"表示比特币兑USDT。必须是交易所支持的有效交易对。大小写敏感。
"side": "BUY",
// 交易方向。指示是买入还是卖出。有效值为"BUY"（买入）或"SELL"（卖出）。大小写敏感。
"type": "LIMIT",
// 订单类型。指定订单的类型。常见的订单类型包括"LIMIT"（限价单）、"MARKET"（市价单）等。限价单允许您指定订单的价格，而市价单则以当前市场价格执行。其他可能支持的订单类型包括"STOP_LOSS"（止损单）、"TAKE_PROFIT"（止盈单）等。交易所支持的订单类型可能有所不同。大小写敏感。
"price": "28000",
// 订单价格。仅当订单类型为限价单时有效。指定您愿意买入或卖出的价格。必须是一个数字字符串。精度取决于交易所的规定。
"amount": "0.01",
// 订单数量。指定要买入或卖出的加密货币数量。必须是一个数字字符串。精度取决于交易所的规定。务必检查最小交易数量。
"signature": "your_signature"
// 签名。使用您的私钥对请求参数进行签名，以确保请求的完整性和真实性。签名算法通常使用HMAC-SHA256或其他加密算法。签名需要按照交易所的规范进行计算，并将所有参数（包括access_token、timestamp等）纳入计算范围。 }

响应示例：

该示例展示了一个成功的订单提交响应，包含订单的详细信息。响应数据采用JSON格式，易于解析和处理。

{

"code": 0,

"message": "success",

"data": {

"id": "1234567890",

// 订单ID，唯一标识该订单。

"symbol": "BTC-USDT",

// 交易对，例如BTC-USDT表示比特币兑USDT的交易。

"side": "BUY",

// 订单方向，BUY表示买入，SELL表示卖出。

"type": "LIMIT",

// 订单类型，LIMIT表示限价单，MARKET表示市价单。

"price": "28000",

// 订单价格，对于限价单，表示期望成交的价格。

"amount": "0.01",

// 订单数量，表示要买入或卖出的数量。

"status": "PENDING"

// 订单状态，PENDING表示挂单中，FILLED表示已成交，CANCELED表示已撤销。

}

}

字段解释：

code : 返回码，0表示成功，其他值表示失败。可能出现的错误码包括但不限于：1001 (参数错误), 1002 (余额不足), 1003 (交易对不存在)等。

message : 返回信息，对返回码的文字描述。例如：“success”，“Insufficient balance”。

data : 包含订单详细信息的对象。

id : 订单的唯一标识符，通常由交易所生成。

symbol : 交易对，例如 "BTC-USDT"，表示比特币兑换USDT。不同的交易所可能采用不同的命名规范。

side : 订单方向，"BUY" 表示买入，"SELL" 表示卖出。

type : 订单类型，"LIMIT" 表示限价单， "MARKET" 表示市价单， 部分交易所可能支持更多类型如"STOP_LOSS" (止损单)， "TAKE_PROFIT" (止盈单)。

price : 订单的指定价格（仅限价单有效）。

amount : 订单的数量，代表希望买入或卖出的资产数量。

status : 订单的状态， "PENDING" (挂单中), "FILLED" (完全成交), "PARTIALLY_FILLED" (部分成交), "CANCELED" (已取消), "REJECTED" (已拒绝)。

WebSocket API

BigONE 提供 WebSocket API，允许用户通过持久连接实时接收市场数据和账户信息。与 REST API 相比，WebSocket API 避免了频繁请求的开销，提供更低的延迟和更高的效率，特别适用于高频交易和实时监控。

通过 WebSocket API，您可以订阅多种数据流，包括但不限于：

• 市场行情： 实时更新的交易对价格、成交量、买卖盘口等信息，帮助您把握市场动态。
• 深度数据： 更详细的订单簿信息，展示不同价格级别的挂单量，辅助您进行更深入的市场分析。
• 交易信息： 实时成交信息，提供市场交易的最新动态。
• K线数据： 不同时间周期的K线图数据，包括开盘价、收盘价、最高价、最低价和成交量，满足不同级别的技术分析需求。
• 订单状态： 您账户的订单状态更新，包括订单创建、成交、撤销等，方便您及时了解订单执行情况。
• 账户资产： 账户余额的实时变动，包括充值、提现、交易等引起的资产变化，方便您进行资产管理。

使用 BigONE WebSocket API 需要进行身份验证，以确保账户安全。您需要在连接时提供 API Key 和 Secret Key，并通过签名验证。请务必妥善保管您的 API Key 和 Secret Key，避免泄露。

WebSocket 连接具有保持连接的特性，需要客户端和服务端均发送心跳包以维持连接。如长时间无数据交互，连接可能自动断开。请确保您的客户端能够正确处理连接断开和重连的情况。

BigONE 提供详细的 WebSocket API 文档，其中包含连接方式、订阅方法、数据格式等信息。请参考文档进行开发，以确保正确使用 API。

连接地址： wss://api.big.one/ws/v3

订阅频道：

• markets.{symbol}.depth : 深度数据 。此频道提供指定交易对（由 {symbol} 表示，例如 BTCUSDT ）的实时深度数据，也称为订单簿数据。它包含多个买单和卖单的价格和数量信息，按照价格排序。订阅此频道可以帮助交易者了解市场的买卖力量分布情况，从而制定更明智的交易策略。深度数据通常会分层展示，例如提供前 N 档买卖盘信息，档数越多，提供的市场深度信息越详细。不同的交易所提供的深度数据的更新频率和档数可能有所不同。
• markets.{symbol}.trades : 成交记录 。此频道推送指定交易对 (同样由 {symbol} 代表，例如 ETHBTC ) 的实时成交记录。每当有交易撮合成功时，就会产生一条成交记录，包括成交价格、成交数量、成交时间以及买卖方向等信息。通过订阅此频道，交易者可以实时跟踪市场交易动态，了解最新的市场价格和交易活跃度。成交记录是分析市场趋势和波动性的重要数据来源。
• orders : 订单状态更新 。此频道推送用户自身订单的实时状态更新。当用户的订单被提交、部分成交、完全成交、取消或被拒绝时，都会在此频道收到相应的通知。这些更新包括订单的详细信息，如订单ID、交易对、订单类型（限价单、市价单等）、委托价格、委托数量、已成交数量、订单状态等。通过订阅此频道，用户可以随时掌握自己的订单执行情况，及时调整交易策略。这是自动化交易和量化交易系统不可或缺的频道。

示例：订阅BTC-USDT交易对的深度数据

为了实时追踪市场动态并进行高效交易，您可以订阅BTC-USDT交易对的深度数据。通过订阅，您可以接收关于买单和卖单簿的更新，从而更好地理解市场供需关系。

以下JSON格式的数据结构展示了如何向交易所发送订阅请求，以获取BTC-USDT交易对的深度信息：

{
   "event":  "subscribe",
   "channel": "markets.BTC-USDT.depth"
}

字段解释：

• event : 该字段指示请求的类型，此处为 "subscribe"，表明这是一个订阅事件。
• channel : 该字段指定要订阅的频道，"markets.BTC-USDT.depth" 表示订阅BTC-USDT交易对的市场深度数据。深度数据通常包括不同价格级别的买单和卖单的数量。

技术细节补充：

• 市场深度： 市场深度是指在不同价格水平上可供交易的买单和卖单的数量。它可以帮助交易者评估市场的流动性和潜在的价格波动。
• 订阅频道： 交易所通常会提供不同的频道来订阅不同类型的数据。确保选择正确的频道以获取所需的信息。
• 数据更新： 订阅成功后，交易所会实时推送市场深度的更新数据。 您需要编写相应的代码来处理这些数据并进行分析。
• 频率限制： 部分交易所对订阅频率有限制。请查阅交易所的API文档，了解具体的限制和最佳实践。
• 数据格式： 交易所返回的深度数据通常包括价格、数量和订单类型等信息。 仔细研究API文档，了解数据的具体格式。

速率限制

为确保BigONE API服务的稳定性和高性能，我们实施了速率限制机制。 该机制旨在防止API被滥用，并为所有用户提供公平的访问体验。 详细的速率限制规则，包括每分钟或每秒的请求次数限制、不同API端点的限制差异以及权重计算方式等，请务必仔细查阅BigONE官方API文档。

开发者应严格遵守并根据速率限制规则调整其API请求频率。 过高的请求频率可能导致触发速率限制，从而导致API请求失败，并返回特定的HTTP错误码（例如429 Too Many Requests）。 详细的错误码说明可以在官方文档中找到。

当API请求因达到速率限制而被拒绝时，我们强烈建议开发者采用指数退避算法进行重试。 指数退避算法是一种有效的处理临时性错误的方法，它通过逐步增加重试之间的等待时间来避免对API造成过大的压力。 例如，第一次重试等待1秒，第二次等待2秒，第三次等待4秒，依此类推。 同时，为了避免无限重试，建议设置最大重试次数。

除了使用指数退避算法，开发者还可以考虑以下策略来优化API使用，避免触发速率限制：

• 批量请求： 如果API支持，尽量将多个操作合并到一个请求中。
• 缓存数据： 将API返回的数据缓存在本地，减少对API的重复请求。
• 优化代码： 检查代码中是否存在不必要的API请求。
• 使用WebSocket： 对于需要实时数据的应用，考虑使用WebSocket协议，减少API请求的频率。

通过理解和遵守BigONE API的速率限制规则，并采用适当的策略，开发者可以构建稳定、高效的应用，并确保所有用户都能获得最佳的API体验。

注意事项

• 安全第一： 请务必妥善保管您的 Access Token 和 Secret Key。它们是您访问 BigONE API 的身份凭证，一旦泄露，可能导致您的账户被非法访问或资产损失。建议使用高强度密码，并定期更换 Access Token 和 Secret Key。同时，避免将这些凭证存储在不安全的地方，例如代码仓库或公共网络。启用双因素认证（2FA）可以进一步增强账户的安全性。
• 文档至上： 在使用 BigONE API 之前，请务必仔细阅读官方 API 文档。文档详细描述了每个接口的功能、参数、请求方式、返回值格式以及错误代码等信息。理解这些细节可以帮助您正确地调用 API，避免出现错误或异常。API 文档通常会包含示例代码，可以帮助您快速上手。
• 按需索取： 请根据您的实际业务需求选择合适的 API 接口。BigONE API 提供了多种接口，用于查询市场数据、交易、账户管理等。不必要的 API 请求会增加服务器的负担，并可能影响您的 API 调用频率。建议在设计应用程序时，仔细评估每个接口的必要性，并仅调用您真正需要的接口。
• 合规为本： 请严格遵守 BigONE 的 API 使用条款和协议。这些条款和协议规定了 API 的使用范围、限制以及责任等。违反这些条款和协议可能导致您的 API 访问权限被暂停或取消。定期查看 API 使用条款和协议，确保您的使用方式符合要求。
• 弹性应对： 建议使用具有重试机制的 HTTP 客户端。由于网络环境的复杂性，API 请求可能会因为网络波动、服务器繁忙等原因而失败。重试机制可以在请求失败后自动重新发送请求，提高 API 调用的成功率和稳定性。常用的编程语言和框架都提供了 HTTP 客户端库，支持自定义重试策略。考虑使用指数退避算法，避免在高并发情况下对服务器造成过大的压力。
• 测试先行： 在将代码部署到生产环境之前，务必进行充分的测试。测试可以帮助您发现代码中的错误和漏洞，并确保 API 调用的正确性。建议编写单元测试、集成测试和端到端测试，覆盖各种可能的场景和边界情况。使用 mock 数据或测试环境，避免对真实数据造成影响。自动化测试可以提高测试效率，并减少人工干预。
• 精准计时： 请特别注意时间戳的精度。BigONE API 中，许多接口都需要使用时间戳作为参数，例如订单创建、撤销等。务必使用毫秒级的时间戳，并确保时间戳的准确性。时间戳错误可能导致 API 调用失败或返回错误的结果。可以使用编程语言提供的标准库或第三方库来生成和处理时间戳。考虑使用网络时间协议（NTP）服务器同步系统时间，确保时间戳的准确性。

示例代码（Python）

以下是一个使用 Python 编写的示例，用于演示如何通过 BigONE API 获取 BTC-USDT 交易对的实时行情数据。该示例包含必要的请求参数签名过程，确保安全地访问 API。

import requests import time import hashlib import urllib.parse import hmac import def get_market_data(symbol, access_token, secret_key): """ 获取指定交易对（symbol）的行情数据，例如 'BTC-USDT'。需要提供有效的 access_token 和 secret_key 用于身份验证。 """ url = f"https://api.big.one/markets/{symbol}" # 构造请求参数 timestamp = int(time.time() * 1000) # 毫秒级时间戳 params = { 'access_token': access_token, 'timestamp': timestamp } signature = generate_signature(params, secret_key) params['signature'] = signature try: response = requests.get(url, params=params) response.raise_for_status() # 检查 HTTP 状态码，如果不是 200 则抛出异常 data = response.() # 将返回的 JSON 数据解析为 Python 字典 if data.get('code') == 0: # 建议使用 .get() 方法，避免 key 不存在时报错 return data['data'] else: print(f"API Error: {data.get('message', 'Unknown error')}") # 提供更友好的错误信息 return None except requests.exceptions.RequestException as e: print(f"Request Error: {e}") return None # 请注意，BigONE API签名计算中，使用的secret_key需要是原始字符串, 而不是hex编码后的。 如果SecretKey是16进制编码字符串，请先hex解码。 def generate_signature(params, secret_key): """ 生成符合 BigONE API 要求的请求签名。签名过程包括参数排序、URL 编码和 SHA256 HMAC 加密。 """ # 1. 按照参数名称的 ASCII 码顺序排序参数 sorted_params = sorted(params.items()) # 2. 将排序后的参数转换为 URL 编码的字符串 query_string = urllib.parse.urlencode(sorted_params) # 3. 使用 HMAC-SHA256 算法生成签名。HMAC 需要使用 secret_key 作为密钥。 # 注意这里需要将 secret_key 编码为 bytes hmac_obj = hmac.new(secret_key.encode('utf-8'), query_string.encode('utf-8'), hashlib.sha256) signature = hmac_obj.hexdigest() return signature # 示例用法 (请替换为您的实际 Access Token 和 Secret Key) if __name__ == '__main__': access_token = "YOUR_ACCESS_TOKEN" secret_key = "YOUR_SECRET_KEY" symbol = "BTC-USDT" # 要查询的交易对 market_data = get_market_data(symbol, access_token, secret_key) if market_data: print(f"Market Data for {symbol}:") print(.dumps(market_data, indent=4)) # 格式化打印 JSON 数据 else: print("Failed to retrieve market data.")

替换为您的 API Access Token 和 Secret Key

在使用交易所提供的API进行程序化交易或数据分析时，您需要提供有效的身份验证凭据。这些凭据通常包括一个Access Token（或API Key）和一个Secret Key。

Access Token（API Key）： 类似于您的用户名或账户ID，用于标识您的身份，让交易所知道是谁在请求API服务。请注意，不同的交易所可能使用不同的术语，如API Key、Consumer Key等，但其本质都是用于身份识别。

Secret Key： 类似于您的密码，用于对您的API请求进行签名，确保请求的完整性和安全性。Secret Key必须妥善保管，切勿泄露给他人。一旦泄露，您的账户可能会面临风险。

以下代码示例展示了如何在代码中设置Access Token和Secret Key：

access_token = "your_access_token"
secret_key  = "your_secret_key"

重要提示：

• 务必将 "your_access_token" 和 "your_secret_key" 替换为您从交易所获得的真实凭据。
• 不要将您的Secret Key存储在公共的代码库或容易被他人访问的位置。
• 定期更换您的API Key和Secret Key，以提高安全性。
• 启用双重验证（2FA）可以进一步保护您的账户安全。
• 仔细阅读交易所的API文档，了解如何安全地使用API Key和Secret Key。

不正确的配置或密钥泄露可能导致资金损失或其他安全问题，请务必谨慎操作。

获取 BTC-USDT 的行情数据

要获取 BTC-USDT 的行情数据，可以使用如下代码片段。此段代码展示了如何调用 get_market_data 函数，该函数接受交易对标识符（例如 "BTC-USDT"）、访问令牌 ( access_token ) 和密钥 ( secret_key ) 作为参数。 get_market_data 函数负责与交易所的API交互，并返回包含最新市场数据的字典或JSON对象。

market_data = get_market_data("BTC-USDT", access_token, secret_key)

在调用 get_market_data 函数后，需要检查返回的数据是否有效。以下代码片段展示了如何检查 market_data 是否成功返回数据，并打印出来。如果 market_data 不为空（即函数成功返回数据），则会将行情数据以易于阅读的格式打印到控制台。这通常包括价格、交易量、买单和卖单信息等。

if market_data: print(f"BTC-USDT Market Data: {market_data}")

请务必将代码中的 access_token 和 secret_key 替换为你自己的 Access Token 和 Secret Key。这些凭证通常在交易所的API管理页面上创建。保护你的 secret_key 至关重要，切勿将其泄露或存储在不安全的位置。Access Token 用于标识你的身份，而 Secret Key 用于对你的API请求进行签名，确保交易的安全性和完整性。没有正确的 Access Token 和 Secret Key，你将无法成功获取行情数据。

API 版本更新与维护

BigONE 致力于提供稳定、高效的API服务，并会持续进行优化和功能增强。为了满足不断变化的市场需求和技术发展，BigONE 会定期发布新的 API 版本。 开发者应该密切关注BigONE官方渠道（例如：官方网站公告、开发者邮件列表、社交媒体平台）发布的更新信息，以便能够及时了解最新的 API 变更、新增功能、性能改进以及潜在的兼容性影响。

每个 API 版本更新公告通常会包含以下关键信息：

• 版本号： 清晰标明本次更新的版本号，方便开发者区分和追踪。
• 更新内容概要： 概述本次更新的主要变更内容，包括新增接口、废弃接口、参数修改、数据结构调整等。
• 详细变更列表： 提供详细的变更列表，包括每个接口的具体修改内容、参数说明、返回值示例等，方便开发者进行评估和调整。
• 兼容性说明： 明确说明本次更新是否会影响现有应用的兼容性，以及需要进行哪些修改才能保证应用的正常运行。
• 升级指南： 提供详细的升级指南，指导开发者如何将现有应用迁移到新的 API 版本，并提供示例代码和最佳实践。
• 发布时间： 明确 API 更新的发布时间，给开发者预留充足的准备时间。
• 测试环境： 提供可供开发者进行测试的 API 环境，以便在正式环境上线前进行充分的验证。

为了更好地适应 API 的更新，开发者应该采取以下策略：

• 订阅官方公告： 及时订阅 BigONE 官方公告，确保第一时间获取 API 更新信息。
• 使用版本控制： 在应用中使用 API 版本控制，以便在 API 更新时能够灵活切换到不同的版本。
• 编写健壮的代码： 编写健壮的代码，能够处理 API 返回的各种错误和异常情况。
• 进行充分的测试： 在正式环境上线前，进行充分的测试，确保应用能够正常运行。
• 关注社区讨论： 关注开发者社区的讨论，与其他开发者交流经验，共同解决问题。

技术支持

在使用 BigONE API 进行开发或交易的过程中，您可能会遇到各种技术问题。为了确保您的交易顺畅进行，我们提供专业的 BigONE 技术支持团队，随时为您提供协助。

如果您在使用 BigONE API 过程中遇到任何问题，例如 API 调用失败、数据返回异常、权限问题、或者对 API 文档有任何疑问，请随时联系 BigONE 的技术支持团队。我们将竭诚为您提供专业的解答和支持。

您可以通过以下方式联系 BigONE 技术支持团队：

• 提交工单：访问 BigONE 官方网站，在帮助中心提交工单，详细描述您遇到的问题。
• 发送邮件：发送邮件至 BigONE 技术支持邮箱，附上详细的问题描述、API 请求示例、以及相关的错误信息。
• 在线咨询：通过 BigONE 官方网站的在线客服系统，与技术支持人员进行实时沟通。

为了更快地解决您的问题，请在联系技术支持时提供以下信息：

• 您的 BigONE 账户 ID。
• 您正在使用的 API 端点。
• 您使用的编程语言和 SDK 版本。
• 您的 API 请求示例和返回结果。
• 详细的问题描述和错误信息。

我们致力于为您提供高效、专业的技术支持，帮助您充分利用 BigONE API，实现您的交易目标。

常见问题

• 为什么我的请求总是返回签名错误？ 请仔细检查签名生成过程。务必确保以下几点：
  • 参数拼接： 请求参数和 Secret Key 的拼接顺序必须与 API 文档严格一致。不同的顺序会导致完全不同的签名结果。
  • Secret Key： 确认 Secret Key 是否正确复制，避免遗漏字符或包含空格。
  • SHA256 加密： 使用标准的 SHA256 算法进行加密，并确保加密后的结果为十六进制字符串。大小写也需要注意，通常为小写。
  • 时间戳精度： 时间戳必须精确到毫秒级。如果时间戳的精度不足，签名验证将失败。
  • 时间同步： 确保您的服务器时间与 BigONE 服务器时间保持同步。可以使用 NTP 服务校准时间，避免因时差过大导致签名验证失败。 如果本地时间和服务器时间相差过大(超过30秒)，也会出现签名错误。
  • 字符编码： 确保在签名过程中使用 UTF-8 编码处理所有字符串，避免编码问题导致的签名不一致。
  • URL编码： 某些特殊字符可能需要进行URL编码后再参与签名，请参考API文档。
• 如何处理速率限制？ 遇到速率限制时，强行重试可能会导致更严重的限制。建议采用更合理的策略：
  • 指数退避算法： 使用指数退避算法重试请求。第一次请求失败后，等待较短的时间（例如 1 秒）重试；第二次请求失败后，等待更长的时间（例如 2 秒）重试。每次重试都增加等待时间，直到请求成功或达到最大重试次数。
  • 错误码判断： 根据 API 返回的错误码判断是否是速率限制。如果是速率限制，则执行退避重试策略。如果不是速率限制，则可能是其他错误，需要根据错误信息进行处理。
  • 批量请求： 尽量将多个请求合并成一个批量请求，减少请求次数。
  • 优化代码： 检查代码是否存在频繁请求同一接口的问题，优化代码逻辑，避免不必要的请求。
  • 订阅消息： 如果API提供了websocket或其他订阅消息推送的机制，建议采用该方式获取数据，减少轮询请求。
• 如何查看我的API使用情况？ 为了更好地管理和优化您的 API 使用，BigONE 提供了 API 使用情况统计功能：
  • API 仪表板： 通过 BigONE API 仪表板，您可以清晰地查看 API 调用量统计，了解您的 API 使用情况。
  • 数据分析： API 调用量统计数据可以帮助您分析 API 使用模式，识别潜在的性能瓶颈，并及时调整策略。
  • 策略调整： 根据 API 使用情况，您可以调整请求频率、优化代码逻辑，或者升级 API 权限，以更好地满足您的业务需求。
  • 访问路径： 请登录您的 BigONE 账户，前往开发者中心查看 API 使用情况详情。开发者中心通常会提供更详细的统计数据和图表，帮助您更好地了解 API 使用情况。
  • 联系客服： 如果您有任何关于 API 使用情况的问题，可以联系 BigONE 客服，他们会为您提供专业的解答和支持。