BitMEX API接口申请指南：开启加密货币交易掘金之旅

from bitmex import bitmex

apikey = "YOURAPIKEY" apisecret = "YOURAPISECRET"

client = bitmex(test=False, apikey=apikey, apisecret=apisecret) # test=True 使用测试网

• test=False 表示使用 BitMEX 主网。
• test=True 表示使用 BitMEX 测试网，用于开发和测试。

获取 ETHUSD 的深度数据

为了获取以太坊 (ETH) 兑美元 (USD) 交易对的深度数据，您可以使用 Bybit API 提供的 OrderBook.getL2 方法。此方法允许您检索指定数量的买单和卖单，从而深入了解市场订单簿的结构。

以下代码展示了如何使用 Python Bybit 客户端获取 ETHUSD 的深度数据：

from pybit import usdt_perpetual
client = usdt_perpetual.HTTP(
    endpoint="https://api.bybit.com",  # 替换为您的 API Endpoint
    api_key="YOUR_API_KEY",          # 替换为您的 API 密钥
    api_secret="YOUR_API_SECRET"      # 替换为您的 API 密钥密码
)

order_book = client.OrderBook.OrderBook_getL2(symbol='ETHUSD', depth=2).result()
print(order_book)

代码解释：

• 您需要导入 pybit 库并创建一个 usdt_perpetual.HTTP 客户端实例。
• 在创建客户端时，您需要提供您的 API Endpoint，API 密钥和API 密钥密码。这些凭据用于验证您的身份并授权您访问 Bybit API。请务必妥善保管您的 API 密钥和密码，避免泄露。
• OrderBook.OrderBook_getL2(symbol='ETHUSD', depth=2) 方法用于请求 ETHUSD 交易对的订单簿数据。 symbol 参数指定了交易对， depth 参数指定了要检索的订单簿深度，即买单和卖单的数量。在这个例子中， depth=2 表示我们想要获取最佳的 2 个买单和 2 个卖单。
• .result() 方法用于从 API 响应中提取结果数据。
• print(order_book) 语句用于将检索到的订单簿数据打印到控制台。

返回数据格式：

OrderBook.getL2 方法返回的订单簿数据是一个包含多个字典的列表。每个字典代表一个订单簿条目，包含以下字段：

• symbol : 交易对 (例如: 'ETHUSD')
• id : 订单簿条目的唯一 ID
• side : 订单簿条目的类型 ('Buy' 或 'Sell')
• price : 订单簿条目的价格
• size : 订单簿条目的数量

通过分析这些数据，您可以了解当前市场上的买卖压力，并制定相应的交易策略。请注意，订单簿数据是动态变化的，需要定期更新以保持准确性。

下单

在加密货币交易中，下单是指在交易所提交买入或卖出某种加密货币的指令。通过编程方式下单，可以实现自动化交易策略，提高交易效率。以下示例展示了如何使用客户端库创建一个限价买单。

order = client.Order.Order_new(symbol='ETHUSD', side='Buy', orderQty=1, price=2000, ordType='Limit').result()

这行代码的功能是向交易所提交一个新的订单。让我们详细分解每个参数的含义：

• client.Order.Order_new() : 这是客户端库中用于创建新订单的函数。不同的交易所和客户端库可能有不同的命名方式，但核心功能都是相同的。
• symbol='ETHUSD' : 指定交易的交易对。在这个例子中，是 ETH/USD，即用美元购买以太坊。交易所通常使用特定的代码来表示交易对。
• side='Buy' : 指定订单的方向，即买入或卖出。这里是 'Buy'，表示买入订单。相应的，卖出订单通常使用 'Sell' 表示。
• orderQty=1 : 指定订单的数量。在这个例子中，是买入 1 个 ETH。数量的单位取决于交易对中基础货币的单位。
• price=2000 : 指定订单的价格。由于 ordType 设置为 'Limit'，这表示这是一个限价单，只有当市场价格达到或低于 2000 美元时，订单才会成交。
• ordType='Limit' : 指定订单的类型。'Limit' 表示限价单，用户可以指定订单的成交价格。其他常见的订单类型包括市价单 ('Market')，即以当前市场价格立即成交的订单。
• .result() : 执行订单请求，并获取返回结果。返回结果通常包含订单的详细信息，例如订单 ID、状态、成交价格等。

