Bitfinex API 文档概览
介绍
Bitfinex API 提供了访问 Bitfinex 数字资产交易平台各项功能的程序化接口，极大地扩展了用户的交易体验和数据分析能力。开发者和交易员可以利用该 API 编程化地执行各类交易操作，包括但不限于限价单、市价单、止损单等高级订单类型。API 还支持实时市场数据的获取，涵盖交易对的最新价格、交易量、深度图等关键信息，为算法交易和市场监控提供坚实基础。账户管理功能同样通过 API 开放，允许用户查询账户余额、管理 API 密钥、监控交易历史等。Bitfinex API 的设计目标是为开发者提供一个强大、灵活且高度可定制的工具集，旨在助力他们构建复杂的自动化交易策略、优化交易执行流程，以及将 Bitfinex 的丰富市场数据无缝集成到各种现有应用程序、分析工具和金融科技解决方案中。通过充分利用 Bitfinex API，用户可以显著提升交易效率，并更好地把握市场机遇。
API 版本
Bitfinex API 拥有多个版本，为了确保最佳性能、安全性和功能，强烈建议使用最新的API版本。当前推荐的API版本通常为 v2，因为它包含了最新的优化和功能增强。然而，必须认识到不同API版本之间可能存在显著的不兼容性，例如请求参数、响应格式以及认证机制的差异。
在使用Bitfinex API之前，至关重要的是查阅并深入理解您所选择的API版本对应的官方文档。这些文档详细描述了端点的功能、参数要求、速率限制、错误代码以及数据结构。仔细研究文档有助于避免常见错误，并确保您的应用程序能够正确地与Bitfinex平台进行交互。忽略版本兼容性可能导致应用程序无法正常工作或返回意外结果。
请关注Bitfinex官方的更新日志和公告，以便及时了解API版本更新、废弃以及安全补丁等重要信息。适时地将您的应用程序迁移到最新的API版本，能够确保您始终能够利用最新的功能和改进，并最大限度地减少潜在的安全风险。
认证
大多数 API 端点为了保障用户数据安全，都需要进行身份认证才能访问，尤其是那些涉及到账户余额、交易历史等敏感信息的端点。 Bitfinex 平台采用 API 密钥 (API Key) 和 Secret 密钥 (Secret Key) 的组合来进行身份验证。 用户可以在 Bitfinex 账户设置的安全中心页面中生成并管理这些密钥。
有效的身份认证过程通常包含以下几个关键步骤，以确保请求的合法性和安全性：
- 生成唯一的 nonce (number used once，一次性随机数): nonce 是一个每次请求都必须不同的数字或字符串，用于防止重放攻击。重放攻击是指攻击者截获并重新发送有效的请求，从而未经授权地执行操作。 为了保证 nonce 的唯一性，通常使用递增的整数或基于时间戳生成的高精度数值。 强烈建议使用单调递增的 nonce，服务器端会验证 nonce 的有效性。
-
构建签名字符串:
将请求的 API 路径 (例如
/v2/ticker/tBTCUSD)、nonce 值以及请求体 (request body，如果存在) 按照特定规则组合成一个字符串。 这个字符串将作为后续加密的输入。请求体应该保持与发送时完全一致，包括键的顺序。 - 生成 HMAC-SHA384 签名: 使用您的 Secret 密钥 (Secret Key) 对上一步构建的签名字符串进行 HMAC-SHA384 加密。 HMAC-SHA384 是一种带密钥的哈希算法，它能有效地防止篡改和伪造。 Secret 密钥必须妥善保管，绝对不能泄露给任何人。
-
构造 HTTP 请求头:
将 API 密钥 (API Key)、nonce 值以及 HMAC-SHA384 加密后的签名作为 HTTP 请求头发送给 Bitfinex 服务器。 通常，这些请求头的名称为
bfx-apikey、bfx-nonce和bfx-signature。 服务器会验证这些信息的有效性，以确认请求的身份。
为了简化认证过程，各种编程语言和库都提供了方便的工具。例如，在 Python 中，可以使用标准库中的
hmac
和
hashlib
模块来实现 HMAC-SHA384 加密。 许多第三方库也提供了更高级的 API 封装，可以自动处理认证过程。 在使用这些库时，请务必仔细阅读其文档，并确保正确配置 API 密钥和 Secret 密钥。
数据格式
Bitfinex API 主要采用 JSON (JavaScript Object Notation) 格式作为其标准的数据交换语言。JSON 是一种轻量级的数据交换格式，凭借其易读性、简洁性和跨平台兼容性，已成为 Web API 的行业标准。所有通过 Bitfinex API 发送的请求以及收到的响应，都将以 JSON 字符串的形式呈现。这意味着无论您使用何种编程语言或开发环境，都可以方便地解析和处理这些数据。JSON 的结构基于键值对，能够清晰地组织复杂的数据结构，例如交易信息、账户余额、订单簿数据等。Bitfinex API 详细的文档中提供了各种数据结构的 JSON 示例，帮助开发者快速理解和集成。
速率限制
为保障 Bitfinex API 的稳定运行，并确保所有用户的公平访问，Bitfinex 实施了速率限制机制。这意味着，在一定的时间段内，API 允许的请求数量存在上限。速率限制的具体数值因不同的 API 端点和用户身份验证级别而异。例如，公共 API 端点通常具有比私有 API 端点更严格的限制，而高级别账户可能享有更高的请求配额。
当应用程序超出预设的速率限制时，Bitfinex API 会返回一个错误代码（通常是 HTTP 状态码 429，表示“请求过多”）。为了避免服务中断，开发者必须在应用程序中构建健壮的错误处理逻辑和重试机制。这包括检测 API 返回的速率限制错误，并在短暂的延迟后自动重试请求。更高级的策略包括使用指数退避算法来逐步增加重试之间的延迟，以避免进一步加剧 API 负载。另外，利用API响应头中包含的速率限制信息，如剩余请求数量和重置时间，可以帮助开发者更有效地管理请求频率。
WebSocket API
除了 REST API 之外，Bitfinex 还提供了功能强大的 WebSocket API，专门用于接收实时的市场数据和账户更新。 与 REST API 的轮询模式不同，WebSocket API 采用推送模式，极大地降低了延迟，使得用户能够更迅速地响应市场变化。
WebSocket API 允许用户订阅多个特定的频道，从而根据自身需求定制接收的数据类型。这些频道包括但不限于：特定交易对的最新报价（Ticker）、实时成交记录（Trades）、以及深度订单簿的增量更新（Order Book）。通过订阅这些频道，用户可以实时掌握市场动态，构建对市场变化高度敏感的交易策略。
通过 WebSocket API，用户可以构建超低延迟的交易系统，这些系统能够实时监控市场动态，并在最佳时机执行交易。例如，量化交易者可以利用 WebSocket API 接收到的实时数据，快速计算出套利机会，并立即下单执行套利策略。高频交易者则可以基于实时订单簿数据，进行微观结构分析，从而优化其交易决策。 WebSocket API 也被广泛应用于风险管理系统中，用于实时监控账户风险，并及时发出预警。
为了确保数据的可靠性和安全性，Bitfinex 的 WebSocket API 采用了严格的安全措施，包括身份验证、数据加密和流量控制。开发者可以通过 Bitfinex 提供的详细文档和示例代码，快速上手 WebSocket API 的使用。 Bitfinex 还会定期对 WebSocket API 进行升级和优化，以提高其性能和稳定性。
REST API 端点
以下是一些常用的 REST API 端点，它们是与加密货币交易所交互的关键入口，允许开发者获取市场数据、管理账户和执行交易。
- /v2/tickers: 获取指定交易对的最新行情数据。除了最高价、最低价、成交量，该端点通常还会提供开盘价、收盘价、加权平均价、价格变动百分比等更详细的行情信息。可以根据需要指定多个交易对，或通过参数筛选特定时间段的数据。
- /v2/trades: 获取指定交易对的成交记录，反映市场实时交易活动。除了成交价格、成交时间和成交数量，通常还会包含成交方向（买入或卖出）、成交ID等信息。通过分页参数可以获取大量的历史成交记录，用于市场深度分析和交易策略回测。
- /v2/book: 获取指定交易对的订单簿信息，深度了解市场供需关系。订单簿包含买单（bid）和卖单（ask）的价格和数量，可以清晰地看到市场挂单情况。订单簿的深度（即显示的订单数量）通常可以通过参数进行调整。高频交易者和套利者会密切关注订单簿的变化。
- /v2/candles: 获取指定交易对的历史 K 线数据，用于技术分析和趋势预测。每个 K 线代表一个时间周期内的开盘价、最高价、最低价和收盘价。可指定不同的时间周期，如1分钟、5分钟、1小时、1天等，以满足不同时间跨度的分析需求。还可以包括成交量、成交额等辅助信息。
- /v2/account_info: 获取账户信息，包括账户余额、可用资金、已用保证金、交易手续费率等。该端点需要身份验证，确保账户安全。提供的具体信息取决于交易所的API设计。
- /v2/order/new: 创建新的订单，执行交易操作。需要身份验证，并提供必要的订单参数，如交易对、订单类型（市价单、限价单、止损单等）、交易方向（买入或卖出）、委托价格（针对限价单和止损单）、委托数量等。API通常会返回订单ID，用于后续查询和管理。
- /v2/order/cancel: 取消订单，撤销未成交的挂单。需要身份验证，并提供要取消的订单ID。成功取消后，交易所会释放相应的保证金。
- /v2/positions: 获取当前持仓信息，了解账户的资产配置情况。包括持仓的交易对、持仓数量、平均持仓成本、未实现盈亏、已实现盈亏、保证金占用等。该端点需要身份验证。
- /v2/wallets: 获取钱包余额信息，查看账户中各种加密货币的可用余额。通常会显示币种、可用余额、冻结余额等。该端点需要身份验证。 部分交易所可能将钱包余额与账户信息合并在同一个端点中。
每个端点都支持不同的参数，例如指定时间范围、交易对、请求数量等。建议查阅相应的 API 文档，详细了解每个端点的参数说明、返回格式、请求频率限制和身份验证方式，以便正确有效地使用这些API。
错误处理
Bitfinex API 遵循标准的 HTTP 状态码约定，以此明确指示请求的处理结果。例如，状态码
200
表明请求已成功处理并返回预期结果；
400
则表示客户端请求存在错误，例如参数格式不正确或缺失必需字段；
401
状态码指示客户端未经过身份验证或提供的身份验证信息无效，导致请求被拒绝；
429
意味着客户端已超过 API 的速率限制，需要稍后重试；
500
状态码则表明 Bitfinex 服务器内部发生错误，影响了请求的处理。
当 Bitfinex API 返回错误响应时，通常会在响应体中包含更详细的错误信息，包括特定的错误代码 (error code) 和描述性的错误消息 (error message)。这些信息旨在帮助开发者快速诊断和解决问题，理解错误的根本原因，例如无效的参数、账户权限不足或服务器端故障等。开发者应根据这些错误信息调整请求参数、检查账户设置或稍后重试，以确保 API 请求的成功执行。错误代码和错误消息的具体格式和含义，请参考 Bitfinex 官方 API 文档中的错误码列表。
订阅频道 (WebSocket API)
WebSocket API 采用 JSON 格式进行实时数据传输和消息交换。客户端通过发送订阅消息，可以实时接收感兴趣的特定频道数据更新。以下列出了几个常用的频道类型及其功能描述：
- ticker: 订阅指定交易对的实时行情数据快照。该频道提供交易对的最新成交价、最高价、最低价、成交量等关键指标，帮助用户快速掌握市场动态。
- trades: 订阅指定交易对的实时成交记录。该频道提供每一笔成交订单的详细信息，包括成交价格、成交数量、成交时间等，方便用户进行高频交易分析和策略回测。
- book: 订阅指定交易对的实时订单簿信息。该频道提供买单和卖单的挂单价格和数量，呈现市场的买卖深度，帮助用户判断市场支撑位和阻力位，进行更精准的交易决策。 订单簿数据通常包含多个深度级别，反映不同价格区间的挂单情况。
- candles: 订阅指定交易对的历史 K 线数据。该频道提供不同时间周期（如1分钟、5分钟、1小时、1天等）的K线数据，包括开盘价、收盘价、最高价、最低价，用户可以利用这些数据进行技术分析，判断市场趋势。
订阅消息必须包含
event
字段，并且其值必须设置为 "subscribe"，用于标识该消息为订阅请求。
同时，还需要包含
channel
字段，用于明确指定需要订阅的频道名称，例如 "ticker"、"trades"、"book" 或 "candles"。
除了上述基本字段外，通常还需要包含其他参数，例如
symbol
字段，用于指定要订阅的交易对，例如 "BTCUSDT" 或 "ETHBTC"。
其他可选参数可能包括时间周期（对于candles频道）和深度级别（对于book频道）。
服务器会定期推送更新消息，这些消息以 JSON 格式发送，包含频道名称以及与该频道相关的数据。 客户端需要负责解析这些接收到的消息，并根据自身的业务逻辑进行相应的处理。 例如，客户端可以将ticker数据实时显示在界面上，或者将trades数据用于自动交易策略。 消息处理需要考虑数据格式、错误处理和数据同步等因素。
取消订阅频道 (WebSocket API)
要停止接收来自特定频道的实时数据，客户端需要发送一个取消订阅请求到WebSocket服务器。该请求的核心在于取消之前建立的订阅关系。取消订阅消息必须严格遵循特定的格式，以确保服务器能够正确识别并处理该请求。
取消订阅消息的关键组成部分包括：
event
字段，其值必须明确设置为 "unsubscribe"，用以告知服务器这是一个取消订阅的意图；以及
chanId
字段，该字段的值为需要取消订阅的特定频道 ID。
chanId
是一个整数，用于唯一标识一个WebSocket频道。缺少任何一个关键字段或字段值不正确都可能导致取消订阅失败。
每个成功订阅的频道都会由服务器分配一个唯一的频道 ID (
chanId
)。这个
chanId
是在订阅请求成功后，服务器返回给客户端的响应数据的一部分。客户端必须妥善保存这些频道 ID，并将它们与相应的订阅内容关联起来。在后续需要停止接收特定频道的数据时，客户端需要使用对应的
chanId
来构造取消订阅消息。如果客户端丢失了
chanId
，将无法取消订阅该频道，除非重新建立订阅。
心跳检测 (WebSocket API)
为了确保 WebSocket 连接的稳定性和可靠性，Bitfinex API 采用了定期发送心跳消息的机制。这种机制旨在监控连接的有效性，并及时发现和处理潜在的网络问题。客户端必须正确地接收这些心跳消息，并在规定的时间内做出响应，从而维持连接的活跃状态，避免因长时间无数据交互而被服务器断开。
具体来说，服务器会周期性地发送特定的心跳消息（通常是简单的ping消息），客户端在接收到这些消息后，需要立即回复相应的pong消息。这个ping-pong过程验证了客户端与服务器之间的网络链路是畅通的。如果在设定的超时时间内，客户端未能收到心跳消息，或者发送的响应消息未能被服务器接收，客户端应主动断开当前的WebSocket连接，并尝试重新建立连接。这种主动重连策略能够有效地应对网络波动或服务器端的问题，保证应用程序的持续运行。
心跳检测机制是构建健壮的WebSocket应用程序的关键组成部分。通过及时检测和处理连接中断问题，可以避免数据丢失、延迟增加等不良影响，从而提升用户体验，确保数据传输的准确性和实时性。
示例代码
以下是一个使用 Python 编程语言，通过 HTTP 请求获取 Bitfinex 交易所 BTCUSD 交易对最新行情数据的示例代码。此示例展示了如何与 RESTful API 交互，获取加密货币市场的实时信息。
import requests
url = "https://api.bitfinex.com/v2/tickers?symbols=tBTCUSD"
response = requests.get(url)
if response.status_code == 200:
data = response.()
print(data)
else:
print(f"Error: {response.status_code} - {response.text}")
该代码段首先导入 `requests` 库，该库用于发起 HTTP 请求。然后，定义了 API 端点 URL，指向 Bitfinex 交易所的 `/v2/tickers` 接口，并指定查询 `tBTCUSD` 交易对。`requests.get(url)` 函数发送 GET 请求到指定的 URL，并将响应存储在 `response` 对象中。检查 HTTP 状态码，如果状态码为 200 (OK)，表示请求成功，则使用 `response.()` 方法将 JSON 格式的响应数据解析为 Python 对象，并打印到控制台。如果状态码不是 200，则打印错误信息，包括状态码和响应文本，以便进行调试。
这是一个使用 Python 获取 Bitfinex 交易所 BTCUSD 交易对最近成交历史记录的示例代码。此示例演示了如何检索指定交易对的交易历史数据，包括成交价格、成交数量和成交时间。
import requests
url = "https://api.bitfinex.com/v2/trades/tBTCUSD/hist"
response = requests.get(url)
if response.status_code == 200:
data = response.()
print(data)
else:
print(f"Error: {response.status_code} - {response.text}")
类似地，此代码段也导入了 `requests` 库。API 端点 URL 指向 Bitfinex 交易所的 `/v2/trades/tBTCUSD/hist` 接口，用于获取 `tBTCUSD` 交易对的交易历史。发送 GET 请求并检查 HTTP 状态码。如果状态码为 200，则将 JSON 响应数据解析为 Python 对象并打印到控制台。否则，打印包含状态码和响应文本的错误信息。
请注意，以上示例代码为了便于演示，仅展示了最基本的功能。在实际应用中，需要对代码进行适当的修改和完善，例如添加错误处理机制、数据验证、分页处理、API 密钥管理、速率限制处理和数据持久化等。应仔细阅读 Bitfinex 交易所的 API 文档，了解 API 的具体使用方法和限制，并根据实际需求进行调整。请务必注意保护您的 API 密钥，避免泄露。
Bitfinex API 提供了一个强大的平台，用于访问其交易所的功能。 通过仔细阅读 API 文档，并遵循最佳实践，开发者可以构建高效、可靠的交易应用程序。强烈建议开发者在开始使用 API 之前，仔细阅读官方文档，并进行充分的测试。
