玩转BitMEX API：快速上手自动化交易【新手指南】

编程 2025-03-06 99 次浏览

本文详细讲解BitMEX API的开通与使用，包括账户注册、API密钥启用、REST API和WebSocket API的使用方法，以及常见问题解答，帮助用户快速上手进行自动化交易和数据分析。

BitMEX API 接口开通使用详细教程

本文将详细介绍如何开通并使用 BitMEX API 接口，旨在帮助用户快速上手，进行自动化交易和数据分析。

一、注册 BitMEX 账户

为了参与BitMEX平台的加密货币衍生品交易，首要步骤是创建一个BitMEX账户。如果您尚未拥有账户，请访问BitMEX官方网站（www.bitmex.com）进行注册。请注意，由于不同地区对加密货币交易平台的监管政策各不相同，请务必确认您所在地区是否允许访问和使用BitMEX提供的服务。注册过程通常较为直观，您需要按照网站提示逐步填写必要的信息，例如有效的电子邮箱地址、设置安全强度高的密码，以及可能需要的其他身份验证信息。请务必使用您常用的电子邮箱地址，因为BitMEX会向该邮箱发送验证邮件，用于激活您的账户，以及接收重要的账户安全通知和交易相关的更新。

二、启用 API 密钥

  1. 登录 BitMEX 账户： 使用您已注册的电子邮件地址和密码登录 BitMEX 账户。请确保您的网络连接安全，并仔细核对 BitMEX 的官方网址，以避免钓鱼网站的风险。
  2. 进入 API 密钥管理页面： 成功登录后，将鼠标悬停在页面右上角的账户图标上。这将展开一个下拉菜单。在这个菜单中，选择 “API Keys” 或 “账户 & 安全”，具体取决于 BitMEX 平台的界面更新。在“账户 & 安全”页面中，找到并选择 “API Keys” 选项卡。
  3. 创建新的 API 密钥： 在 API 密钥管理页面，您会看到一个 “创建 API 密钥” 按钮。点击此按钮开始创建新的 API 密钥。如果之前已经创建过 API 密钥，它们也会在此页面列出。
  4. 设置 API 密钥权限： 在弹出的窗口中，您需要精确地设置 API 密钥的权限。BitMEX 提供了多种权限选项，每种权限对应不同的操作能力。谨慎选择权限至关重要，直接关系到您的账户安全。以下是一些常见的权限选项：
    • Trade (交易): 允许使用 API 密钥进行交易操作，包括创建订单、修改订单和取消订单。如果您计划使用 API 密钥进行自动化交易，则需要启用此权限。需要注意的是，启用此权限意味着您的 API 密钥可以执行买卖操作，请务必谨慎使用。
    • Withdraw (提币): 允许使用 API 密钥发起提币请求。 强烈建议不要启用此权限 ，除非您有非常充分的理由，并且完全了解潜在的安全风险。即使在需要提币的情况下，也建议通过 BitMEX 官方网站手动操作，而非通过 API 密钥。启用此权限会大大增加您的账户被盗的风险。
    • Order (订单): 允许使用 API 密钥查看订单信息，例如订单状态、成交价格和成交数量。此权限通常用于监控交易活动或进行数据分析。与 "Trade" 权限相比，"Order" 权限的风险较低。
    • Access API WebSocket Stream (访问 API WebSocket 数据流): 允许使用 API 密钥访问 WebSocket 数据流，获取实时行情数据，例如最新成交价、买卖盘口信息等。WebSocket 是一种实时通信协议，可以更快地获取市场数据。此权限通常用于开发高频交易策略或实时监控工具。
    • Access historical data (访问历史数据): 允许使用 API 密钥访问历史交易数据，例如历史价格、成交量等。此权限通常用于回测交易策略或进行市场分析。请注意，BitMEX 可能对历史数据访问进行速率限制。

    您需要根据您的实际需求，选择合适的权限。 例如，如果您只想进行自动化交易，您需要选择 “Trade” 权限。 为了安全起见，请遵循最小权限原则，只赋予 API 密钥必要的权限。 例如，如果您只需要查看订单信息，则只选择 "Order" 权限，不要选择 "Trade" 权限。

  5. 设置 API 密钥备注： 您可以为您的 API 密钥设置一个备注，方便您区分不同的 API 密钥。例如，您可以备注 “交易机器人”、“数据分析”、“风险控制” 等。清晰的备注可以帮助您更好地管理您的 API 密钥，并防止混淆。建议使用具有描述性的备注，例如 “交易机器人 - BTC/USD 永续合约” 或 “数据分析 - 历史成交量”。
  6. 绑定 IP 地址 (可选)： 为了进一步提高安全性，您可以将 API 密钥绑定到特定的 IP 地址。 这样，只有来自指定 IP 地址的请求才能使用该 API 密钥。 如果您的程序运行在固定的服务器上，强烈建议绑定 IP 地址。 例如，如果您使用云服务器运行交易机器人，可以将 API 密钥绑定到该云服务器的 IP 地址。 即使 API 密钥泄露，未经授权的 IP 地址也无法使用它。 您可以设置多个 IP 地址白名单，以便允许多个服务器访问。请注意，如果您的 IP 地址是动态的，则不适合使用此功能。
  7. 生成 API 密钥： 设置完成后，仔细检查您设置的权限和 IP 地址，确保它们符合您的需求。 然后，点击 “创建 API 密钥” 按钮。 BitMEX 将会立即生成您的 API 密钥（API Key）和 API Secret。
  8. 保存 API 密钥和 API Secret： 请务必妥善保存您的 API 密钥和 API Secret！ API Secret 只会显示一次，如果您忘记了，将无法找回，只能重新生成 API 密钥。 务必将 API 密钥和 API Secret 保存在安全的地方，例如加密的文本文件、密码管理器中，或者使用硬件钱包进行存储。 强烈建议使用密码管理器，例如 LastPass、1Password 或 KeePass，它们可以安全地存储您的 API 密钥和 API Secret，并提供强大的加密保护。 切勿将 API 密钥和 API Secret 存储在明文文件中，或者通过不安全的渠道传输，例如电子邮件或聊天消息。 定期更换 API 密钥也是一个良好的安全实践。

