BitMart API 交易指南：手把手教你玩转自动化交易！

2025-03-06 分析 23℃

BitMart API 交易教程

介绍

BitMart 是一家全球领先的数字资产交易平台，致力于为全球用户提供安全、便捷的加密货币交易服务。平台支持包括比特币（Bitcoin）、以太坊（Ethereum）等主流加密货币以及新兴的区块链项目代币的交易。BitMart 提供的交易服务范围广泛，包括现货交易、杠杆交易、合约交易等，满足不同投资者的需求。

API（应用程序编程接口）是 BitMart 平台对外开放的数据接口，允许开发者通过编程方式与 BitMart 系统进行交互。通过 BitMart API，开发者可以获取实时市场数据、执行交易指令、管理账户信息，以及进行更高级的量化交易策略开发。API 的使用极大地方便了自动化交易和数据分析，降低了交易成本，提高了交易效率。

本教程旨在引导读者快速上手 BitMart API 交易。教程将详细介绍如何配置 API 密钥、使用 API 接口进行现货交易、以及处理常见的 API 调用问题。即使您是 API 开发的初学者，也能通过本教程了解 BitMart API 的基本原理和操作方法，为后续的深入学习和应用打下坚实的基础。

准备工作

在使用 BitMart API 之前，为了确保顺利对接和保障账户安全，您需要完成以下准备工作：

BitMart 账户: 如果您尚未拥有 BitMart 账户，请访问 BitMart 官方网站（例如：www.bitmart.com）进行注册。注册时，请务必仔细阅读并同意相关服务条款和隐私政策。
API 密钥: 成功登录您的 BitMart 账户后，导航至账户中心的“API 管理”或类似名称的页面。在此页面，您可以创建新的 API 密钥对。创建 API 密钥时，务必精确设置所需的权限范围，例如：现货交易、合约交易、读取账户余额、获取历史订单等。请根据您的应用场景，仅授予必要的权限，避免不必要的安全风险。强烈建议启用 IP 地址限制功能，只允许特定的 IP 地址或 IP 地址段访问您的 API 密钥，从而有效防止未经授权的访问。创建完成后，系统会生成 API Key（公钥）和 Secret Key（私钥）。请务必安全保存这两个密钥。Secret Key 只会显示一次，请立即备份。API Key 用于标识您的身份，Secret Key 用于签名您的 API 请求。请像保管银行密码一样妥善保管您的密钥信息，切勿以任何方式泄露给他人，包括但不限于通过电子邮件、聊天工具或代码仓库等渠道。如果密钥泄露，请立即禁用并重新生成新的密钥对。
开发环境: 选择您最熟悉且擅长的编程语言以及相应的开发环境。主流的编程语言如 Python、Java、Node.js、C# 等都支持与 BitMart API 进行交互。对于 Python，常用的库包括 `requests` 和 `ccxt`；对于 Java，可以使用 Apache HttpClient 或 OkHttp；对于 Node.js，可以使用 `node-fetch` 或 `axios`。根据您的语言选择，安装相应的 HTTP 请求库以及 JSON 解析库。建议使用集成开发环境（IDE）或文本编辑器来编写和调试代码，例如 PyCharm、IntelliJ IDEA、VS Code 等。确保您的开发环境已正确配置，并能够连接到互联网。

API 密钥安全须知

切勿在公共代码仓库中存储 API 密钥 ：诸如 GitHub 等公共代码仓库是恶意行为者的首选目标。将 API 密钥直接嵌入到代码中并提交到这些平台，会使其暴露于公众视野，极易被滥用。建议使用环境变量、配置文件或密钥管理服务等安全方式存储和管理 API 密钥。
定期轮换 API 密钥 ：即使采取了最佳安全措施，API 密钥仍有可能泄露。为了降低潜在风险，应定期更换 API 密钥。密钥轮换的频率取决于安全需求和风险承受能力。实施自动化密钥轮换策略，可以进一步简化流程并减少人为错误。
实施 IP 地址限制 ：通过配置 IP 地址限制，可以限制只有来自特定 IP 地址的请求才能使用 API 密钥。这可以有效防止未经授权的访问，即使 API 密钥泄露，也只有来自授权 IP 地址的请求才会被接受。务必仔细维护允许的 IP 地址列表，并定期审查其准确性。
严密监控 API 交易活动 ：持续监控 API 的使用情况至关重要。密切关注交易量、请求来源以及任何异常活动。设置警报，以便在检测到可疑行为时立即收到通知。分析 API 日志可以帮助识别潜在的安全漏洞和未经授权的访问尝试。

