BitMEX 数据接口详解
BitMEX 作为一个老牌的加密货币衍生品交易所，其数据接口对于量化交易者、研究人员以及市场观察者来说至关重要。 通过 BitMEX 的 API，开发者可以获取实时市场数据、历史交易数据、账户信息、下单执行等功能，从而构建自动化交易策略、分析市场动态以及进行风险管理。
API 概览
BitMEX 提供两种主要的数据接口：REST API 和 WebSocket API，以满足不同用户的需求。REST API 适用于请求-响应模式，通过 HTTP 协议进行数据交互；WebSocket API 则提供实时数据流，适用于需要快速、持续更新的应用场景。
REST API 允许用户执行各种操作，例如下单、查询账户信息、获取历史交易数据等。它采用标准 HTTP 方法 (GET, POST, PUT, DELETE) 进行操作，并返回 JSON 格式的数据。为了安全起见，所有请求都需要进行身份验证，通常使用 API 密钥和签名。
WebSocket API 允许用户订阅特定的市场数据流，例如实时交易、订单簿更新和指数数据。一旦建立连接，服务器将持续推送数据更新，无需客户端重复请求，从而显著降低延迟并提高效率。这种方式特别适合高频交易者和需要实时监控市场的应用。
选择哪种 API 取决于具体的应用场景。对于需要批量获取历史数据或执行管理操作的场景，REST API 更为合适。对于需要实时监控市场动态并进行快速交易的场景，WebSocket API 则更具优势。
REST API: 提供了一次性的请求-响应模式，适用于获取历史数据、账户信息等非实时性数据。 通过发送 HTTP 请求，可以获取 JSON 格式的响应数据。 WebSocket API: 提供实时的双向通信，适用于接收实时市场数据、订单状态更新等高频数据。 数据以 JSON 格式推送。选择哪种 API 取决于具体需求。 如果需要低延迟的实时数据，则 WebSocket API 是更好的选择。 如果只需要获取历史数据或执行一些管理操作，则 REST API 更简单易用。
REST API 详解
在加密货币交易领域，REST API（Representational State Transfer Application Programming Interface）是连接交易平台与外部应用程序的关键接口。BitMEX 作为领先的加密货币衍生品交易所，其 REST API 允许开发者以编程方式访问市场数据、管理账户、执行交易等。理解和熟练使用 BitMEX REST API 对于量化交易者、算法交易者以及任何希望自动化交易策略的人来说至关重要。
BitMEX REST API 的基准 URL 是访问所有 API 端点的基础。根据您所处的环境，您需要使用不同的 URL。主网 URL
https://www.bitmex.com/api/v1
用于实际的加密货币交易，涉及到真实的资金。测试网 URL
https://testnet.bitmex.com/api/v1
则提供一个模拟交易环境，允许您在不承担任何财务风险的情况下测试和调试您的 API 集成。强烈建议在将您的应用程序部署到主网之前，先在测试网上进行充分的测试。
所有 API 端点都基于此基准 URL 构建。这意味着每个可用的 API 功能都对应于一个特定的 URL 路径，该路径附加到基准 URL 之后。例如，要获取最新的交易数据，您可能需要访问类似于
https://www.bitmex.com/api/v1/trade
的端点。每个端点接受特定的 HTTP 方法（如 GET、POST、PUT、DELETE）和参数，以执行不同的操作。详细的 API 文档可在 BitMEX 官方网站上找到，其中包含了每个端点的详细说明、参数列表、请求示例和响应格式，务必查阅官方文档以便正确使用 API。
常用 REST API 端点:
-
/api/v1/instrument: 获取合约信息 。此端点提供所有可用交易合约的详细信息，包括：- 合约代码: 交易合约的唯一标识符，例如 "BTC-USD"。
- 结算货币: 用于结算盈亏的货币，例如 "USD" 或 "BTC"。
- 保证金要求: 开仓所需的最低保证金比例或金额。
- 合约类型: 合约的类型，例如永续合约、交割合约或期权合约。
- 最小价格变动单位: 价格变动的最小增量。
- 最大订单数量: 允许下的最大订单数量。
/api/v1/instrument?symbol=BTC-USD。 -
/api/v1/orderBook/L2: 获取订单簿数据 。此端点提供特定合约的实时订单簿信息，包括：- 买单(Bid)价格和数量: 愿意买入的价格和对应的数量。
- 卖单(Ask)价格和数量: 愿意卖出的价格和对应的数量。
/api/v1/orderBook/L2?symbol=BTC-USD&depth=10将返回前10个买单和卖单。 -
/api/v1/trade: 获取成交记录 。此端点提供特定合约的历史成交记录，包括：- 成交价格: 交易的执行价格。
- 成交数量: 交易的数量。
- 成交时间: 交易发生的时间。
- 买卖方向: 交易是买入还是卖出。
/api/v1/trade?symbol=BTC-USD&startTime=2023-10-26T00:00:00Z&endTime=2023-10-27T00:00:00Z将返回 2023年10月26日到27日之间的 BTC-USD 成交记录。 -
/api/v1/user/wallet: 获取用户的钱包余额 。此端点需要用户身份验证才能访问，返回用户账户中各种加密货币的余额信息。包括：- 可用余额: 可以用于交易的余额。
- 已用余额: 已经被用于开仓或挂单的余额。
- 总余额: 可用余额和已用余额的总和。
-
/api/v1/order: 用于下单、修改和取消订单 。 此端点也需要用户身份验证。- 下单: 允许用户提交新的交易订单，指定交易合约、数量、价格、订单类型（例如市价单、限价单）等参数。
- 修改订单: 允许用户修改尚未成交的订单，例如更改价格或数量。
- 取消订单: 允许用户取消尚未成交的订单。
示例 (Python):
以下 Python 示例展示了如何使用 BitMEX API 获取钱包余额。 为了安全地与 BitMEX API 交互，需要生成请求签名，该签名基于您的 API 密钥、API 密钥密钥以及请求的具体细节创建。
导入必要的 Python 库：
requests
用于发送 HTTP 请求，
hashlib
用于创建哈希值，
hmac
用于生成基于哈希的消息验证码，以及
time
用于获取当前时间。
import requests
import hashlib
import hmac
import time
import
将
api_key
和
api_secret
替换为您从 BitMEX 获得的实际 API 密钥和密钥。 请务必妥善保管您的 API 密钥，避免泄露。
api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"
generate_signature
函数用于生成请求签名。 它接收 API 密钥密钥、HTTP 方法 (verb)、API 端点 URL、过期时间戳以及请求数据作为参数。 该函数首先将这些参数连接成一个字符串，然后使用 HMAC-SHA256 算法对该字符串进行哈希处理，API 密钥密钥作为密钥。 生成的哈希值即为请求签名。
def generate_signature(api_secret, verb, url, expires, data):
"""生成请求签名."""
payload = verb + url + str(expires) + data
signature = hmac.new(api_secret.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256).hexdigest()
return signature
get_wallet_balance
函数使用 BitMEX API 获取钱包余额。 它首先定义 HTTP 方法 (
GET
)、API 端点 URL (
/api/v1/user/wallet
) 以及过期时间戳（从现在起 60 秒）。 然后，它调用
generate_signature
函数生成请求签名。
def get_wallet_balance():
"""从 BitMEX API 获取钱包余额."""
verb = "GET"
url = "/api/v1/user/wallet"
expires = int(time.time()) + 60 # 60 秒后过期
data = ""
调用
generate_signature
函数，使用你的 API 密钥密钥、HTTP 方法、URL、过期时间和数据来创建签名。
signature = generate_signature(api_secret, verb, url, expires, data)
接下来，它创建一个包含 API 密钥、过期时间戳和请求签名的 HTTP 头部。 然后，它使用
requests.get
函数向 BitMEX API 发送 HTTP GET 请求。 请注意，示例使用 BitMEX 测试网 (
https://testnet.bitmex.com
)。 在生产环境中，应使用主网端点 (
https://www.bitmex.com
)。
headers = {
"api-key": api_key,
"api-expires": str(expires),
"api-signature": signature
}
endpoint = "https://testnet.bitmex.com" + url # 使用测试网进行测试
设置请求头，包括 API 密钥、过期时间和生成的签名，以验证请求的真实性。
response = requests.get(endpoint, headers=headers)
该函数检查 HTTP 响应状态码。 如果状态码为 200，则表示请求成功，该函数将钱包余额打印到控制台。 否则，该函数将打印错误消息，其中包含状态码和响应文本。
if response.status_code == 200:
print(.dumps(response.(), indent=4))
else:
print(f"Error: {response.status_code} - {response.text}")
调用
get_wallet_balance()
函数执行 API 调用并检索钱包余额信息。
get_wallet_balance()
- 400: 错误的请求
- 401: 未授权
- 403: 禁止访问
- 429: 请求过多 (限流)
- 500: 服务器内部错误
WebSocket API 详解
BitMEX WebSocket API 提供了一个强大的接口，用于实时获取市场深度、最新成交价（Last Price）、指数价格、交易量以及用户账户相关数据，例如仓位、订单和资金余额。通过建立持久的 WebSocket 连接，客户端能够以极低的延迟接收到这些信息，从而实现快速响应市场变化和高效的交易决策。
连接建立过程通常涉及一个握手阶段，客户端需要发送特定的请求到 BitMEX 的 WebSocket 服务器。一旦连接成功建立，客户端就可以通过发送订阅消息来选择性地订阅不同的频道，接收感兴趣的数据。每个频道对应于特定的数据流，例如
trade
频道提供实时的交易数据，
orderBookL2
频道提供第二层级的订单簿信息，
instrument
频道则提供合约相关的静态和动态信息，包括最高价、最低价、开盘价、收盘价等。客户端可以根据自身需求订阅多个频道，灵活定制所需的数据流。
数据推送采用 JSON 格式，易于解析和处理。为了保持连接的活跃性，客户端通常需要定期发送心跳消息。同时，BitMEX WebSocket API 具有错误处理机制，当发生错误时，服务器会发送错误消息，客户端需要根据错误代码采取相应的措施，例如重新连接或重新订阅。
连接: WebSocket API 的连接地址为wss://www.bitmex.com/realtime (主网) 和 wss://testnet.bitmex.com/realtime (测试网)。
认证: WebSocket API 同样需要进行认证，认证过程通过发送一个 authKeyExpires、authKey 和 authSig 的 JSON 消息来实现。 authKey 对应 API 密钥，authSig 是使用 API 密钥秘钥生成的签名。
常用频道:
- trade: 接收实时成交记录。此频道提供市场上发生的每一笔交易的即时数据，包括成交价格、成交数量和交易时间。它对于高频交易者和算法交易者至关重要，因为它允许他们快速响应市场动态并抓住瞬间的机会。通过监控trade频道，用户可以深入了解市场情绪和交易活动。
- quote: 接收最优买卖报价。此频道发布当前市场上最优的买入价（最高买家出价）和卖出价（最低卖家要价），也被称为“最佳出价/要价”（Best Bid and Offer, BBO）。它对于快速判断市场价格趋势和评估流动性至关重要。投资者可以利用这些信息来优化他们的订单执行策略，并避免不必要的价格滑点。
- orderBookL2: 接收 Level 2 订单簿数据。与仅显示最佳出价和要价的quote频道不同，orderBookL2频道提供更深入的订单簿视图，展示多个价格级别的买入和卖出订单。这允许用户观察市场深度和潜在的支撑/阻力位。Level 2 数据对于识别大型订单和潜在的价格操纵行为非常有用。
- order: 接收订单状态更新。此频道提供关于用户订单的实时状态更新，包括订单提交、部分成交、完全成交、取消和拒绝等。它允许用户跟踪其订单的执行情况，并确保交易按预期进行。通过监控order频道，用户可以及时发现并解决任何订单相关的问题。
- position: 接收仓位信息更新。此频道提供用户当前持仓的实时更新，包括持仓数量、平均持仓成本和未实现盈亏。它允许用户密切关注其投资组合的表现，并及时做出调整。Position频道对于风险管理和投资组合优化至关重要。
示例 (Python):
为了与加密货币交易所的WebSocket API进行交互，以下Python代码展示了如何进行身份验证和订阅交易频道。需要安装
websocket-client
库。 可以使用
pip install websocket-client
命令进行安装。
websocket
库用于建立WebSocket连接，
库用于处理JSON格式的数据，
hmac
和
hashlib
用于生成签名，
time
库用于获取当前时间。
import websocket
import
import hmac
import hashlib
import time
将
YOUR_API_KEY
和
YOUR_API_SECRET
替换为从交易所获得的实际API密钥和密钥。
api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"
generate_signature
函数用于生成请求签名。它接受API密钥、HTTP方法（verb）、请求URL、过期时间和数据作为输入，并使用HMAC-SHA256算法计算签名。交易所使用此签名验证请求的合法性。
def generate_signature(api_secret, verb, url, expires, data):
"""Generate a request signature."""
payload = verb + url + str(expires) + data
signature = hmac.new(api_secret.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256).hexdigest()
return signature
以下回调函数定义了WebSocket连接的不同事件的处理方式。
on_message
函数处理接收到的消息，
on_error
函数处理错误，
on_close
函数在连接关闭时被调用,
on_open
函数在连接建立后被调用。
def on_message(ws, message):
print(message)
def on_error(ws, error):
print(error)
def on_close(ws):
print("### closed ###")
def on_open(ws):
print("### opened ###")
在
on_open
函数中，首先计算过期时间（当前时间 + 60秒），然后使用
generate_signature
函数生成签名。接下来，构造一个包含身份验证信息的JSON对象，并通过WebSocket连接发送。然后，构造一个订阅特定交易对（例如XBTUSD）的交易频道的JSON对象，并发送给服务器。
.dumps()
方法用于将Python字典对象序列化为JSON字符串。
expires = int(time.time()) + 60
signature = generate_signature(api_secret, 'GET', '/realtime', expires, '')
auth = {
"op": "authKey",
"args": [api_key, expires, signature]
}
ws.send(.dumps(auth))
# Subscribe to the trade channel for XBTUSD
subscribe = {
"op": "subscribe",
"args": ["trade:XBTUSD"]
}
ws.send(.dumps(subscribe))
if __name__ == "__main__":
块确保只有在直接运行脚本时才执行以下代码。
websocket.enableTrace(True)
启用WebSocket跟踪，以便在控制台中查看WebSocket通信的详细信息。
WebSocketApp
创建一个WebSocket应用程序实例，指定WebSocket URL（在本例中使用测试网），以及各种回调函数。
ws.run_forever()
启动WebSocket客户端，使其保持运行状态并监听来自服务器的消息。
if __name__ == "__main__":
websocket.enableTrace(True)
ws = websocket.WebSocketApp("wss://testnet.bitmex.com/realtime", # Use testnet for testing
on_message=on_message,
on_error=on_error,
on_close=on_close,
on_open=on_open)
ws.run_forever()
table 字段，指示数据的类型 (例如 trade、quote)，以及一个 data 字段，包含具体的数据。
限流
为保障系统稳定和公平使用，BitMEX 对 REST API 和 WebSocket API 均实施速率限制策略。这旨在防止恶意滥用和保障所有用户的服务质量。
REST API 限流： 未认证的 REST API 请求限制为每分钟 150 次，已认证的请求则提高至每分钟 300 次。身份验证后更高的限额，反映了平台对注册用户更高级别的信任和服务承诺。速率限制根据用户身份和权限的不同而有所调整，以此来平衡资源分配并优化系统性能。未通过身份验证的请求受到更严格的限制，鼓励用户注册并验证其身份以获得更大的灵活性。
WebSocket API 限流： WebSocket API 的速率限制更为复杂，取决于订阅的频道数量和所传输的数据量。订阅的频道越多，数据传输量越大，速率限制可能越严格。平台会根据用户对不同交易品种或市场深度数据的需求动态调整限流策略。BitMEX会动态监控并调整WebSocket API的速率限制，以适应不断变化的市场条件和用户行为，确保平台的整体稳定性和响应能力。
超出速率限制的请求将被服务器拒绝，并返回 HTTP 429 错误代码（Too Many Requests）。开发者应妥善处理此错误，并采取适当的措施来降低请求频率。当接收到 429 错误时，应立即停止发送新的请求，并等待一段合理的时间后再尝试重发。避免在短时间内连续发送大量请求，从而触发限流机制。
重试机制： 实施重试机制是处理限流问题的关键。开发者应该采用指数退避算法或类似的策略，逐渐增加重试之间的时间间隔，以避免进一步加剧服务器的负载。例如，第一次重试可以在 1 秒后进行，第二次重试在 3 秒后，第三次重试在 7 秒后，以此类推。这种机制可以在不给服务器带来额外压力的前提下，有效地处理被限流的请求。
强烈建议开发者详细阅读 BitMEX 官方文档，以获取最新的限流策略信息和最佳实践指南。BitMEX 可能会根据市场情况和系统负载调整限流规则，因此定期查阅官方文档至关重要。 官方文档将提供关于限流策略的最新更新和详细信息，帮助开发者更好地理解和遵守平台的规则。遵循官方指南能够最大程度地减少被限流的风险，并确保应用程序的稳定性和可靠性。
BitMEX 数据接口为开发者提供了丰富的功能，可以用于构建各种加密货币交易和分析应用。 掌握 REST API 和 WebSocket API 的使用方法，理解认证机制和限流策略，是有效利用 BitMEX 数据的关键。
