BitMEX 平台 API 连接指南

简介

BitMEX (Bitcoin Mercantile Exchange) 是全球领先的加密货币衍生品交易平台之一，专注于为专业交易者和机构投资者提供高级金融工具。 核心产品包括比特币和其他数字货币的永续合约、期货合约以及其他创新型衍生品。 这些衍生品允许用户在不实际持有基础资产的情况下，对加密货币的价格波动进行投机或对冲风险。

BitMEX 平台的突出特点之一是其强大的应用程序编程接口（API），为开发者和量化交易者提供了高度灵活和自动化的交易能力。 通过 BitMEX API，用户可以创建和执行复杂的交易策略，实时获取市场深度数据和历史交易数据，并有效管理其交易账户和订单。 API 接口支持多种编程语言，使其易于集成到现有的交易系统中。

本指南旨在为开发者提供连接到 BitMEX API 并进行基本数据交互的详细步骤和实用示例。 我们将涵盖身份验证、数据请求、订单管理以及常见问题的解决方案，帮助开发者快速上手并充分利用 BitMEX API 的强大功能。 通过掌握这些技能，开发者可以构建自己的自动化交易机器人、量化分析工具以及其他定制化的加密货币交易解决方案。 本文将侧重于REST API的使用，让开发者了解如何通过发送HTTP请求来与BitMEX服务器进行交互。

准备工作

在开始之前，你需要完成以下准备工作，确保后续与 BitMEX API 的交互顺利进行：

• 注册 BitMEX 账户： 访问 BitMEX 官方网站，按照指引完成账户注册。注册过程可能需要提供邮箱地址、设置密码，并完成必要的身份验证（KYC）。请务必使用强密码并启用双重验证 (2FA)，以提高账户安全性。
• 生成 API 密钥： 成功登录 BitMEX 账户后，导航至 API 管理页面。该页面通常位于用户 "Account" 菜单下的 "API Keys" 或类似名称的子菜单中。在此页面，你可以创建新的 API 密钥。创建时，务必仔细设置密钥的权限。BitMEX 允许你精细控制 API 密钥的权限，例如只允许读取账户信息、允许进行交易操作等。为了安全起见，强烈建议 禁用提币权限 。即使 API 密钥泄露，攻击者也无法利用它转移你的资金。为每个应用程序或脚本创建单独的 API 密钥，并为其分配最小必要的权限，可以进一步提高安全性。妥善保管你的 API 密钥和密钥，切勿将其泄露给他人或存储在不安全的地方。
• 选择编程语言和库： BitMEX API 采用 RESTful 架构，这意味着你可以使用任何支持 HTTP 请求的编程语言与 API 进行交互。流行的选择包括 Python (配合 requests、ccxt 库)、JavaScript (配合 node-fetch、axios 库)、Java (配合 HttpClient 库) 以及 Go 语言等。语言的选择取决于你的个人偏好和项目需求。例如，Python 由于其简洁的语法和丰富的第三方库，常被用于快速原型开发和数据分析。而 Java 则更适合构建大型、企业级的应用程序。 ccxt 是一个统一的加密货币交易 API，支持许多交易所，简化了代码，降低了学习成本。
• 安装必要的库： 如果你选择 Python 作为编程语言，你需要安装 requests 库，该库提供了便捷的 HTTP 请求功能。可以使用 Python 的包管理工具 pip 进行安装：

bash

pip install requests

API 连接方式

BitMEX API 主要分为两种，分别是 Public API 和 Private API，二者提供不同的数据访问和功能权限：

• Public API： 提供公开透明的市场数据，例如实时交易深度（Order Book）、最新成交价格（Last Traded Price）、历史交易数据（Historical Data）等。 这些数据对于市场分析、策略回测和价格监控至关重要。 Public API 的特点是无需进行身份验证即可直接访问，降低了数据获取的门槛，方便开发者快速集成。
• Private API： 提供账户管理和交易执行等敏感功能，例如查询账户余额、下单、取消订单、修改订单等。 为了保障账户安全，Private API 必须使用 API 密钥（API Key）和密钥（Secret Key）进行严格的身份验证。 API 密钥用于标识用户身份，密钥用于对请求进行签名，防止未经授权的访问。使用 Private API 时务必妥善保管 API 密钥和密钥，防止泄露。

Public API 连接