API 文档查阅

BitMart 提供了全面的 API 文档，这是进行高效交易和数据分析的关键资源。您可以参考其官方文档，深入了解 API 的具体接口、参数类型、返回值结构、以及错误代码等详细信息。文档不仅涵盖了REST API，还可能包含WebSocket API，以便实时数据流的访问。

API 文档通常包含了各种编程语言（例如Python、Java、JavaScript）的示例代码，这些代码片段可以帮助您快速上手，并了解如何使用不同的编程语言与BitMart API进行交互。示例代码通常会涵盖身份验证、下单、查询账户余额、以及历史数据检索等常见操作。

务必仔细阅读API文档中的速率限制（Rate Limits）部分，以避免因超出限制而被阻止访问。同时，关注API版本的更新说明，以确保您的应用程序与最新的API保持兼容。 BitMart可能会定期更新其API，以改进功能或修复漏洞。

现货交易 API

以下是 BitMart 现货交易 API 的一些常用接口，这些接口允许开发者和交易者自动化交易策略、获取市场数据并管理账户：

获取服务器时间 (GET /system/time): 用于同步客户端应用程序与 BitMart 服务器的时间，这是确保所有 API 请求的有效性和避免时间戳相关错误的关键步骤。服务器返回的时间戳可以用于校准本地时钟或作为后续请求的一部分。
获取交易对信息 (GET /spot/v1/symbols): 获取 BitMart 平台支持的所有现货交易对的详细信息。此接口返回的数据包括交易对名称 (例如：BTC_USDT)、交易对描述、最小交易数量 (允许交易的最小单位)、价格精度 (价格的小数位数)、交易手续费率等重要信息，方便用户了解交易规则和参数。
获取深度数据 (GET /spot/v1/level2/depth): 查询指定交易对的实时深度数据，也称为订单簿数据。深度数据包含了指定交易对当前市场上买单和卖单的价格和数量分布情况，通常按价格排序。此接口返回的数据对高频交易、算法交易和市场深度分析至关重要。通过分析深度数据，用户可以评估市场流动性、预测价格变动趋势，并制定相应的交易策略。还可以指定返回的深度档位数量。
获取最近成交 (GET /spot/v1/trades): 获取指定交易对的最近成交记录。此接口返回的信息包括成交时间、成交价格、成交数量以及买卖方向。通过分析最近成交记录，用户可以了解市场的实时交易活动、判断当前的市场情绪，并辅助决策。
获取账户信息 (GET /spot/v1/wallet): 查询您的现货账户信息，包括各种加密货币的可用余额、冻结余额 (例如：委托挂单占用的资金)。可用余额是指您可以立即用于交易的资金，而冻结余额是指已经被用于挂单但尚未成交的资金。通过此接口，用户可以随时掌握账户资金情况，方便进行资金管理和风险控制。
下单 (POST /spot/v1/orders): 创建现货交易订单。BitMart 支持多种订单类型，包括市价单 (以当前市场最优价格立即成交)、限价单 (以指定价格挂单等待成交)、止损单等。下单时，需要指定交易对 (例如：BTC_USDT)、订单类型、买卖方向 (买入或卖出)、数量以及价格 (仅限价单需要指定)。下单前，请务必确认账户余额充足，并仔细核对订单参数，避免因参数错误导致交易失败。
取消订单 (DELETE /spot/v1/orders): 取消指定的现货交易订单。用户需要提供要取消订单的订单 ID。只有尚未完全成交的订单才能被取消。取消订单后，相应的冻结资金将会返还到您的可用余额中。
获取订单详情 (GET /spot/v1/orders): 获取指定订单的详细信息。此接口返回的数据包括订单 ID、订单状态 (例如：待成交、部分成交、已完全成交、已取消)、订单类型、交易对、买卖方向、下单时间、成交数量、成交价格、手续费等信息。通过此接口，用户可以随时跟踪订单状态，了解订单执行情况。
获取历史订单 (GET /spot/v1/history_orders): 获取您的历史订单记录。此接口允许用户查询指定时间范围内的所有已完成的交易订单。返回的信息与获取订单详情接口类似，但包含了更长时间范围的历史数据，方便用户进行交易记录查询、盈亏分析和税务申报。可以根据时间范围、交易对等条件进行筛选。

