开发者指南 · Bitfinex v2 REST API

写给贷方的 Bitfinex API 详解

Bitfinex 的 API 文档覆盖了数百个 endpoint；一个放贷机器人只需要其中十几个。本指南就只讲这十几个：创建禁用提现的 API 密钥、通过公开 API 读取资金费率和资金簿、通过鉴权 API 提交和撤销资金报价，以及你在实践中一定会撞上的速率限制和数据怪癖——全部配有可直接运行的 Python 示例。

endpoint 路径与行为已对照 Stratum 在生产环境中使用的官方 Bitfinex v2 API 验证，2026 年 8 月。官方 Bitfinex 文档是权威参考。

试用公共端点

实时 Bitfinex 融资 API 浏览器

选择端点与币种并运行真实的免认证请求。Stratum 端点将 FRR、均值、可用融资和固定利率订单簿层级标准化为一个响应。

端点币种

https://app.stratum.money/api/v1/public/funding-rates.json

响应预览

{
  "generatedAt": "2026-08-23T06:48:15.408007891Z",
  "updatedAt": "2026-08-23T06:05:00Z",
  "source": "Bitfinex Public REST API",
  "currency": {
    "code": "USD",
    "bitfinexSymbol": "fUSD",
    "current": {
      "timestamp": "2026-08-23T06:05:00Z",
      "dailyRatePercent": "0.031025",
      "annualizedAprPercent": "11.324125",
      "averagePeriodDays": "91.470000",
      "fundingAmount": "5991052941.288744",
      "fundingAmountUsed": "5935309488.394312",
      "fundingAvailable": "55743452.894432",
      "fundingBelowThreshold": "763483370.5925878"
    },
    "averages": {
      "hours24": {
        "dailyRatePercent": "0.031200",
        "annualizedAprPercent": "11.388073",
        "observations": 25
      },
      "days7": {
        "dailyRatePercent": "0.031710",
        "annualizedAprPercent": "11.574020",
        "observations": 169
      },
      "days30": {
        "dailyRatePercent": "0.033403",
        "annualizedAprPercent": "12.192212",
        "observations": 721
      }
    },
    "market": {
      "bestFixedBid": {
        "dailyRatePercent": "0.027397",
        "annualizedAprPercent": "10.000000",
        "periodDays": 120,
        "amount": "11593282.43646913"
      },
      "bestFixedAsk": {
        "dailyRatePercent": "0.014188",
        "annualizedAprPercent": "5.178600",
        "periodDays": 2,
        "amount": "264.93559176"
      },
      "fixedBids": [
        {
          "dailyRatePercent": "0.027397",
          "annualizedAprPercent": "10.000000",
          "periodDays": 120,
          "amount": "11593282.43646913"
        },
        {
          "dailyRatePercent": "0.018011",
          "annualizedAprPercent": "6.574000",
          "periodDays": 120,
          "amount": "133240.73391109"
        },
        {
          "dailyRatePercent": "0.017770",
          "annualizedAprPercent": "6.486100",
          "periodDays": 120,
          "amount": "23123.30278361"
        },
        {
          "dailyRatePercent": "0.017400",
          "annualizedAprPercent": "6.351000",
          "periodDays": 120,
          "amount": "12350.0"
        },
        {
          "dailyRatePercent": "0.017130",
          "annualizedAprPercent": "6.252500",
          "periodDays": 120,
          "amount": "14000.0"
        },
        {
          "dailyRatePercent": "0.017125",
          "annualizedAprPercent": "6.250600",
          "periodDays": 117,
          "amount": "560000.0"
        },
        {
          "dailyRatePercent": "0.017120",
          "annualizedAprPercent": "6.248800",
          "periodDays": 120,
          "amount": "20000.0"
        },
        {
          "dailyRatePercent": "0.017111",
          "annualizedAprPercent": "6.245500",
          "periodDays": 120,
          "amount": "2000000.0"
        },
        {
          "dailyRatePercent": "0.016125",
          "annualizedAprPercent": "5.885600",
          "periodDays": 117,
          "amount": "560000.0"
        },
        {
          "dailyRatePercent": "0.016000",
          "annualizedAprPercent": "5.840000",
          "periodDays": 120,
          "amount": "10009162.66122322"
        },
        {
          "dailyRatePercent": "0.016000",
          "annualizedAprPercent": "5.840000",
          "periodDays": 14,
          "amount": "9306.90081316"
        },
        {
          "dailyRatePercent": "0.015111",
          "annualizedAprPercent": "5.515500",
          "periodDays": 117,
          "amount": "560000.0"
        }
      ],
      "fixedAsks": [
        {
          "dailyRatePercent": "0.014188",
          "annualizedAprPercent": "5.178600",
          "periodDays": 2,
          "amount": "264.93559176"
        },
        {
          "dailyRatePercent": "0.014190",
          "annualizedAprPercent": "5.179300",
          "periodDays": 2,
          "amount": "250.0"
        },
        {
          "dailyRatePercent": "0.014192",
          "annualizedAprPercent": "5.180100",
          "periodDays": 2,
          "amount": "200.0"
        },
        {
          "dailyRatePercent": "0.014978",
          "annualizedAprPercent": "5.467000",
          "periodDays": 2,
          "amount": "3837.92472142"
        },
        {
          "dailyRatePercent": "0.014982",
          "annualizedAprPercent": "5.468400",
          "periodDays": 2,
          "amount": "323.64921816"
        },
        {
          "dailyRatePercent": "0.014988",
          "annualizedAprPercent": "5.470600",
          "periodDays": 2,
          "amount": "605.58777224"
        },
        {
          "dailyRatePercent": "0.014998",
          "annualizedAprPercent": "5.474300",
          "periodDays": 2,
          "amount": "2079.77565528"
        },
        {
          "dailyRatePercent": "0.014999",
          "annualizedAprPercent": "5.474600",
          "periodDays": 2,
          "amount": "1968.80422628"
        },
        {
          "dailyRatePercent": "0.015047",
          "annualizedAprPercent": "5.492200",
          "periodDays": 2,
          "amount": "484.95397132"
        },
        {
          "dailyRatePercent": "0.015196",
          "annualizedAprPercent": "5.546500",
          "periodDays": 2,
          "amount": "150.0"
        },
        {
          "dailyRatePercent": "0.015418",
          "annualizedAprPercent": "5.627600",
          "periodDays": 2,
          "amount": "200.0"
        },
        {
          "dailyRatePercent": "0.015607",
          "annualizedAprPercent": "5.696500",
          "periodDays": 2,
          "amount": "1150.0"
        }
      ],
      "fixedBidDepth": "37154170.83381627",
      "fixedAskDepth": "536825.22487061",
      "frrBidDepth": "0",
      "frrOfferDepth": "0",
      "sampledLevels": 356
    },
    "historyPreview": [
      {
        "timestamp": "2026-08-23T06:05:00Z",
        "dailyRatePercent": "0.031025",
        "annualizedAprPercent": "11.324125",
        "averagePeriodDays": "91.470000",
        "fundingAmount": "5991052941.288744",
        "fundingAmountUsed": "5935309488.394312",
        "fundingAvailable": "55743452.894432",
        "fundingBelowThreshold": "763483370.5925878"
      },
      {
        "timestamp": "2026-08-23T05:05:00Z",
        "dailyRatePercent": "0.031025",
        "annualizedAprPercent": "11.324125",
        "averagePeriodDays": "92.570000",
        "fundingAmount": "5989152818.724412",
        "fundingAmountUsed": "5934084828.197341",
        "fundingAvailable": "55067990.527071",
        "fundingBelowThreshold": "769699003.4136398"
      },
      {
        "timestamp": "2026-08-23T04:05:00Z",
        "dailyRatePercent": "0.031025",
        "annualizedAprPercent": "11.324125",
        "averagePeriodDays": "92.030000",
        "fundingAmount": "5988567317.18653",
        "fundingAmountUsed": "5933880711.029357",
        "fundingAvailable": "54686606.157173",
        "fundingBelowThreshold": "769905136.1789076"
      }
    ]
  }
}