注意:

  • API 密钥 (API Key) 相当于你的用户名，它用于识别你的身份，允许你访问特定的API资源。API Secret 相当于你的密码，必须妥善保管，用于验证你的身份，确保你的API请求的安全性。请务必理解API Key和API Secret的作用，以便更好地保护你的账户安全。
  • 请勿将 API 密钥和 API Secret 泄露给他人。一旦泄露，他人可以利用你的身份进行非法操作，导致你的账户资产损失或其他安全风险。如果怀疑API密钥或API Secret已经泄露，请立即采取措施进行更换，以避免潜在的风险。
  • 定期更换 API 密钥可以提高安全性。定期更换 API Key 和 API Secret 可以有效降低被攻击的风险，即使旧的密钥泄露，攻击者也无法长期利用。建议根据你的安全策略，定期生成新的 API Key 和 API Secret，并将旧的密钥失效，以确保账户安全。可以通过交易所提供的API管理功能来完成密钥的更换。

三、使用 API 接口

BitMEX 提供了两种主要的应用程序编程接口（API）供开发者和交易者使用，分别是 REST API 和 WebSocket API。这两种接口各有特点，适用于不同的应用场景。

REST API (Representational State Transfer API) ：REST API 是一种基于 HTTP 协议的同步请求-响应式接口。它允许用户通过发送 HTTP 请求（例如 GET, POST, PUT, DELETE）来获取市场数据、执行交易、管理账户等。REST API 的主要优点是易于理解和使用，适合进行一次性数据查询和操作。由于是同步接口，每次请求都需要等待服务器响应，因此在高频交易场景下可能存在延迟。

WebSocket API ：WebSocket API 是一种基于 WebSocket 协议的双向通信接口。它允许服务器主动向客户端推送数据，而无需客户端频繁发送请求。这种接口非常适合实时数据流的应用，例如实时行情数据、订单簿更新等。WebSocket API 的主要优点是低延迟和高效率，适合进行高频交易和实时监控。但是，使用 WebSocket API 需要建立持久连接，并处理断线重连等问题。

