Bitfinex API掘金指南：解锁交易平台的秘密武器！

Bitfinex API 文档接口信息

Bitfinex 提供了一套强大的 REST 和 WebSocket API，允许开发者访问其交易平台的功能。本文将深入探讨 Bitfinex API 的关键接口信息，旨在帮助开发者更好地理解和使用这些接口。

REST API

Bitfinex REST API 提供了一种同步的方式来访问全面的账户信息、实时的市场数据以及强大的交易功能。开发者可以通过该接口执行各种操作，例如查询账户余额、获取最新的交易价格、提交和管理订单等。为了保证数据传输的安全性和完整性，所有与 Bitfinex REST API 的交互都需要通过加密的 HTTPS 协议进行。请求的根 URL 为 https://api.bitfinex.com/v2 。每个具体的 API 端点都会附加到这个根 URL 之后，形成完整的请求地址。例如，获取某个交易对的市场数据的端点可能是 /ticker ，那么完整的请求地址就是 https://api.bitfinex.com/v2/ticker 。

1. 市场数据

Bitfinex 提供全面且精细化的市场数据，涵盖交易对信息、实时订单簿、历史交易记录和多时间维度的蜡烛图数据，为交易者提供深度市场洞察。

• 交易对信息 ( /tickers )：该接口允许获取指定或所有交易对的实时快照信息，对于监控市场异动，制定交易策略至关重要。返回数据包括：最新成交价 (LAST_PRICE)，24 小时成交量 (VOLUME)，当日最高价 (HIGH)，当日最低价 (LOW)，买一价 (BID)，买一量 (BID_SIZE)，卖一价 (ASK)，卖一量 (ASK_SIZE)，以及 24 小时价格涨跌 (DAILY_CHANGE) 和涨跌百分比 (DAILY_CHANGE_PERC)。

  请求示例： GET /v2/tickers?symbols=tBTCUSD,tETHUSD (获取 BTC/USD 和 ETH/USD 的信息)

  返回示例： [[SYMBOL, BID, BID_SIZE, ASK, ASK_SIZE, DAILY_CHANGE, DAILY_CHANGE_PERC, LAST_PRICE, VOLUME, HIGH, LOW], ...] 例如 [["tBTCUSD", 29000, 0.5, 29000.5, 0.3, 100, 0.0034, 29000.2, 50, 29100, 28900], ...]

• 订单簿 ( /book/{symbol}/{precision} )：该接口提供指定交易对的实时订单簿数据，通过调整精度 (precision) 参数，可以控制返回数据的深度。较低的精度级别 (如 R0) 返回最接近市场价格的订单，而较高的精度级别可以提供更深入的订单簿信息，便于分析市场买卖力量的分布情况。订单簿数据的更新频率直接影响交易决策的准确性。

  请求示例： GET /v2/book/tBTCUSD/R0 (获取 BTC/USD 的原始精度订单簿)

  返回示例： [[PRICE, COUNT, AMOUNT], ...] 例如 [[29000, 2, 1.2], [28999.5, 5, 3.7], ...] PRICE 是价格，COUNT 是该价格等级的订单数量，AMOUNT 是该价格等级的订单总数量。正数 AMOUNT 代表买单，负数 AMOUNT 代表卖单。

• 交易历史 ( /trades/{symbol} )：该接口提供指定交易对的历史成交记录，允许用户回溯市场行为，分析交易模式。返回数据包含：交易 ID (ID)，交易时间戳 (MTS)，交易数量 (AMOUNT) 和成交价格 (PRICE)。AMOUNT 为正表示买入，AMOUNT 为负表示卖出。利用这些数据，可以进行成交量分析、价格趋势跟踪和算法回测。

  请求示例： GET /v2/trades/tBTCUSD (获取 BTC/USD 的交易历史)

  返回示例： [[ID, MTS, AMOUNT, PRICE], ...] 例如 [[123456789, 1678886400000, 0.5, 29000.2], ...] ID 是交易 ID，MTS 是交易的时间戳（毫秒级），AMOUNT 是交易数量（正数代表买入，负数代表卖出），PRICE 是交易价格。