GET /v2/ticker/{symbol} · tBTCUSD / fUSD

资金 ticker——FRR（索引 0，日利率）、最优买/卖价及其期限、日成交量。放贷中最有用的单个 endpoint。

INDEX	tBTCUSD	fUSD
0	BID	FRR
1	BID_SIZE	BID
2	ASK	BID_PERIOD
3	ASK_SIZE	BID_SIZE
4	CHANGE	ASK
5	CHANGE_RELATIVE	ASK_PERIOD
6	LAST_PRICE	ASK_SIZE
7	VOLUME	DAILY_CHANGE
8	HIGH	DAILY_CHANGE_PERC
9	LOW	LAST_PRICE
10	FIRST_TRADE	VOLUME
11	—	HIGH
12	—	LOW
15	—	FRR_AMOUNT_AVAILABLE
16	—	FIRST_TRADE

REST: 90 req/min ·docs.bitfinex.com/reference/rest-public-ticker

第零步

创建限定权限的 API 密钥（关闭提现）

下文只有鉴权 endpoint 才需要 API 密钥——费率、K 线和资金簿都是公开的。当你确实要创建密钥时（Bitfinex → API Keys → Create New Key），把权限限定在贷方真正需要的范围：Margin Funding 读 + 写（查看和提交报价）、Wallets 读（查看余额）、Account History 读（读取账本）。提现、交易和划转全部保持禁用。