访问 Public API 是一项简单的任务，主要通过发送 HTTP GET 请求到指定的 API 端点来实现。无需身份验证，您可以轻松访问公开的数据。例如，要获取 BitMEX 交易所 XBTUSD 永续合约的实时交易深度信息，可以使用以下代码示例：

import requests

url = "https://www.bitmex.com/api/v1/orderBook/L2?symbol=XBTUSD&depth=25"
response = requests.get(url)

if response.status_code == 200:
data = response.()
print(data)
else:
print(f"请求失败：{response.status_code}, {response.text}")

上述 Python 代码段使用 requests 库发送一个 GET 请求到 BitMEX 的 /orderBook/L2 API 端点。 symbol 参数指定了所需的交易对，在此示例中为 XBTUSD (比特币/美元永续合约)。 depth 参数定义了返回的订单簿深度，这里设置为 25，意味着返回最佳的 25 个买单和卖单。成功执行后，API 将返回一个包含买单和卖单信息的 JSON 数据结构，该数据结构详细描述了当前市场上的订单情况，包括价格和数量。

需要注意的是， response.() 方法用于将 API 返回的 JSON 格式字符串转换为 Python 字典或列表，方便后续的数据处理和分析。检查 response.status_code 可以确保请求成功，HTTP 状态码 200 表示成功。如果请求失败，将打印错误信息，包括状态码和服务器返回的文本，方便调试。

Private API 连接

访问 Private API 需要使用 API 密钥进行身份验证，确保只有授权用户才能访问敏感数据和执行交易操作。BitMEX 使用 HMAC-SHA256 算法对每个请求进行签名，以此验证请求的来源和完整性，防止中间人攻击。

生成签名时需要包含以下关键信息，这些信息共同构成了请求的唯一标识，任何细微的修改都会导致签名验证失败：

1. API 密钥: 你的私有 API 密钥，务必妥善保管，避免泄露。
2. API 密钥 ID: 用于标识特定 API 密钥的唯一 ID。在 BitMEX 平台生成 API 密钥时会同时生成对应的 ID，方便管理多个密钥。
3. HTTP 方法: 请求所使用的 HTTP 方法，例如 GET , POST , PUT , DELETE 。必须与实际请求方法一致。
4. 请求路径: 目标 API 端点的完整路径，例如 /api/v1/order ，区分大小写。
5. 请求正文: 对于 POST 或 PUT 请求，需要包含请求正文，且必须是符合 API 要求的 JSON 格式。
6. 过期时间: 一个 Unix 时间戳，表示请求的有效期限。为了安全起见，过期时间不应设置过长，建议设置为请求发送后的几秒或几分钟。

以下是一个使用 Python 和 requests 库发送 Private API 请求的示例 (以获取账户余额为例)。该示例演示了如何计算签名、构建请求头和发送请求，以及如何处理响应结果：

import requests
import hashlib
import hmac
import time
import 

def generate_signature(api_secret, method, path, expires, data=""):
    """
    生成 BitMEX API 请求签名。

    参数:
        api_secret (str): API 密钥。
        method (str): HTTP 方法 (GET, POST, PUT, DELETE)。
        path (str): API 端点路径。
        expires (int): 请求过期时间 (Unix 时间戳)。
        data (str): 请求正文 (JSON 字符串，可选)。

    返回:
        str: HMAC-SHA256 签名。
    """
    message = method + path + str(expires) + data
    signature = hmac.new(api_secret.encode('utf-8'), message.encode('utf-8'), digestmod=hashlib.sha256).hexdigest()
    return signature

api_key = "YOUR_API_KEY"  # 替换成你的 API 密钥 ID
api_secret = "YOUR_API_SECRET"  # 替换成你的 API 密钥
base_url = "https://www.bitmex.com"
endpoint = "/api/v1/user/wallet"
method = "GET"

expires = int(time.time()) + 60  # 设置 60 秒后过期

signature = generate_signature(api_secret, method, endpoint, expires)

headers = {
    "api-key": api_key,
    "api-signature": signature,
    "api-expires": str(expires)
}

url = base_url + endpoint
response = requests.get(url, headers=headers)

if response.status_code == 200:
    data = response.()
    print(data)
else:
    print(f"请求失败：{response.status_code}, {response.text}")

在这个例子中：