• 蜡烛图数据 ( /candles/trade:{timeframe}:{symbol}/{section} )：该接口提供指定交易对在不同时间周期下的 K 线数据，是技术分析的基础。通过指定时间周期 (timeframe)，例如 1m (1 分钟), 5m (5 分钟), 1h (1 小时), 1D (1 天) 等，可以获取不同粒度的价格信息。返回数据包含：蜡烛图的开始时间戳 (MTS)，开盘价 (OPEN)，收盘价 (CLOSE)，最高价 (HIGH)，最低价 (LOW) 和成交量 (VOLUME)。

  请求示例： GET /v2/candles/trade:1m:tBTCUSD/hist (获取 BTC/USD 的 1 分钟 K 线历史数据)

  返回示例： [[MTS, OPEN, CLOSE, HIGH, LOW, VOLUME], ...] 例如 [[1678886400000, 29000, 29000.5, 29001, 28999.5, 10], ...] MTS 是蜡烛图的开始时间戳（毫秒级），OPEN 是开盘价，CLOSE 是收盘价，HIGH 是最高价，LOW 是最低价，VOLUME 是成交量。

2. 账户信息

访问账户信息需要使用 API 密钥进行身份验证，这是保障账户安全的关键措施。Bitfinex API 密钥需要在 Bitfinex 网站上预先生成，并且务必根据实际需求设置相应的权限。例如，如果只需要读取账户信息，则仅授予读取权限，避免不必要的风险。

• 账户信息 ( /auth/r/info/user ): 该接口提供用户的账户详细信息，包括但不限于账户 ID、费率等级（包括交易费率和融资费率）、邀请码 (Affiliate Code) 等。费率等级会影响交易手续费，较高的费率等级通常意味着更低的交易费用。邀请码则用于追踪通过用户邀请链接注册的新用户。

  请求示例： POST /v2/auth/r/info/user (请求头中需要携带有效的 API 密钥和签名)。签名是利用 API 密钥和请求参数生成的，用于验证请求的合法性，防止恶意篡改。

  返回示例： [ID, MTS, FEES_FUNDING, FEES_TRADING, AFF_CODE] 。其中， ID 代表账户 ID， MTS 代表时间戳（通常是 Unix 时间戳，表示信息最后更新的时间）， FEES_FUNDING 代表融资费率， FEES_TRADING 代表交易费率， AFF_CODE 代表邀请码。

• 钱包信息 ( /auth/r/wallets ): 该接口提供用户的钱包信息，详细展示了用户在不同币种上的资产状况，包括总余额和可用余额。这些信息对于追踪资产配置和进行交易决策至关重要。

  请求示例： POST /v2/auth/r/wallets (请求头中需要携带有效的 API 密钥和签名)。与账户信息接口类似，此请求也需要进行签名验证，确保安全性。

  返回示例： [[WALLET_TYPE, CURRENCY, BALANCE, UNREALIZED_PL, AVAILABLE_BALANCE, MTS_UPDATE], ...] 。其中， WALLET_TYPE 是钱包类型 (例如： exchange 交易所钱包，用于现货交易； margin 杠杆钱包，用于杠杆交易； funding 融资钱包，用于提供融资)， CURRENCY 是币种代码 (例如： BTC 比特币， ETH 以太坊)， BALANCE 是总余额，包括已冻结的资产； UNREALIZED_PL 是未实现的盈亏，反映了持仓的浮动盈利或亏损； AVAILABLE_BALANCE 是可用余额，即可用于交易或提现的余额； MTS_UPDATE 是钱包信息最后更新的时间戳。