放贷机器人永远不需要把你的钱转出交易所的能力。一把没有提现和交易权限的密钥，最坏的情况也只是以糟糕的利率把你的资金钱包放出去——它无法掏空钱包。这正是 Stratum 强制执行的权限限定：任何可提现或可交易的密钥在添加时即被拒绝。

利率单位换算

Ticker、book 与 funding/stats 使用不同的 FRR 单位

Ticker 和订单簿利率是每日小数。funding/stats 的 FRR 字段是显示日 FRR 的 1/365。比较或回测前请使用对应公式。

ticker/book daily % = API rate × 100
ticker/book gross APR % = API rate × 365 × 100
funding/stats daily % = FRR field × 365 × 100
funding/stats gross APR % = FRR field × 365 × 365 × 100

curl https://app.stratum.money/api/v1/public/funding-rates.json
curl https://app.stratum.money/api/v1/public/funding-rates.csv
curl "https://api-pub.bitfinex.com/v2/ticker/fUSD"
curl "https://api-pub.bitfinex.com/v2/book/fUSD/P0?len=25"

对融资真正重要的 endpoint

公开（无需密钥，api-pub.bitfinex.com）

GET /v2/ticker/fUSD

资金 ticker——FRR（索引 0，日利率）、最优买/卖价及其期限、日成交量。放贷中最有用的单个 endpoint。

GET /v2/candles/{key}/hist

按期限划分的历史资金费率 K 线，例如 key 为 trade:1h:fUSD:p2 表示 2 天期 USD 资金。这就是你用来回测的数据序列。

GET /v2/book/fUSD/P2 and /R0

实时资金簿——聚合价格档位（P0–P3）或原始订单（R0）。每一笔挂单买价和报价的利率、期限和规模。

GET /v2/funding/stats/fUSD/hist

每小时资金统计：FRR、平均期限、已用资金总额。陷阱：FRR 列存储的是 FRR/365——乘以 365 才能与 ticker 对上。

鉴权（api.bitfinex.com，HMAC 签名）

POST /v2/auth/r/wallets

钱包余额，包括机器人用来放贷的资金钱包。

POST /v2/auth/r/funding/offers/fUSD

你未成交的资金报价；/hist 变体返回已成交和已撤销的报价。

POST /v2/auth/r/funding/credits/fUSD

当前已借出的资金（活跃 credit）：利率、期限、开始时间。/hist 变体是你的已结清贷款历史。

POST /v2/auth/w/funding/offer/submit

提交资金报价：币种、金额、日利率、期限（2–120 天）。用 offer/cancel 或 offer/cancel/all 撤销。

POST /v2/auth/r/ledgers/USD/hist

账本——每笔贷款每天的每一笔利息支付及其 15% 手续费扣除。这是计算收益和税务数字唯一正确的依据。

POST /v2/auth/w/funding/keep

按 credit 控制自动续借——相当于 UI 中自动续借开关的 API 版本。

可运行的代码

Python 示例

读取 FRR 和资金簿（无需密钥）

import requests

PUB = "https://api-pub.bitfinex.com"

# 资金 ticker：索引 0 是 FRR，以日利率报价
ticker = requests.get(f"{PUB}/v2/ticker/fUSD", timeout=10).json()
frr_daily = ticker[0]
print(f"FRR: {frr_daily * 365 * 100:.2f}% APR")

# 实时资金簿的最优档（聚合）
book = requests.get(f"{PUB}/v2/book/fUSD/P2", params={"len": 25}, timeout=10).json()
for rate, period, count, amount in book[:5]:
    side = "offer" if amount < 0 else "bid"
    print(f"{side}: {rate * 365 * 100:.2f}% APR for {period}d, size {abs(amount):,.0f}")

提交资金报价（鉴权）

import hashlib, hmac, json, time, requests

KEY, SECRET = "your-key", "your-secret"
BASE = "https://api.bitfinex.com"

def auth_post(path: str, body: dict):
    nonce = str(int(time.time() * 1_000_000))  # 同一密钥下必须严格递增
    raw = f"/api/{path}{nonce}{json.dumps(body)}"
    sig = hmac.new(SECRET.encode(), raw.encode(), hashlib.sha384).hexdigest()
    return requests.post(f"{BASE}/{path}", data=json.dumps(body), timeout=15, headers={
        "bfx-nonce": nonce, "bfx-apikey": KEY, "bfx-signature": sig,
        "content-type": "application/json",
    }).json()

