Bigone API集成指南：快速上手交易平台功能！

目录： 介绍 阅读：40

Bigone API 连接

本文档旨在帮助开发者理解和使用 Bigone API，以便集成 Bigone 交易平台的功能到自己的应用程序中。我们将详细介绍 API 连接的各个方面，包括认证、请求方式、数据格式，以及一些常见的 API 调用示例。

概述

Bigone API 提供了一套全面的RESTful接口，允许开发者和用户通过编程方式无缝访问和控制其 Bigone 账户。 这意味着用户可以自动化交易策略，集成 Bigone 的功能到其他应用程序中，以及构建定制化的交易工具。通过 API，用户可以实时进行市场数据查询，包括但不限于交易对的最新价格、成交量、历史数据等。API还支持高效的下单交易操作，涵盖市价单、限价单等多种订单类型，并能实时追踪订单状态。账户信息管理功能也十分完善，用户可以通过API获取账户余额、交易历史、持仓情况等详细信息，从而更好地管理自己的资产。

为了保证 API 的安全性，Bigone 采用了严格的身份验证机制，即 API Key 和 Secret Key。 API Key 用于标识用户身份，而 Secret Key 则用于对请求进行签名，防止数据篡改。 用户需要在Bigone平台创建并妥善保管自己的 API Key 和 Secret Key。 强烈建议用户启用双因素认证（2FA）以增强账户安全性。 在使用 API 时，务必遵循 Bigone 的安全指南和最佳实践，以防止潜在的安全风险，例如将 Secret Key 泄露给他人或在不安全的环境中使用 API Key。 请注意API的使用频率限制（Rate Limiting），避免因过于频繁的请求而被暂时限制访问。 API Key具有不同的权限等级，请根据实际业务需求选择合适的权限，并定期轮换API Key，以进一步提升安全性。

认证

在使用 Bigone API 之前，您需要创建 API Key 和 Secret Key，以便安全地访问和使用API服务。您可以通过 Bigone 官方网站的用户账户设置中的“API 管理”页面来生成和管理您的 API 密钥对。该页面提供创建、查看、编辑和删除 API 密钥的功能，确保您可以灵活地控制您的 API 访问权限。

API Key 用于唯一标识您的应用程序或账户，Bigone 使用此 Key 来跟踪和管理 API 的使用情况。Secret Key 是一个私密的密钥，用于对您的 API 请求进行数字签名，从而验证请求的来源和完整性。签名机制可以有效地防止恶意攻击者伪造或篡改您的请求，保证数据的安全传输。务必极其谨慎地保管您的 Secret Key，切勿将其以任何方式泄露给他人，包括公开在代码库、论坛或任何公共渠道中。一旦 Secret Key 泄露，攻击者可以使用您的密钥执行未经授权的操作，造成严重的资产损失或其他安全风险。

所有需要身份验证的 API 请求，即需要授权才能访问的 API 端点，都必须在 HTTP Header 中包含以下信息，以进行身份验证和授权：

  • X-API-KEY : 您的 API Key，用于标识发起请求的应用程序或用户。Bigone 使用此 Key 来查找与您的账户相关的权限和限制。
  • X-API-TIMESTAMP : 请求的时间戳，以 Unix 时间戳格式表示（自 Unix 纪元以来的毫秒数）。时间戳用于防止重放攻击，即攻击者捕获并重新发送您的请求。Bigone 会验证时间戳的有效性，如果时间戳与服务器时间相差过大，请求将被拒绝。
  • X-API-SIGNATURE : 请求的数字签名。签名是使用您的 Secret Key 对请求的特定参数进行哈希运算生成的。Bigone 会使用相同的算法和您的 Secret Key 重新计算签名，并将其与您提供的签名进行比较。如果两个签名匹配，则表明请求是合法的，并且没有被篡改。签名的生成通常涉及以下步骤：
    1. 构建一个包含所有必需参数的字符串。参数通常按照字母顺序排序，并用特定的分隔符连接。
    2. 使用您的 Secret Key 和选定的哈希算法（例如，HMAC-SHA256）对参数字符串进行哈希运算。
    3. 将生成的哈希值作为 X-API-SIGNATURE 的值添加到 HTTP Header 中。