• 订单信息 ( /auth/r/orders ): 该接口提供用户的订单信息，涵盖当前挂单和历史订单的详细数据。这对于分析交易策略和评估交易绩效至关重要。

  请求示例： POST /v2/auth/r/orders (请求头中需要携带有效的 API 密钥和签名)。确保 API 密钥具有读取订单信息的权限。

  返回示例： [[ID, GID, CID, SYMBOL, MTS_CREATE, MTS_UPDATE, AMOUNT, AMOUNT_ORIG, TYPE, TYPE_PREV, MTS_IF_CANCEL, MTS_IF_OCO_CANCEL, FLAGS, STATUS, PRICE, PRICE_AVG, PRICE_TRAILING, PRICE_AUX_LIMIT, HIDDEN, PL, PL_PERC, MTS_CREATE_FULL, MTS_UPDATE_FULL], ...] 。各个字段的含义如下： ID 订单 ID，唯一标识订单； GID 订单组 ID，用于关联批量订单； CID 客户端 ID，由客户端自定义； SYMBOL 交易对 (例如： BTCUSD )； MTS_CREATE 订单创建时间戳； MTS_UPDATE 订单最后更新时间戳； AMOUNT 订单剩余数量 (如果已完全成交，则为 0)； AMOUNT_ORIG 订单原始数量； TYPE 订单类型 (例如： LIMIT 限价单， MARKET 市价单)； TYPE_PREV 前一个订单类型 (如果订单被修改过)； MTS_IF_CANCEL 条件取消订单的时间戳； MTS_IF_OCO_CANCEL OCO (One-Cancels-the-Other) 订单取消时间戳； FLAGS 订单标志； STATUS 订单状态 (例如： ACTIVE 活跃， CANCELED 已取消， EXECUTED 已成交)； PRICE 订单价格； PRICE_AVG 平均成交价格； PRICE_TRAILING 追踪止损价格； PRICE_AUX_LIMIT 辅助限价； HIDDEN 是否隐藏订单； PL 盈亏； PL_PERC 盈亏百分比； MTS_CREATE_FULL 完整创建时间戳； MTS_UPDATE_FULL 完整更新时间戳。

3. 交易功能

交易功能同样需要通过 API 密钥进行身份验证，以确保账户安全和操作的合法性。密钥包含公钥和私钥，公钥用于识别用户身份，私钥用于生成签名，验证请求的完整性和真实性。

• 下单 ( /auth/w/order/new ): 该接口允许用户提交新的交易订单，是执行加密货币买卖的核心功能。为了确保订单能够被正确执行，需要详细指定以下关键参数：

请求参数详解:

• 交易对 (symbol) : 指定交易的市场，例如 tBTCUSD 表示比特币兑美元。交易对的格式通常为 tXXXYYY ，其中 XXX 是基础货币， YYY 是报价货币。
• 订单类型 (type) : 指定订单的执行方式。常见的订单类型包括：
  • LIMIT (限价单): 以指定的价格或更优的价格执行。如果市场价格未达到指定价格，订单将保持挂单状态。
  • MARKET (市价单): 立即以当前市场最佳价格执行。市价单能够快速成交，但最终成交价格可能与预期有所偏差。
  • STOP (止损单): 当市场价格达到指定的止损价格时，订单将自动转换为市价单执行。
  • STOP LIMIT (止损限价单): 当市场价格达到指定的止损价格时，订单将自动转换为限价单执行。
  • TRAILING STOP (追踪止损单): 止损价格会根据市场价格的变动而自动调整，始终与市场价格保持一定的距离。
• 订单数量 (amount) : 指定买入或卖出的数量。正数表示买入，负数表示卖出。数量的单位通常是基础货币，例如， amount: 0.1 表示买入 0.1 个比特币。
• 价格 (price) : 对于限价单，必须指定价格。对于市价单，则不需要指定价格。价格的单位是报价货币，例如， price: 10000 表示以 10000 美元的价格买入一个比特币。
• 客户订单 ID (cid) : 由客户端自定义的订单 ID，用于唯一标识订单。方便客户端追踪订单状态。

请求示例： POST /v2/auth/w/order/new (必须包含通过 API 密钥和请求参数生成的签名，以验证请求的合法性)

请求体示例： {"cid": 12345, "type": "LIMIT", "symbol": "tBTCUSD", "amount": 0.1, "price": 10000}

返回示例： [ID, GID, CID, SYMBOL, MTS_CREATE, MTS_UPDATE, AMOUNT, AMOUNT_ORIG, TYPE, TYPE_PREV, MTS_IF_CANCEL, MTS_IF_OCO_CANCEL, FLAGS, STATUS, PRICE, PRICE_AVG, PRICE_TRAILING, PRICE_AUX_LIMIT, HIDDEN, PL, PL_PERC, MTS_CREATE_FULL, MTS_UPDATE_FULL] ，返回数组包含了订单的各项详细信息，例如订单 ID ( ID )、订单状态 ( STATUS )、成交均价 ( PRICE_AVG ) 等。 通过解析返回信息，可以了解订单的执行情况。

