BitMEX API 设置教程
本教程将引导您完成 BitMEX API 的设置过程，以便您可以通过编程方式访问 BitMEX 交易所的数据和功能。
前提条件
- BitMEX 账户： 您必须在 BitMEX 交易所拥有一个已注册并完成身份验证的账户。这将允许您访问 BitMEX 的 API 并执行交易操作。请确保您的账户已启用 API 访问权限，并生成相应的 API 密钥和密钥。
- 编程基础： 需要具备一定的编程基础，例如 Python、JavaScript、Go 或其他主流编程语言。了解基本的数据结构、控制流和函数概念至关重要。熟悉 HTTP 请求和 JSON 数据格式对于与 API 交互是必要的。
- 开发环境配置： 需要安装所选编程语言的解释器或编译器，并配置相应的开发环境。例如，如果选择 Python，则需要安装 Python 解释器和 pip 包管理器。对于 JavaScript，可以使用 Node.js 和 npm 包管理器。还需要安装与 BitMEX API 交互所需的库，例如 Python 中的 `requests` 和 `websockets` 库。对于更复杂的应用，建议使用虚拟环境来隔离项目依赖。
步骤 1：创建 BitMEX API 密钥
- 登录 BitMEX 账户： 前往 BitMEX 官方网站 (www.bitmex.com) 并使用您的注册账户凭据登录。确保您访问的是官方网站，谨防钓鱼网站。
- 导航到 API 设置： 成功登录后，将鼠标悬停在页面右上角您的用户名或账户图标上，系统会弹出一个下拉菜单。在此下拉菜单中，找到并选择 "API Keys" 或类似的选项，进入 API 密钥管理页面。
- 创建新的 API 密钥： 在 API Keys 管理页面，通常会有一个明显的 "Generate API Key"、"Create New Key" 或类似的按钮。点击此按钮，开始创建新的 API 密钥，以便您的应用程序或脚本能够安全地访问您的 BitMEX 账户。
-
配置 API 密钥权限：
在弹出的窗口或页面中，您需要仔细配置 API 密钥的权限。这是创建 API 密钥过程中至关重要的一步，因为您需要明确指定此密钥可以访问和操作哪些功能，以保障账户安全和数据隐私。
- Account： 此权限允许 API 密钥访问您的 BitMEX 账户的各种信息，例如账户余额、持仓情况、交易历史、保证金水平等。如果您需要查询账户信息或进行风险分析，则必须启用此权限。但请谨慎授予，仅在必要时开启。
- Order： 此权限允许 API 密钥执行下单、修改订单、取消订单等交易操作。如果您需要通过 API 自动进行交易、创建交易机器人或执行算法交易策略，则需要启用此权限。在授予此权限时，请务必谨慎设计您的交易逻辑，避免意外损失。
- Withdraw： 警告！ 此权限允许 API 密钥发起提现请求，将您的资金转移到指定的地址。 强烈建议不要启用此权限，除非您对使用此密钥的应用程序或脚本绝对信任，并且已经充分了解其安全性。 启用此权限可能会导致资金被盗，请务必慎重考虑。如果您必须启用提币权限，请务必采取额外的安全措施，例如设置提现白名单。
- Leagues： 如果您参与 BitMEX 组织的交易竞赛，则可以使用此权限访问与竞赛相关的账户信息和排名数据。
- Deposit: 创建充值地址的权限。允许API密钥为您的账户生成新的充值地址。通常用于自动化充值流程，方便用户将资金转入BitMEX账户。
- 设置允许提现到的地址 (可选)： 在 API 密钥的创建或编辑页面，您可以设置允许提现到的地址列表，也称为提现白名单。这是一个重要的安全措施，可以有效避免 API 密钥泄露后，资金被未经授权地转移到未知地址。请务必仔细核对提现地址的正确性。需要注意的是，此功能只有在您开启了提币权限时才会生效。
- 设置密钥过期时间 (推荐)： BitMEX 允许您为 API 密钥设置过期时间。设置过期时间可以显著提高安全性，因为即使密钥不幸泄露，在到达过期时间后也会自动失效，从而降低潜在的风险。建议您根据实际需求设置合理的过期时间，例如 30 天、60 天或 90 天。定期轮换 API 密钥也是一个良好的安全习惯。
- 输入您的 2FA 验证码： 为了进一步加强安全性，您需要输入您的双因素验证 (2FA) 代码才能完成 API 密钥的创建。这可以确保只有授权用户才能创建和管理 API 密钥，有效防止未经授权的访问。
- 保存 API 密钥： 创建成功后，您会看到 API 密钥（API Key）和密钥 Secret（API Secret）。 请务必妥善保管您的密钥 Secret，因为它只会在创建时显示一次，并且无法恢复。 如果您不慎丢失了密钥 Secret，则需要立即重新生成新的 API 密钥，并删除旧的密钥，以确保账户安全。强烈建议将 API Key 和 Secret 存储在安全的地方，例如密码管理器或加密的存储设备中。
步骤 2：安装 BitMEX API 客户端
要开始与 BitMEX 交易所进行交互，您需要安装一个 BitMEX API 客户端。 这个客户端库将处理底层的 HTTP 请求和响应，并提供更高级别的函数，以便您更轻松地访问 BitMEX 的各种功能。根据您选择使用的编程语言，有几种可用的客户端库可供选择。务必选择与您的编程语言和项目需求相匹配的客户端。
以下列举了一些常用的 BitMEX API 客户端，并针对不同编程语言提供了安装指南：
-
Python:
Python 开发者通常使用以下两个库之一：
pip install bitmex-websocket或pip install pybitmex。bitmex-websocket库专门用于实时数据流，例如市场行情和交易更新。而pybitmex是一个更全面的库，支持 REST API 和 WebSocket API。需要注意的是，pybitmex相对较老，但仍然可用，具体取决于您的项目要求。推荐优先考虑使用bitmex-websocket获取实时数据，并根据需要使用pybitmex处理更广泛的 API 功能。 -
JavaScript:
JavaScript 开发者可以使用
npm install bitmex-api安装官方的 BitMEX API 客户端。该客户端提供了对 BitMEX REST API 的全面支持，允许您执行诸如下单、查询账户信息和获取市场数据等操作。请确保您已安装 Node.js 和 npm (Node Package Manager) 以便成功安装此库。 -
Go:
对于 Go 语言开发者，可以使用命令
go get github.com/bitmex/api-client-go/swagger来获取官方的 BitMEX API 客户端。 该客户端是基于 Swagger 规范生成的，并提供了对 BitMEX API 的类型安全访问。使用此库需要 Go 语言环境已正确配置。
请根据您选择的编程语言，从上述列表中选择合适的客户端库，并仔细阅读其官方文档以获取详细的安装和配置说明。每个客户端库都有其特定的依赖项和配置要求，因此请务必按照文档中的步骤进行操作，以确保客户端库能够正确安装并与 BitMEX API 进行通信。正确安装客户端库后，您就可以开始编写代码来与 BitMEX 交易所进行交互了。
步骤 3：使用 API 密钥进行身份验证
在成功安装 API 客户端后，为了安全地访问和操作您的 BitMEX 账户，您必须使用 API 密钥及其对应的密钥 Secret 进行身份验证。这些凭据是您与 BitMEX 服务器建立信任连接的关键。请务必妥善保管您的 API 密钥和密钥 Secret，避免泄露给未经授权的第三方。
以下演示了如何使用 Python 的
bitmex-websocket
库进行身份验证和数据订阅的示例。此库专门设计用于建立持久的 WebSocket 连接，从而实时接收市场数据更新。
from bitmex_websocket import BitMEXWebsocket
def main():
# 创建 BitMEXWebsocket 实例，指定 API 端点、交易品种、API 密钥和密钥 Secret
ws = BitMEXWebsocket(endpoint="https://www.bitmex.com/api/v1",
symbol="XBTUSD",
api_key="YOUR_API_KEY",
api_secret="YOUR_API_SECRET")
# 订阅 orderBookL2_25 主题，接收深度为 25 档的订单簿数据
ws.subscribe_topic('orderBookL2_25')
# 进入主循环，持续获取并打印当前价格
while True:
print(ws.get_ticker()) # 输出当前价格
# 您可以在此处添加自定义逻辑，例如根据市场数据执行交易策略
# 可以使用 ws.get_instrument() 获取合约信息
# 可以使用 ws.recent_trades() 获取最近的交易记录
务必将代码中的
YOUR_API_KEY
和
YOUR_API_SECRET
替换为您在步骤 1 中从 BitMEX 账户创建并获得的实际 API 密钥和密钥 Secret。请注意，这些凭据区分大小写。
另外，以下展示了如何使用 Python 的
pybitmex
库进行身份验证的示例。
pybitmex
库提供了一组更广泛的功能，包括下单、取消订单、获取账户信息等。
from pybitmex import bitmex
# 创建 BitMEX 客户端实例，指定测试环境 (test=True) 或真实交易环境 (test=False)，以及 API 密钥和密钥 Secret
client = bitmex(test=False, api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET")
# 现在您可以使用 client 对象调用 BitMEX API 端点，例如：
# 获取账户信息: client.User.User_getMargin().result()
# 下单: client.Order.Order_new(symbol='XBTUSD', side='Buy', orderQty=1, price=10000).result()
同样，请将代码中的
YOUR_API_KEY
和
YOUR_API_SECRET
替换为您实际的 API 密钥和密钥 Secret。选择适合您需求的库，并仔细阅读其文档，以了解如何有效地使用 API 进行交易和数据分析。
获取账户信息
在加密货币交易中，获取账户信息是至关重要的一步，它允许用户监控其账户余额、保证金水平以及其他重要参数。通过客户端的特定方法，我们可以轻松地检索这些信息。
以下代码片段展示了如何使用API客户端获取用户保证金账户信息，该信息对于了解风险敞口和交易能力至关重要。
account_info = client.User.User_getMargin().result()
这段代码调用了API客户端中与用户账户相关的
User_getMargin()
方法。此方法通常用于检索用户在特定交易所或平台上的保证金账户信息。
.result()
用于同步地获取API调用的结果。
print(account_info)
获取账户信息后，使用
print()
函数将结果打印到控制台。打印的信息通常包含账户余额、可用保证金、已用保证金、未实现盈亏等详细数据。 这些数据有助于用户做出明智的交易决策，并有效地管理其账户。
account_info
变量将包含一个字典或类似的数据结构，其中包含各种账户指标。建议查阅API文档以了解返回对象的完整结构和每个字段的含义，例如:
- 可用余额 (Available Balance): 可用于交易的资金数量。
- 保证金余额 (Margin Balance): 账户中的总保证金金额。
- 已用保证金 (Used Margin): 当前交易占用的保证金数量。
- 未实现盈亏 (Unrealized PNL): 尚未实现的盈利或亏损。
- 风险等级 (Risk Level): 账户风险程度的指标。
了解这些参数的含义对于有效管理交易风险和优化交易策略至关重要。定期检查账户信息是确保账户安全和保持良好财务状况的关键步骤。不同的交易所或平台可能返回略有不同的字段，因此始终参考相关API文档是最佳实践。
下单
使用BitMEX API进行下单操作，您需要调用
Order_new
方法。以下代码展示了如何创建一个限价买单，交易XBTUSD合约，数量为1张，价格为8000美元：
order = client.Order.Order_new(symbol='XBTUSD', side='Buy', orderQty=1, price=8000, ordType='Limit').result()
print(order)
这段代码中，
symbol
参数指定交易的合约代码（XBTUSD代表比特币/美元永续合约），
side
参数指定买卖方向（Buy代表买入），
orderQty
参数指定下单数量，
price
参数指定限价价格，
ordType
参数指定订单类型（Limit代表限价单）。 执行成功后，
order
变量将包含服务器返回的订单信息，您可以打印出来查看。
请确保将代码中的
YOUR_API_KEY
和
YOUR_API_SECRET
替换为您在BitMEX平台申请的真实API密钥和密钥Secret。 API密钥用于身份验证，密钥Secret用于对请求进行签名，保证交易安全。 在初始化BitMEX客户端时，设置
test=False
表示连接到正式交易环境，此时所有交易将使用您的真实资金。 设置
test=True
表示连接到测试环境，您可以使用模拟资金进行交易，这对于测试交易策略和熟悉API接口非常有用，可以有效避免因操作失误造成的真实资金损失。
步骤 4：使用 API 进行操作
成功完成身份验证流程后，您便可以充分利用 API 的强大功能，执行一系列关键操作，从而实现高效的加密货币交易和管理。
- 获取市场数据： 通过 API 获取全面且实时的市场数据，包括但不限于：最新的交易价格、交易量指标、订单深度信息、历史价格走势，以及其他关键的市场指标。这些数据对于进行技术分析、制定交易策略至关重要。
- 下单： 利用 API 实现高效便捷的订单管理，您可以创建新的买入或卖出订单、根据市场变化实时修改现有订单的价格或数量，并根据需要取消未成交的订单。API 提供的自动化下单功能极大地提高了交易效率。
- 查询账户信息： 实时查询您的账户信息，包括账户余额、历史订单记录、当前持仓信息（例如，持有的加密货币种类和数量）、交易历史记录等。这些信息对于监控账户状态、评估交易绩效至关重要。
- 管理仓位： 通过 API 设置止损订单和止盈订单，自动控制交易风险。止损订单可以在价格下跌到预设水平时自动卖出，以限制潜在损失；止盈订单可以在价格上涨到预设水平时自动卖出，以锁定利润。API 允许您根据自身的风险承受能力和交易策略灵活调整止损止盈水平。
- 提现： 务必谨慎使用！ 通过 API 发起提现请求，将您的加密货币转移到其他钱包或交易所。在执行提现操作前，请务必仔细核对提现地址和金额，确保资金安全。API 提现功能应谨慎使用，避免因操作失误造成资金损失。
具体 API 操作的实现方式和具体步骤取决于您所选用的 API 客户端、编程语言以及交易所的具体 API 文档。建议您详细阅读相应的 API 文档，并参考官方提供的示例代码，以便正确使用 API 并避免潜在错误。不同的交易所可能具有不同的 API 调用规则和参数要求，务必仔细研读并测试。
常见问题
-
API 密钥无效：
确保您在应用程序或脚本中输入的 API 密钥和密钥 Secret 完全匹配您的BitMEX账户信息。请仔细检查，避免复制粘贴错误。某些字符可能不易区分，如数字0和字母O，数字1和字母l。进入您的BitMEX账户的安全设置页面，重新生成API密钥和Secret，并更新到您的应用中。验证API密钥是否已激活，未激活的密钥无法使用。
还需确认API密钥的权限范围是否涵盖您所需执行的操作。部分API密钥可能仅具有只读权限，无法进行交易或提现操作。API密钥也可能存在过期时间，过期后将无法使用，请定期检查并更新您的API密钥。
-
连接错误：
检查您的计算机或服务器的网络连接是否稳定。尝试访问其他网站或服务，确认网络是否正常工作。如果您的网络连接通过代理服务器，请确保您的应用程序或脚本已正确配置代理设置。
确认您使用的 BitMEX API 端点 URL 是否正确。BitMEX 可能会更新其 API 端点，请查阅官方文档以获取最新的端点信息。例如，测试环境和正式环境使用不同的端点。
检查您的防火墙设置是否阻止了应用程序或脚本与 BitMEX API 之间的通信。防火墙可能会阻止特定端口或协议的连接。临时关闭防火墙进行测试，确认是否为防火墙问题。
-
权限错误：
仔细审查您 API 密钥的权限设置。不同的操作需要不同的权限。例如，进行交易需要 "Order" 权限，查询账户余额需要 "Account" 权限，提取资金需要 "Withdrawal" 权限。在BitMEX账户中配置API密钥时，务必勾选所有必要的权限。
请注意，授予过多的权限可能会增加安全风险。建议您仅授予 API 密钥执行所需操作的最小权限集。遵循最小权限原则，降低潜在的安全风险。
-
频率限制：
BitMEX 为了保障平台的稳定性和公平性，对 API 请求的频率进行了限制（也称为速率限制）。如果您在短时间内发送了过多的请求，服务器可能会返回错误响应，例如 HTTP 429 Too Many Requests。
请查阅 BitMEX API 文档，了解具体的频率限制规则。不同的 API 端点可能具有不同的频率限制。实现合理的请求队列管理，控制请求发送速度，避免触发频率限制。使用指数退避算法，在收到频率限制错误后，逐渐增加请求之间的间隔时间。监控 API 请求的响应，及时发现并处理频率限制错误。缓存 API 响应数据，减少不必要的 API 请求。
安全注意事项
- 妥善保管您的 API 密钥和密钥 Secret： API 密钥和密钥 Secret 是访问您 BitMEX 账户的凭证，务必将其视为高度敏感信息。切勿将其泄露给任何第三方。不要将其存储在不安全的位置，例如公共代码仓库（如 GitHub），未加密的文本文件，或者容易被访问的服务器目录中。考虑使用安全的密钥管理系统或硬件安全模块 (HSM) 来存储这些凭据，并进行适当的访问控制。定期轮换 API 密钥可以进一步降低风险。
- 使用安全连接： 始终使用 HTTPS (Hypertext Transfer Protocol Secure) 连接来访问 BitMEX API。HTTPS 通过 SSL/TLS 协议对通信进行加密，防止中间人攻击，确保数据在传输过程中的安全性。避免使用 HTTP 连接，因为它不加密数据，可能导致敏感信息泄露。验证您使用的 API 客户端是否强制使用 HTTPS 连接。
- 定期审查您的 API 密钥权限： 确保您的 API 密钥只具有执行所需操作的最小权限集。例如，如果您的应用程序只需要读取市场数据，则不要授予它交易权限。BitMEX API 提供细粒度的权限控制，您可以根据实际需求配置 API 密钥的权限。定期审查和更新这些权限，以确保它们仍然符合您的应用程序需求，并及时撤销不再需要的权限。
- 启用双因素验证 (2FA)： 启用双因素验证 (2FA) 可以显著提高您 BitMEX 账户的安全性。即使攻击者获得了您的密码，他们仍然需要提供第二个验证因素（例如，来自手机应用程序的验证码）才能访问您的账户。BitMEX 支持多种 2FA 方法，例如 Google Authenticator 和 SMS 验证。强烈建议您启用 2FA 并妥善保管您的 2FA 恢复代码。
- 监控您的账户活动： 定期检查您的 BitMEX 账户活动，包括交易历史、API 密钥使用情况、以及任何异常的登录尝试。BitMEX 提供账户活动日志，您可以使用它来监控账户活动。如果发现任何可疑活动，立即更改您的密码，撤销 API 密钥，并联系 BitMEX 客服。设置警报系统，例如电子邮件或短信通知，以便在检测到异常活动时及时收到通知。
以上是设置 BitMEX API 的基本安全步骤和注意事项。请务必仔细阅读 BitMEX API 的官方文档，并根据您的具体应用场景和安全需求进行配置。了解 API 的所有功能和限制，并采取适当的安全措施，以保护您的账户和资金。