签名生成方法:

  1. 参数排序： 将请求中所有参与签名的参数，包括查询参数（Query Parameters）和请求体参数（Body Parameters，如果存在），按照参数名称的字母升序进行排列。 这是构建规范化字符串的第一步，确保签名的唯一性和可验证性。
  2. 参数连接： 将排序后的每个参数名和对应的参数值使用等号 = 连接起来，构成键值对字符串。然后，将所有这些键值对字符串使用 & 符号连接成一个长字符串。这个步骤创建了一个标准化的参数字符串，为后续的签名操作奠定基础。务必确保 URL 编码正确处理，特殊字符需要进行转义，以符合 URL 规范。
  3. HTTP 方法转换： 将发起请求时使用的 HTTP 方法（例如 GET 、 POST 、 PUT 、 DELETE 、 OPTIONS 、 HEAD 等）统一转换为大写形式。 HTTP 方法是签名算法的重要组成部分，大写转换确保了签名的一致性。
  4. URL 路径拼接： 将请求的 URL 路径（不包含域名和查询参数）添加到上一步骤生成的参数字符串之前，作为签名的前缀。 URL 路径是请求资源定位的关键信息，必须包含在签名中以保证请求的完整性。
  5. HMAC-SHA384 加密： 使用您的 Secret Key 对上一步骤生成的完整字符串进行 HMAC-SHA384 加密。 HMAC (Hash-based Message Authentication Code) 是一种利用哈希函数进行消息认证的技术。 SHA384 是一种安全的哈希算法。 使用 Secret Key 对规范化字符串进行 HMAC-SHA384 加密，生成一个唯一的签名摘要。请确保 Secret Key 的安全性，避免泄露。
  6. Base64 编码： 将 HMAC-SHA384 加密后的二进制结果转换为 Base64 编码的字符串。 Base64 编码将二进制数据转换为可打印的 ASCII 字符，方便在 HTTP 头部等文本协议中传输。生成的 Base64 编码字符串即为最终的签名值。

示例 (Python):

此示例展示了如何使用 Python 生成用于加密货币 API 请求的签名。签名用于验证请求的完整性和真实性，防止恶意篡改。

需要导入以下 Python 库：

  • hmac ：用于生成基于密钥的哈希消息认证码（HMAC）。
  • hashlib ：提供多种哈希算法，例如 SHA384。
  • base64 ：用于将二进制数据编码为 ASCII 字符串。
  • time ：用于获取当前时间戳。
  • urllib.parse ：用于处理 URL，尤其是查询字符串的编码。 
import hmac
import hashlib
import base64
import time
import urllib.parse

generate_signature 函数用于生成 API 签名。它接受 HTTP 方法（例如 GET、POST）、API 路径、请求参数和密钥作为输入。 

def generate_signature(method, path, params, secret_key):
    """
    生成 API 签名
    """

获取当前时间戳，以毫秒为单位，并将其添加到请求参数中。使用时间戳可以防止重放攻击。 

    timestamp = str(int(time.time() * 1000))
    params['timestamp'] = timestamp

然后，对所有请求参数进行排序，并将它们编码成 URL 查询字符串。排序对于确保签名的一致性至关重要，因为参数的顺序会影响最终的签名值。 

    sorted_params = sorted(params.items())
    query_string = urllib.parse.urlencode(sorted_params)

接下来，构造用于计算签名的消息。该消息由 HTTP 方法、API 路径和查询字符串组成。HTTP 方法需要转换为大写。 

    message = method.upper() + path + '?' + query_string

将消息和密钥都编码为 UTF-8 字节串，因为 hmac 库需要字节串作为输入。 

    message = message.encode('utf-8')
    secret_key = secret_key.encode('utf-8')

使用 hmac.new 函数生成 HMAC-SHA384 签名。SHA384 是一种安全的哈希算法，可以提供足够的安全性。 digest() 方法返回哈希值的二进制表示形式。 

    signature = hmac.new(secret_key, message, hashlib.sha384).digest()

使用 Base64 编码将二进制签名转换为 ASCII 字符串，以便在 HTTP 请求头中传输。对时间戳进行同样处理，返回签名和时间戳。 

    signature = base64.b64encode(signature).decode('utf-8')

    return signature, timestamp

示例数据

以下代码段展示了如何设置API密钥、私钥、请求方法、API路径以及查询参数，为后续的签名生成做好准备。请务必替换占位符"YOUR_API_KEY"和"YOUR_SECRET_KEY"为你实际的API密钥和私钥。API密钥用于身份验证，私钥则用于生成请求签名，确保请求的安全性。 

api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
method = "GET"
path = "/api/v3/asset/accounts"  # 示例API路径
params = {} # 查询参数

这里， method 变量定义了HTTP请求方法为"GET"， path 变量指定了要访问的API端点，即获取资产账户信息的"/api/v3/asset/accounts"。 params 变量则用于存放查询参数，本例中为空，表示不传递任何查询参数。 实际应用中，可以根据API文档的要求，将需要的参数以字典形式添加到 params 中，例如： params = {"symbol": "BTCUSDT"}

这段代码调用 generate_signature 函数，利用前面定义的请求方法（ method ）、API路径（ path ）、查询参数（ params ）以及私钥（ secret_key ）来生成请求签名和时间戳。生成的签名用于验证请求的合法性，防止篡改；时间戳则用于防止重放攻击，确保请求的时效性。 

signature, timestamp = generate_signature(method, path, params, secret_key)