• 取消订单 ( /auth/w/order/cancel ): 该接口允许用户撤销尚未成交的订单。取消订单的操作可以防止市场价格波动带来的潜在损失。

  取消订单时，可以通过以下两种方式指定要取消的订单：

  • 订单 ID (id) : 交易所分配的唯一订单标识符。
  • 客户订单 ID (cid) : 客户端自定义的订单标识符。如果创建订单时指定了 cid ，则可以使用 cid 来取消订单。

  请求示例： POST /v2/auth/w/order/cancel (需要包含通过 API 密钥和请求参数生成的签名)

  请求体示例： {"id": 123456} 或 {"cid": 12345} ，根据需要选择使用订单 ID 或客户订单 ID。

  返回示例： [ID, GID, CID, SYMBOL, MTS_CREATE, MTS_UPDATE, AMOUNT, AMOUNT_ORIG, TYPE, TYPE_PREV, MTS_IF_CANCEL, MTS_IF_OCO_CANCEL, FLAGS, STATUS, PRICE, PRICE_AVG, PRICE_TRAILING, PRICE_AUX_LIMIT, HIDDEN, PL, PL_PERC, MTS_CREATE_FULL, MTS_UPDATE_FULL] ，返回数组包含被取消订单的详细信息。 注意，取消订单并不保证一定能够成功，如果订单已经成交或正在被处理，则可能无法取消。

WebSocket API

Bitfinex WebSocket API 是一种强大的工具，能够提供市场数据和账户信息的实时更新。它通过建立持久的双向通信通道，让用户能够以极高的效率接收推送数据。与传统的 REST API 相比，WebSocket API 在数据传输速度和延迟方面具有显著优势，特别适合需要快速响应市场变化的交易策略和高频交易。

具体来说，REST API 依赖于客户端发起请求，服务器响应的方式，每次数据更新都需要客户端发送新的请求。而 WebSocket API 则允许服务器主动推送数据到客户端，无需客户端频繁轮询。这种机制极大地降低了延迟，并减少了不必要的数据传输，从而提高了整体效率。利用 WebSocket API，用户可以实时获取交易对的最新价格、订单簿深度、成交历史等市场数据，以及账户余额、持仓信息、订单状态等账户信息。这些实时数据对于制定精准的交易决策至关重要。

1. 市场数据频道

通过订阅不同的市场数据频道，用户可以实时接收关于特定加密货币交易对的市场数据更新，用于程序化交易、风险管理和市场分析。

• Ticker Channel ( ticker ) : 提供交易对的实时价格、成交量和其他关键指标，是快速掌握市场动态的核心频道。

  订阅示例： {"event": "subscribe", "channel": "ticker", "symbol": "tBTCUSD"} 。此命令指示服务器推送比特币兑美元 (tBTCUSD) 交易对的实时 ticker 数据。

  更新示例： [CHANNEL_ID, BID, BID_SIZE, ASK, ASK_SIZE, DAILY_CHANGE, DAILY_CHANGE_PERC, LAST_PRICE, VOLUME, HIGH, LOW] 。其中：

  • CHANNEL_ID : 频道ID，用于标识数据流。
  • BID : 当前最高买入价。
  • BID_SIZE : 当前最高买入价的挂单量。
  • ASK : 当前最低卖出价。
  • ASK_SIZE : 当前最低卖出价的挂单量。
  • DAILY_CHANGE : 当日价格变动。
  • DAILY_CHANGE_PERC : 当日价格变动百分比。
  • LAST_PRICE : 最新成交价。
  • VOLUME : 当日成交量。
  • HIGH : 当日最高价。
  • LOW : 当日最低价。
• Trades Channel ( trades ) : 提供交易对的实时交易信息，包括成交时间、价格和数量，可以帮助用户追踪市场参与者的行为。

  订阅示例： {"event": "subscribe", "channel": "trades", "symbol": "tBTCUSD"} 。该订阅指令用于接收 tBTCUSD 交易对的实时成交记录。

  更新示例： [CHANNEL_ID, [ID, MTS, AMOUNT, PRICE]] 。其中：

  • CHANNEL_ID : 频道ID，用于标识数据流。
  • ID : 交易ID，每笔交易的唯一标识符。
  • MTS : 交易时间戳，通常是 Unix 毫秒时间戳。
  • AMOUNT : 交易数量，正数为买入，负数为卖出。
  • PRICE : 交易价格。
