本教程将指导你如何使用 BitMart 的 API 进行交易。我们将涵盖 API 密钥的创建、身份验证、交易请求的构建、以及常用 API 接口的使用。
在使用 BitMart API 之前，获取并妥善管理 API 密钥至关重要。API 密钥是访问 BitMart 交易平台数据和执行交易指令的凭证。这些密钥通常分为两部分：API Key (公钥) 和 Secret Key (私钥)。
API Key (公钥) ：此密钥用于唯一标识你的身份。每当你通过 API 发送请求时，公钥都会包含在请求头中，以便 BitMart 服务器识别你的身份并验证你的权限。
Secret Key (私钥) ：这是至关重要的安全密钥，用于对你的 API 请求进行数字签名。签名过程通过特定的加密算法（例如 HMAC-SHA256）生成一个唯一的哈希值，该哈希值附加到你的请求中。BitMart 服务器使用你的公钥和私钥来验证签名的有效性，从而确保请求的完整性和真实性，防止中间人攻击和数据篡改。务必妥善保管私钥， 切勿 与任何人分享，并且不要将其存储在不安全的地方，比如代码库或公共服务器上。若私钥泄露，攻击者可以伪造你的身份执行交易，导致资金损失。
密钥创建与管理最佳实践：
BitMart API 采用 HMAC-SHA256 算法对请求进行身份验证，确保交易安全可靠。所有 API 请求都需要经过签名，以验证请求的来源和完整性。以下是签名过程的详细步骤：
&
符号连接各个参数。参数名和参数值之间使用
=
符号连接。需要注意的是，URL 编码后的参数也应该参与签名。例如：
symbol=BTC_USDT&side=buy&type=limit&price=10000&size=0.01
如果请求包含数组类型的参数，则需要将数组展开并按照键值对的形式进行排序和连接。GET 请求的参数直接包含在 URL 中，而 POST 请求的参数则包含在请求体中，都需要参与签名计算。
X-BM-KEY
: 你的 API Key。API Key 用于标识你的账户，可以从 BitMart 账户管理页面获取。
X-BM-SIGN
: 计算得到的签名。签名是使用 Secret Key 对请求字符串进行 HMAC-SHA256 加密后的结果，用于验证请求的完整性和真实性。
X-BM-TIMESTAMP
: 当前 UTC 时间戳 (毫秒级别)。时间戳用于防止重放攻击，确保请求的时效性。请确保你的服务器时间与 UTC 时间同步。
请注意，所有的 Header 字段名必须完全匹配，包括大小写。如果缺少任何一个 Header，或者 Header 字段的值不正确，都将导致请求失败。
正确设置 HTTP Headers 示例：
X-BM-KEY: YOUR_API_KEY
X-BM-SIGN: CALCULATED_SIGNATURE
X-BM-TIMESTAMP: 1678886400000
该示例演示了如何使用 Python 与 BitMart 交易所的 API 进行交互。它包括生成签名、发送请求以及处理响应的基本步骤。请确保已安装
requests
库:
pip install requests
。
import hmac
import hashlib
import time
import urllib.parse
import requests
这些是必要的 Python 库。
hmac
和
hashlib
用于生成安全签名，
time
用于获取时间戳，
urllib.parse
用于编码 URL 参数，
requests
用于发送 HTTP 请求。
api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
base_url = "https://api.bitmart.com" # BitMart API 基础 URL
请务必将
YOUR_API_KEY
和
YOUR_SECRET_KEY
替换为您在 BitMart 交易所获得的实际 API 密钥和密钥。
base_url
定义了 BitMart API 的基础 URL。注意：API密钥和密钥需要从BitMart官方网站获取，请勿泄露。
def generate_signature(params, secret_key):
"""生成 HMAC-SHA256 签名"""
encoded_params = urllib.parse.urlencode(sorted(params.items()))
signature = hmac.new(secret_key.encode('utf-8'), encoded_params.encode('utf-8'), hashlib.sha256).hexdigest()
return signature
generate_signature
函数用于生成 API 请求的 HMAC-SHA256 签名。它接受请求参数和密钥作为输入，并返回十六进制格式的签名。参数首先按字母顺序排序，然后进行 URL 编码。然后，使用密钥和编码后的参数计算 HMAC-SHA256 哈希值。
def send_request(method, endpoint, params=None, data=None):
"""发送 API 请求"""
timestamp = str(int(time.time() * 1000))
url = base_url + endpoint
send_request
函数负责发送 API 请求。它接受 HTTP 方法（GET、POST、DELETE 等）、API 端点以及可选的参数和数据作为输入。函数首先生成时间戳，并将其添加到请求头中。
headers = {
"X-BM-KEY": api_key,
"X-BM-TIMESTAMP": timestamp,
"Content-Type": "application/" # 显式设置 Content-Type
}
if params:
signature_params = params.copy()
signature = generate_signature(signature_params, secret_key)
headers["X-BM-SIGN"] = signature
elif data:
signature_params = data.copy()
signature = generate_signature(signature_params, secret_key)
headers["X-BM-SIGN"] = signature
else:
signature_params = {}
signature = generate_signature(signature_params, secret_key)
headers["X-BM-SIGN"] = signature
if method.upper() == "GET":
response = requests.get(url, headers=headers, params=params)
elif method.upper() == "POST":
response = requests.post(url, headers=headers, =data) # 使用 =data 正确发送 JSON 数据
elif method.upper() == "DELETE":
response = requests.delete(url, headers=headers, params=params)
else:
raise ValueError("Invalid HTTP method")
response.raise_for_status() # 检查 HTTP 状态码
return response.()
根据请求类型 (GET, POST, DELETE)， 使用
requests
库发送相应的 HTTP 请求。对于 POST 请求，将数据作为 JSON 格式发送。如果状态码不是 200，则
response.raise_for_status()
会引发异常。将响应作为 JSON 对象返回。
本示例演示如何通过API接口获取账户的详细信息，包括账户余额、可用资金、冻结资金等。该操作对于监控账户状态、进行风险评估和自动化交易策略至关重要。
endpoint = "/spot/v1/account"
上述代码定义了API端点，指向用于获取账户信息的特定URL。
/spot/v1/account
通常表示现货交易账户的V1版本API接口。 实际端点可能会因交易所而异，请务必查阅交易所的官方API文档。
account_info = send_request("GET", endpoint)
这行代码调用名为
send_request
的函数，该函数负责向指定的API端点发送HTTP请求。
"GET"
方法表示这是一个获取数据的请求。 函数接收API端点作为参数，并返回包含账户信息的响应数据。
send_request
函数的具体实现会涉及身份验证、请求签名和错误处理等步骤，这部分逻辑通常封装在自定义的函数中，以简化代码。
print(account_info)
这行代码将从API端点获取的账户信息打印到控制台。 账户信息通常以JSON格式返回，包含诸如可用余额、已用余额、挂单数量等详细数据。 请注意，为了安全起见，实际生产环境中应避免直接打印敏感信息，例如API密钥或私钥。建议对返回的数据进行适当的解析和格式化，以便于阅读和分析。
要提交现货交易订单，您需要构建并发送一个POST请求到指定的API端点。以下是一个示例，展示如何使用
/spot/v1/submit_order
端点创建一个限价买单。
endpoint = "/spot/v1/submit_order"
此变量定义了API的终点URL，订单将发送到此URL。 确保URL的正确性，任何错误都将导致订单提交失败。
params = {
"symbol": "BTC_USDT",
"side": "buy",
"type": "limit",
"price": "10000",
"size": "0.01"
}
params
字典包含了订单的所有必要参数：
symbol
: 交易对，例如 "BTC_USDT"，表示比特币兑美元泰达币。 请确保交易对的有效性和正确性。
side
: 订单方向，"buy" 表示买入， "sell" 表示卖出。
type
: 订单类型，"limit" 表示限价单，"market" 表示市价单。 限价单允许您指定购买或出售资产的价格。
price
: 限价单的价格，例如 "10000"，表示您希望以10000 USDT的价格购买比特币。价格必须是有效且合理的，否则订单可能无法成交。
size
: 订单数量，例如 "0.01"，表示您希望购买0.01个比特币。数量必须满足交易所的最小交易量要求。
order_info = send_request("POST", endpoint, data=params) # 注意这里使用 data 参数，发送 JSON 数据
send_request
函数负责将订单参数以JSON格式发送到API端点。 重要的是要使用
data
参数，而不是
params
参数，以确保数据正确地以JSON格式发送。 许多API要求数据以JSON格式进行发送，尤其是在创建或修改资源时。
print(order_info)
此命令将打印API响应，其中包含有关订单的信息，例如订单ID，订单状态和任何错误消息。 仔细检查响应以确保订单已成功提交。 如果出现错误，请查看错误消息以确定问题并进行更正。
generate_signature
函数至关重要，它使用您的私钥对请求参数进行哈希处理，生成符合交易所安全要求的签名。该签名用于验证请求的合法性，防止恶意篡改，确保交易安全。它通常会结合请求方法（如GET、POST）、请求路径、时间戳以及其他必要参数，通过特定的哈希算法（如HMAC-SHA256）生成一个唯一的签名字符串。正确实现签名机制是与交易所API交互的先决条件。
send_request
函数是对HTTP请求的封装，它负责将构造好的API请求发送到交易所服务器，并处理服务器返回的响应。除了发送请求，该函数还负责添加必要的HTTP头部信息，例如
Content-Type
、
API-Key
以及由
generate_signature
函数生成的签名。它还应处理各种网络异常和HTTP错误码，并对响应数据进行解析，以便后续程序使用。为了增强代码的健壮性，该函数应该包含重试机制，以便在网络不稳定的情况下自动重试请求。
generate_signature
和
send_request
函数，以及处理API返回的结果。
以下是一些常用的 BitMart 现货交易 API 接口，用于管理您的交易活动和获取市场数据：
/spot/v1/account
(GET)
此接口用于检索您的 BitMart 账户余额、可用资金和已冻结资金等信息。它不需要任何请求参数。
/spot/v1/submit_order
(POST)
此接口用于创建新的交易订单。务必仔细检查所有参数，以确保订单符合您的交易策略。
symbol
: 交易对，指定要交易的两种加密货币。例如，
BTC_USDT
表示比特币兑泰达币的交易对。确保交易对的格式正确。
side
: 交易方向，指示您是买入还是卖出指定的加密货币。
buy
表示买入，
sell
表示卖出。
type
: 订单类型，定义订单的执行方式。
limit
表示限价单，以指定价格执行；
market
表示市价单，以当前市场最优价格立即执行。
price
: 价格 (仅限价单)。指定您愿意买入或卖出的价格。只有当市场价格达到或超过此价格时，限价单才会被执行。
size
: 数量，指定您要买入或卖出的加密货币的数量。
client_order_id
: (可选) 客户端自定义订单ID，用于追踪订单。
/spot/v1/cancel_order
(POST)
此接口用于取消尚未成交的订单。请注意，一旦订单完全成交，将无法取消。
symbol
: 交易对，与要取消的订单相关联的交易对。
order_id
: 订单 ID，要取消的订单的唯一标识符。您可以通过“获取订单详情”或“获取历史订单”接口获取订单 ID。
/spot/v1/order_detail
(GET)
此接口用于检索特定订单的详细信息，包括订单状态、成交价格、成交数量等。
order_id
: 订单 ID，要查询的订单的唯一标识符。
/spot/v1/history_orders
(GET)
此接口用于检索指定交易对的历史订单记录。您可以根据时间范围和其他参数进行过滤。
symbol
: 交易对，要查询历史订单的交易对。
start_time
: 开始时间 (UTC 毫秒时间戳)，指定要检索的历史订单的起始时间。
end_time
: 结束时间 (UTC 毫秒时间戳)，指定要检索的历史订单的结束时间。
offset
: 偏移量，用于分页查询，指定从哪个位置开始返回订单记录。
limit
: 数量限制，指定每次返回的订单记录的最大数量。默认值和最大值可能有限制，请参考 BitMart API 文档。
/spot/v1/ticker
(GET)
此接口用于检索指定交易对的最新市场行情数据，包括最新成交价、最高价、最低价、成交量等。
symbol
: 交易对，要查询市场行情的交易对。
在使用 BitMart API 进行交易和数据查询时，可能会遇到各种类型的错误。BitMart API 遵循 RESTful 架构，并通过 HTTP 状态码和 JSON 格式的响应体来指示错误。理解并正确处理这些错误信息对于构建健壮的应用程序至关重要。
当 API 调用失败时，BitMart API 会返回一个包含错误代码和错误信息的 JSON 响应。开发者应检查 HTTP 状态码以及响应体中的
code
和
message
字段，以便确定错误的具体原因并采取相应的措施。错误代码通常是数字字符串，错误信息是描述性文本，有助于诊断问题。
常见的错误类型包括：
400 Bad Request
: 此错误表示客户端发送的请求存在问题。这通常是由于请求参数不正确、缺少必需参数、参数格式错误或者参数值超出范围造成的。仔细检查 API 文档，确认所有必需参数都已提供，并且参数值符合预期的格式和范围。例如，检查时间戳是否有效，交易数量是否符合最小交易量限制，以及价格是否在合理范围内。
401 Unauthorized
: 此错误表明客户端未经过身份验证或授权。通常是由于 API 密钥无效、API 密钥权限不足、或签名错误造成的。确保 API 密钥已正确配置，并且具有执行所需操作的权限。检查请求的签名是否正确生成，包括使用的哈希算法、时间戳和密钥。注意 API 密钥可能需要启用特定的权限（例如，交易权限、提现权限等）。
429 Too Many Requests
: 此错误表示客户端在短时间内发送了过多的请求，超过了 API 的速率限制。BitMart API 为了防止滥用和维护系统稳定性，对每个 API 密钥的请求频率都有限制。当收到此错误时，应暂停发送请求，并在一段时间后重试。建议实施指数退避策略，即每次重试之间的时间间隔逐渐增加。查看 API 文档了解具体的速率限制规则，并根据需要调整请求频率。可以使用缓存机制来减少对 API 的不必要调用。
500 Internal Server Error
: 此错误表示服务器遇到了意外错误，无法完成请求。这通常是 BitMart 服务器端的问题，客户端无法直接解决。当遇到此错误时，可以稍后重试请求。如果问题持续存在，请联系 BitMart 技术支持，提供详细的请求信息，以便他们调查和解决问题。
403 Forbidden
: 此错误表示服务器拒绝了客户端的请求。这可能是由于多种原因造成的，例如，客户端 IP 地址被阻止，或者客户端尝试访问其没有权限访问的资源。
503 Service Unavailable
: 此错误表示服务器暂时无法处理请求。这可能是由于服务器过载或正在进行维护造成的。稍后重试请求。
429 Too Many Requests 错误，你需要降低你的请求频率。遵循这些安全最佳实践至关重要，可以最大程度地降低与 BitMart API 交易相关的风险。请务必仔细阅读 BitMart 官方 API 文档，深入理解所有安全策略，并根据你的需求和安全要求进行开发和配置。持续关注 BitMart 的安全更新和公告，及时调整你的安全措施。祝你交易顺利！
