BitMEX API:连接加密货币交易的自动化桥梁
BitMEX API:连接加密货币交易世界的桥梁
BitMEX API 是一个强大而灵活的工具,允许开发者和交易者自动化交易策略,获取市场数据,并与 BitMEX 平台进行深度集成。通过 API,用户可以超越传统的手动交易界面,构建定制化的交易体验,并在高频交易、算法交易和数据分析等领域释放无限潜力。
API 概览
BitMEX API 采用 REST (Representational State Transfer) 架构风格。REST 是一种利用 HTTP 协议进行数据交互的软件架构风格,它强调资源的状态转移。BitMEX API 充分利用标准的 HTTP 方法,如
GET
(用于检索资源)、
POST
(用于创建资源)、
PUT
(用于更新资源)和
DELETE
(用于删除资源),以便客户端与服务器进行有效的通信。这种架构设计使得 API 易于理解和使用,降低了开发者的学习成本。
数据交换主要采用 JSON (JavaScript Object Notation) 格式。JSON 是一种轻量级的数据交换格式,易于人阅读和编写,同时也易于机器解析和生成。JSON 基于 JavaScript 编程语言的一个子集,但它是一种独立于语言的格式,被广泛应用于各种网络应用和 API 中,用于在客户端和服务器之间传递数据。其简洁性和高效性使其成为现代 Web 开发的首选数据格式。
BitMEX 提供了两个主要的 API 端点:
公共 API (Public API):无需身份验证即可访问,主要用于获取市场数据,例如:- 交易历史 (Trades)
- 订单簿 (Order Book)
- 行情数据 (Quotes)
- 指数信息 (Indices)
- 合约信息 (Instrument)
- 下单 (Place Order)
- 修改订单 (Amend Order)
- 取消订单 (Cancel Order)
- 获取账户信息 (Get Account Information)
- 获取持仓信息 (Get Position)
- 获取资金信息 (Get Wallet Information)
- 提取资金 (Withdraw)
认证机制
访问 BitMEX 私有 API 需要进行严格的身份验证以确保账户安全。BitMEX 采用 API 密钥 (
API Key
) 和 API 密钥密码 (
API Secret
) 结合的方式验证用户的身份。API 密钥和 API 密钥密码必须在 BitMEX 官方网站的账户安全设置页面中生成。强烈建议启用双因素认证 (2FA) 以提高账户的安全性。
有效的身份验证过程包含以下关键步骤:
-
生成 API 密钥和 API 密钥密码:
登录 BitMEX 账户,导航至账户设置中的 API 管理页面,创建新的 API 密钥。创建时,您可以设置该密钥的权限,例如交易、提现等。请务必妥善保管您的 API 密钥密码 (
API Secret
),切勿通过任何不安全渠道传输或存储,并且切勿泄露给任何第三方,包括 BitMEX 的工作人员。一旦泄露,应立即撤销并重新生成新的 API 密钥。 -
构造签名:
签名是验证请求完整性和真实性的关键。构建签名时,需要将 HTTP 请求方法(例如
GET
、POST
、PUT
、DELETE
),要访问的 API 端点 (endpoint
),以及请求体 (request body
,如果存在) 按照特定规则组合后进行哈希计算,生成一个唯一的签名字符串。BitMEX API 普遍采用 HMAC-SHA256 算法进行签名。签名算法的选择和参数设置必须与 BitMEX API 的要求一致,否则验证将失败。 -
添加到请求头:
将 API 密钥 (
API Key
)、生成的签名 (signature
) 和时间戳 (timestamp
) 作为自定义 HTTP 请求头的一部分发送到 BitMEX API 服务器。这些请求头通常命名为api-key
、api-signature
和api-timestamp
。正确设置请求头是成功通过身份验证的前提。
BitMEX API 使用的时间戳是自 Unix 纪元(1970 年 1 月 1 日 00:00:00 UTC)起至当前时间的秒数,通常称为 Unix 时间戳。时间戳用于防止重放攻击,即攻击者截获并重新发送先前的有效请求。BitMEX API 服务端会验证时间戳的有效性,通常会拒绝时间戳与服务器时间相差过大的请求。因此,客户端必须确保其系统时钟与 UTC 时间同步,以避免身份验证错误。建议使用网络时间协议 (NTP) 服务同步系统时间。
常用API接口详解
以下是一些常用的 BitMEX API接口的详细说明,旨在帮助开发者更好地理解和使用BitMEX平台提供的功能。
公共接口 (Public Endpoints)
公共接口无需身份验证即可访问,主要用于获取市场数据和平台信息。
-
/api/v1/instrument
: 获取交易品种信息。可以查询所有可交易合约的详细参数,例如合约代码、保证金要求、最小交易数量等。支持筛选特定合约。
示例 : 获取XBTUSD合约的信息。 -
/api/v1/orderBook/L2
: 获取指定合约的Level 2 订单簿。提供市场深度信息,包括买单和卖单的价格及数量。
示例 : 获取XBTUSD合约的订单簿前10档数据。 -
/api/v1/trade
: 获取成交记录。可以查询指定合约的历史成交数据,包括成交价格、数量和时间。
示例 : 获取XBTUSD合约最近100笔成交记录。 - /api/v1/announcement : 获取BitMEX平台公告。获取平台发布的最新消息,包括维护通知、新功能上线等。
私有接口 (Private Endpoints)
私有接口需要身份验证才能访问,用于执行交易操作、管理账户和获取个人信息。
使用私有接口前,需要创建API密钥并设置相应的权限。API密钥包括API Key ID和API Secret,务必妥善保管。
-
/api/v1/order
: 管理订单。可以创建、修改和取消订单。支持限价单、市价单、止损单等多种订单类型。
示例 : 创建一个XBTUSD的限价买单。 - /api/v1/position : 获取持仓信息。查询当前账户的持仓情况,包括合约代码、数量、平均入场价格和未实现盈亏。
- /api/v1/user/wallet : 获取钱包信息。查询账户余额和交易历史。
- /api/v1/user/margin : 获取保证金信息。查询账户的保证金水平,包括可用保证金和已用保证金。
API 使用注意事项
- 速率限制 : BitMEX API 对请求频率有限制。请注意控制请求频率,避免触发速率限制。
- 身份验证 : 使用私有接口时,需要在请求头中添加API Key ID和签名。签名需要使用API Secret对请求参数进行加密生成。
- 错误处理 : 仔细阅读API文档,了解各种错误代码的含义,并进行相应的错误处理。
- 数据格式 : BitMEX API 使用 JSON 格式进行数据交换。
- 安全 : 务必保护好您的API密钥,避免泄露。不要将API密钥存储在客户端代码中。
- 版本 : 注意API的版本号,并使用最新版本。
1. 获取交易历史 (
GET /api/v1/trade
)
- 用途: 获取指定合约在BitMEX平台上的历史成交记录。此接口允许开发者检索特定合约的交易数据,用于分析市场趋势、回测交易策略或监控交易活动。
-
参数:
-
symbol
(必需): 合约代码,指定要查询的合约。例如,XBTUSD
代表比特币/美元永续合约。务必提供有效的合约代码,否则API将返回错误。 -
count
(可选): 返回的交易数量上限。默认为100
,最大允许值为500
。如果请求的交易数量超过500,API将只返回最新的500条交易记录。合理设置count
可以优化API响应时间。 -
start
(可选): 起始交易的索引。用于分页显示大量交易数据。例如,如果已经获取了前100条交易记录,则可以将start
设置为100
以获取接下来的100条交易记录。索引从0开始。 -
reverse
(可选): 指定返回的交易记录的排序方式。默认为false
,表示按时间升序排列(从旧到新)。如果设置为true
,则按时间降序排列(从新到旧)。 倒序排列对于获取最新的交易活动非常有用。
-
-
返回值:
一个包含交易信息的 JSON 数组。数组中的每个元素代表一笔已发生的交易,包含以下关键字段:
-
timestamp
: 交易发生的时间戳,通常为ISO 8601格式的字符串。 -
price
: 交易的成交价格。 -
size
: 交易的数量(合约数量)。 -
side
: 交易方向,表示买入 (Buy
) 或卖出 (Sell
)。 -
tickDirection
: 逐笔委托成交方向。可能的值包括PlusTick
(价格高于前一笔交易),ZeroPlusTick
(价格等于前一笔交易,但属于向上撮合),MinusTick
(价格低于前一笔交易),ZeroMinusTick
(价格等于前一笔交易,但属于向下撮合)。 -
trdMatchID
: 交易撮合ID,用于唯一标识一笔交易。 -
grossValue
: 交易的名义价值,以基础货币计价。 -
homeNotional
: 以本位币计价的合约数量。 -
foreignNotional
: 以外币计价的合约数量。
-
2. 获取订单簿 (GET /api/v1/orderBook/L2)
- 用途: 获取指定交易合约的二级(L2)订单簿快照数据。订单簿数据对于分析市场深度、评估流动性和制定交易策略至关重要。
-
参数:
-
symbol
(必需): 合约代码,用于指定需要查询的交易合约。例如,XBTUSD
代表比特币兑美元的永续合约。请务必使用交易所支持的有效合约代码。 -
depth
(可选): 返回的订单簿深度,表示需要返回的最佳买入和卖出价格的数量。 默认值为25
,这意味着将返回最佳的 25 个买单和 25 个卖单。 您可以调整此参数以获取更深或更浅的订单簿视图,但这可能会影响API的响应时间和数据量。 较小的深度值可以减少网络流量。
-
-
返回值:
一个包含订单簿信息的 JSON 数组。每个元素代表一个订单簿条目,包含以下关键信息:
-
price
: 订单的价格。表示该订单簿条目的价格水平。 -
size
: 订单的数量。表示在该价格水平上的可用订单总数量,通常以合约单位或标的资产数量表示。 -
side
: 订单簿类型 (Bid
/Ask
)。Bid
代表买单(买入报价),Ask
代表卖单(卖出报价)。 买单表示用户愿意购买的价格,卖单表示用户愿意出售的价格。
示例 JSON 响应:
[ { "price": 27000.50, "size": 1.25, "side": "Bid" }, { "price": 27001.00, "size": 0.75, "side": "Ask" }, ... ]
-
3. 下单 (
POST /api/v1/order
)
- 用途: 创建并提交一个新的订单到交易系统。此接口允许用户指定交易合约、买卖方向、订单数量和订单类型等参数,从而实现各种交易策略。
-
参数:
-
symbol
(必需): 指定交易的合约代码,代表具体的交易标的。例如,XBTUSD
表示比特币兑美元的永续合约。用户必须提供有效的合约代码才能成功下单。 -
side
(必需): 指明订单的买卖方向。Buy
表示买入开多或平空仓位,Sell
表示卖出开空或平多仓位。这是确定交易行为的关键参数。 -
orderQty
(必需): 定义订单的数量,即交易的合约单位数量。这个数值必须是正整数,并且需要符合交易所对该合约的最小交易数量限制。 -
price
(可选): 仅在限价单 (Limit
,LimitIfTouched
,StopLimit
,Pegged
) 中使用。指定订单的委托价格。只有当市场价格达到或优于此价格时,订单才会被执行。如果未提供,对于市价单,系统将以当时的市场最优价格成交。 -
orderType
(必需): 定义订单的类型,决定订单的执行方式。支持的订单类型包括:-
Market
: 市价单,以当前市场最优价格立即成交。 -
Limit
: 限价单,只有当市场价格达到或优于指定价格时才成交。 -
Stop
: 止损单,当市场价格达到指定的止损价格 (stopPx
) 时,订单转换为市价单并立即执行。 -
StopLimit
: 止损限价单,当市场价格达到指定的止损价格 (stopPx
) 时,订单转换为限价单,并以指定的委托价格 (price
) 挂单。 -
MarketIfTouched
: 触及市价单,当市场价格达到指定的触发价格时,订单转换为市价单并立即执行。 -
LimitIfTouched
: 触及限价单,当市场价格达到指定的触发价格时,订单转换为限价单,并以指定的委托价格挂单。 -
Pegged
: 挂单,订单的价格根据市场价格自动调整,与市场价格保持一定的偏移量。
-
-
stopPx
(可选): 仅在止损单 (Stop
,StopLimit
) 中使用。设定止损价格,当市场价格达到此价格时,触发订单执行。 -
pegOffsetValue
(可选): 仅在挂单 (Pegged
) 中使用。定义订单价格与市场价格的偏移量。正值表示高于市场价格,负值表示低于市场价格。
-
-
返回值:
成功提交订单后,API 将返回一个 JSON 对象,包含关于该订单的详细信息。这些信息包括:
-
orderID
: 订单的唯一标识符,由系统自动生成。 -
orderStatus
: 订单的当前状态,例如New
(新订单)、Filled
(已成交)、Canceled
(已取消)、Rejected
(已拒绝) 等。 -
price
: 订单的委托价格 (如果订单类型是限价单)。 -
orderQty
: 订单的原始数量。 -
cumQty
: 订单的已成交数量。 -
avgPx
: 订单的平均成交价格。 - 其他与订单相关的详细信息,例如下单时间、最后更新时间等。
-
4. 修改订单 (
PUT /api/v1/order
)
- 用途: 修改已存在的订单。此接口允许您更新订单的各种属性,例如订单数量、价格和止损价格。
-
参数:
-
orderID
(必需): 需要修改的订单的唯一标识符。 这是一个字符串,用于在系统中精确定位要更新的特定订单。 -
orderQty
(可选): 订单的新数量。 如果未提供,则订单数量将保持不变。 必须是大于零的数字。 允许修改订单的交易规模。 -
price
(可选): 订单的新价格。 如果未提供,订单价格将保持不变。 对于限价单,这是执行订单的价格。 -
stopPx
(可选): 新的止损触发价格。 如果未提供,止损价格将保持不变。 止损价格在达到时会触发止损单。
-
-
返回值:
一个 JSON 对象,包含修改后的订单的详细信息。 此对象包括:
-
orderID
: 已修改订单的唯一标识符。 -
orderStatus
: 订单的当前状态(例如,新建、已取消、已部分成交、已完全成交)。 -
price
: 订单的当前价格。 -
orderQty
: 订单的当前数量。 - 其他相关订单信息: 例如订单类型、创建时间、最后更新时间等。
-
5. 取消订单 (DELETE /api/v1/order)
- 用途: 取消用户提交的、目前状态为未成交的订单。此接口允许用户撤销先前设定的交易指令。
-
参数:
-
orderID
(必需): 需要取消的订单的唯一标识符。这是一个字符串类型的值,必须准确匹配要取消订单的orderID
。该参数不能为空,且大小写敏感。请确保提供的orderID
是有效的,并且属于当前用户。
-
-
返回值:
一个包含订单详细信息的 JSON 对象。该对象会包含以下关键字段:
-
orderID
: 被取消的订单的唯一标识符,与请求参数中的orderID
一致。 -
status
: 订单的最新状态,取消成功时通常为 "cancelled" 或类似的状态值。 -
symbol
: 交易对,例如 "BTCUSDT"。 -
orderType
: 订单类型,例如 "limit"(限价单)或 "market"(市价单)。 -
price
: 订单的委托价格。 -
quantity
: 订单的委托数量。 -
timestamp
: 订单取消的时间戳。 - 其他与订单相关的详细信息,如手续费、成交均价等。
{"code": 400, "message": "订单不存在或已成交"}
-
6. 获取账户信息 (GET /api/v1/user/margin)
- 用途: 获取用户杠杆交易账户的详细信息,涵盖账户余额、已用余额、风险等级以及其他重要财务指标。此接口允许用户监控其杠杆账户的健康状况和风险敞口。
- 参数: 此接口调用无需任何请求参数。所有必要信息均通过身份验证和服务器端数据获取。
-
返回值:
一个包含账户信息的 JSON 对象,提供账户状态的全面视图。该对象包含以下关键字段:
-
账户余额 (account_balance)
: 账户中的总资产价值,以基础货币计价。 -
已用保证金 (used_margin)
: 当前持仓所使用的保证金总额。这是维持现有交易头寸所需的资金。 -
可用保证金 (available_margin)
: 可用于开立新头寸或提取的保证金金额。计算方式通常为账户余额减去已用保证金。 -
风险等级 (risk_level)
: 账户当前的风险水平,通常表示为数值或分类(例如,低、中、高)。风险等级基于账户的保证金率和持仓风险计算得出。 -
保证金率 (margin_ratio)
: 已用保证金与账户权益的比率,是衡量账户风险的重要指标。保证金率越高,账户面临的清算风险越高。 -
强平价格 (liquidation_price)
: 若市场价格达到此水平,用户的仓位将被强制平仓以防止进一步损失。 - 其他账户属性: 根据交易所的不同,可能包含额外的信息,例如未实现盈亏、已实现盈亏、手续费等。
-
7. 获取持仓信息 (GET /api/v1/position)
- 用途: 获取用户在特定或所有合约上的持仓信息,用于监控账户风险和评估交易表现。
-
参数:
-
symbol
(可选): 合约代码,用于指定需要查询的合约。例如,XBTUSD
代表比特币/美元永续合约。如果省略此参数,API 将返回所有已建立仓位的合约持仓信息。务必使用交易所支持的正确合约代码。
-
-
请求方式:
GET
-
请求URL:
/api/v1/position
-
返回值:
一个 JSON 数组,数组中的每个元素对应一个合约的持仓数据。每个元素包含以下关键字段:
-
symbol
: 合约代码。 -
currentQty
: 当前持仓数量。正数表示多头仓位,负数表示空头仓位。 -
avgEntryPrice
: 平均入场价格,即持仓的平均成本价格。 -
liquidationPrice
: 预估的强制平仓价格,当市场价格达到此价格时,仓位可能被强制平仓。请注意,此价格仅为预估值,实际强平价格可能因市场波动和交易所风控策略而有所不同。 -
unrealisedPnl
: 未实现盈亏,指当前持仓的浮动盈亏。正数表示盈利,负数表示亏损。计算公式通常为(当前市场价格 - 平均入场价格) * 持仓数量
。 -
realisedPnl
: 已实现盈亏,指已平仓部分的盈亏总和。 -
isOpen
: 布尔值,指示仓位是否开放。true
表示仓位未平仓,false
表示仓位已完全平仓。 -
crossMargin
: 布尔值,指示仓位是否使用全仓保证金模式。true
表示使用全仓保证金,false
表示使用逐仓保证金。 -
leverage
: 当前仓位的杠杆倍数.
-
-
示例返回值:
[ { "symbol": "XBTUSD", "currentQty": 100, "avgEntryPrice": 9500.00, "liquidationPrice": 9000.00, "unrealisedPnl": 500, "realisedPnl": 100, "isOpen": true, "crossMargin": true, "leverage": 10 }, { "symbol": "ETHUSD", "currentQty": -50, "avgEntryPrice": 200.00, "liquidationPrice": 220.00, "unrealisedPnl": -250, "realisedPnl": 50, "isOpen": true, "crossMargin": false, "leverage": 20 } ]
-
注意事项:
- 请务必妥善保管您的 API 密钥,避免泄露。
- 频繁调用 API 可能会受到频率限制。请参考交易所的 API 文档了解具体的限制规则。
- 返回的数据是动态的,会随着市场变化而变化。
- 在进行交易决策时,请结合其他信息来源,不要仅依赖 API 返回的数据。
错误处理
BitMEX API 利用标准的 HTTP 状态码体系来指示 API 请求的处理结果。通过检查状态码,开发者可以快速了解请求是否成功,或者遇到了何种类型的错误。以下是一些在与 BitMEX API 交互时可能遇到的常见 HTTP 状态码及其详细含义:
-
200 OK
: 请求成功。服务器已成功处理请求,并返回了预期的结果。这通常表示 API 调用一切正常。 -
400 Bad Request
: 客户端发出的请求存在错误。这可能包括请求体格式不正确、缺少必要的参数、参数值超出范围或类型不匹配等。服务器无法理解或处理此类请求。开发者应当仔细检查请求参数和格式,确保符合 API 文档的要求。 -
401 Unauthorized
: 客户端未提供有效的身份验证凭据。这通常意味着 API 密钥缺失、无效或签名错误。在调用需要身份验证的 API 端点时,请确保正确配置 API 密钥和签名,并且密钥具有访问该端点的权限。检查时间戳是否在允许的范围内也很重要。 -
403 Forbidden
: 客户端已通过身份验证,但没有权限访问请求的资源。这可能是由于 API 密钥的权限不足,或者访问了需要更高权限级别的端点。请检查 API 密钥的权限设置,并确保其具有访问目标资源的必要权限。 -
404 Not Found
: 请求的资源不存在。这可能是由于 URL 地址错误,或者请求的资源已被删除。请仔细检查 URL 地址,并确认请求的资源仍然存在。 -
429 Too Many Requests
: 客户端在短时间内发送了过多的请求,触发了速率限制。BitMEX API 对请求频率有限制,以防止滥用和保护服务器资源。开发者应该实施速率限制策略,例如使用指数退避算法,以避免触发此错误。HTTP 响应头中通常会包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining` 和 `X-RateLimit-Reset` 字段,用于指示速率限制的详细信息。 -
500 Internal Server Error
: 服务器遇到了意外的错误,无法完成请求。这通常是服务器端的问题,开发者可以稍后重试请求。如果问题持续存在,请联系 BitMEX 技术支持。
除了 HTTP 状态码之外,BitMEX API 在返回错误时,通常会在响应体中包含一个 JSON 对象,提供关于错误的更详细的信息。这个 JSON 对象通常包含以下字段:
-
error.message
: 错误的文本描述,提供关于错误的简要说明。 -
error.name
: 错误的名称或代码,用于标识错误的类型。
开发者应编写代码来解析这些错误信息,并根据错误的类型采取适当的措施,例如重试请求、记录错误日志或通知用户。通过妥善处理错误,可以提高应用程序的健壮性和用户体验。
限流
BitMEX API 实施了严格的限流机制,旨在防御潜在的滥用行为并维护整体系统的稳定性和可靠性。这些限流策略并非一成不变,而是会根据所访问的具体 API 端点以及用户的账户等级进行动态调整。当客户端的请求频率超出预设的阈值时,API 将返回一个明确的错误响应,HTTP 状态码为
429 Too Many Requests
,明确告知客户端其请求已因超出速率限制而被拒绝。
为了确保应用程序能够稳定高效地与 BitMEX API 交互,开发者应采取积极措施来优化其请求行为。合理的设计至关重要,应避免在短时间内向 API 发送大量请求。以下是一些建议的优化策略:
- 实施缓存机制: 对于不经常变动的数据,建议在客户端或服务器端实施缓存。通过缓存先前请求的结果,可以显著减少对 API 的重复调用,从而降低请求频率。
- 采用批量请求: 如果 API 支持批量请求,应尽可能将多个相关的操作合并到一个请求中。这可以减少请求的总数量,并降低服务器的负载。
-
应用指数退避算法:
当收到
429 Too Many Requests
错误时,不要立即重试请求。相反,应采用指数退避算法,逐渐增加重试之间的时间间隔。这有助于避免对 API 造成进一步的压力,并提高请求最终成功的可能性。 - 利用 WebSocket API: 对于需要实时更新的数据,建议使用 BitMEX 提供的 WebSocket API,而不是轮询 REST API。WebSocket 允许服务器主动推送数据到客户端,从而避免了频繁的请求,并降低了延迟。
- 监控 API 使用情况: 定期监控应用程序的 API 使用情况,以便及时发现潜在的性能瓶颈或请求频率过高的问题。根据监控结果,可以调整应用程序的请求策略,以满足 API 的限流要求。
SDK(软件开发工具包)
为了方便开发者在应用程序中集成 BitMEX API,BitMEX 社区以及第三方开发者维护了一系列开源的 SDK。 这些 SDK 覆盖了多种主流编程语言,包括但不限于 Python、JavaScript (Node.js)、Java 和 C# (.NET)。 SDK 的核心作用在于对 BitMEX API 的调用过程进行抽象和简化,开发者无需关注底层的 HTTP 请求细节,而是可以通过 SDK 提供的函数或类来完成诸如账户管理、订单提交、数据获取等操作。
使用 SDK 的优势显著。 例如,自动签名功能极大地简化了身份验证流程,开发者无需手动计算和添加 API 签名。 错误处理机制可以捕获并处理 API 返回的错误信息,避免程序崩溃。 重试机制则可以在网络不稳定的情况下自动重试 API 请求,提高程序的健壮性。 部分 SDK 还提供了数据模型定义、类型检查、异步请求支持等功能,进一步提高开发效率。
选择合适的 SDK 需要考虑多种因素。 开发者应根据自身熟悉的编程语言、项目对性能的要求、以及 SDK 的维护活跃度等因素进行选择。 建议查阅 SDK 的文档和示例代码,了解其功能和使用方法。 某些第三方 SDK 可能存在安全风险,使用前应进行充分的安全评估。