使用BitMEX API 进行自动化交易：从入门到精通
BitMEX 作为领先的加密货币衍生品交易所，提供强大的 API (应用程序编程接口) ，允许开发者构建自动化交易策略。 本文将深入探讨如何使用 BitMEX API 进行自动化交易，涵盖从 API 密钥获取到实际代码示例的关键步骤。
1. 获取 BitMEX API 密钥
要开始使用 BitMEX API 进行自动化交易或数据分析，您首先需要在 BitMEX 交易所注册一个账户。 注册成功后，务必完成必要的身份验证（KYC）流程，以确保符合交易所的规定并解锁全部 API 功能。 完成注册和验证后，登录您的 BitMEX 账户，然后导航至账户设置或个人资料设置中的 "API Keys" 部分。 这个部分通常位于安全设置或类似的标签下。
在 "API Keys" 部分，您会找到一个创建新 API 密钥的选项，通常标记为 "创建 API 密钥" 或类似按钮。 点击该按钮以开始创建过程。 创建 API 密钥时，需要仔细配置以下关键参数，以确保安全性和功能性：
- API Key Name: 为您的 API 密钥指定一个清晰且易于识别的名称，例如 "TradingBot" 或 "ArbitrageStrategy"。 这样做有助于您区分不同的 API 密钥，尤其是在您有多个交易机器人或应用程序使用 API 的情况下。
-
CIDR Whitelist:
为了最大程度地提高安全性，强烈建议限制 API 密钥的访问 IP 地址。 输入您运行交易机器人的服务器或计算机的公网 IP 地址。 这意味着只有来自这些特定 IP 地址的请求才能使用该 API 密钥。 如果您不确定服务器的 IP 地址，可以使用在线 IP 查询工具。 在开发或测试阶段，您可以暂时将其设置为
0.0.0.0/0以允许来自任何 IP 地址的访问，但强烈建议在生产环境中避免这样做。 细粒度的 IP 限制可以有效防止未经授权的访问。请注意，错误的 IP 设置可能导致 API 连接失败。 - Key Permissions: 精确地设置 API 密钥的权限至关重要。 对于交易机器人，您至少需要 "Order" 权限，以便机器人可以创建、修改和取消订单。 "Position" 权限允许机器人访问您的持仓信息，这对于风险管理和策略执行至关重要。 某些机器人可能还需要 "Wallet" 权限来查询账户余额。 除非您明确需要通过 API 进行资金提现，否则应避免授予 "Withdraw" 权限，以降低安全风险。 授予 API 密钥的权限应尽可能最小化，遵循最小权限原则。
- TOTP: 为了显著增强账户安全性，强烈建议启用双重验证 (2FA)，例如使用 Google Authenticator 或 Authy 等 TOTP 应用。 创建 API 密钥时，系统会要求您输入当前有效的 TOTP 代码。 这可以防止即使 API 密钥泄露，未经授权的用户也无法使用该密钥。 定期检查和更新您的 2FA 设置也是一个好习惯。 如果您丢失了 2FA 设备，请立即联系 BitMEX 客服进行重置。
成功创建 API 密钥后，BitMEX 将向您提供一个 API Key (也称为 API ID) 和一个 API Secret。 请务必妥善保管您的 API Secret，并绝对不要将其泄露给任何人。 API Key 和 API Secret 类似于您账户的用户名和密码，拥有它们的人可以完全控制您的账户，包括下单交易、查询余额和（如果授予了权限）提取资金。 将 API Secret 存储在安全的地方，例如使用密码管理器或硬件钱包。 定期审查您的 API 密钥和权限，并删除不再使用的密钥，以降低潜在的安全风险。 如果您怀疑 API 密钥已泄露，请立即删除该密钥并创建一个新的密钥。
2. 选择编程语言和库
与 BitMEX API 交互，可以选择多种编程语言，包括但不限于 Python、JavaScript、Java、Go 和 C#。选择取决于您的项目需求、个人偏好以及您对语言的熟悉程度。Python 以其清晰的语法、丰富的库支持和易于学习的特点，在加密货币开发领域中被广泛采用。本文将重点介绍使用 Python 与 BitMEX API 进行交互的方法。
以下是一些常用的 Python 库，可以用于简化与 BitMEX API 的集成：
-
bitmex: BitMEX 官方提供的 Python 客户端库，它对 BitMEX API 的所有端点进行了封装，使得开发者能够方便地调用各种 API 功能，如查询账户信息、下单、取消订单等。该库简化了认证流程和请求构造，降低了开发难度。 -
requests: 这是一个通用的 HTTP 请求库，允许您手动构建 HTTP 请求与 BitMEX API 交互。虽然需要手动处理 API 的认证、请求构建和响应解析，但 `requests` 库提供了更大的灵活性和控制权。您可以根据自己的需求定制 HTTP 请求头、请求体和错误处理逻辑。 -
ccxt: CCXT (CryptoCurrency eXchange Trading Library) 是一个统一的加密货币交易 API 库，它支持包括 BitMEX 在内的数百家加密货币交易所。通过 CCXT，您可以使用相同的代码与不同的交易所进行交互，而无需为每个交易所编写单独的 API 客户端。CCXT 提供了现货和衍生品交易的接口，方便进行跨交易所的策略开发。
推荐使用
pip
包管理器安装
bitmex
库，命令如下：
bash
pip install bitmex
通过执行上述命令，
bitmex
库及其依赖项将被安装到您的 Python 环境中，您可以立即开始使用该库与 BitMEX API 进行交互。
3. 连接到 BitMEX API
与 BitMEX API 建立连接是进行任何交易操作的基础。
bitmex
Python 库简化了这一过程，允许开发者通过提供 API 密钥和密钥来验证身份并访问 BitMEX 的功能。 密钥的安全存储至关重要，建议使用环境变量或其他安全方法来避免硬编码在脚本中。
以下代码展示了如何使用
bitmex
库连接到 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)
# 现在可以使用 'client' 对象与 BitMEX API 交互
# 例如，获取帐户信息：
# account_info = client.User.User_getMargin().result()
# print(account_info)
参数说明：
-
api_key: 你的 BitMEX API 密钥。 你可以在 BitMEX 网站的 API 设置页面生成。 -
api_secret: 你的 BitMEX API 密钥。 和密钥一起用于验证你的请求。 -
test=False: 指定是否连接到 BitMEX 的测试网（testnet）。 如果设置为True, 则连接到测试网，用于模拟交易和测试策略，不会涉及真实资金。 如果设置为False(如本例所示), 则连接到主网（实盘交易环境）。
安全提示：
- 永远不要在代码中硬编码你的 API 密钥和密钥。
- 使用环境变量或配置文件安全地存储你的密钥。
- 限制 API 密钥的权限，只授予必要的访问权限。
- 定期轮换你的 API 密钥。
选择是测试网还是主网环境
在进行任何实际交易操作之前，必须明确指定是使用测试网络（Testnet）还是主网络（Mainnet）。测试网络提供了一个沙盒环境，允许开发者和交易者在不承担真实资金风险的情况下测试策略、算法和API集成。主网络则是真实的交易环境，所有操作都涉及真实资金。
通过设置
is_testnet
变量来选择环境：
is_testnet = True # 使用测试网络
is_testnet = False # 使用主网络
根据
is_testnet
变量的值，可以实例化 BitMEX API 客户端。以下代码展示了如何根据环境选择来创建客户端实例：
if is_testnet:
client = bitmex.bitmex(test=True, api_key=api_key, api_secret=api_secret)
else:
client = bitmex.bitmex(api_key=api_key, api_secret=api_secret)
注意：
-
如果
is_testnet为True，则客户端将连接到 BitMEX 测试网络。test=True参数显式指定使用测试网。 -
如果
is_testnet为False，则客户端将连接到 BitMEX 主网络。在这种情况下，不需要显式传递test参数。 -
无论使用哪个网络，都需要提供有效的 API 密钥（
api_key）和 API 密钥密钥（api_secret）。测试网络和主网络拥有不同的 API 密钥。 - 在使用真实资金之前，强烈建议在测试网络上进行全面的测试，以确保代码和策略的正确性。
验证连接是否成功
以下代码片段展示了如何验证与BitMEX API的连接是否成功。通过调用
User_getMargin()
方法尝试获取账户保证金信息，可以有效判断API密钥和连接配置是否正确。如果连接成功，将打印账户信息；如果连接失败，则会捕获异常并打印错误信息。
try:
account = client.User.User_getMargin().result()
print(f"账户信息: {account}")
except Exception as e:
print(f"连接失败: {e}")
在使用上述代码之前，请务必将
YOUR_API_KEY
和
YOUR_API_SECRET
替换为您在BitMEX平台上申请的实际API Key和API Secret。这两个凭证是访问API的必要条件。
is_testnet
变量用于指定连接的网络环境。将其设置为
True
以连接到BitMEX测试网，设置为
False
以连接到主网。强烈建议您在开发和测试阶段使用测试网，因为它提供了一个安全的沙盒环境，可以在不涉及真实资金的情况下进行实验和调试，从而有效避免因代码错误或配置问题导致的不必要资金损失。请注意，测试网上的资金是模拟资金，不具有实际价值。
4. 发送交易指令
以下代码示例展示了如何利用
bitmex
Python 库向 BitMEX 交易所发送一个限价买入订单，用于交易指定的加密货币合约。
symbol = "XBTUSD"
# 交易对，指定要交易的合约，例如 XBTUSD 代表比特币永续合约。
side = "Buy"
# 订单方向，指定是买入（"Buy"）还是卖出（"Sell"）。
order_qty = 1
# 订单数量（合约数量），表示要交易的合约数量。需要注意的是，这个数量通常代表的是合约的价值，而不是实际的比特币数量。
price = 9000
# 价格，设置限价单的价格。只有当市场价格达到或低于该价格时，买单才会成交。
order_type = "Limit"
# 订单类型，指定订单类型为 "Limit"，即限价单。限价单只有在达到指定价格时才会被执行。
该代码段尝试提交一个限价买入订单。如果订单成功提交，将打印订单的详细信息；如果提交失败，将捕获异常并打印错误信息。
try:
order = client.Order.Order_new(symbol=symbol, side=side, orderQty=order_qty, price=price, ordType=order_type).result()
print(f"订单已提交: {order}")
except Exception as e:
print(f"下单失败: {e}")
您可以通过修改
symbol
、
side
、
order_qty
、
price
和
order_type
等参数来自定义您的订单。
symbol
决定交易的合约，
side
决定交易方向，
order_qty
决定交易数量，
price
决定交易价格，而
ordType
则定义了订单的类型。
ordType
参数允许您选择不同的订单类型，包括但不限于：
-
"Market"(市价单): 以当前市场最优价格立即成交。 -
"Limit"(限价单): 只有当市场价格达到或优于指定价格时才会成交。 -
"Stop"(止损单): 当市场价格达到指定触发价格时，订单会被触发并以市价单的形式执行。 -
"StopLimit"(止损限价单): 当市场价格达到指定触发价格时，订单会被触发并以限价单的形式挂出。
5. 查询订单状态
以下代码展示了如何使用
bitmex
库查询特定订单的状态。订单查询功能允许用户追踪订单的执行情况，例如是否已成交、部分成交或被取消等。
bitmex
API 提供了灵活的过滤选项，可以根据订单 ID、符号、订单状态等条件进行查询。
order_id = order[0]['orderID']
# 上一步创建的订单ID。 此处假设在上一步创建订单后，订单信息存储在名为 `order` 的变量中，并且通过索引 `[0]` 获取第一个订单的信息。`['orderID']` 提取该订单的唯一标识符，即订单 ID。请根据您的实际代码结构调整此处的变量名和索引。
try:
orders = client.Order.Order_getOrders(filter=f'{{"orderID": "{order_id}"}}').result()
print(f"订单状态: {orders}")
except Exception as e:
print(f"查询订单状态失败: {e}")
代码详解：
-
client.Order.Order_getOrders(filter=f'{{"orderID": "{order_id}"}}')：调用 BitMEX API 的Order_getOrders方法，用于查询订单。filter参数是一个 JSON 格式的字符串，用于指定查询条件。在此示例中，我们使用orderID作为过滤条件，只查询与指定order_id匹配的订单。注意，BitMEX API 通常期望filter参数是一个有效的 JSON 字符串。 -
.result()：执行 API 调用并获取结果。BitMEX API 的客户端库通常使用异步方式处理 API 请求，.result()方法会阻塞当前线程，直到 API 请求完成并返回结果。 -
try...except块：用于捕获可能发生的异常。例如，如果 API 调用失败，或者指定的order_id不存在，则会抛出异常。通过捕获异常，可以防止程序崩溃，并提供更友好的错误提示信息。 -
输出的
orders变量是一个列表，其中包含与指定order_id匹配的所有订单的信息。如果订单不存在，则该列表为空。每个订单的信息通常包含订单 ID、符号、订单数量、订单价格、订单状态等。
6. 获取仓位信息
以下代码片段演示了如何利用
bitmex
库，精确检索并获取指定交易对的仓位信息。通过调用 BitMEX API 的仓位查询接口，您可以实时掌握账户在该合约上的持仓情况，包括多空方向、持仓数量、开仓均价等关键数据。
bitmex
库提供了便捷的
Position.Position_get()
方法，该方法允许您通过过滤器参数精确指定需要查询的合约。在下面的示例中，我们使用
filter
参数，并以 JSON 格式的字符串指定了
symbol
字段，从而仅查询指定合约 (
symbol
) 的仓位信息。请将
symbol
替换为您实际交易的合约代码，例如 "XBTUSD" 或 "ETHUSD"。
为了确保代码的健壮性，我们使用了
try...except
块来捕获可能发生的异常。例如，如果 API 连接失败、用户权限不足或合约代码不存在，都会抛出异常。在
except
块中，我们会打印错误信息，帮助您快速定位问题。
示例代码：
try:
position = client.Position.Position_get(filter=f'{{"symbol": "{symbol}"}}').result()
print(f"仓位信息: {position}")
except Exception as e:
print(f"获取仓位信息失败: {e}")
这段代码首先尝试从 BitMEX 获取与指定交易对 (
symbol
) 相关的仓位信息。
client.Position.Position_get()
函数被调用，并通过
filter
参数传递一个 JSON 格式的字符串，用于指定要查询的交易对。
.result()
方法用于从 API 响应中提取结果数据。
如果成功获取到仓位信息，代码会将仓位数据打印到控制台。
position
变量将包含一个包含详细仓位信息的字典或列表。
如果获取仓位信息失败，代码会捕获异常，并将错误信息打印到控制台，以便进行调试。常见的错误包括网络连接问题、API 密钥配置错误或无效的交易对代码。务必检查您的 API 密钥是否已正确配置，并且您使用的交易对代码在 BitMEX 平台上是有效的。
7. 编写自动化交易策略
上述代码片段仅为入门示例，实际应用中，你需要根据个人交易策略构建完整的自动化交易机器人。 一个功能完备的交易机器人通常包含以下关键组件，协同工作以实现自动交易：
- 数据获取: 从 BitMEX API 或其他数据源实时获取市场数据，例如最新成交价（Last Traded Price, LTP）、深度数据（Order Book Depth）、历史成交记录（Trade History）、以及其他相关指标。数据质量和及时性对交易策略的有效性至关重要。
- 策略逻辑: 核心模块，根据获取到的市场数据和预先设定的交易规则，生成明确的交易信号。交易规则可以基于技术指标（如移动平均线、相对强弱指标 RSI、MACD 等）、价格模式（如头肩顶、双底等）、或者更复杂的机器学习模型。
- 订单管理: 接收策略逻辑生成的交易信号，并负责向交易所发送和管理订单。这包括创建、修改和取消订单。订单类型可以是市价单（立即成交）、限价单（指定价格成交）、止损单（达到特定价格触发）等。高效的订单管理系统能够确保订单以最优价格和速度执行。
- 风险管理: 在自动化交易中至关重要。该模块负责监控账户风险，并采取措施控制潜在损失。常见的风险管理手段包括设置止损（Stop-Loss，在价格下跌到一定程度时自动卖出）和止盈（Take-Profit，在价格上涨到一定程度时自动卖出）订单，限制单笔交易的风险敞口，以及控制总仓位规模。
- 日志记录: 详细记录交易机器人的所有活动，包括数据获取、策略执行、订单操作、以及任何错误或异常情况。日志对于调试、性能分析、以及合规性审计都至关重要。清晰且完整的日志记录能够帮助你理解交易机器人的行为，并及时发现和解决问题。
以下示例展示了一个更复杂的移动平均线交叉策略的简化实现。请注意，这仅用于演示目的，在实际交易环境中使用前需要进行充分的测试和优化：
import time
def moving_average(data, window): """计算移动平均线""" return sum(data[-window:]) / window
def trading strategy(): """移动平均线交叉策略""" short window = 5 long_window = 20
while True:
try:
# 获取最新成交价
trades = client.Trade.Trade_get(symbol=symbol, count=long_window).result()
prices = [trade['price'] for trade in trades[0]]
prices.reverse() # 确保价格按时间顺序排列
# 计算移动平均线
short_ma = moving_average(prices, short_window)
long_ma = moving_average(prices, long_window)
# 获取当前仓位
position = client.Position.Position_get(filter=f'{{"symbol": "{symbol}"}}').result()
current_qty = position[0][0]['currentQty'] if position[0] else 0
# 交易逻辑
if short_ma > long_ma and current_qty <= 0:
# 短期均线高于长期均线，买入
print("买入信号")
client.Order.Order_new(symbol=symbol, side="Buy", orderQty=1, ordType="Market").result()
elif short_ma < long_ma and current_qty >= 0:
# 短期均线低于长期均线，卖出
print("卖出信号")
client.Order.Order_new(symbol=symbol, side="Sell", orderQty=abs(current_qty), ordType="Market").result()
except Exception as e:
print(f"交易策略执行出错: {e}")
time.sleep(1) # 每隔 1 秒执行一次
该示例仅为演示。实际应用中，交易策略需要根据你的具体风险偏好、资金规模和市场认知进行精细调整。还需要实现更强大的错误处理机制、更严格的风险管理模块以及详细的交易日志记录功能，以确保交易机器人在复杂市场环境下的稳定性和可靠性。 在部署任何自动化交易策略之前，务必进行充分的回测（Backtesting）和模拟交易（Paper Trading），以评估其潜在盈利能力和风险水平。
8. 安全注意事项
- 妥善保管 API 密钥: API 密钥是访问加密货币交易所或服务的关键凭证，务必将其视为高度敏感信息。切勿将 API 密钥泄露给任何人，包括朋友、同事，更不能在公共论坛或社交媒体上发布。同时，不要将 API 密钥存储在不安全的地方，例如未加密的文本文件、电子邮件或版本控制系统中。推荐使用专门的密钥管理工具或硬件钱包来安全存储 API 密钥。
- 限制 API 密钥权限: 为了降低潜在的安全风险，只授予 API 密钥执行所需操作的最小权限。例如，如果您的应用程序只需要读取市场数据，则不要授予 API 密钥提款或交易的权限。仔细审查交易所或服务提供的 API 权限选项，并根据您的应用程序需求进行配置。
- 使用 IP 白名单: 通过限制 API 密钥的访问 IP 地址，可以有效防止未经授权的访问。将允许访问 API 密钥的 IP 地址添加到白名单中，拒绝所有其他 IP 地址的访问。这种方法可以防止攻击者即使获得了 API 密钥，也无法从未经授权的 IP 地址访问您的账户。
- 启用双重验证 (2FA): 双重验证 (2FA) 在您的账户登录过程中增加了一层额外的安全保障。启用 2FA 后，除了密码之外，您还需要提供一个来自验证器应用程序或短信的验证码才能登录。即使攻击者获得了您的密码，也无法在没有验证码的情况下访问您的账户。
- 使用测试网进行测试: 在使用真实资金进行交易之前，务必在测试网上进行充分的测试。测试网是与主网类似的模拟环境，允许您在不承担任何实际风险的情况下测试您的交易策略和 API 集成。确保您的应用程序在测试网上运行良好，并且您已经处理了所有潜在的错误和异常情况。
- 监控交易活动: 定期检查您的交易活动，确保没有未经授权的交易。密切关注您的账户余额、交易历史和 API 密钥的使用情况。如果发现任何可疑活动，例如未授权的交易或 API 密钥的异常访问，立即采取措施，例如禁用 API 密钥、更改密码和联系交易所或服务提供商。
9. 总结
通过 BitMEX API 进行自动化交易可以帮助您更快地执行交易策略，并减少人工干预。 但是，自动化交易也存在风险，需要谨慎对待。 在开始自动化交易之前，请确保您已经充分了解 BitMEX API 的使用方法，并且已经制定了完善的交易策略和风险管理措施。
