開發者指南 · Bitfinex v2 REST API

Bitfinex API 指南：ticker、funding 與速率限制

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 即時利率元件