Python 示例代码 (现货下单)

以下是使用 Python 实现的现货下单示例代码，它演示了如何通过交易所的API进行现货交易。

import requests

import hashlib

import hmac

import time

import

这段代码通常包括以下几个关键步骤：

导入必要的库： requests 用于发送 HTTP 请求， hashlib 和 hmac 用于生成安全签名， time 用于处理时间戳，用于处理 JSON 格式的数据。
配置 API 密钥： 访问交易所 API 需要 API 密钥和密钥，这些密钥需要安全存储，并在每次请求中用于身份验证。
构建请求参数： 定义下单所需的参数，例如交易对（例如 BTC/USDT）、订单类型（市价单或限价单）、买卖方向（买入或卖出）、数量和价格（如果为限价单）。
生成签名： 使用密钥和请求参数生成签名。签名是防止请求被篡改的重要安全措施。通常使用 HMAC-SHA256 算法。
发送 HTTP 请求： 使用 requests 库向交易所 API 端点发送 POST 请求，并在请求头中包含 API 密钥和签名。
处理响应： 解析交易所返回的 JSON 响应，检查订单是否成功提交。如果订单失败，则需要根据错误代码进行适当的处理。

示例代码片段（补充）：


# 假设的 API 密钥和密钥 (请勿在实际生产环境中使用硬编码)
api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
base_url = "https://api.example.com" # 替换为实际交易所API地址

def create_order(symbol, side, type, quantity, price=None):
    """
    创建现货订单
    :param symbol: 交易对 (例如 'BTCUSDT')
    :param side:  'BUY' 或 'SELL'
    :param type:  'MARKET' 或 'LIMIT'
    :param quantity: 数量
    :param price: 价格 (仅限价单需要)
    :return: 订单响应
    """
    endpoint = "/api/v1/order"
    timestamp = int(time.time() * 1000) # 毫秒级时间戳

    params = {
        "symbol": symbol,
        "side": side,
        "type": type,
        "quantity": quantity,
        "timestamp": timestamp
    }

    if type == "LIMIT":
        params["price"] = price

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

    headers = {
        "X-MBX-APIKEY": api_key
    }

    params["signature"] = signature

    url = base_url + endpoint

    try:
        response = requests.post(url, headers=headers, params=params)
        response.raise_for_status()  # 检查 HTTP 状态码
        return response.()
    except requests.exceptions.RequestException as e:
        print(f"请求错误: {e}")
        return None

# 示例调用
if __name__ == '__main__':
    order_response = create_order(
        symbol="BTCUSDT",
        side="BUY",
        type="MARKET",
        quantity=0.01  # 例如，买入 0.01 BTC
    )

    if order_response:
        print("订单响应:", order_response)
    else:
        print("订单创建失败")

重要提示：

请务必仔细阅读并理解交易所的 API 文档。
在生产环境中使用前，请在测试环境中进行充分的测试。
妥善保管您的 API 密钥和密钥，避免泄露。
根据交易所的 API 使用条款，合理控制请求频率，避免触发速率限制。
处理 API 响应时，需要考虑各种错误情况，并进行相应的处理。