选择使用哪种 API 取决于具体的应用需求。如果需要进行一次性查询或执行少量交易，REST API 可能更适合。如果需要实时获取市场数据或进行高频交易，WebSocket API 则更有效率。开发者可以根据自己的需求选择合适的 API 接口，并结合 BitMEX 提供的 API 文档进行开发。

1. REST API

REST API (Representational State Transfer Application Programming Interface) 是一种基于 HTTP 协议的应用程序编程接口，它利用 HTTP 方法（如 GET, POST, PUT, DELETE）来实现客户端与服务器之间的通信。 你可以通过构造并发送标准的 HTTP 请求，例如使用 cURL, Python的requests库或其他编程语言中的HTTP客户端，来访问 BitMEX 的各种功能，包括查询市场数据、下单、管理账户等。 每一个API端点都对应BitMEX服务器上的特定资源，通过不同的HTTP方法和请求参数，你可以对这些资源进行读取、创建、更新或删除操作。 例如，GET 请求通常用于检索信息，而 POST 请求则用于创建新的订单或执行其他操作。BitMEX 的 REST API 允许程序化地访问其交易平台，从而实现自动化交易策略和集成到第三方应用中。理解HTTP状态码（如200 OK, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error）对于调试API交互至关重要，这些状态码指示了请求的处理结果。

REST API Endpoint: https://www.bitmex.com/api/v1

请求示例 (使用 Python):

本示例演示了如何使用 Python 语言与 BitMEX API 进行交互，获取您的未成交订单。它包含了必要的 API 密钥配置、签名生成以及请求发送过程。

我们需要导入必要的 Python 库： requests 用于发送 HTTP 请求， hashlib 和 hmac 用于生成 API 签名， time 用于获取当前时间以设置签名过期时间。 

import requests
import hashlib
import hmac
import time

接下来，您需要配置您的 API 密钥和 API Secret。这些密钥用于身份验证，并确保您的请求是安全且经过授权的。请务必妥善保管您的 API Secret，不要将其泄露给他人。 

api_key = "YOUR_API_KEY"  # 替换成你的 API Key
api_secret = "YOUR_API_SECRET"   # 替换成你的 API Secret
endpoint = "https://www.bitmex.com/api/v1"

endpoint 变量定义了 BitMEX API 的基础 URL。所有 API 请求都将基于此 URL 构建。

generate_signature 函数用于生成 API 请求的签名。签名是使用您的 API Secret、请求方法 (verb)、请求路径 (path)、过期时间 (expires) 和请求数据 (data) 通过 HMAC-SHA256 算法计算得出的。此签名附加到请求头中，用于验证请求的完整性和来源。 

def generate_signature(secret, verb, path, expires, data=""):
    """Generate a request signature."""
    message = verb + path + str(expires) + data
    signature = hmac.new(secret.encode('utf-8'), message.encode('utf-8'), digestmod=hashlib.sha256).hexdigest()
    return signature

get_orders 函数演示了如何获取未成交订单。它首先定义了请求方法 ( verb ) 为 "GET"，请求路径 ( path ) 为 "/order"。然后，它计算签名过期时间，通常设置为当前时间加上一个较短的时间间隔（例如 60 秒）。 

def get_orders():
    """Get open orders."""
    verb = "GET"
    path = "/order"
    expires = int(time.time()) + 60  # 60 seconds from now

使用 generate_signature 函数生成签名，并将签名、API Key 和过期时间添加到请求头中。这些头部信息对于 API 的身份验证至关重要。 

    signature = generate_signature(api_secret, verb, path, expires)

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

接下来，使用 requests.get 函数发送 GET 请求到 BitMEX API。请确保将 headers 参数设置为包含身份验证信息的字典。 

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

检查响应状态码。如果状态码为 200，表示请求成功。您可以打印响应内容，其中包含您的未成交订单信息。否则，打印错误信息，包括状态码和响应文本，以便进行调试。 

    if response.status_code == 200:
        print(response.())
    else:
        print(f"Error: {response.status_code}, {response.text}")

调用 get_orders() 函数执行上述流程，并获取您的未成交订单。 

get_orders()