print(order)

这行代码用于打印订单的详细信息，方便用户查看订单是否成功提交，以及订单的当前状态。返回的 order 对象通常包含交易所返回的各种字段，例如订单ID，创建时间，更新时间，订单状态（例如：新建、已成交、已取消）等。开发者可以根据实际需求解析和处理这些信息。

2.2 常用 API 接口

BitMEX API 提供了全面的接口集合，覆盖了从实时市场数据抓取到账户管理、订单执行等关键交易环节。利用这些接口，开发者可以构建自动化交易策略、风险管理系统以及数据分析工具。以下是一些常用的 API 接口，并对其功能和使用场景进行详细说明：

• GET /api/v1/instrument : 获取合约信息。此接口允许查询所有或特定合约的详细信息。返回数据包括合约代码（symbol）、标的资产、结算货币、最小合约价值、保证金比例（initial margin & maintenance margin）、结算时间（settle）、交割日期、以及其他相关合约参数。这些信息对于理解合约条款和风险至关重要。
• GET /api/v1/orderBook/L2 : 获取深度数据（Level 2 Order Book）。此接口提供指定合约的实时买卖盘挂单信息，按照价格排序，显示每个价格档位的挂单数量。深度数据对于高频交易、算法交易和市场微观结构分析至关重要，能够帮助交易者了解市场流动性、支撑阻力位和潜在的价格波动。通常需要订阅才能获取实时更新。
• GET /api/v1/trade : 获取成交记录。此接口返回指定合约的历史成交数据，包括成交价格、成交数量、成交时间以及成交方向（买入或卖出）。通过分析成交记录，可以了解市场的交易活跃度、价格趋势和交易量分布，用于技术分析和回溯测试。
• GET /api/v1/user/margin : 获取账户余额和保证金信息。此接口用于查询账户的资金状况，包括可用余额（available balance）、已用保证金（used margin）、未实现盈亏（unrealized profit/loss）、已实现盈亏（realized profit/loss）、以及总权益（wallet balance）。它是监控账户风险和调整交易策略的关键接口。
• POST /api/v1/order : 下单。此接口用于创建新的订单。支持多种订单类型，如限价单（limit order）、市价单（market order）、止损单（stop order）、冰山单（iceberg order）等。下单时需要指定合约代码、订单类型、买卖方向（side）、订单数量（quantity）和价格（对于限价单）。
• PUT /api/v1/order : 修改订单。此接口允许修改已存在的未成交订单。可以修改订单的价格、数量等参数。修改订单需要提供原始订单的订单ID（orderID）。这对于在市场变化时调整交易策略非常有用。
• DELETE /api/v1/order : 撤销订单。此接口用于撤销尚未成交的订单。撤销订单需要提供订单ID（orderID）。可以单个撤销，也可以批量撤销。
• GET /api/v1/position : 获取持仓信息。此接口用于查询当前持仓的详细信息，包括持仓数量、平均持仓成本（average entry price）、未实现盈亏（unrealized profit/loss）、已实现盈亏（realized profit/loss）、保证金占用（margin used）、以及强平价格（liquidation price）。监控持仓信息是风险管理的重要组成部分。

2.3 API 限流

BitMEX API 实施了严格的请求频率限制策略，旨在防止恶意滥用和保障平台的稳定运行。理解并遵守这些限流规则对于成功地与 BitMEX API 集成至关重要，避免因超出限制而导致请求失败。

• 公共 API (Public API): 公共 API 主要提供无需身份验证即可访问的市场数据，例如交易对的最新成交价、深度信息等。由于访问量较大，公共 API 的限流规则相对宽松，但仍然需要注意避免短时间内发送大量请求。
• 私有 API (Private API): 私有 API 允许用户执行需要身份验证的操作，例如下单、修改订单、查询账户余额等。由于这些操作涉及到用户的资金安全和交易执行，私有 API 的限流规则更为严格。过度请求私有 API 可能会导致账户被暂时限制访问。