API 密钥

API 密钥和密钥对是访问加密货币交易所或相关服务API的凭证，务必妥善保管，防止泄露。

api_key = "YOUR_API_KEY"

secret_key = "YOUR_SECRET_KEY"

API 密钥（ api_key ）类似于你的用户名，用于标识你的身份。密钥（ secret_key ）则类似于密码，用于验证你的身份并授权你执行特定的操作，两者通常成对使用。

请务必使用你自己的 API 密钥和密钥，替换掉示例中的 "YOUR_API_KEY" 和 "YOUR_SECRET_KEY" 。通常可以在你所使用的加密货币交易所的账户设置或 API 管理页面找到它们。

重要提示： 切勿将你的 secret_key 泄露给任何人，也不要将其存储在不安全的地方，例如公共代码仓库或客户端应用程序中。泄露密钥可能导致你的账户被盗用，造成资金损失。

推荐使用环境变量或专门的密钥管理工具来安全存储和访问你的 API 密钥和密钥。

API 接口

base_url = "https://api-cloud.bitmart.com" 是 BitMart API 的基础 URL，所有 API 请求都将基于此 URL 构建。请确保使用 HTTPS 协议以保证数据传输的安全性。

generate_signature(url, req_body, timestamp) 函数用于生成 API 请求的签名。签名是验证请求身份和确保数据完整性的关键步骤。它使用 HMAC-SHA256 算法，结合 API 密钥、请求 URL、时间戳和请求体来生成唯一的签名字符串。

以下是签名生成过程的详细说明：

将请求 URL、时间戳和请求体字符串拼接成一个消息字符串，格式为 url + '&' + timestamp + '&' + req_body 。
将消息字符串和 API 密钥分别编码为 UTF-8 格式的字节串。
使用 HMAC-SHA256 算法对消息字符串进行哈希，并将 API 密钥作为密钥。
将哈希结果转换为十六进制字符串，即为请求签名。

place_order(symbol, side, type, size, price="") 函数用于在 BitMart 交易所下订单。它接受交易对代码 ( symbol )、交易方向 ( side ，买入或卖出)、订单类型 ( type ，市价单或限价单)、订单数量 ( size ) 和价格 ( price ，仅限价单需要) 作为参数。

下单流程如下：

定义 API 接口的端点： endpoint = "/spot/v1/orders" 。
构建完整的 API 请求 URL： url = base_url + endpoint 。
获取当前时间戳，以毫秒为单位： timestamp = str(int(time.time() * 1000)) 。时间戳必须是整数类型的字符串。
构建请求体 ( req_body )，它是一个包含订单信息的字典。
如果订单类型为限价单 ( type == "limit" )，则将价格 ( price ) 添加到请求体中。
将请求体字典转换为 JSON 字符串： req_body_str = .dumps(req_body, separators=(',', ':')) 。 separators=(',', ':') 参数确保 JSON 字符串的格式符合 BitMart API 的要求，移除空格以保证签名的正确性。
调用 generate_signature() 函数生成请求签名。
构建 HTTP 请求头 ( headers )，它包含 API 密钥 ( X-BM-KEY )、请求签名 ( X-BM-SIGN )、时间戳 ( X-BM-TIMESTAMP ) 和内容类型 ( Content-Type )。
使用 requests.post() 函数发送 POST 请求到 API 接口。
检查 HTTP 响应状态码。如果状态码表示请求成功 (例如 200)，则解析响应内容并返回。如果发生错误，则捕获 requests.exceptions.RequestException 异常并打印错误信息。

HTTP 请求头必须包含以下字段：

X-BM-KEY : 您的 API 密钥。
X-BM-SIGN : 使用您的 API 密钥生成的签名。
X-BM-TIMESTAMP : 请求发送的时间戳 (毫秒)。
Content-Type : application/ ，表明请求体是 JSON 格式的数据。