代码解释:

  • api_key 和 api_secret : 请务必将此处替换为您在BitMEX交易所注册后获得的真实API Key和API Secret。API Key用于标识您的身份，而API Secret则用于生成请求签名，确保请求的安全性。请妥善保管您的API Secret，切勿泄露给他人，避免资产损失。
  • generate_signature 函数: 此函数用于生成符合BitMEX API要求的请求签名。BitMEX采用HMAC-SHA256算法进行身份验证和数据完整性校验。签名的目的是验证请求的来源以及确保数据在传输过程中没有被篡改。该函数接受请求方法、请求路径、过期时间以及API Secret作为参数，然后使用HMAC-SHA256算法对这些参数进行加密生成签名。
  • headers : HTTP请求头包含了重要的元数据，用于服务器识别客户端并进行相应的处理。在这个示例中，请求头包含了API Key（ api-key ）、请求签名（ api-signature ）以及过期时间（ api-expires ）。 api-expires 表示请求的有效时间，超过这个时间，请求将被服务器拒绝，有助于防止重放攻击。
  • requests.get(url, headers=headers) : 这行代码使用Python的 requests 库向BitMEX API发送GET请求。 url 参数指定了请求的API端点，例如获取市场数据或账户信息。 headers 参数包含了身份验证信息和过期时间，用于验证请求的合法性。GET请求通常用于获取数据，而不是修改数据。
  • response.() : 当服务器返回响应后，需要解析响应数据。 response.() 方法将服务器返回的JSON格式的响应数据转换为Python字典或列表，方便后续对数据进行处理和分析。如果服务器返回的不是JSON格式的数据，则调用此方法可能会导致错误。
需要注意的是，BitMEX 的 REST API 请求需要进行签名验证。 你需要使用你的 API Secret 和请求参数生成签名，并在 HTTP 请求头中携带签名信息。 具体的签名算法请参考 BitMEX 官方文档。

2. WebSocket API

WebSocket API 是一种基于 WebSocket 协议的应用程序编程接口，它为开发者提供了一种高效且双向的通信方式。通过建立持久的 WebSocket 连接，你可以实时接收 BitMEX 交易所的行情数据更新、账户信息变动以及其他关键事件通知，无需像传统的 HTTP 请求那样频繁地发送请求和等待响应。这显著降低了延迟，并能实时追踪市场动态。

具体来说，WebSocket 协议允许在客户端和服务器之间建立一个长连接，数据可以在任何时间点双向流动。这与传统的 HTTP 协议不同，后者是请求-响应模式，每次通信都需要建立一个新的连接。因此，WebSocket 特别适合需要实时数据更新的场景，例如金融交易平台、在线游戏和实时协作工具。BitMEX 利用 WebSocket API 推送各种市场数据，例如实时交易数据、深度数据以及其他相关信息。用户可以通过订阅特定的频道或数据流来获取他们感兴趣的信息。

为了有效利用 BitMEX 的 WebSocket API，你需要具备一定的编程基础和对 WebSocket 协议的理解。 通常，你需要使用一种支持 WebSocket 连接的编程语言（例如 Python, JavaScript, Go 等），并使用相应的 WebSocket 客户端库来建立和维护连接。 连接建立后，你可以发送订阅消息来指定你希望接收的数据频道， 然后 BitMEX 将会实时推送相关数据到你的客户端。 你也需要妥善处理断线重连机制以保证程序的稳定运行。

WebSocket API Endpoint: wss://www.bitmex.com/realtime (生产环境) 或 wss://testnet.bitmex.com/realtime (测试环境)

连接示例 (使用 Python):

本示例展示如何使用 Python 的 websocket 库连接到加密货币交易所的 WebSocket API，并订阅实时交易数据。 您需要安装 websocket-client 库。 可以使用以下命令进行安装： pip install websocket-client .

import websocket import import hmac import hashlib import time

api_key = "YOUR_API_KEY" # 替换成你的 API Key api_secret = "YOUR_API_SECRET" # 替换成你的 API Secret

请务必将 YOUR_API_KEY 和 YOUR_API_SECRET 替换为您在交易所注册后获得的真实 API 密钥和密钥。请保管好您的API Secret，泄露可能造成资产损失。