BitMEX 官方文档详细列出了各个 API 端点的具体限流规则，包括每分钟或每秒允许的最大请求数量。开发者应仔细阅读文档，并根据实际需求进行合理的请求规划。当请求超过限流阈值时，API 通常会返回特定的 HTTP 错误码，例如 429 (Too Many Requests)。此时，应用程序应暂停发送请求，并根据 Retry-After 响应头（如果存在）指示的时间进行等待，然后再尝试重新发送请求。为了更有效地管理 API 调用，可以考虑以下策略：

• 批量请求: 对于支持批量操作的 API 端点，可以将多个相关的请求合并成一个请求发送，从而减少总的请求次数。例如，可以一次性提交多个限价单，而不是逐个提交。
• 使用 WebSocket: BitMEX 提供了 WebSocket API，允许用户实时订阅市场数据和账户信息。通过建立持久的 WebSocket 连接，应用程序可以接收推送更新，而无需定期轮询 API，显著降低了请求频率。
• 使用缓存: 对于不经常变化的数据，例如交易对的信息、账户配置等，可以将其缓存在本地。在发起 API 请求之前，先检查本地缓存是否有效，避免不必要的重复请求。合理设置缓存过期时间，确保数据的及时更新。

3. WebSocket 实时数据流

BitMEX 提供强大的 WebSocket API，允许用户实时订阅和接收市场数据更新，例如最新成交价、深度行情、以及订单簿变化。WebSocket 是一种先进的双向通信协议，相较于传统的 HTTP 请求-响应模式，它能够在客户端和服务器之间建立持久连接，从而实现服务器主动向客户端推送数据，无需客户端频繁轮询。这种实时数据流对于高频交易者、量化交易团队和需要快速响应市场变化的应用程序至关重要。

通过 WebSocket，用户可以订阅多种数据流，包括但不限于：

• 市场数据： 实时交易价格、交易量、以及买卖盘口信息。
• 订单簿数据： 订单簿的实时更新，包括新增、修改和删除的订单。
• 订单状态： 用户自身订单的状态变化，例如订单创建、成交、取消或被拒绝。
• 账户信息： 账户余额、保证金水平等信息的实时更新。

使用 WebSocket 接口需要进行身份验证，并且需要根据 BitMEX 的 API 文档正确构造订阅消息。开发者可以使用各种编程语言和 WebSocket 客户端库来连接和处理数据流。需要注意的是，高频率的数据推送可能会对客户端的性能产生影响，因此需要合理控制订阅的数据量和处理速度。

3.1 连接 WebSocket

为了实时接收BitMEX交易所的数据流，例如交易行情、订单簿更新和账户信息，可以使用 Python 的 websocket-client 库连接到BitMEX提供的WebSocket接口。通过WebSocket连接，应用程序能够保持与服务器的持久连接，从而高效地接收推送的数据，避免频繁建立和关闭连接的开销。

1. 安装 websocket-client 库： 在开始之前，请确保已经安装了 websocket-client 库。 使用 pip 包管理器可以轻松完成安装：

   pip install websocket-client

   这条命令会从Python Package Index (PyPI) 下载并安装最新版本的 websocket-client 库及其依赖项。

安装 WebSocket 客户端库

在 Python 环境中，可以使用 websocket-client 库来建立和管理 WebSocket 连接。这个库提供了一个易于使用的 API，方便开发者在客户端应用程序中集成 WebSocket 功能。安装过程非常简单，只需使用 Python 的包管理工具 pip 即可。

安装步骤：

打开终端或命令提示符，并执行以下命令：

pip install websocket-client

执行该命令后， pip 将会自动从 Python Package Index (PyPI) 下载并安装 websocket-client 库及其依赖项。安装完成后，就可以在 Python 代码中导入并使用该库了。

验证安装：

为了验证 websocket-client 库是否成功安装，可以在 Python 解释器中尝试导入该库：

import websocket

如果没有出现任何错误提示，则表示该库已成功安装。如果出现 ModuleNotFoundError 错误，则表明安装过程可能存在问题，需要重新执行安装命令或检查 Python 环境配置。

连接 WebSocket:

使用 Python 的 websocket 库可以方便地建立 WebSocket 连接，从而实时接收数据。需要安装该库：