# 以每天 0.03%（约 10.95% APR）报价 $150（Bitfinex 最低额），期限 2 天
result = auth_post("v2/auth/w/funding/offer/submit", {
    "type": "LIMIT", "symbol": "fUSD",
    "amount": "150", "rate": "0.0003", "period": 2,
})
print(result)

API 中的利率始终是日利率——乘以 365 得到 APR——并且始终是毛利率，即 Bitfinex 从已赚利息中收取 15% 手续费之前的数字。最低报价为 150 美元等值；期限为 2–120 天。如果你不想手写签名而更愿意用维护良好的客户端，Bitfinex 发布了官方 Python 库（bfxapi）。

速率限制，以及真正浪费你几小时的陷阱

nonce 必须严格递增

每个签名请求的 bfx-nonce 都必须大于同一密钥上一次使用的值。两个进程共用一把密钥会因 "nonce: small" 错误互相冲突——每个进程使用独立密钥。

按 endpoint 划分的速率限制

公开 endpoint 根据路由不同大约允许每分钟 10–90 次请求；鉴权 endpoint 与之相当。超限会返回 HTTP 429 和 ERR_RATE_LIMIT 响应体——请指数退避并缓存读取结果。

funding/stats 存储的是 FRR/365

/v2/funding/stats 中的 FRR 列是日 FRR 除以 365 的值，而 /v2/ticker 直接报日利率。比较前把 stats 的值乘以 365——否则会悄无声息地扭曲你的回测。

所有数字都是费前毛值

资金簿利率、K 线和 FRR 都是费前数字。你的钱包实际收到已赚利息的 85%（隐藏报价为 82%）。对账要以账本为准，而不是报价利率。

贷款会提前结束

一笔 120 天的 credit 并不意味着 120 天的利息——借款人平仓时就会还款，credit 可能几天内就回到手里。要按预期持有时间建模，而不是名义期限。

自建 vs 托管

如果你不想自己运行这一套

上面的一切正是 Stratum 在生产环境中运行的内容：同样的 endpoint、签名、退避和账本对账，外加在三年资金 K 线上回测过的 11 种策略、模拟模式和税务导出——全部通过一把你按第零步描述精确限定权限的禁用提现密钥。如果你享受掌控整套技术栈，就自建机器人（本指南加上开源项目是一条切实可行的路）；如果你想跳过 nonce bug 和凌晨 3 点的 429，就用托管的。

Bitfinex API 常见问题

Bitfinex 放贷机器人需要哪些 API 权限？

Margin Funding 读和写、Wallets 读、Account History 读。提现、交易和划转应保持禁用——放贷机器人永远不需要把资金转出交易所，而限定权限的密钥即使泄露也能把损失控制住。

Bitfinex API 可以免费使用吗？

可以。公开 API（费率、K 线、资金簿）和鉴权 API（报价、钱包、账本）都是免费的；只有鉴权部分需要账户和 API 密钥。api-pub.bitfinex.com 上的公开 endpoint 完全不需要密钥。

有官方的 Bitfinex Python 库吗？

有——bfxapi，由 Bitfinex 发布，同时覆盖 REST 和 WebSocket。本页示例使用原生 requests 加手写 HMAC 签名，好让你看清线上实际发生了什么；生产代码用官方库能省去大量样板代码。

Bitfinex API 的利率是日利率还是年利率？

日利率。0.0003 的利率表示每天 0.03%，单利约合 10.95% APR。乘以 365 得到 APR，并记住所有报价利率都是毛值——Bitfinex 收取已赚利息的 15%，所以再乘以 0.85 才是实际到达你钱包的数字。

放贷机器人需要用 WebSocket API 吗？

起步阶段不需要。REST 轮询足以支撑一个简单的机器人。当你想要实时资金簿更新或即时成交通知、又不想消耗 REST 速率限制时，WebSocket（公开 wss://api-pub.bitfinex.com/ws/2，鉴权 wss://api.bitfinex.com/ws/2）才变得重要——Stratum 正是这样实时跟踪钱包、报价和 credit 事件的。

Bitfinex API 的速率限制是多少？

因 endpoint 而异，公开路由大约每分钟 10–90 次请求，鉴权路由的额度与之相当。超限会返回 HTTP 429（ERR_RATE_LIMIT）；行为良好的客户端会缓存公开读取，并在 429 时指数退避。具体数字在官方文档中按 endpoint 列出。

API 是最简单的部分

提交一笔报价只要二十行 Python；知道该报什么利率和期限才是真正的问题。Stratum 在上文描述的同一套 API 上运行回测过的策略——或者拿走本页的代码，自己动手构建。

在 Stratum 添加 API 密钥实时资金费率查看实时 Bitfinex 资金簿开源机器人对比 Bitfinex funding 数据集 Bitfinex funding 实时利率组件