• Order Book Channel ( book ) : 提供交易对的实时订单簿信息，展示市场深度，帮助用户了解买卖力量的分布情况。

  订阅示例： {"event": "subscribe", "channel": "book", "symbol": "tBTCUSD", "prec": "R0", "len": "25"} 。此示例订阅 tBTCUSD 交易对的订单簿数据， prec 参数定义了价格精度（例如， R0 表示原始精度）， len 参数定义了订单簿的深度，即返回多少档买卖盘数据 (此处为25档)。

  更新示例： [CHANNEL_ID, [[PRICE, COUNT, AMOUNT], ...]] 。其中：

  • CHANNEL_ID : 频道ID，用于标识数据流。
  • PRICE : 价格。
  • COUNT : 相同价格的订单数量。
  • AMOUNT : 订单数量，正数为买单，负数为卖单。
• Candles Channel ( candles ) : 提供交易对的实时蜡烛图数据，用户可以按不同时间周期（如1分钟、5分钟、1小时）获取开盘价、收盘价、最高价、最低价和成交量等信息，用于技术分析。

  订阅示例： {"event": "subscribe", "channel": "candles", "key": "trade:1m:tBTCUSD"} 。此命令用于订阅 tBTCUSD 交易对的 1 分钟蜡烛图数据。 key 参数包含了时间周期和交易对信息。

  更新示例： [CHANNEL_ID, [MTS, OPEN, CLOSE, HIGH, LOW, VOLUME]] 。其中：

  • CHANNEL_ID : 频道ID，用于标识数据流。
  • MTS : 蜡烛图结束时间戳，通常是 Unix 毫秒时间戳。
  • OPEN : 开盘价。
  • CLOSE : 收盘价。
  • HIGH : 最高价。
  • LOW : 最低价。
  • VOLUME : 成交量。

2. 账户信息频道

完成身份验证（KYC）后，用户可以订阅账户信息频道，实时接收与其账户相关的各类信息的更新。这些频道提供对订单状态、钱包余额等关键数据的即时访问，确保用户能够迅速响应市场变化。

• Orders Channel ( orders ) : 此频道提供订单状态的实时、动态更新，覆盖订单生命周期的各个阶段。用户可以通过订阅此频道，获取关于订单创建、执行、部分成交、完全成交、取消以及其他状态变更的即时通知。

  认证后更新示例： [0, "os", [ID, GID, CID, SYMBOL, MTS_CREATE, MTS_UPDATE, AMOUNT, AMOUNT_ORIG, TYPE, TYPE_PREV, MTS_IF_CANCEL, MTS_IF_OCO_CANCEL, FLAGS, STATUS, PRICE, PRICE_AVG, PRICE_TRAILING, PRICE_AUX_LIMIT, HIDDEN, PL, PL_PERC, MTS_CREATE_FULL, MTS_UPDATE_FULL]]

  字段说明：

  • ID : 订单的唯一标识符。
  • GID : 群组订单标识符（如果订单属于一个群组）。
  • CID : 客户端订单标识符（用户自定义）。
  • SYMBOL : 交易的交易对，例如 "BTCUSD"。
  • MTS_CREATE : 订单创建的时间戳（毫秒）。
  • MTS_UPDATE : 订单上次更新的时间戳（毫秒）。
  • AMOUNT : 订单的剩余数量（正数为买单，负数为卖单）。
  • AMOUNT_ORIG : 订单的原始数量。
  • TYPE : 订单类型，例如 "LIMIT"、"MARKET"、"STOP" 等。
  • TYPE_PREV : 前一个订单类型（如果订单类型发生更改）。
  • MTS_IF_CANCEL : 如果订单被取消，则为取消的时间戳（毫秒）。
  • MTS_IF_OCO_CANCEL : 如果订单因 OCO 订单被取消，则为取消的时间戳（毫秒）。
  • FLAGS : 订单标志。
  • STATUS : 订单状态，例如 "ACTIVE"、"EXECUTED"、"CANCELED" 等。
  • PRICE : 订单的价格。
  • PRICE_AVG : 平均成交价格。
  • PRICE_TRAILING : 追踪止损价格。
  • PRICE_AUX_LIMIT : 辅助限价。
  • HIDDEN : 指示订单是否隐藏在订单簿中。
  • PL : 盈亏。
  • PL_PERC : 盈亏百分比。
  • MTS_CREATE_FULL : 订单完整创建时间戳（毫秒）。
  • MTS_UPDATE_FULL : 订单完整更新时间戳（毫秒）。