pip install websocket-client

然后，导入必要的模块：

import websocket
import 

定义消息处理函数 on_message 。当 WebSocket 接收到消息时，该函数会被调用，并将消息内容打印到控制台：

def on_message(ws, message):
    print(message)

定义错误处理函数 on_error 。如果在 WebSocket 连接过程中发生任何错误，该函数会被调用，并将错误信息打印到控制台：

def on_error(ws, error):
    print(error)

定义连接关闭处理函数 on_close 。当 WebSocket 连接关闭时，该函数会被调用，并打印 "### closed ###" 到控制台：

def on_close(ws):
    print("### closed ###")

定义连接打开处理函数 on_open 。当 WebSocket 连接成功建立后，该函数会被调用。在此函数中，可以发送订阅消息，例如订阅 BitMEX 交易所 XBTUSD 交易对的深度数据（Level 2，深度25档）：

def on_open(ws):
    print("### opened ###")
    ws.send(.dumps({"op": "subscribe", "args": ["orderBookL2_25:XBTUSD"]})) # 订阅 XBTUSD 的深度数据

op 字段指定操作类型为 "subscribe"， args 字段是一个列表，包含要订阅的主题。 orderBookL2_25:XBTUSD 表示订阅 XBTUSD 的 Level 2 深度数据，深度为 25 档。

在主程序中，创建 WebSocketApp 实例，并配置相应的回调函数。同时，启用 WebSocket 的跟踪功能，以便在控制台输出调试信息。选择连接到 BitMEX 的实时数据 WebSocket 接口（可以是主网或测试网）：

if __name__ == "__main__":
    websocket.enableTrace(True)
    ws = websocket.WebSocketApp("wss://www.bitmex.com/realtime",  # 主网: wss://www.bitmex.com/realtime, 测试网: wss://testnet.bitmex.com/realtime
                              on_message = on_message,
                              on_error = on_error,
                              on_close = on_close)
    ws.on_open = on_open
    ws.run_forever()

websocket.enableTrace(True) 开启调试信息输出。 ws = websocket.WebSocketApp(...) 创建 WebSocket 应用实例，指定连接地址和回调函数。 ws.run_forever() 启动 WebSocket 连接，并保持运行状态，直到连接中断。

注意：BitMEX 提供了主网和测试网两个 WebSocket 接口。在进行测试时，建议使用测试网接口 wss://testnet.bitmex.com/realtime 。

3.2 订阅频道

成功建立 WebSocket 连接后，为了接收特定市场的数据更新，必须订阅相应的频道。BitMEX 通过频道提供实时数据流，涵盖了从市场深度到账户信息的多种数据类型。

BitMEX 提供了丰富的频道选项，允许用户根据自身需求定制数据流。以下是一些常用的频道示例：

• orderBookL2_25:XBTUSD ：提供 XBTUSD 交易对的 Level 2 深度数据，包含买单和卖单的挂单价格和数量，深度为 25 档。这个频道对于高频交易和订单簿分析至关重要。
• trade:XBTUSD ：实时推送 XBTUSD 交易对的成交记录，包括成交价格、成交数量以及交易时间。适用于追踪市场动向和交易量分析。
• instrument:XBTUSD ：提供 XBTUSD 合约的详细信息，例如合约乘数、结算货币、保证金要求和交易状态等。用于获取合约参数和风险管理。
• position ：提供当前账户的持仓信息，包括持仓数量、平均持仓成本、未实现盈亏和杠杆倍数。该频道需要身份验证，确保账户信息的安全。
• order ：实时更新账户的订单信息，包括订单状态、订单价格、订单数量和订单类型。同样需要身份验证，保障交易数据的私密性。

订阅频道需要向 WebSocket 服务器发送特定的 JSON 格式消息。使用 ws.send() 方法发送订阅请求，消息体需要包含 op （操作）和 args （参数）字段。 op 字段设置为 "subscribe"， args 字段是一个包含要订阅频道名称的数组。

例如，以下代码展示了如何使用 Python 的 .dumps() 方法创建一个 JSON 字符串，并将其发送到 WebSocket 服务器以订阅 orderBookL2_25:XBTUSD 和 trade:XBTUSD 频道：