generate_signature 函数的具体实现会根据交易所或API提供商的要求而有所不同，通常涉及以下步骤：将请求参数按照特定规则排序、拼接成字符串，然后使用私钥对该字符串进行哈希（如HMAC-SHA256）加密，得到最终的签名。时间戳通常是当前时间的Unix时间戳，也需要包含在签名过程中或作为单独的请求头发送。

构造请求头

为了安全地与API进行交互，我们需要构造包含身份验证信息的请求头。 通常情况下，这涉及到API密钥、时间戳以及签名，用于验证请求的来源和完整性。以下是一个Python字典，用于构建符合要求的HTTP请求头： 


headers = {
    "X-API-KEY": api_key,
    "X-API-TIMESTAMP": timestamp,
    "X-API-SIGNATURE": signature
}

X-API-KEY 字段用于标识您的API密钥，它通常由API提供商提供，用于识别您的身份并授权访问API。 X-API-TIMESTAMP 字段表示请求发送的时间戳，这有助于防止重放攻击。 时间戳通常以Unix时间戳（自1970年1月1日午夜以来的秒数）的形式表示。 X-API-SIGNATURE 字段是使用您的Secret Key和请求的其他参数生成的签名。 签名用于验证请求的完整性，确保请求在传输过程中没有被篡改。

可以通过以下Python代码打印构造好的请求头： 

print(headers)

务必将代码中的 YOUR_API_KEY 和 YOUR_SECRET_KEY 替换为您从API提供商处获得的真实 API Key 和 Secret Key。 API Key通常是公开的，但Secret Key必须严格保密，切勿泄露。 建议将Secret Key存储在安全的环境变量或配置文件中，而不是直接硬编码在代码中。 强烈建议您阅读API提供商的官方文档，以了解正确的签名生成方法和请求头的具体要求，以确保您能够成功地通过身份验证并安全地使用API。

请求方式

Bigone API 遵循 RESTful 设计原则，支持以下标准的 HTTP 请求方法，以便与 API 进行交互：

  • GET : 此方法用于从服务器检索资源。GET 请求通常用于读取数据，且不应对服务器上的数据产生任何修改。在 Bigone API 中，您可以使用 GET 请求获取诸如市场行情、账户余额等信息。请求参数通常以查询字符串的形式附加在 URL 之后。
  • POST : POST 方法用于向服务器提交数据，通常用于创建新的资源。在 Bigone API 中，您可以使用 POST 请求来提交订单、创建提现请求等。请求数据通常包含在请求体中，并使用合适的 Content-Type（例如 `application/`）进行编码。
  • PUT : PUT 方法用于替换服务器上的现有资源。与 POST 方法不同，PUT 方法通常用于更新整个资源，而不是部分字段。如果资源不存在，某些 API 可能会创建它，但也有些会返回错误。请仔细阅读 Bigone API 文档以了解特定端点的行为。
  • DELETE : DELETE 方法用于删除服务器上的指定资源。使用 DELETE 请求时，请务必谨慎，因为删除操作通常是不可逆的。在 Bigone API 中，您可以使用 DELETE 请求取消订单等。

为了确保 API 请求的成功执行，您必须根据每个 API 接口的定义，精确地选择与之对应的请求方法。错误的方法可能会导致 API 返回错误代码或无法按预期执行操作。在发起 API 请求前，务必仔细查阅 Bigone API 的官方文档，明确指定端点所支持的 HTTP 方法，以及所需携带的参数和数据格式。

数据格式

Bigone API 采用 JSON (JavaScript Object Notation) 作为标准的数据交换格式。所有发送到 API 的请求以及 API 返回的响应，都必须是格式正确的 JSON 字符串。这意味着数据结构需要符合 JSON 的语法规则，例如键值对使用双引号包裹，以及正确使用数组和对象等。

在时间表示方面，Bigone API 统一使用 Unix 时间戳（Unix timestamp）的毫秒级表示。Unix 时间戳是从协调世界时（UTC）1970 年 1 月 1 日 0 时 0 分 0 秒起至现在的总毫秒数。这种格式保证了时间数据的精确性和跨平台兼容性，方便开发者进行时间计算和转换。例如， "1678886400000" 代表 2023年3月15日 00:00:00 (UTC) 。开发者在使用 API 时，应注意将其他时间格式转换为 Unix 毫秒级时间戳，并对 API 返回的时间戳进行相应处理。

API 调用示例

以下是一些常见的 API 调用示例，展示了如何在加密货币交易和数据获取中使用 API：

获取市场数据

通过 API 获取加密货币的实时市场数据是常见的需求。例如，可以获取指定交易对（如 BTC/USD）的最新价格、成交量、最高价和最低价。 

GET /api/v1/ticker/BTCUSDT

此 API 调用通常返回一个 JSON 对象，其中包含以下信息：

  • symbol : 交易对，例如 "BTCUSDT"
  • price : 最新成交价格
  • volume : 24 小时成交量
  • high : 24 小时最高价
  • low : 24 小时最低价
  • timestamp : 数据更新的时间戳