• generate_signature 函数用于使用 HMAC-SHA256 算法生成请求签名，确保请求的安全性。该函数接受 API 密钥、HTTP 方法、请求路径、过期时间和请求正文作为输入。
• api_key 和 api_secret 必须替换成你自己的 API 密钥 ID 和密钥。请注意，API 密钥的安全性至关重要，请勿将其泄露给他人。
• expires 设置请求的过期时间为当前时间加上 60 秒。过期时间的设置可以有效防止重放攻击。
• headers 包含了 API 密钥 ID、签名和过期时间。这些头部信息是 BitMEX API 进行身份验证和授权的关键。
• 我们发送一个 GET 请求到 /api/v1/user/wallet 端点，获取账户余额。根据不同的 API 端点，可能需要发送 POST , PUT , DELETE 等其他类型的请求。
• 对于 POST 或 PUT 请求，需要将请求数据序列化为 JSON 格式，并将其作为 data 参数传递给 requests.post() 或 requests.put() 函数。同时，需要在 generate_signature 函数中包含请求数据的哈希值。

常用 API 端点

以下是一些常用的 BitMEX API 端点，这些端点允许开发者和交易者与 BitMEX 交易所进行交互，获取市场数据和管理账户。

• Public API:
  • /orderBook/L2 : 获取交易深度（Order Book）。提供指定合约的买单和卖单的订单簿信息，通常按照价格级别聚合，L2 表示第二层深度，可以精确地反映市场供需情况。该端点支持指定深度级别，可用于构建交易策略和分析市场微观结构。
  • /trade : 获取最新成交记录（Trades）。返回最近发生的交易信息，包括交易价格、数量、交易方向（买入或卖出）和交易时间。 可以实时追踪市场交易动态，用于高频交易策略和市场情绪分析。
  • /instrument : 获取合约信息（Instruments）。提供所有可交易合约的详细信息，包括合约代码、标的资产、结算货币、合约乘数、最小价格变动单位、以及其他相关参数。 是了解合约规格和计算盈亏的关键端点。
  • /historicalData : 获取历史数据 (仅限商业用户)。允许商业用户访问历史市场数据，包括历史价格、成交量、开盘价、最高价、最低价等信息。 这些数据对于回测交易策略、进行统计分析和构建预测模型至关重要。 需要注意的是，该端点通常需要额外的授权或付费才能访问。
• Private API:
  • /user/wallet : 获取账户余额（Wallet）。返回用户的账户余额信息，包括可用余额、已用余额、保证金余额、未实现盈亏等。 账户余额是管理交易和评估风险的重要指标。
  • /order : 下单、撤单、修改订单（Orders）。允许用户通过 API 提交、取消和修改订单。 支持各种订单类型，如限价单、市价单、止损单等。 是进行自动化交易和算法交易的核心端点。
  • /position : 获取持仓信息（Positions）。提供用户的当前持仓信息，包括持仓数量、平均持仓价格、未实现盈亏、保证金占用等。 通过该端点，用户可以实时监控自己的交易风险和盈利情况。
  • /user/affiliateStatus : 获取邀请码和返佣信息（Affiliate Status）。提供用户的邀请码和返佣信息，允许用户追踪自己的邀请活动和返佣收益。 是 BitMEX 联盟计划参与者的重要端点。

错误处理

在使用 BitMEX API 进行交易或数据获取时，有效的错误处理至关重要。API 响应的 HTTP 状态码提供了问题诊断的重要线索。通过分析状态码，开发者可以快速定位并解决请求中的问题。以下是常见状态码及其含义的详细说明：

• 200 OK : 请求已成功处理。这表示服务器已成功接收、理解并处理了你的请求，并返回了预期的结果。
• 400 Bad Request : 请求格式错误或包含无效参数。这意味着客户端发送的请求不符合API的要求。常见原因包括缺少必要的参数、参数值格式不正确或者数据类型不匹配。仔细检查请求的参数，并参考API文档进行修正。
• 401 Unauthorized : 身份验证失败。通常是由于 API 密钥无效、过期或者没有访问特定资源的权限。请确保你的 API 密钥正确配置，并且拥有执行所请求操作的必要权限。检查密钥是否已激活，以及是否被限制访问特定的端点。
• 403 Forbidden : 服务器拒绝请求。与 401 Unauthorized 类似，但 403 Forbidden 表示服务器理解请求，但拒绝执行，即使身份验证成功。这通常是由于权限不足导致的。
• 429 Too Many Requests : 请求频率超出限制，触发了速率限制。BitMEX API 为了防止滥用，对请求频率进行了限制。如果你的请求频率过高，将会收到此错误。建议实施指数退避算法，或者根据API文档调整请求频率，避免触发速率限制。某些API允许查询剩余的请求次数，可以利用此功能优化请求策略。
• 500 Internal Server Error : BitMEX 服务器内部错误。这表明服务器在处理请求时遇到了意外错误。这通常是服务器端的问题，客户端无法直接解决。如果持续出现此错误，建议联系 BitMEX 技术支持。
• 503 Service Unavailable : 服务器暂时无法处理请求。这通常是由于服务器维护或过载导致的。可以稍后重试请求。
• 504 Gateway Timeout : 服务器作为网关或代理，等待上游服务器响应超时。表明上游服务器响应缓慢或不可用。