• Wallets Channel ( wallets ) : 此频道提供用户钱包余额的实时更新，包括不同货币的余额、未实现盈亏、可用余额以及上次更新的时间戳。用户可以通过订阅此频道，随时掌握其资金状况，以便做出明智的交易决策。

  认证后更新示例： [0, "wu", [WALLET_TYPE, CURRENCY, BALANCE, UNREALIZED_PL, AVAILABLE_BALANCE, MTS_UPDATE]]

  字段说明：

  • WALLET_TYPE : 钱包类型，例如 "EXCHANGE"、"MARGIN"、"FUNDING" 等。
  • CURRENCY : 货币代码，例如 "BTC"、"USD"、"ETH" 等。
  • BALANCE : 钱包余额。
  • UNREALIZED_PL : 未实现盈亏。
  • AVAILABLE_BALANCE : 可用余额。
  • MTS_UPDATE : 上次更新的时间戳（毫秒）。

3. 身份验证

为了保障 WebSocket API 的安全访问，身份验证机制至关重要。客户端需要发送一条包含 API 密钥、时间戳（nonce）以及经过加密签名的认证消息，以此证明其身份的合法性。该过程类似于提供数字签名，服务端会验证签名以确认请求的来源和完整性。

认证消息示例（JSON 格式）：

{
  "event": "auth",
  "apiKey": "YOUR_API_KEY",
  "authSig": "YOUR_AUTH_SIGNATURE",
  "authPayload": "AUTH_PAYLOAD",
  "authNonce": "NONCE"
}

字段解释：

• event : 固定值为 "auth"，表明这是一个身份验证请求。
• apiKey : 您的 API 密钥，用于标识您的账户。 请妥善保管，切勿泄露。
• authSig : 认证签名，是对 authPayload 进行加密后的结果，确保消息的安全性。
• authPayload : 认证载荷，包含认证所需的数据。
• authNonce : 一个随机数 (nonce)，用于防止重放攻击。每次请求都应生成不同的 nonce。

authSig 的生成过程如下：使用您的 API 密钥的 secret 对 authPayload 进行 HMAC-SHA384 加密。 然后，将加密结果作为 authSig 的值。 authPayload 的构建方式为 AUTH_PAYLOAD = 'AUTH' + NONCE 。 这里 'AUTH' 是一个固定的字符串，与 NONCE 拼接而成。 选择 HMAC-SHA384 算法是为了提供更强的安全性保证，防止数据篡改和伪造。

错误处理

Bitfinex API 利用标准 HTTP 状态码来明确指示请求的处理结果。例如， 200 OK 状态码表明请求已成功处理并返回了预期数据。 400 Bad Request 则意味着客户端请求存在问题，例如缺少必要的参数、参数格式不正确或参数值超出允许范围。 401 Unauthorized 表示客户端未提供有效的身份验证凭据或提供的凭据无效，导致服务器拒绝访问。 500 Internal Server Error 指示服务器在处理请求时遇到了未预期的内部错误，可能需要 Bitfinex 方面进行修复。

除了 HTTP 状态码，Bitfinex API 返回的 JSON 响应通常也会包含详细的错误信息，以便开发者能够更精确地定位和解决问题。错误信息可能包括错误代码、错误消息以及相关的上下文数据。开发者务必对 API 返回的 JSON 响应进行全面检查，特别关注是否存在 error 或 message 等字段，这些字段通常包含错误描述。通过解析这些错误信息，开发者可以更快地诊断问题，例如请求频率超限、账户余额不足或交易参数不符合规则等，从而采取相应的解决措施，例如调整请求频率、充值账户或修改交易参数。