BitMEX API 接口申请条件及使用方法
BitMEX (Bitcoin Mercantile Exchange) 是一家提供比特币和其他加密货币衍生品交易的平台。其强大的 API 接口允许开发者自动化交易策略、获取市场数据以及集成到第三方应用程序中。本文将详细介绍 BitMEX API 的申请条件和使用方法。
BitMEX API 概述
BitMEX API 提供全面的功能，允许开发者构建各种加密货币交易应用程序。其主要功能包括：
- 实时市场数据： 获取最新、最准确的市场数据，包括实时交易价格、订单簿深度（买盘和卖盘的挂单情况）以及成交量信息。这些数据对于算法交易、市场分析和风险管理至关重要。
- 交易下单和管理： 通过程序化方式创建、修改和取消订单，支持限价单、市价单、止损单等多种订单类型。API 提供了灵活的订单参数配置，以满足不同的交易策略需求。
- 账户管理： 查询账户余额、当前持仓信息（包括多头和空头头寸）以及历史交易记录。开发者可以利用这些信息监控账户状态、评估交易表现和进行风险控制。
- 结算和历史数据： 获取详细的结算信息，包括每日结算价格、结算费率等。同时，API 提供历史市场数据下载，用于回测交易策略、构建量化模型和进行历史趋势分析。
BitMEX API 主要分为 REST API 和 WebSocket API 两种类型，分别适用于不同的应用场景。
- REST API： 采用基于 HTTP 请求的架构，适用于执行特定的操作，例如下单、修改订单、查询账户信息等。 REST API 遵循请求-响应模型，客户端发送一个 HTTP 请求到服务器，服务器处理请求后返回一个响应。这种方式简单易用，适合于执行一次性的操作。REST API 通常使用 JSON 格式传输数据，便于解析和处理。
- WebSocket API： 提供一个持久化的双向通信通道，适用于需要实时接收市场数据和事件的场景。客户端和服务器之间建立一个长连接，服务器可以主动推送数据到客户端，无需客户端频繁发送请求。WebSocket API 在低延迟、高并发的场景下表现出色，适合于构建实时交易系统、行情监控工具等。通过订阅不同的频道，可以接收特定交易对的实时价格更新、订单簿变化、交易执行情况等信息。
BitMEX API 申请条件
申请 BitMEX API Key 需要满足以下条件，确保您能安全有效地使用其功能：
- BitMEX 账户: 您必须拥有一个活跃的 BitMEX 账户。如果您还没有账户，请访问 BitMEX 官方网站进行注册。注册过程通常需要您提供有效的邮箱地址、设置强密码，并根据平台的指示完成账户激活。请注意，选择一个安全且难以猜测的密码至关重要，并妥善保管您的账户信息。
- KYC 验证: 为了遵守全球范围内的反洗钱 (AML) 和了解你的客户 (KYC) 法规，BitMEX 强制要求用户完成 KYC 验证流程。根据您的交易需求和账户类型，KYC 验证可能分为不同的等级。通常，您需要提交身份证明文件（如护照、身份证）、地址证明文件（如银行账单、水电费账单）以及其他可能被要求的文件。更高的验证等级通常意味着更高的 API 使用权限和交易限额。请确保您提供的所有信息真实有效，并及时更新，以避免账户受限。
-
API Key 权限设置:
在您的 BitMEX 账户中，您可以创建并管理 API Key。创建 API Key 时，必须谨慎设置其权限，以控制其可以执行的操作。权限包括：
- 交易权限: 允许 API Key 代表您进行交易，例如下单、取消订单等。
- 提现权限: 允许 API Key 从您的 BitMEX 账户中提取资金。 强烈建议不要授予 API Key 提现权限，以防止未经授权的资金转移。
- 数据读取权限: 允许 API Key 访问市场数据、账户余额、交易历史等信息。
- 风险提示: 加密货币交易，特别是使用杠杆的 BitMEX 交易，inherently 涉及高风险。使用 API 进行自动化交易需要您具备扎实的编程知识、对 BitMEX 交易规则的深入理解以及有效的风险管理能力。在部署 API 之前，请务必进行充分的测试，并使用模拟账户进行验证。BitMEX 官方也会明确提示用户了解所有潜在风险，并承担因使用 API 产生的任何后果，包括但不限于资金损失、系统故障等。请审慎评估自身风险承受能力，并量力而行。
- 遵守 API 使用条款: 使用 BitMEX API 必须严格遵守其官方使用条款。这些条款详细规定了 API 的使用规范、限制以及法律责任。违反使用条款可能导致您的 API Key 被立即禁用，甚至您的 BitMEX 账户可能被永久冻结。请定期阅读并理解 BitMEX 的 API 使用条款，确保您的使用行为符合其规定，维护良好的交易环境。常见的违规行为包括但不限于：滥用 API 接口、干扰平台运营、进行市场操纵等。
BitMEX API 使用方法
获得 BitMEX API Key 和 Secret 后，便可以通过编程方式与 BitMEX 交易所进行交互。BitMEX API 提供了广泛的功能，包括下单、查询账户信息、获取市场数据等。你可以使用各种编程语言（如 Python、JavaScript、Java、C# 等）调用 BitMEX API。以下以 Python 为例，详细介绍如何通过 Python 使用 BitMEX API 进行身份验证和基本操作。
在使用 Python 调用 BitMEX API 之前，你需要安装 BitMEX 官方提供的 Python 库，通常可以使用 pip 进行安装：
pip install bitmex-api
。此库封装了与 BitMEX API 交互的底层细节，简化了开发过程。
在进行 API 调用时，需要进行身份验证。身份验证通过 API Key 和 Secret 实现。API Key 用于标识你的账户，Secret 用于生成 API 请求的签名，确保请求的安全性。请务必妥善保管你的 API Key 和 Secret，避免泄露。
以下是使用 Python 通过 BitMEX API 获取账户余额的示例代码：
import bitmex
api_key = 'YOUR_API_KEY'
api_secret = 'YOUR_API_SECRET'
client = bitmex.bitmex(test=False, api_key=api_key, api_secret=api_secret)
try:
account = client.User.User_getMargin().result()
balance = account[0]['walletBalance'] / 100000000 # 余额以聪为单位，需要转换为 XBT
print(f"账户余额：{balance} XBT")
except Exception as e:
print(f"API 调用失败：{e}")
上述代码首先导入
bitmex
库，然后使用你的 API Key 和 Secret 创建一个 BitMEX 客户端实例。
test=False
表示使用正式环境的 API。接下来，调用
User.User_getMargin()
方法获取账户保证金信息。获取到的保证金信息包含账户余额，以聪（satoshis）为单位，需要除以 100,000,000 转换为 XBT。打印账户余额。如果在 API 调用过程中发生任何错误，将捕获异常并打印错误信息。
除了获取账户余额，你还可以使用 BitMEX API 执行其他操作，例如：
-
下单：使用
Order.Order_new()方法可以创建新的订单。 -
取消订单：使用
Order.Order_cancel()方法可以取消订单。 -
获取订单状态：使用
Order.Order_getOrders()方法可以获取订单状态。 -
获取市场数据：使用
Trade.Trade_get()和Quote.Quote_get()方法可以获取交易和报价数据。
在实际使用 BitMEX API 时，请务必仔细阅读 API 文档，了解每个接口的参数和返回值，并根据你的需求进行调用。同时，请注意控制 API 调用的频率，避免触发速率限制。BitMEX API 文档提供了详细的速率限制说明。
1. 安装依赖库:
在开始之前，你需要确保你的开发环境中安装了 BitMEX API 的 Python 客户端库。这个库简化了与 BitMEX 交易所进行交互的复杂性，提供了便捷的函数和类来处理 API 请求和响应。
你可以使用 Python 的包管理工具 pip 来安装
bitmex-api
库。打开你的终端或命令提示符，然后执行以下命令：
pip install bitmex-api
这条命令会从 Python Package Index (PyPI) 下载并安装
bitmex-api
及其所有必要的依赖项。安装完成后，你就可以在你的 Python 脚本中导入并使用该库了。
如果你的环境中存在多个 Python 版本，你可能需要使用
pip3
来确保为正确的 Python 版本安装库。例如：
pip3 install bitmex-api
你也可以通过指定版本号来安装特定版本的
bitmex-api
，例如：
pip install bitmex-api==1.2.3安装完成后，建议通过简单的导入测试来验证安装是否成功。在 Python 解释器中尝试以下操作：
import bitmex
print(bitmex.__version__)
如果成功打印出
bitmex-api
的版本号，则说明安装已成功。
2. 导入库和设置 API Key：
你需要导入 BitMEX 的 Python 客户端库，该库封装了与 BitMEX API 交互所需的各种函数和方法。
import bitmex
接下来，你需要设置你的 API Key 和 API Secret。这些密钥用于身份验证，允许你的程序访问你的 BitMEX 账户并执行交易。请务必妥善保管你的 API Secret，避免泄露。
api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"
然后，你需要创建一个 BitMEX 客户端实例。创建客户端时，你需要提供你的 API Key 和 API Secret，并指定交易环境（真实或测试）。
test=False
参数表示使用 BitMEX 的真实交易环境，这意味着你将使用真实的资金进行交易。如果要在测试环境（Testnet）中进行交易，可以将
test
设置为
True
。使用测试环境可以让你在不冒真实资金风险的情况下测试你的交易策略和程序。
client = bitmex.bitmex(test=False, api_key=api_key, api_secret=api_secret) # test=False 表示使用真实交易环境
请务必将代码中的
YOUR_API_KEY
和
YOUR_API_SECRET
替换为你实际从 BitMEX 平台获取的 API Key 和 Secret。API Key 用于标识你的应用程序，而 API Secret 用于验证你的身份。
test=False
设置为使用真实的 BitMEX 交易环境。如果需要在测试环境（Testnet）中使用 API，则应将
test
设置为
True
。在测试环境中交易允许你在不承担实际财务风险的情况下安全地测试你的代码和策略。
3. 调用 REST API:
以下代码展示了如何使用 REST API 获取账户余额。通过调用
User_getMargin()
方法，可以获取账户的保证金信息，包括可用余额、已用保证金等关键数据。该接口返回的数据结构包含了账户的风险敞口和财务状况的详细信息，对于风险管理和交易决策至关重要。
try:
account = client.User.User_getMargin().result()
print(account)
except Exception as e:
print(f"Error: {e}")
以下代码展示了如何使用 REST API 下一个限价单。限价单允许交易者指定一个特定的价格来买入或卖出一定数量的资产。只有当市场价格达到或优于指定价格时，订单才会被执行。这是一种常用的交易策略，可以帮助交易者在特定价位入场或离场，从而控制交易成本和风险。
在下面的示例中，
symbol
变量指定了交易的合约代码，例如'XBTUSD'代表比特币/美元永续合约。
orderQty
定义了订单的数量，这里设置为1。
price
变量设定了限价单的价格，即20000。
side
变量指示了交易方向，'Buy'表示买入，'Sell'则表示卖出。
ordType='Limit'
明确指定订单类型为限价单。
symbol = 'XBTUSD'
orderQty = 1 # 下单数量
price = 20000 # 限价
side = 'Buy' # 买入方向
以下代码片段展示了如何实际提交限价订单。
Order_new()
函数用于创建新的订单。该函数接收交易标的 (
symbol
)、数量 (
orderQty
)、价格 (
price
)、交易方向 (
side
) 和订单类型 (
ordType
) 作为参数。如果订单成功创建，将返回包含订单详细信息的响应。如果发生任何错误，例如网络问题或无效参数，将捕获异常并打印错误消息，有助于调试和诊断问题。
try:
order = client.Order.Order_new(symbol=symbol, orderQty=orderQty, price=price, side=side, ordType='Limit').result()
print(order)
except Exception as e:
print(f"Error: {e}")
4. 调用 WebSocket API:
以下代码示例展示了如何使用 Python 的
websocket
库，通过 WebSocket API 订阅实时市场数据。 使用 WebSocket 协议，能够建立一个持久的连接，实时接收市场变动信息，降低延迟，实现高效的数据推送。
为了使用该代码，首先需要安装
websocket-client
库。可以使用 pip 命令进行安装：
pip install websocket-client
import websocket import # 引入库来处理JSON数据 def on_message(ws, message): """ 接收到服务器推送消息时调用的函数。 在这里，消息被解析并打印出来。 """ try: data = .loads(message) # 尝试将消息解析为JSON格式 print(data) # 打印解析后的数据 except .JSONDecodeError: print(f"Received non-JSON message: {message}") #如果不是JSON格式，则打印原始消息 def on_error(ws, error): """ 发生错误时调用的函数。 用于记录和处理 WebSocket 连接错误。 """ print(f"WebSocket error: {error}") def on_close(ws, close_status_code, close_msg): """ 连接关闭时调用的函数。 提供了关闭状态码和关闭消息，可以用于诊断连接关闭的原因。 """ print(f"### Connection closed ###\nClose code: {close_status_code}\nClose message: {close_msg}") def on_open(ws): """ 连接建立成功时调用的函数。 在这里，发送订阅请求到服务器。 """ subscribe_message = { "op": "subscribe", "args": ["trade:XBTUSD"] } ws.send(.dumps(subscribe_message)) # 将订阅消息转换为JSON字符串并发送 print("Subscribed to trade:XBTUSD") if __name__ == "__main__": websocket.enableTrace(True) # 启用 WebSocket 追踪，用于调试 # 连接到 BitMEX WebSocket API ws = websocket.WebSocketApp( "wss://www.bitmex.com/realtime", # BitMEX 实时数据 WebSocket 地址 on_message=on_message, on_error=on_error, on_close=on_close ) ws.on_open = on_open # 设置连接建立成功时的回调函数 ws.run_forever() # 保持连接，直到手动停止或发生错误
这段代码会连接到 BitMEX 的 WebSocket API，并订阅 XBTUSD 的交易数据。
wss://www.bitmex.com/realtime
是 BitMEX 提供的 WebSocket 接口地址，用于接收实时市场数据。
trade:XBTUSD
指定了要订阅的数据频道，这里订阅的是 XBTUSD 交易对的实时交易信息。
每当有新的交易发生时，
on_message
函数会被调用，解析并打印出包含交易信息的 JSON 格式数据。通过检查输出的数据，可以获取交易的价格、数量、时间等信息。如果收到非 JSON 格式的消息, 会打印原始消息，方便调试。
请注意，实际使用时，请替换为真实的 API 密钥，并根据需要调整订阅的频道。
5. 错误处理:
在使用 BitMEX API 进行交易或数据获取时，周密的错误处理至关重要。API 请求并非总能成功执行，潜在的失败原因多种多样，包括但不限于：网络连接中断或不稳定、API 密钥权限配置不正确、请求参数格式错误或缺失、以及超出API速率限制等。为确保程序的健壮性和可靠性，必须在代码中集成全面的错误处理机制。
推荐采用
try...except
代码块来捕获可能抛出的异常。这样，当API调用失败时，程序不会崩溃，而是能够优雅地处理错误，并采取适当的应对措施。例如，可以记录错误日志以便后续分析，重试API请求（在遵守速率限制的前提下），或者向用户发出警告。具体的错误处理策略应根据应用场景和业务需求进行定制。
除了捕获异常，还应该仔细检查API返回的HTTP状态码和错误信息。BitMEX API 通常会提供详细的错误信息，有助于诊断问题所在。例如，400状态码表示请求参数错误，403状态码表示权限不足，429状态码表示超出速率限制。通过解析这些错误信息，可以更精确地处理错误，并为用户提供更有意义的反馈。
在处理速率限制错误时，合理的重试策略至关重要。避免立即重试，而是应该采用指数退避算法，逐渐增加重试的间隔时间。这样可以减轻服务器的压力，提高重试成功的可能性。同时，建议监控API的使用情况，并根据实际情况调整速率限制的设置。
6. 安全性:
API Key 是访问加密货币交易所或服务的重要凭证，务必妥善保管，切勿泄露给任何未经授权的第三方。一旦 API Key 泄露，恶意行为者可能利用它来访问你的账户并进行非法操作，造成资金损失或其他严重后果。务必像保护你的银行账户密码一样保护你的 API Key。
绝对不要将 API Key 直接存储在公共代码库中，例如 GitHub 或其他公开的代码托管平台。一旦代码库被公开或被他人访问，API Key 就会暴露，极易被滥用。这是一种非常不安全的做法，应该避免。
使用环境变量或专门的配置文件来存储 API Key 是一种更为安全的做法。环境变量可以将 API Key 存储在操作系统层面，避免直接暴露在代码中。配置文件则可以将 API Key 存储在单独的文件中，并采取相应的权限控制措施，防止未经授权的访问。许多编程语言和框架都提供了便捷的方式来读取环境变量和配置文件，方便在代码中使用 API Key。
定期更换 API Key 是一种有效的安全措施。即使 API Key 没有泄露，定期更换也可以降低潜在的风险。许多交易所或服务都允许用户生成新的 API Key 并停用旧的 API Key。建议根据自身的安全需求，制定合理的 API Key 更换策略，并定期执行。
7. API 文档：
BitMEX 提供了一套全面的应用程序编程接口 (API)，允许开发者通过编程方式与平台进行交互，实现自动化交易、数据分析和其他定制化功能。官方 API 文档是理解和有效使用这些接口的关键资源。该文档详细描述了每个可用 API 接口的功能、请求参数、响应格式以及错误代码，确保开发者能够准确地构建和部署他们的应用程序。
在使用 BitMEX API 时，仔细阅读 API 文档至关重要。文档中包含了每个接口的完整说明，包括其用途、所需参数（例如身份验证凭据、交易对、订单类型、价格和数量），以及返回的数据结构。理解这些细节能够避免常见的错误，并确保应用程序能够正确地与 BitMEX 平台进行交互。
API 文档通常包含示例代码片段，展示如何在不同的编程语言（如 Python、JavaScript、Java 等）中使用 API 接口。这些示例可以作为快速入门的指南，帮助开发者理解如何构造 API 请求、处理响应数据以及处理可能的错误情况。开发者应该根据自己的编程语言和需求，参考这些示例并进行相应的调整。
API 文档还会说明 API 的使用限制，例如请求频率限制（Rate Limits）。这些限制旨在保护平台的稳定性和性能，防止恶意或过度的 API 调用。开发者需要了解这些限制，并确保他们的应用程序不会超出允许的请求频率，否则可能会被暂时或永久地限制访问。
BitMEX 官方 API 文档的地址可以在 BitMEX 官网上找到。建议定期查阅该文档，以获取最新的 API 更新、功能添加和更改通知。及时了解这些信息可以确保您的应用程序始终与最新的 API 版本兼容，并能够利用最新的功能。
除了官方文档，BitMEX 社区中也有许多开发者分享了他们使用 API 的经验和技巧。参与社区讨论、阅读相关的博客文章和教程，可以帮助您更深入地理解 BitMEX API，并解决在开发过程中遇到的问题。但请注意，始终以官方文档为准，并谨慎对待来自非官方渠道的信息。
8. 版本控制:
BitMEX API 作为持续迭代的金融工具，可能会进行版本更新，从而引入新的功能、修复已知问题或者优化性能。这些版本更新有可能导致 API 接口发生变化，例如参数的调整、返回数据的格式变更或者新增端点。
因此，在使用 BitMEX API 时，务必密切关注 BitMEX 官方发布的公告、更新日志以及开发者文档。这些渠道会及时发布最新的 API 版本信息以及详细的更新内容，包括新功能介绍、废弃的端点、以及任何可能影响现有集成方式的变更。
建议开发者定期检查其应用程序与最新 API 版本的兼容性，并根据官方发布的指南进行必要的调整和升级。未及时更新可能导致应用程序出现错误、数据不一致或者无法正常访问 API 服务。
了解 BitMEX API 的版本控制策略也很重要，例如是否支持向后兼容，或者是否需要迁移到新的版本才能继续使用某些功能。可以通过查阅官方文档或联系 BitMEX 的技术支持团队来获取更多信息。
9. 限速机制：API调用的频率限制
BitMEX API实施了一套完善的限速机制，旨在保护服务器资源，防止恶意或无意的API滥用行为，确保所有用户的公平访问和系统稳定运行。当API请求的频率超过预设的阈值，BitMEX服务器将对该客户端的后续请求进行限制，即触发限速。
触发限速通常表现为API调用返回错误状态码，例如HTTP 429 "Too Many Requests"。错误信息中通常会包含重试所需等待的时间，允许开发者在冷却期结束后再次尝试API调用。理解并妥善处理限速是构建稳定可靠的BitMEX API应用的关键。
合理控制API调用频率至关重要，开发者应采取以下策略避免触发限速：
- 批量处理： 尽可能将多个API请求合并为一个，减少总的请求次数。例如，如果需要获取多个合约的信息，可以使用支持批量查询的API端点。
- 使用WebSocket： 对于需要实时数据更新的应用，优先使用WebSocket API。WebSocket提供持久连接，避免了频繁的HTTP请求，显著降低了触发限速的风险。
- 实施重试机制： 当遇到限速错误时，不要立即放弃。实施指数退避算法，逐步增加重试间隔时间，直到请求成功或达到最大重试次数。
- 缓存数据： 对于不经常变化的数据，可以将其缓存在本地，减少对API的依赖。设置合理的缓存过期时间，确保数据的时效性。
- 监控API使用情况： 定期检查API调用频率，识别并优化潜在的瓶颈。BitMEX可能提供API使用统计信息，开发者可以利用这些数据进行分析。
- 优化代码： 检查代码逻辑，消除不必要的API调用。例如，避免在循环中频繁调用API，或者使用更高效的算法减少数据处理量。
通过以上策略，开发者可以有效地控制API调用频率，降低触发限速的风险，确保应用程序的稳定性和可靠性。务必参考BitMEX官方API文档，了解具体的限速规则和最佳实践。
10. 市场深度数据的使用:
BitMEX API 提供市场深度数据 (Order Book)，它是反映市场买卖力量的重要指标。 理解并有效利用这些数据，对于制定交易策略和风险管理至关重要。使用者务必充分理解 Level 1, Level 2 和 Full Book 三种不同深度级别的概念，并根据自身交易策略和API调用频率的需求，明智地选取最适合的深度级别。 盲目地或过度频繁地请求 Full Book 可能会迅速触及 API 的速率限制，导致请求失败和交易中断。 因此，根据实际需要选择合适的市场深度级别至关重要。
Level 1 ：Level 1 数据提供市场上最佳的出价（最高买入价）和要价（最低卖出价）。 这是最基础的市场深度信息，适合对市场价格变动有快速反应需求的交易者。 Level 1 数据量小，请求速度快，适合高频交易和快速决策。 通过观察最佳买卖价格，可以快速了解市场的供需情况。
Level 2 ：Level 2 数据在 Level 1 的基础上，进一步提供多个价位的订单薄信息。 它通常会显示买方和卖方的前 N 个最佳价格和对应的订单数量。 这能让交易者更全面地了解市场上的买卖力量分布，判断支撑位和阻力位。 Level 2 数据适用于需要更深入了解市场结构，并根据订单薄情况进行交易决策的交易者。 例如，可以观察特定价格的订单量来判断价格突破的可能性。
Full Book ：Full Book 数据提供完整的订单薄信息，包括所有挂单的价格和数量。 虽然 Full Book 提供了最全面的市场信息，但它也意味着最大的数据量。 频繁请求 Full Book 会消耗大量的带宽和计算资源，更容易触发 API 的速率限制。 因此，只有在对完整订单薄数据有特殊需求的场景下，才建议使用 Full Book。 例如，一些高级交易策略可能需要分析整个订单薄的形状来预测价格走势。
在实际应用中，应该根据交易策略的需求和 API 的速率限制，合理选择市场深度数据级别。 对于需要快速响应市场价格变化的交易者，Level 1 可能足够；对于需要更深入了解市场结构的交易者，Level 2 可能更适合；只有在少数情况下，才需要使用 Full Book。 同时，也要注意优化 API 调用策略，避免过度请求 Full Book，以确保 API 调用的稳定性和可靠性。 合理利用市场深度数据，可以帮助交易者更好地了解市场，制定更有效的交易策略，并降低交易风险。