下单交易

使用 API 可以在交易所下单进行交易。这需要身份验证和授权，以确保交易安全。 

POST /api/v1/order
{
  "symbol": "ETHUSDT",
  "side": "BUY",
  "type": "MARKET",
  "quantity": 1.0
}

此 API 调用表示以市价购买 1.0 个 ETH，交易对为 ETH/USDT。请求头中通常包含 API 密钥和签名，用于验证身份。

  • symbol : 交易对
  • side : 交易方向（BUY 或 SELL）
  • type : 订单类型（MARKET, LIMIT, STOP_LOSS 等）
  • quantity : 交易数量

获取账户余额

通过 API 可以查询账户中的加密货币余额。这对于监控投资组合和自动化交易非常有用。 

GET /api/v1/account

此 API 调用通常返回一个 JSON 对象，其中包含各种加密货币的余额信息：

  • currency : 加密货币代码，例如 "BTC", "ETH", "USDT"
  • available : 可用余额
  • locked : 锁定余额 (用于挂单等)

获取历史交易数据

获取历史交易数据（例如，过去一段时间内的价格和成交量）对于分析市场趋势和开发交易策略至关重要。这些数据通常用于回测交易算法。 

GET /api/v1/klines/BTCUSDT?interval=1h&limit=24

这个 API 调用请求获取 BTC/USDT 交易对过去 24 小时的 K 线数据，时间间隔为 1 小时。

  • interval : K 线的时间间隔（例如，1m, 5m, 1h, 1d）
  • limit : 返回的数据点数量

订阅实时数据流 (WebSockets)

除了 REST API 之外，许多交易所还提供 WebSocket API，用于订阅实时市场数据。这可以实现低延迟的数据更新，适用于高频交易和实时监控。

连接到 WebSocket 端点后，可以订阅特定的频道，例如 BTC/USDT 的实时交易数据或深度数据。 

// WebSocket 连接示例 (JavaScript)
const ws = new WebSocket("wss://example.com/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({ "op": "subscribe", "channel": "trade", "symbol": "BTCUSDT" }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data); // 处理实时交易数据
};

以上示例展示了如何使用 JavaScript 连接到 WebSocket 端点并订阅 BTC/USDT 的实时交易数据。 onmessage 事件处理程序用于接收和处理实时数据。

1. 获取账户信息 (GET /api/v3/asset/accounts)

获取账户信息接口允许用户查询其在交易所中的资产概览。该接口采用 GET 方法，访问路径为 /api/v3/asset/accounts 。通过调用此接口，用户可以获得包括账户余额、可用余额、冻结余额等关键信息，以便进行资产管理和交易决策。

请求方式： GET

接口地址： /api/v3/asset/accounts

使用Python的 requests 库可以方便地调用该接口，以下是一个示例代码片段： 

import requests

url = "https://api.example.com/api/v3/asset/accounts" # 替换为实际的API地址
headers = {"X-API-KEY": "YOUR_API_KEY"} # 替换为你的API密钥
try:
    response = requests.get(url, headers=headers)
    response.raise_for_status() # 检查请求是否成功，如果状态码不是200，则抛出HTTPError
    data = response.()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"请求出错：{e}")

参数说明：

  • 此接口通常需要提供API密钥进行身份验证，具体参数和认证方式请参考交易所的API文档。
  • 一些交易所可能支持分页参数，例如 limit 和 offset ，用于控制返回数据的数量和起始位置。
  • 如果需要查询特定币种的账户信息，可能需要通过参数指定币种代码。

返回数据格式：

接口返回的数据通常为JSON格式，包含以下字段（具体字段可能因交易所而异）：

  • currency : 币种代码，例如 "BTC", "ETH"。
  • balance : 总余额，包括可用余额和冻结余额。
  • available : 可用余额，即可以用于交易的余额。
  • frozen : 冻结余额，即暂时无法使用的余额。
  • timestamp : 数据更新时间戳。

注意事项：

  • 请务必妥善保管您的API密钥，避免泄露。
  • 频繁调用API可能会受到频率限制，请合理控制请求频率。
  • 在进行交易决策前，请仔细核对账户信息，确保数据准确。
  • 请参考交易所的官方API文档，了解接口的最新信息和使用规则。

import requests

示例数据 (替换为您的实际值)

api_key = "YOUR_API_KEY"

secret_key = "YOUR_SECRET_KEY"

method = "GET"

path = "/api/v3/asset/accounts"

params = {} # 请求参数，根据 API 文档设置，此处为空字典表示无参数。

signature, timestamp = generate_signature(method, path, params, secret_key) # 调用签名生成函数，获取签名和时间戳。

headers = { "X-API-KEY": api_key, "X-API-TIMESTAMP": timestamp, "X-API-SIGNATURE": signature } # 构造请求头，包含 API 密钥、时间戳和签名，用于身份验证。