当 API 请求失败时， response.text 通常会包含更详细的错误信息，例如具体的错误描述、错误代码等，这对于调试至关重要。你应该在代码中实现健壮的错误处理机制，例如使用 try-except 块捕获异常、重试失败的请求（注意速率限制），以及记录详细的错误日志，以便于分析和诊断问题。可以考虑使用专门的日志管理工具，方便错误信息的收集、分析和报警。对于关键的交易操作，应设置监控系统，实时监控API响应状态，并在出现异常时及时通知相关人员。

速率限制

BitMEX API 为了确保平台的稳定性和公平性，实施了速率限制策略，旨在防止恶意滥用和过度请求。速率限制的具体数值会根据调用的 API 端点、用户的账户等级以及市场情况进行动态调整。当应用程序超出设定的速率限制时，API 服务器将会返回 429 Too Many Requests 错误，表明请求频率过高。

开发者可以通过检查 HTTP 响应头来实时监控 API 速率限制的状态。 X-RateLimit-Limit 字段指示在当前时间窗口内允许的最大请求数量。 X-RateLimit-Remaining 字段显示剩余的可用请求次数。而 X-RateLimit-Reset 字段则提供一个 Unix 时间戳，表明速率限制将在何时重置，允许新的请求配额。这些信息对于构建健壮且符合速率限制要求的应用程序至关重要。

为了避免因超出速率限制而导致 IP 地址被封禁，开发者应在应用程序设计中充分考虑速率限制。一种有效的策略是实施请求队列或延迟机制。请求队列允许应用程序将请求排队，并按照预定的速率逐个发送，从而避免突发的大量请求。延迟机制则可以通过在每个请求之间添加短暂的延迟来平滑请求频率。还可以采用指数退避算法，在遇到 429 错误时，逐渐增加请求之间的延迟，直到成功发送请求为止。 开发者需要根据实际业务需求和 API 的速率限制策略，选择合适的速率控制方法。

安全注意事项

• 保护你的 API 密钥： API 密钥是访问你的加密货币账户的凭证，务必妥善保管。切勿将 API 密钥分享给任何第三方，包括朋友或同事。避免将 API 密钥硬编码到应用程序中，也不要将其存储在公共代码仓库（如 GitHub）或不安全的云存储服务中。建议使用环境变量或专门的密钥管理服务来安全地存储和管理 API 密钥。
• 使用只读权限： 大多数加密货币交易所都允许你创建具有不同权限级别的 API 密钥。如果你的应用程序只需要获取市场数据，例如价格、交易量等，那么应该创建一个只具有只读权限的 API 密钥。这将大大降低你的账户风险，即使 API 密钥泄露，攻击者也无法进行交易或提币。
• 限制提币权限： 强烈建议禁用 API 密钥的提币权限。这是保护你的资金安全的最重要措施之一。即使攻击者获得了你的 API 密钥，他们也无法将资金从你的账户中提取。只有在极少数情况下，你需要使用 API 密钥进行提币操作时，才应该临时启用提币权限，并在操作完成后立即禁用。
• 监控你的账户： 定期检查你的账户活动和 API 密钥的使用情况，以确保没有异常行为。监控内容包括：API密钥的访问日志、交易历史、资金变动等。如果发现任何可疑活动，例如未经授权的交易或提币请求，应立即禁用相关的 API 密钥，并联系交易所的客服部门进行处理。同时，定期轮换 API 密钥也是一个很好的安全实践。

BitMEX API 提供了强大的交易自动化能力，但也需要谨慎使用。 了解 API 的工作原理、遵守速率限制、并采取必要的安全措施，才能安全有效地利用 BitMEX API 进行交易。