Bitfinex API 文档接口信息
概述
Bitfinex API 提供了一套全面的接口，允许开发者访问平台的各种功能，涵盖现货和衍生品交易、实时市场数据、账户管理、资金划转以及报告生成等。 这些接口基于 REST 和 WebSocket 协议，旨在提供高效、低延迟、高可靠的数据传输和交易执行能力，满足高频交易者、做市商和机构投资者的需求。开发者可以利用这些接口构建自动化交易系统、市场数据分析工具、风险管理系统以及定制化的交易界面。
REST API 适用于执行交易指令、查询账户信息和历史数据等非实时性操作，它采用标准的 HTTP 请求方法（GET, POST, PUT, DELETE）进行数据交互，并返回 JSON 格式的数据。 REST API 提供了丰富的端点，包括：
- 交易接口： 用于下单、撤单、修改订单，查询订单状态和历史成交记录。
- 账户接口： 用于查询账户余额、交易历史、资金流水，以及进行资金划转。
- 市场数据接口： 用于获取交易对的最新价格、成交量、深度数据、历史 K 线图等。
- 钱包接口： 用于查看钱包信息，进行充币、提币等操作。
- 报告接口： 用于生成各种交易报告和账户报表。
WebSocket API 适用于接收实时市场数据更新、账户状态变化等需要低延迟响应的场景。它通过建立持久连接，实现双向数据传输，避免了频繁的 HTTP 请求，显著降低了延迟。 WebSocket API 提供了以下主要功能：
- 实时市场数据： 订阅交易对的实时价格、成交量、深度数据更新。
- 实时订单更新： 接收订单状态变化（创建、成交、取消）的实时通知。
- 实时账户更新： 接收账户余额、交易历史变化的实时通知。
Bitfinex API 还提供了身份验证机制，以确保用户账户的安全。 开发者需要使用 API 密钥和密钥签名来验证其身份，才能访问受保护的 API 端点。 Bitfinex 提供了详细的 API 文档和示例代码，帮助开发者快速上手并有效地利用这些接口。
为了更好地使用 Bitfinex API，开发者需要熟悉 REST 和 WebSocket 协议、JSON 数据格式、HTTP 请求方法，并了解 Bitfinex 平台的交易规则和费用结构。 开发者还需要注意 API 的速率限制，以避免被服务器限制访问。
认证
为了安全访问 Bitfinex 的部分 API 端点，特别是那些涉及用户交易活动、账户余额查询以及敏感数据操作的功能，开发者必须进行严格的身份验证。Bitfinex 采用基于 API 密钥 (API Key) 和密钥签名 (Signature) 的机制来确保用户身份的合法性和数据传输的安全性。
- API 密钥 (API Key): 开发者需要在 Bitfinex 平台的用户账户中创建 API 密钥。这些密钥并非千篇一律，而是可以根据开发者的具体需求进行权限配置。例如，可以设置密钥仅用于读取市场数据，或者授权其进行交易操作，或者仅允许查询账户余额等。权限设置的细粒度控制，有助于降低潜在的安全风险。请务必妥善保管您的 API 密钥，防止泄露。
- 密钥签名 (Signature): 密钥签名是验证 API 请求完整性和真实性的关键。它通过使用开发者的私有 API 密钥对请求数据进行加密计算生成。请求数据通常包括请求的 API 路径（例如，`/v2/order/new`），一个唯一的时间戳 (nonce)，以及可能包含的请求体（例如，下单参数）。服务器收到请求后，会使用与 API 密钥关联的密钥对签名进行验证，以此确认请求是否由授权用户发起，以及数据在传输过程中是否被篡改。
生成密钥签名的详细步骤如下：
- 构造请求负载 (Payload): 创建一个 JSON 对象，该对象包含所有必要的请求参数。一个至关重要的参数是 nonce，它是一个时间戳，必须是单调递增的，用于防止重放攻击。除了 nonce 之外，负载还应包含任何其他 API 端点所需的参数，例如交易品种、数量、价格等。
- 序列化负载: 将构建好的 JSON 对象序列化成一个字符串。序列化过程必须保证一致性，常用的方法是使用 `JSON.stringify()` 函数。需要注意的是，不同编程语言或库的序列化结果可能存在细微差异，这可能会导致签名验证失败。因此，请确保使用的序列化方法与 Bitfinex 服务器预期的一致。
- 计算 HMAC 签名: 这是生成签名的核心步骤。使用您的 API 密钥作为密钥 (key)，对序列化的负载字符串执行 HMAC-SHA384 哈希算法。HMAC-SHA384 是一种消息认证码算法，它结合了哈希函数和密钥，能够有效地防止篡改和伪造。不同的编程语言都提供了相应的 HMAC-SHA384 计算库。
- 添加签名头: 将生成的 HMAC 签名作为 `bfx-signature` HTTP 头添加到您的 API 请求中。还需要在请求头中包含 `bfx-apikey` (您的 API 密钥) 和 `bfx-nonce` (您使用的时间戳)。这些头部信息是服务器验证请求身份和完整性的必要组成部分。
综上所述，正确的认证过程对于保护您的 Bitfinex 账户安全至关重要。不正确的认证实现可能导致您的账户受到未经授权的访问和潜在的资金损失。请务必仔细阅读 Bitfinex 官方 API 文档，并严格按照说明进行操作。强烈建议在生产环境中使用之前，在测试环境中进行充分的验证和调试，以确保认证流程的正确性和安全性。
REST API
Bitfinex REST API 允许开发者通过发送标准的 HTTP 请求，以编程方式访问平台的各种功能。该 API 提供了全面的接口，用于管理账户、获取市场数据、执行交易等。开发者可以利用这些端点构建自定义交易策略、自动化交易流程、并与其他系统集成。API 密钥用于认证和授权，确保只有授权用户才能访问其账户数据和执行交易。
以下是一些主要的 REST API 端点，涵盖了常用功能：
- 公共端点（Public Endpoints）： 提供无需身份验证即可访问的市场数据。例如，获取最新的交易对价格（ticker）、订单簿深度（order book depth）、历史交易记录（trades history）等。这些端点是构建信息聚合和分析工具的基础。
- 私有端点（Private Endpoints）： 需要身份验证才能访问，用于管理用户的账户信息和执行交易。例如，查询账户余额、下单、取消订单、查看订单状态等。访问私有端点需要提供 API 密钥和签名，以确保安全性。
- 钱包端点（Wallet Endpoints）： 用于管理用户的钱包资产，包括查询钱包余额、划转资金等。Bitfinex 支持多种加密货币的钱包管理，这些端点允许开发者集成钱包功能到自己的应用程序中。
- 订单管理端点（Order Management Endpoints）： 提供创建、修改和取消订单的功能。支持各种订单类型，如市价单、限价单、止损单等。开发者可以使用这些端点构建复杂的交易策略。
- 市场数据端点（Market Data Endpoints）： 提供详细的市场数据，包括交易对信息、历史数据、蜡烛图数据等。这些数据对于技术分析和策略回测至关重要。
公共端点
-
/v2/tickers: 获取多个交易对的最新交易信息，用于实时监控市场行情。可以指定一个或多个交易对，通过逗号分隔，并返回每个交易对的最新成交价、成交量、最高价、最低价、涨跌幅、以及24小时成交额等详细信息。适用于构建实时行情看板或交易策略的回测。GET /v2/tickers?symbols=tBTCUSD,tETHUSD
返回示例：
[ [ "tBTCUSD", // 交易对名称 12345, // 最新成交价 10, // 成交量 12350, // 24小时最高价 12340, // 24小时最低价 -0.01, // 24小时涨跌幅 0.1, // 24小时成交量 12342, // 最终结算价 100 // 24小时成交额 ], [ "tETHUSD", 1234, 10, 1235, 1230, -0.01, 0.1, 1232, 100 ] ]
-
/v2/trades/{symbol}/hist: 获取指定交易对的历史成交记录，可用于技术分析和趋势预测。 可以指定起始时间和结束时间，通过`start`和`end`参数设置Unix时间戳，以及使用`limit`参数控制返回的记录数量，避免数据量过大。历史成交记录包括成交时间、成交价格和成交数量，可以用于计算移动平均线等技术指标。GET /v2/trades/tBTCUSD/hist?limit=100
返回示例：
[ [ 1678886400000, // 成交时间 (Unix 时间戳，毫秒) 12345, // 成交价格 0.01 // 成交数量 ], [ 1678886390000, 12346, 0.02 ] ]
-
/v2/book/{symbol}/{precision}: 获取指定交易对的订单簿，提供市场深度信息。 可以指定订单簿的精度，例如 P0、P1、P2 等，精度越高，订单簿的深度越深，返回的数据量也越大。订单簿数据包括买单和卖单的价格和数量，可以用于分析市场的买卖压力和流动性。理解订单簿结构对于高频交易和套利策略至关重要。GET /v2/book/tBTCUSD/P0
返回示例：
[ [ 12345, // 价格 10, // 数量 1.0 // 总量 ], [ 12344, 20, -1.0 //总量 ] ]
私有端点
-
/v2/auth/r/wallets: 获取账户的钱包余额信息。需要进行身份验证，确保只有授权用户才能访问其账户的财务数据。POST /v2/auth/r/wallets
此端点允许用户检索其在不同交易所和交易账户中的资金余额。 身份验证是强制性的，以保护用户的隐私和资产安全。
返回示例：
返回的数组包含多个子数组，每个子数组代表一个钱包的余额信息。具体字段含义如下：
[ [ "exchange", // 钱包类型：交易所 (exchange), 交易 (trading), 保证金 (margin), 融资 (funding) 等 "USD", // 币种：钱包中持有的货币类型，例如美元 (USD), 比特币 (BTC) 等 1000.0, // 余额：当前钱包中的可用余额数量 0.0 // 未用余额：钱包中未被使用的余额数量，例如，已被挂单锁定的资金 ], [ "trading", // 钱包类型 "BTC", // 币种 1.0, // 余额 0.0 // 未用余额 ] ] -
/v2/auth/w/order/new: 创建新的订单。需要进行身份验证。可以指定交易对、订单类型、数量、价格等参数，从而实现灵活的交易策略。POST /v2/auth/w/order/new
此端点允许经过身份验证的用户在交易所下达新的交易订单。 用户可以在请求体中指定订单的各种参数。
请求体示例：
以下是一个创建限价订单的请求体示例。确保提供的参数符合交易所的要求和规范。
{ "cid": 123456789, // 客户端订单 ID (Client Order ID)，用于在客户端唯一标识一个订单，方便追踪 "type": "LIMIT", // 订单类型：LIMIT (限价单), MARKET (市价单), STOP (止损单) 等 "symbol": "tBTCUSD", // 交易对：指定要交易的货币对，例如 tBTCUSD 代表比特币/美元 "amount": "0.1", // 数量：要购买或出售的货币数量。正数表示购买，负数表示出售 "price": "12340" // 价格：限价单的价格。只有当市场价格达到或超过此价格时，订单才会被执行 }返回示例：
返回的数组包含了订单创建的结果信息。 第一项表示操作状态，后续项包含订单的详细数据。
[ 0, // 操作状态码：0 表示成功，其他值表示失败 "on", // 订单状态： "on" 表示订单已提交 null, // 错误代码：如果没有错误，则为 null null, // 错误信息：如果没有错误，则为 null [ null, // 订单 ID：交易所分配的订单 ID null, // 订单组 ID：如果订单属于某个订单组，则为组 ID 1678886400000, // 创建时间戳：订单创建的时间戳（毫秒） "tBTCUSD", // 交易对 null, // 订单类型：原始订单类型 "LIMIT", // 订单类型：订单类型 null, // 订单状态：订单当前状态 0.1, // 原始数量：订单的原始数量 0.0, // 已执行数量：订单已执行的数量 null, // 平均执行价格：订单的平均执行价格 null, // 订单剩余数量 null, // 订单价格类型 null, // 订单价格条件 null, // 订单价格调整 null, // 订单触发条件 null, // 订单有效期 12340, // 价格 null, // 止损价格 null, // 追踪止损价格 null, // 追踪止损偏离 null, // 隐藏订单 null, // 订单标志 null, // 订单消息 123456789 // 客户端订单 ID (cid) ] ] -
/v2/auth/w/order/cancel: 取消指定的订单。需要进行身份验证，确保只有订单的所有者才能取消订单，防止恶意操作。POST /v2/auth/w/order/cancel
此端点允许经过身份验证的用户取消之前提交的订单。 通过提供订单 ID，用户可以取消尚未成交的订单。
请求体示例：
以下是一个取消订单的请求体示例。 只需要提供要取消的订单的 ID。
{ "id": 12345 // 要取消的订单的 ID }返回示例：
返回的数组包含订单取消的结果信息。 第一项表示操作状态，后续项包含已取消订单的详细数据。
[ 0, // 操作状态码：0 表示成功，其他值表示失败 "oc", // 订单状态： "oc" 表示订单已取消 null, // 错误代码：如果没有错误，则为 null null, // 错误信息：如果没有错误，则为 null [ null, // 订单 ID：交易所分配的订单 ID null, // 订单组 ID：如果订单属于某个订单组，则为组 ID 1678886400000, // 创建时间戳：订单创建的时间戳（毫秒） "tBTCUSD", // 交易对 null, // 订单类型：原始订单类型 "LIMIT", // 订单类型：订单类型 null, // 订单状态：订单当前状态 0.1, // 原始数量：订单的原始数量 0.0, // 已执行数量：订单已执行的数量 null, // 平均执行价格：订单的平均执行价格 null, // 订单剩余数量 null, // 订单价格类型 null, // 订单价格条件 null, // 订单价格调整 null, // 订单触发条件 null, // 订单有效期 12340, // 价格 null, // 止损价格 null, // 追踪止损价格 null, // 追踪止损偏离 null, // 隐藏订单 null, // 订单标志 null, // 订单消息 12345 // 订单 ID ] ]
WebSocket API
Bitfinex WebSocket API 提供了一个强大的实时数据流接口，允许开发者订阅并接收最新的市场数据和账户信息。该API专为需要低延迟和高吞吐量数据更新的应用程序设计，例如交易机器人、实时图表工具和市场监控系统。
WebSocket API 基于 JSON（JavaScript Object Notation）格式的消息进行通信。这意味着所有发送和接收的数据都以易于解析和处理的结构化JSON对象的形式存在。开发者可以使用各种编程语言和库来创建WebSocket客户端，并与Bitfinex服务器建立持久连接，从而实时接收更新。
通过WebSocket API，您可以订阅各种频道以获取特定类型的数据。这些频道包括但不限于：
- Ticker频道： 提供单个交易对的最新价格、交易量和其他关键统计信息。
- Trades频道： 提供实时发生的交易数据，包括价格、数量和时间戳。
- Order Book频道： 提供订单簿的快照，显示了特定交易对的当前买单和卖单。
- Candles/OHLC频道： 提供特定时间周期的开盘价、最高价、最低价和收盘价（OHLC）数据。
- Authentication (Auth)频道： 用于访问账户信息，例如余额、订单和交易历史记录（需要API密钥）。
订阅频道通常涉及发送一个JSON格式的订阅消息到Bitfinex服务器，其中包含要订阅的频道名称和任何必要的参数，例如交易对。一旦订阅成功，服务器将开始推送实时数据到您的客户端。
使用WebSocket API需要一定的技术知识，包括WebSocket协议、JSON数据格式和Bitfinex API的特定要求。 然而，许多现成的库和示例代码可以帮助开发者快速入门并构建自己的实时交易和数据分析应用程序。
公共频道
-
ticker: 订阅指定交易对的最新成交价、最高价、最低价、成交量等概要信息，实时推送交易对的行情变动快照。 通过此频道，用户能够迅速掌握市场动态。 -
trades: 订阅指定交易对的实时成交记录，获取每一笔交易的价格、数量和时间戳。 这对于高频交易者和算法交易者至关重要，他们需要了解市场的微观结构。 -
book: 订阅指定交易对的订单簿信息，包括买单和卖单的价格和数量。 订单簿的深度代表了市场的流动性，通过分析订单簿可以预测价格走向和支撑阻力位。 订阅的可以是整个订单簿，也可以是指定深度的订单簿快照。
订阅示例：
{
"event": "subscribe",
"channel": "ticker",
"symbol": "tBTCUSD"
}
此示例展示了如何订阅tBTCUSD交易对的
ticker
频道，服务器会返回该交易对的实时行情数据。
取消订阅示例：
{
"event": "unsubscribe",
"chanId": 1234
}
此示例展示了如何取消订阅
chanId
为1234的频道。每个成功订阅的频道都会分配一个唯一的
chanId
，用于后续的取消订阅操作，务必保存好此
chanId
。
私有频道
-
auth: 订阅账户信息，例如钱包余额、订单状态、交易历史、以及个性化的账户设置等。这类频道由于涉及用户敏感数据，需要进行严格的身份验证和权限控制，以确保用户信息的安全性和隐私性。未经验证的用户将无法访问这些频道的信息。
订阅示例：
以下是一个用于订阅
auth
频道的JSON格式请求示例。请注意，你需要替换示例中的占位符，如
YOUR_API_KEY
,
YOUR_AUTH_SIGNATURE
,
YOUR_AUTH_NONCE
, 和
AUTH_PAYLOAD
，为你自己的有效值。
apiKey
用于识别你的账户，而
authSig
,
authNonce
, 和
authPayload
共同构成身份验证机制，用于验证请求的合法性和防止重放攻击。
authPayload
通常包含需要签名的信息，例如时间戳和账户标识符，以确保请求的完整性。
{
"event": "auth",
"apiKey": "YOURAPIKEY",
"authSig": "YOURAUTHSIGNATURE",
"authNonce": "YOURAUTHNONCE",
"authPayload": "AUTH_PAYLOAD"
}
字段解释：
-
event: 指定订阅的事件类型，这里是"auth"，表示请求订阅私有认证频道。 -
apiKey: 你的API密钥，用于标识你的账户。请妥善保管你的API密钥，避免泄露。 -
authSig: 使用你的私钥对authPayload进行签名后生成的签名值，用于验证请求的真实性。签名算法通常包括HMAC-SHA256等。 -
authNonce: 一个随机数或时间戳，用于防止重放攻击。每次请求都应该生成一个新的nonce。 -
authPayload: 包含需要签名的数据的字符串。这通常包括时间戳、账户ID、以及任何其他相关信息，用于确保请求的完整性。服务端会使用同样的算法和你的公钥来验证签名。
安全提示：
- 请勿在客户端代码中存储或硬编码你的私钥。应该在安全的服务器端环境中进行签名操作。
- 定期轮换你的API密钥，以降低密钥泄露的风险。
- 实施速率限制，以防止恶意攻击者滥用你的API密钥。
- 仔细审查你的签名算法和身份验证流程，确保其安全性。
错误处理
Bitfinex API 利用 HTTP 状态码和 JSON 格式的错误消息来指示问题。当API请求失败时，服务器会返回一个HTTP状态码，用于初步判断错误的类型。同时，为了提供更详细的错误信息，API还会返回一个包含错误代码和错误描述的JSON对象，开发者可以根据这些信息进行针对性的处理。
常见的 HTTP 状态码及其含义包括：
-
400 Bad Request: 该状态码表明客户端发出的请求存在错误，例如请求格式不正确、缺少必要的参数、参数值无效等。开发者应检查请求的语法和参数是否符合API的要求。 -
401 Unauthorized: 此状态码表示客户端未经授权尝试访问受保护的资源。通常是因为身份验证失败，例如API密钥无效、权限不足等。开发者应检查API密钥是否正确，以及是否具有访问所需资源的权限。 -
429 Too Many Requests: 当客户端在短时间内发送过多的请求时，服务器会返回该状态码，表明请求频率超过了API的限制。为了避免这种情况，开发者应实施速率限制策略，例如使用指数退避算法重试请求。 -
500 Internal Server Error: 该状态码表示服务器在处理请求时遇到了内部错误，导致无法完成请求。这通常是服务器端的问题，开发者可以稍后重试请求。如果问题持续存在，应联系Bitfinex的技术支持团队。
错误消息通常以 JSON 格式返回，包含以下字段：
error
: 一个字符串，表示错误代码。错误代码通常以
ERR_
开头，例如
ERR_RATE_LIMIT
表示速率限制错误。
message
: 一个字符串，提供更详细的错误描述，例如
Rate limit exceeded
表示超过了速率限制。
例如：
{
"error": "ERR_RATE_LIMIT",
"message": "Rate limit exceeded"
}
为了构建健壮的应用程序，开发者应该针对不同的错误代码和错误描述实施相应的错误处理逻辑。例如，当遇到
429 Too Many Requests
错误时，可以使用指数退避算法重试请求。如果身份验证失败，应提示用户检查API密钥是否正确。对于其他错误，可以记录错误日志并通知管理员。正确的错误处理可以显著提高应用程序的稳定性和可靠性。
速率限制
Bitfinex API 实施了速率限制机制，旨在防止恶意滥用行为，确保平台整体的稳定性和可靠性，从而为所有用户提供流畅高效的服务体验。速率限制的具体数值会根据不同的API端点以及用户的API密钥级别进行差异化调整。这意味着某些更复杂或资源消耗更高的API调用可能具有更严格的限制，而更高权限的API密钥可能允许更高的请求频率。
当请求频率超过预设的速率限制时，Bitfinex API 将拒绝超出限制的请求，并返回一个明确的错误信息：
429 Too Many Requests
。这个错误代码清晰地表明请求被拒绝的原因是超过了允许的请求频率。为避免触发速率限制，开发者需要采取必要的措施来精确控制其应用程序的请求频率，例如实施请求队列、使用指数退避算法或者采用缓存策略来减少对API的直接调用次数。
强烈建议开发者在集成 Bitfinex API 时，仔细查阅官方文档，了解各个API端点的具体速率限制参数。同时，务必在应用程序中实现相应的错误处理逻辑，以便在收到
429 Too Many Requests
错误时，能够采取适当的应对措施，例如暂停发送请求一段时间或者调整请求策略，从而避免对平台造成不必要的负担，并确保应用程序的稳定运行。
注意事项
- 充分准备： 在使用 Bitfinex API 之前，务必详尽阅读并理解官方文档。官方文档包含了API的使用规则、速率限制、数据结构以及最佳实践等重要信息。理解这些规则对于高效且稳定地使用API至关重要。
- 密钥安全： API 密钥是访问您的 Bitfinex 账户的凭证，务必妥善保管。切勿将密钥存储在不安全的地方，例如公共代码库或共享文档中。强烈建议使用环境变量或密钥管理系统来存储和访问您的 API 密钥，并定期更换密钥以提高安全性。
- 测试环境： 在将您的应用程序部署到生产环境之前，务必在 Bitfinex 提供的测试环境（沙盒环境）中进行充分测试。测试环境允许您模拟交易和数据请求，而不会对您的真实交易产生任何影响。这有助于您发现潜在的错误和问题，并确保您的应用程序在真实环境中能够正常运行。
- 错误处理： 您的应用程序应能够正确处理各种 API 返回的错误。仔细阅读 Bitfinex API 文档中关于错误代码的说明，并针对不同的错误类型采取适当的处理措施，例如重试请求、记录错误日志或通知用户。良好的错误处理机制可以提高应用程序的稳定性和可靠性。
- 持续关注： Bitfinex 会定期更新和改进其 API。关注 Bitfinex 官方公告、博客和社交媒体渠道，了解 API 的更新、变更以及新增功能。及时更新您的应用程序以适应最新的 API 版本，可以确保您能够充分利用 API 的功能，并避免因 API 变更而导致的问题。也要注意Bitfinex平台的交易规则变化，确保程序符合最新规则。