base_url = "https://big.one" # Bigone API 基本 URL，所有 API 请求都基于此 URL 构建。

url = base_url + path # 完整的 API 请求 URL，由基本 URL 和 API 路径组成。

try: response = requests.get(url, headers=headers, params=params) response.raise_for_status() # 检查 HTTP 状态码，如果状态码不是 200，则抛出异常。 

data = response.() # 解析JSON响应
print(data)

except requests.exceptions.RequestException as e: print(f"请求出错: {e}") # 捕获请求过程中可能发生的异常，例如网络错误、超时等，并打印错误信息。

2. 下单 (POST /api/v3/orders)

在加密货币交易中，下单是执行买入或卖出操作的关键步骤。通过POST请求发送至 /api/v3/orders 端点，你可以创建新的交易订单。此过程涉及构建包含必要参数的请求体，并使用API密钥进行身份验证。

下单接口允许你指定多种订单类型，例如限价单（Limit Order）和市价单（Market Order）。限价单允许你设定期望的交易价格，只有当市场价格达到或超过该价格时，订单才会被执行。市价单则会以当前市场最佳价格立即执行，确保快速成交。

除了订单类型，你还需要指定交易的币对（例如，BTC/USDT），以及买入或卖出的数量。合理设置这些参数对于成功执行交易至关重要。

为了确保安全性，所有API请求都需要进行签名验证。这通常涉及使用你的私钥对请求参数进行哈希处理，并将生成的签名包含在请求头中。服务端会使用你的公钥验证签名，从而确认请求的真实性和完整性。

以下是一个使用Python requests 库进行下单操作的示例代码片段，展示了如何构建并发送POST请求： 

import requests
import hashlib
import hmac
import time

# API密钥和密钥
api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"

# API端点
base_url = "https://api.example.com" # 替换为实际的API地址
endpoint = "/api/v3/orders"

# 请求参数
params = {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": 0.01,
    "price": 30000,
    "timestamp": int(time.time() * 1000)
}

# 创建签名
def create_signature(params, secret_key):
    query_string = '&'.join(["{}={}".format(k, v) for k, v in params.items()])
    signature = hmac.new(secret_key.encode('utf-8'), query_string.encode('utf-8'), hashlib.sha256).hexdigest()
    return signature

signature = create_signature(params, secret_key)
params["signature"] = signature

# 设置请求头
headers = {
    "X-MBX-APIKEY": api_key
}

# 发送POST请求
url = base_url + endpoint
response = requests.post(url, headers=headers, params=params)

# 打印响应
print(response.status_code)
print(response.())

代码详解:

  • api_key 和 secret_key : 替换成你自己的API Key和Secret Key，它们用于身份验证和签名。
  • base_url : 替换成交易所提供的API基础URL。
  • params : 包含了订单的所有必要参数。
    • symbol : 交易对，例如 "BTCUSDT"。
    • side : 交易方向，"BUY" (买入) 或 "SELL" (卖出)。
    • type : 订单类型，"LIMIT" (限价单), "MARKET" (市价单)等。
    • timeInForce : 订单的有效期，"GTC" (Good Till Cancelled) 表示直到被取消前有效。
    • quantity : 交易数量。
    • price : 限价单的价格。 如果是市价单，则不需要此参数。
    • timestamp : 当前时间戳（毫秒）。
  • create_signature 函数: 使用 Secret Key 和请求参数生成签名。签名用于验证请求的真实性。
  • X-MBX-APIKEY Header: 在请求头中包含 API Key。
  • requests.post : 发送 POST 请求到 API 端点。
  • response.status_code 和 response.() : 打印响应状态码和 JSON 数据，用于检查请求是否成功以及订单的状态。

请注意，以上代码仅为示例，你需要根据交易所的具体API文档进行调整。务必仔细阅读API文档，了解每个参数的含义和要求，以避免出现错误。

示例数据 (替换为您的实际值)

api_key = "YOUR_API_KEY"
这是你的API密钥，用于身份验证。务必妥善保管，切勿泄露给他人。API密钥是访问交易所API的凭证，泄露可能导致资产损失。一般由交易所提供，请在您的交易所账户管理页面查找。

secret_key = "YOUR_SECRET_KEY"
这是你的私钥，与API密钥配合使用，用于签名请求。私钥的安全性至关重要，强烈建议使用高强度密码并启用双重验证，并避免存储在不安全的地方。私钥同样由交易所提供，请务必备份。

method = "POST"
这是HTTP请求方法，指定为"POST"。在创建订单的场景下，通常使用POST方法向服务器提交数据。其他常用的HTTP方法包括GET、PUT、DELETE等，不同的API端点可能需要不同的请求方法。

path = "/api/v3/orders"
这是API端点的路径，指定为"/api/v3/orders"。该路径指示了服务器上处理订单请求的位置。不同的API功能对应不同的路径，例如获取账户信息的路径可能是"/api/v3/account"。需要参考交易所的API文档来确认正确的路径。