错误处理：使用 response.raise_for_status() 方法检查 HTTP 响应状态码。如果状态码表示请求失败（例如 400、401、500），则会引发一个 HTTPError 异常。使用 try...except 块捕获 requests.exceptions.RequestException 异常，以便在请求失败时进行适当的错误处理。该异常可以捕获各种网络相关的错误，例如连接错误、超时错误和 HTTP 错误。在捕获到异常后，打印错误信息并返回 None 或其他适当的指示错误的值。

示例：市价买入 0.01 BTC 的 BTC_USDT 交易对

以下代码演示了如何通过API在指定交易所市价买入 0.01 BTC 的 BTC_USDT 交易对。确保您已正确配置API密钥和交易所连接。

关键参数说明：

symbol : 交易对代码，指定交易的市场，例如 "BTC_USDT"。
side : 交易方向，"buy" 代表买入，"sell" 代表卖出。
type : 订单类型，"market" 代表市价单，立即以当前市场最优价格成交。
size : 交易数量，代表购买或出售的标的数量，单位取决于交易对，这里 "0.01" 代表 0.01 BTC。

代码示例：


symbol = "BTC_USDT"
side  =  "buy"
type = "market"
size =  "0.01" # BTC

调用下单函数：


response = place_order(symbol, side, type, size)

place_order 函数负责向交易所发送订单请求。此函数需要您自行实现，它会根据您的API密钥和交易所接口进行身份验证和数据格式化。

处理响应：


if response and response["code"] == 1000:
     print("下单成功:", response["message"], response["data"])
else:
     print("下单失败:", response)

交易所API通常会返回一个包含订单状态信息的响应。成功的响应通常包含一个唯一的订单ID和其他相关数据。通过检查 response["code"] ，您可以判断订单是否已成功提交。

错误处理：

请注意，交易可能由于多种原因失败，例如账户余额不足、API密钥无效或交易所出现问题。在实际应用中，您需要添加更完善的错误处理机制，例如重试机制或告警系统。

示例：限价卖出 0.01 BTC 的 BTC_USDT，价格为 30000 USDT

为了演示限价卖单的创建过程，我们将以卖出 0.01 个比特币（BTC）兑换美元稳定币（USDT）为例，设定的卖出价格为每个比特币 30000 美元。以下代码片段展示了如何使用交易API提交一个限价卖单。


symbol = "BTC_USDT"  // 交易对：比特币/美元稳定币
side = "sell"       // 交易方向：卖出
type = "limit"      // 订单类型：限价单
size = "0.01"       // 订单数量：0.01 BTC
price = "30000"     // 订单价格：每个BTC 30000 USDT

上述代码定义了创建限价卖单所需的关键参数。 symbol 指定了交易对， side 指定了交易方向为卖出， type 设置为 limit 表明这是一个限价单。 size 定义了要卖出的比特币数量， price 则设定了期望的卖出价格。

接下来，我们调用 place_order 函数提交订单：


response = place_order(symbol, side, type, size, price)

place_order 函数接收上述参数，并向交易所的API发送请求以创建订单。返回的 response 对象包含了订单创建的结果信息。

我们检查 response 对象以确定订单是否成功创建：


if response and response["code"] == 1000:
    print("下单成功:", response["message"], response["data"])
else:
    print("下单失败:", response)

如果 response 对象存在，并且其 code 属性值为 1000，则表示订单已成功提交。此时，我们会打印包含成功消息和订单数据的相关信息。否则，我们会打印失败消息以及完整的 response 对象，以便进行错误诊断。

请注意， response["message"] 通常包含人类可读的订单状态描述，而 response["data"] 则可能包含交易所生成的订单ID和其他相关信息。 place_order 函数的具体实现取决于您所使用的交易平台API。

代码解释:

导入必要的库: requests 库用于发起和处理 HTTP 请求，这是与外部 API 交互的基础。 hashlib 库提供了多种哈希算法，而 hmac 模块则用于创建基于哈希的消息认证码，增强安全性。 time 库用于获取当前时间戳，确保请求的时效性。库用于将 Python 对象序列化为 JSON 字符串，反之亦然，以便在网络上传输数据。
设置 API 密钥和 API Endpoint: YOUR_API_KEY 和 YOUR_SECRET_KEY 必须替换为您的 BitMart 账户对应的真实 API 密钥。API 密钥用于身份验证，而密钥则用于生成签名。 base_url 定义了 BitMart API 的根 URL，所有 API 请求都将基于此 URL 构建。例如，现货交易的 API Endpoint 通常不同于合约交易的 API Endpoint，需要根据实际使用的 API 进行设置。
generate_signature 函数: 该函数是安全通信的核心，用于生成 API 请求的数字签名。该签名验证请求的来源和完整性，防止篡改。HMAC-SHA256 是一种常用的消息认证算法，它使用密钥对消息进行哈希运算。签名的内容通常包括 API Endpoint 的路径、当前时间戳以及请求体（如果存在），这些信息被组合成一个字符串并使用密钥进行签名。签名的目的是证明请求是由拥有密钥的合法用户发起的。具体流程可能涉及到将时间戳转换为字符串，请求体进行 JSON 序列化，并将这些元素连接起来进行哈希计算。
place_order 函数: 此函数封装了下单逻辑，使得下单操作更加便捷。它接受多个参数，包括：交易对 symbol (例如 'BTC_USDT')，指定交易的标的；买卖方向 side (例如 'buy' 或 'sell')，指示是买入还是卖出；订单类型 type (例如 'limit' 或 'market')，决定订单的执行方式；数量 size ，指定交易的资产数量；价格 price (仅限价单需要)，设置订单的成交价格。函数内部会根据这些参数构建一个包含订单详细信息的请求体。
构建请求头: HTTP 请求头携带了关于请求的元数据，对于 API 交互至关重要。 X-BM-KEY 字段包含了您的 API 密钥，用于标识您的身份。 X-BM-SIGN 字段包含了请求的签名，用于验证请求的真实性和完整性。 X-BM-TIMESTAMP 字段包含了时间戳，用于防止重放攻击。 Content-Type 字段设置为 application/ ，表明请求体的内容是 JSON 格式的数据。正确设置请求头是成功调用 API 的关键步骤。
发送 POST 请求: requests.post 函数用于向 BitMart API 发送 POST 请求。POST 请求通常用于创建或更新资源。该函数需要传递 API Endpoint 的 URL 和包含请求数据的请求体，以及包含认证信息的请求头。 requests 库会自动处理请求的发送和响应的接收。
处理响应: API 响应的状态码和内容提供了关于请求执行结果的重要信息。HTTP 状态码指示了请求是否成功。例如，200 表示成功，400 表示请求错误，500 表示服务器错误。响应内容通常是 JSON 格式的数据，包含了 API 返回的具体信息，例如订单 ID、成交价格等。需要检查响应状态码和响应内容，以判断下单是否成功，并根据响应内容进行相应的处理。例如，如果下单失败，可以根据错误信息进行调试和重试。应该包含对错误码的解析和处理，并且针对不同的错误码给出相应的提示或者处理方法。

其他

本教程旨在为用户提供 BitMart API 交易的基本概念、操作流程以及示例代码。然而，这仅仅是 BitMart API 功能的冰山一角。为了更深入地掌握 API 的全部潜力，建议您仔细研读 BitMart 官方 API 文档，其中包含了更高级的功能、参数详解、错误代码说明以及更复杂的交易策略示例。文档中还详细描述了诸如闪电交易、市价单高级选项、止损限价单等高级交易功能的使用方法。

在将 API 应用于真实交易环境之前，务必进行充分的模拟盘测试，并建立完善的风险管理机制。API 交易具有高速、自动化的特点，但也意味着潜在风险较高。例如，程序错误、网络延迟或者市场剧烈波动都可能导致意外损失。因此，建议采取以下措施：