ws.send(.dumps({"op": "subscribe", "args": ["orderBookL2_25:XBTUSD", "trade:XBTUSD"]}))

请注意，订阅多个频道可以在 args 数组中包含多个频道名称，从而在一个请求中完成多个频道的订阅。成功订阅后，WebSocket 连接将开始接收订阅频道的数据更新。

3.3 认证

为了保障数据安全和用户权益，部分频道，例如涉及实时交易数据的 position （持仓）频道和 order （订单）频道，要求用户进行身份认证后才能订阅。未经认证的用户将无法访问这些敏感数据。

认证的核心在于生成有效的签名。该签名基于您的API Key（应用程序编程接口密钥）和Secret Key（私密密钥）通过特定的加密算法生成。API Key用于标识您的身份，Secret Key用于安全地生成签名，切勿泄露您的Secret Key。

认证过程通常包括以下步骤：

1. 获取API Key和Secret Key： 在您的交易所账户中创建或获取API Key和Secret Key。确保您已启用所需的API权限，例如订阅特定频道的数据。
2. 构建认证消息： 根据交易所的要求，构建包含必要信息的认证消息。通常包括时间戳、请求路径、请求方法和请求参数。
3. 生成签名： 使用Secret Key和指定的加密算法（例如HMAC-SHA256）对认证消息进行签名。
4. 发送认证请求： 将API Key和生成的签名包含在请求头或请求体中，发送到交易所的认证端点。
5. 验证认证结果： 交易所会验证您提供的API Key和签名。如果验证通过，您将获得访问相应频道的权限。

更详细、准确的认证流程和代码示例，请务必参考BitMEX或其他相关交易所的官方API文档。不同的交易所可能采用不同的认证机制，官方文档会提供最权威和最新的信息，包括支持的加密算法、认证消息的格式以及错误代码的解释。仔细阅读并理解官方文档是成功进行API认证的关键。

4. 错误处理

与 BitMEX API 的交互并非总是顺利无阻，开发者在使用过程中不可避免地会遇到各类错误，这些错误可能源于多种因素，例如但不限于：间歇性网络连接问题、API 访问频率限制（即限流）、请求参数不符合API规范、服务器内部错误，甚至是用户权限不足等。为了确保交易程序的健壮性和可靠运行，必须实施一套完善的错误处理机制。

• 异常捕获与处理: 采用 try...except 语句块是Python编程中处理异常的标准做法。通过将可能抛出异常的API调用代码置于 try 块中，并在 except 块中定义针对特定异常类型的处理逻辑，可以有效地防止程序因未捕获的异常而崩溃。例如，可以捕获 requests.exceptions.RequestException 来处理网络请求相关的错误，或自定义异常类来处理特定API返回的错误代码。
• 请求重试机制: 针对某些瞬时性或可恢复的错误，如临时的网络中断或服务器过载导致的请求失败，实施自动重试机制是一种有效的解决方案。可以设置最大重试次数和重试间隔时间，在每次重试前进行短暂的休眠，以避免对服务器造成过大的压力。在达到最大重试次数后，如果请求仍然失败，则记录错误信息并采取适当的措施，如告警或停止交易。
• 详细的日志记录: 详细的日志记录是诊断和解决问题的关键。应该将所有重要的事件，包括API请求、响应、错误信息、以及任何其他相关的调试信息，都记录到日志文件中。日志信息应包含时间戳、错误级别、错误代码、错误消息、堆栈跟踪等，以便于追踪问题的根源。建议使用专门的日志库，如Python的 logging 模块，来实现灵活的日志配置和管理。
• API 返回码的校验与解读: BitMEX API 通过返回码（HTTP 状态码和自定义错误码）来指示请求的结果。开发者应该仔细检查API返回的HTTP状态码和错误信息。例如，4xx状态码通常表示客户端错误（如参数错误、权限不足），而5xx状态码表示服务器错误。BitMEX API 文档详细描述了各种错误码的含义和可能的解决方案，开发者应参考文档来理解错误原因并采取相应的措施。自定义错误码通常包含更详细的错误信息，有助于精确定位问题。