下单参数

在加密货币交易中，下单涉及指定交易的各种参数。以下是一个包含关键参数的示例，这些参数定义了买卖订单的细节，例如交易方向、交易对、订单类型、价格和数量。

params = { "side": "buy", # 指示交易方向。 "buy" 代表买入，而 "sell" 代表卖出。 "symbol": "BTC-USDT", # 指定交易的货币对，例如 "BTC-USDT" 表示比特币兑泰达币。 "type": "limit", # 定义订单类型。 "limit" 为限价单，允许指定价格； "market" 为市价单，以当前市场最优价格成交。 "price": "20000", # 设置订单的执行价格（仅当订单类型为限价单时需要）。例如，设置为 "20000" 表示以 20000 USDT 的价格买入或卖出。 "amount": "0.001" # 指定交易的数量。例如，设置为 "0.001" 表示买入或卖出 0.001 个比特币。 }

为了确保交易请求的安全性，通常需要生成签名。签名是通过对请求参数、API 密钥和密钥进行加密哈希处理得到的。时间戳用于防止重放攻击，保证请求的时效性。

signature, timestamp = generate_signature(method, path, params, secret_key)

HTTP 请求头包含了 API 密钥、时间戳和签名，用于身份验证和安全验证。 Content-Type 指定了请求体的格式。

headers = { "X-API-KEY": api_key, # 您的 API 密钥，用于身份验证。 "X-API-TIMESTAMP": timestamp, # 请求的时间戳，用于防止重放攻击。 "X-API-SIGNATURE": signature, # 请求的签名，通过对请求参数进行哈希处理得到，用于验证请求的完整性。 "Content-Type": "application/" # 指定请求体的格式为 JSON。 }

base_url = "https://big.one"

url = base_url + path

使用 requests 库发送 POST 请求。 response.raise_for_status() 用于检查 HTTP 响应状态码，如果状态码表示错误（例如 400 或 500），则会引发异常。

try: response = requests.post(url, headers=headers, data=.dumps(params)) response.raise_for_status() 

data = response.()
print(data)

异常处理用于捕获请求过程中可能出现的错误，例如网络连接问题或服务器错误，并打印错误信息。

except requests.exceptions.RequestException as e: print(f"请求出错: {e}")

3. 获取订单详情 ( GET /api/v3/orders/{id} )

本接口允许开发者通过订单ID检索特定订单的详细信息。您需要提供有效的订单ID才能成功获取订单数据。返回的数据包含了订单的所有相关字段，例如订单状态、创建时间、成交价格、数量等。请确保您的API密钥具有足够的权限来访问此接口。

请求方法： GET

请求URL： /api/v3/orders/{id} ，其中 {id} 需要替换为实际的订单ID。

请求参数：

  • id (路径参数，必选): 订单的唯一标识符。

请求示例 (Python): 

import requests

url = "https://api.example.com/api/v3/orders/12345" # 替换为实际的API endpoint 和 订单ID
headers = {
    "X-API-Key": "YOUR_API_KEY" # 替换为你的API key
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    order_details = response.()
    print(order_details)
else:
    print(f"请求失败，状态码：{response.status_code}")
    print(response.text)

响应示例 (成功 - HTTP 200): 

{
    "id": 12345,
    "symbol": "BTCUSDT",
    "orderId": 67890,
    "orderListId": -1,
    "clientOrderId": "myOrder123",
    "price": "30000.00",
    "origQty": "1.00",
    "executedQty": "1.00",
    "cummulativeQuoteQty": "30000.00",
    "status": "FILLED",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.00",
    "icebergQty": "0.00",
    "time": 1678886400000,
    "updateTime": 1678886400000,
    "isWorking": true,
    "origQuoteOrderQty": "0.00",
    "selfTradePreventionMode": "NONE"
}

响应示例 (失败 - HTTP 404): 

{
    "code": -2011,
    "msg": "订单不存在。"
}

错误代码：

  • -2011 : 订单不存在。请检查提供的订单ID是否正确。
  • 其他错误代码 : 参见 通用错误代码列表 。

import requests

示例数据 (请替换为您的真实 API 密钥、密钥、订单 ID 等信息)

api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
order_id = "YOUR_ORDER_ID" # 您需要查询的订单的唯一标识符
method = "GET" # HTTP 请求方法，此处为获取订单信息，使用 GET 方法
path = f"/api/v3/orders/{order_id}" # API 接口路径，用于获取指定 order_id 的订单信息
params = {} # 查询参数，此处为空，表示不需要额外的查询参数

signature, timestamp = generate_signature(method, path, params, secret_key) # 使用您的密钥生成签名和时间戳，用于身份验证

headers = { # HTTP 请求头
"X-API-KEY": api_key, # 您的 API 密钥
"X-API-TIMESTAMP": timestamp, # 当前时间戳，用于防止重放攻击
"X-API-SIGNATURE": signature # 使用密钥生成的签名
}

base_url = "https://big.one" # BigONE API 的基础 URL

url = base_url + path # 完整的 API 请求 URL，包含基础 URL 和接口路径

try: # 尝试发送请求并处理响应
response = requests.get(url, headers=headers, params=params) # 发送 GET 请求到指定的 URL，并附带请求头和查询参数
response.raise_for_status() # 检查响应状态码，如果不是 200 OK，则抛出 HTTPError 异常 

data = response.() # 将响应内容解析为 JSON 格式
print(data) # 打印解析后的 JSON 数据

except requests.exceptions.RequestException as e: # 捕获请求过程中可能发生的异常
print(f"请求出错: {e}") # 打印错误信息

上述代码是一个使用 Python requests 库访问 BigONE API 并获取订单信息的示例。请务必替换示例数据为您的真实值。 在使用此代码之前，请确保您已经安装了 requests 库 (可以使用 pip install requests 命令安装)。 generate_signature 函数需要您自行实现，该函数根据 BigONE API 的签名规则生成签名。 请仔细阅读 BigONE API 官方文档，了解关于 API 密钥、签名方法、API 接口以及错误处理的详细信息。 特别是签名生成部分，不同的交易所签名规则可能有所不同，务必严格按照官方文档进行操作，否则可能导致请求失败。 在实际生产环境中，请妥善保管您的 API 密钥和密钥，避免泄露。

错误处理

当与 Bigone API 的交互过程中出现问题时，服务器会返回一个包含详细错误信息的 JSON 格式响应。这种响应旨在帮助开发者诊断并解决遇到的问题，保证应用程序的稳定性和可靠性。错误信息主要包括两个关键字段：错误代码和错误描述，它们共同提供了问题的上下文。

错误代码是一个简短的、具有唯一性的标识符，用于快速识别错误的类型。例如，错误代码可能指示无效的参数、权限不足、请求频率过高等。开发者可以通过查阅 Bigone API 的官方文档，找到每个错误代码对应的具体含义，从而了解问题的根本原因。错误描述则提供了更详细的、人类可读的文本信息，进一步解释错误的具体情况。例如，错误描述可能会指出哪个参数无效，或者请求频率超过了限制。

为了确保应用程序的健壮性，开发者应当编写代码来捕获并处理这些错误响应。根据错误代码和错误描述，您可以采取不同的处理策略。例如，对于无效参数的错误，您可以重新检查并修正请求参数；对于权限不足的错误，您可以提示用户授权或检查 API 密钥是否正确配置；对于请求频率过高的错误，您可以实施速率限制策略，例如使用指数退避算法来降低请求频率。建议将错误信息记录到日志中，以便于后续的调试和分析。

API 速率限制

为保障系统稳定性和公平使用，Bigone API 针对每个 API 密钥实施速率限制。开发者可以通过检查 HTTP 响应头中的 X-RateLimit-Limit 和 X-RateLimit-Remaining 字段，实时监控当前的速率限制状态，以便优化请求策略。

  • X-RateLimit-Limit : 此参数标明了特定 API 密钥在设定的时间窗口内所允许发送的最大请求数量。该数值表示该时间段内的请求上限。
  • X-RateLimit-Remaining : 此参数指示在当前时间窗口内，API 密钥还能发送的剩余请求数量。当此数值接近零时，应避免继续发送请求，以免触发速率限制。

当请求量超过设定的速率限制时，API 将返回 HTTP 状态码 429 Too Many Requests ，表明请求被服务器暂时拒绝。为了恢复 API 访问，开发者需要等待至下一个时间窗口开始后，方可再次发送请求。建议实施指数退避算法，在每次收到 429 错误后，逐步增加等待时间，以避免短时间内再次触发速率限制，确保应用程序的稳定运行。

WebSocket API

除了传统的 REST API 之外，Bigone 还提供了 WebSocket API，旨在为用户提供实时的市场数据和账户信息流。WebSocket API 是一种持久化的双向通信协议，它允许客户端和服务器之间建立长连接，从而实现数据的即时推送，极大地提升了数据传输效率和实时性。

与 REST API 的请求-响应模式不同，WebSocket API 允许您接收实时的价格更新、订单簿更新、交易更新以及其他关键的市场活动信息，而无需频繁地轮询 API 端点。这意味着您能够更快地响应市场变化，优化交易策略，并获得更优质的交易体验。

通过订阅特定的频道，您可以根据自身需求定制接收的数据类型。例如，您可以订阅特定交易对的实时价格变动，或者监控您的账户余额和订单状态的实时更新。WebSocket API 采用高效的数据压缩和传输技术，确保数据传输的稳定性和速度，即使在高并发的市场环境下也能提供可靠的服务。

关于 Bigone WebSocket API 的详细信息，包括连接方式、订阅频道、数据格式和错误处理等内容，请务必参考 Bigone 官方文档。官方文档提供了全面的指南和示例代码，可以帮助您快速上手并充分利用 WebSocket API 的强大功能。

常见问题

  • 如何生成 API Key 和 Secret Key? 您可以在 Bigone 官网登录后，前往 "API 管理" 页面生成和管理您的 API 密钥。 API Key 用于标识您的身份，而 Secret Key 用于对您的请求进行签名，保证安全性。 请务必妥善保管您的 Secret Key，切勿泄露给他人。 建议您启用 IP 白名单功能，限制 API Key 的使用 IP，进一步增强安全性。
  • 我的 API 请求一直返回 401 Unauthorized 错误? 请仔细检查您的 API Key 和 Secret Key 是否正确，复制时是否存在空格或其他不可见字符。 请确保您的请求签名算法与 Bigone 官方文档一致。 401 Unauthorized 错误通常表示服务器无法验证您的身份，常见原因是 API Key 或 Secret Key 错误，或者请求签名不正确。 重新生成 API Key 和 Secret Key，并严格按照文档说明进行签名计算，可以有效解决此问题。
  • 我的 API 请求超过了 rate limit? 请查看 HTTP Header 中的 X-RateLimit-Limit 和 X-RateLimit-Remaining 字段，了解当前的 rate limit 状态。 X-RateLimit-Limit 表示在特定时间内允许的最大请求数量， X-RateLimit-Remaining 表示剩余的可用请求数量。 如果 X-RateLimit-Remaining 为 0，则表示您已达到 rate limit，需要等待一段时间后才能再次发送请求。 不同的 API 接口可能有不同的 rate limit 限制，请参考 Bigone 官方 API 文档。 建议您优化您的请求逻辑，减少不必要的请求，并使用缓存机制，避免频繁请求相同的数据。
  • 我应该如何处理 API 错误? 请仔细阅读 API 返回的错误代码和错误描述，它们通常会提供关于错误的详细信息。 Bigone 官方 API 文档通常会提供错误代码的解释和建议的处理方法。 常见的错误类型包括：参数错误、签名错误、余额不足、交易失败等。 根据不同的错误类型，您需要采取相应的处理措施，例如：检查请求参数是否正确、重新计算签名、充值账户余额、重试交易等。 对于一些复杂的错误，您可以联系 Bigone 客服寻求帮助。

安全注意事项

  • 妥善保管您的 Secret Key： Secret Key 是访问您账户的最高权限密钥，务必将其视为最高机密信息。切勿以任何方式泄露给任何第三方，包括声称是交易所工作人员的人员。如果您的 Secret Key 泄露，攻击者可以完全控制您的账户并转移资金。请务必将其存储在离线、加密且安全的环境中。
  • 安全存储 API Key 和 Secret Key： 不要将 API Key 和 Secret Key 存储在不安全的位置，例如：
    • 版本控制系统（如 Git）中的未加密文件中，避免无意中将其推送到公共代码库。
    • 公共代码库，例如 GitHub、GitLab 等，确保密钥不会被公开。
    • 明文配置文件，确保配置文件被正确加密或者进行权限限制。
    • 客户端代码中（例如 JavaScript），避免在浏览器端暴露您的密钥。
    推荐使用专门的密钥管理工具或环境变量来安全存储您的 API Key 和 Secret Key。
  • 使用 HTTPS 协议： 始终使用 HTTPS（安全超文本传输协议）进行 API 请求。 HTTPS 使用 SSL/TLS 加密您的数据传输，防止中间人攻击，确保您的 API Key、Secret Key 和其他敏感数据在传输过程中不被窃取。 确保您的 API 调用 URL 以 `https://` 开头。
  • API 请求签名： 对您的 API 请求进行签名，以验证请求的来源，防止未经授权的访问。签名过程通常涉及使用您的 Secret Key 对请求参数进行哈希运算，并将签名包含在请求头或请求参数中。交易所或服务提供商会使用您的 Public Key 验证签名的有效性。具体签名方法请参考对应API的文档。
  • 定期轮换 API Key 和 Secret Key： 定期更换您的 API Key 和 Secret Key，以降低密钥泄露后造成的损失。密钥轮换的频率取决于您的安全策略和风险承受能力。 建议至少每 90 天轮换一次密钥，或者在发现任何可疑活动时立即轮换密钥。 密钥轮换过程包括生成新的密钥对，更新您的应用程序配置，并停用旧的密钥对。
  • 监控 API 使用情况： 密切监控您的 API 使用情况，例如请求频率、请求量、错误率等。 及时发现和处理异常情况，例如：
    • 未知的 IP 地址或地理位置发起的请求。
    • 异常高的请求频率或请求量。
    • 未经授权的 API 端点访问。
    • 大量的错误请求。
    设置警报系统，以便在检测到异常活动时及时收到通知。分析 API 使用日志，了解潜在的安全风险。

相关推荐：