def generate_wss_signature(api_secret, expires): """Generate a signature for the WebSocket connection.""" message = 'GET/realtime' + str(expires) signature = hmac.new(api_secret.encode('utf-8'), message.encode('utf-8'), digestmod=hashlib.sha256).hexdigest() return signature

此函数使用您的 API Secret 和过期时间生成 WebSocket 连接的签名。 此签名用于身份验证，并确保连接的安全性。 HMAC-SHA256 算法用于生成签名，其中消息由字符串 “GET/realtime” 和过期时间戳组成。

def on_message(ws, message): """Handle incoming messages from the WebSocket.""" print(message)

此函数处理从 WebSocket 接收的传入消息。 当交易所发送新数据时，将调用此函数，并且数据（通常是 JSON 格式）将打印到控制台。您需要解析message的内容，以便获取相应的数据信息。

def on_error(ws, error): """Handle WebSocket errors.""" print(error)

此函数处理 WebSocket 连接中发生的任何错误。 如果发生错误，会将错误消息打印到控制台，帮助您调试连接问题。

def on_close(ws, close_status_code, close_msg): """Handle WebSocket connection close.""" print("### closed ###")

此函数在 WebSocket 连接关闭时调用。 它会打印一条消息，指示连接已关闭。 close_status_code 和 close_msg 提供了关于连接关闭原因的附加信息。

def on_open(ws): """Handle WebSocket connection open.""" expires = int(time.time()) + 60 signature = generate_wss_signature(api_secret, expires)

此函数在 WebSocket 连接成功打开时调用。 它会生成一个签名，并将其与您的 API 密钥和过期时间一起发送到交易所进行身份验证。 过期时间设置为当前时间加上 60 秒，以确保签名的有效性。如果服务端时间与本地时间相差较大，可能导致鉴权失败。请确保时间同步。 

auth = {
    "op": "authKeyExpires",
    "args": [api_key, expires, signature]
}
ws.send(.dumps(auth))

# 订阅 trade 数据
subscribe = {
    "op": "subscribe",
    "args": ["trade:XBTUSD"]
}
ws.send(.dumps(subscribe))

发送身份验证消息后，您可以订阅特定的数据流。 在本例中，我们订阅 trade:XBTUSD 数据流，该数据流提供 XBTUSD 交易对的实时交易数据。 可以根据交易所提供的API文档，修改订阅的内容。

if __name__ == '__main__': websocket.enableTrace(True) # 开启调试模式 ws = websocket.WebSocketApp("wss://www.bitmex.com/realtime", on_open=on_open, on_message=on_message, on_error=on_error, on_close=on_close)

此代码创建一个 WebSocketApp 对象，该对象表示 WebSocket 连接。 websocket.enableTrace(True) 开启调试模式，可以方便的查看websocket的底层数据交互细节。该构造函数接受 WebSocket 服务器的 URL 以及处理连接事件的回调函数。 

ws.run_forever()

此方法启动 WebSocket 连接并使其保持运行状态，直到连接关闭。 程序将持续监听从交易所传入的消息。

代码解释:

  • api_key 和 api_secret : 必须替换成您在交易所或服务提供商处获得的个人 API Key 和 API Secret。这些凭据是访问API的身份验证密钥，务必妥善保管，切勿泄露，以避免资产损失或安全风险。请注意，不同平台对于API Key和API Secret的权限管理和生成方式可能略有不同，请参考对应平台的官方文档进行操作。
  • generate_wss_signature 函数: 此函数的功能是生成用于WebSocket安全连接的签名。签名是基于您的API Secret，当前时间戳以及其他可能的参数进行加密计算得到的一个字符串。服务器会使用您的API Key和Secret验证该签名的有效性，确保连接的安全性。该函数通常包含加密算法，例如HMAC-SHA256。不同的交易所或服务商可能使用不同的签名算法，需要根据其API文档进行调整。
  • on_open 函数: 这是一个回调函数，当WebSocket连接成功建立后会被自动调用。 on_open 函数的主要作用是在连接建立后立即发送必要的认证信息和订阅请求。没有经过认证的连接无法接收数据，因此发送认证信息是至关重要的步骤。
  • auth : auth 字典包含了用于身份验证的信息，通常包括您的 API Key 和由 generate_wss_signature 函数生成的签名。交易所会使用这些信息来验证您的身份，并授权您访问相应的数据流。认证信息的格式和内容需要严格按照交易所的API文档要求进行构建。认证失败会导致无法接收数据。
  • subscribe : subscribe 字典定义了您希望从WebSocket连接接收的数据类型。通过指定不同的频道或主题，您可以选择性地订阅特定交易对的交易数据(如 "trade:XBTUSD" ，表示订阅比特币/美元永续合约的成交数据)，订单簿更新，ticker信息或其他实时数据。订阅信息的格式和频道名称需要参考交易所的API文档。 错误的订阅信息将导致无法接收到所需的数据。部分交易所支持通过正则表达式进行批量订阅。
  • websocket.WebSocketApp : websocket.WebSocketApp 类是Python WebSocket客户端库的核心组件，用于创建一个WebSocket应用实例。 它接受WebSocket服务器的URL，以及一系列回调函数，如 on_open , on_message , on_error , on_close , 用于处理连接的不同阶段。 通过配置这些回调函数，可以实现对WebSocket连接的灵活控制和数据处理。
  • ws.run_forever() : 此方法用于启动WebSocket应用程序，并保持连接处于运行状态。它会循环监听WebSocket服务器的事件，并在连接断开后自动尝试重新连接。这确保了应用程序可以持续接收实时数据流。 run_forever() 方法会阻塞当前线程，直到连接被手动关闭或发生致命错误。 如果需要在后台运行WebSocket连接，可以使用多线程或异步编程。还可以配置 run_forever() 函数的参数，例如 ping_interval 和 ping_timeout，以保持连接活跃。
WebSocket 接口的优势在于实时性。 你可以立即接收到最新的市场数据，而无需轮询 REST API。

四、常见问题

  • 权限不足: 确保你的 API 密钥拥有执行特定操作所需的足够权限。例如，如果你尝试下单，需要确保 API 密钥具有交易权限。不同的API密钥可能分配不同的权限，请仔细检查API密钥的权限设置，必要时重新生成具有所需权限的API密钥。
  • 签名错误: 检查你的签名算法是否与BitMEX要求的算法一致，并确保使用了正确的 API Secret。签名算法通常包括将请求参数、时间戳和API Secret组合并进行哈希运算。时间戳的准确性也很重要，偏差过大可能导致签名验证失败。仔细核对API Secret，确保没有空格或其他不可见字符。
  • IP 地址限制: 检查你的 API 密钥是否绑定了特定的 IP 地址。如果是，确保你的请求是从绑定的 IP 地址发出的。为了安全起见，BitMEX允许将API密钥绑定到特定的IP地址。如果你的IP地址发生变化，你需要更新API密钥的IP地址绑定设置。或者，你可以取消IP地址限制，但这可能会降低安全性。
  • API 频率限制: BitMEX 对 API 请求的频率有限制，以防止滥用和维护系统稳定。如果超过限制，会返回 HTTP 状态码 429 (Too Many Requests)。可以通过添加延迟（例如，在每次API调用之间暂停几百毫秒）或者使用 WebSocket API 来避免频率限制。WebSocket API 允许你建立一个持久连接，并通过该连接实时接收数据和发送请求，这通常比 REST API 更有效率，且能减少频率限制的影响。考虑使用更高效的查询方式，减少不必要的API调用。
  • 文档不一致: 如果遇到任何疑问或无法解决的问题，请务必参考最新的 BitMEX 官方 API 文档。API 文档会定期更新，其中包含了最新的接口说明、参数定义、错误代码和示例代码。BitMEX官方会提供示例代码，有助于理解API的使用方法。

请仔细阅读 BitMEX 官方 API 文档，了解更多信息和示例代码，以便更好地理解 API 的使用方法和限制。详细阅读错误代码说明，有助于快速定位和解决问题。在开发过程中，可以使用API的测试环境进行调试，避免对真实交易环境造成影响。