A API da Bitfinex, explicada para credores
A documentação da API da Bitfinex cobre centenas de endpoints; um bot de lending precisa de cerca de uma dúzia. Este guia cobre exatamente esses: criar uma chave de API sem permissão de saque, ler taxas de funding e livros pela API pública, colocar e cancelar ofertas de funding pela API autenticada, e os limites de requisições e peculiaridades dos dados que você vai encontrar na prática — com exemplos funcionais em Python.
Caminhos de endpoints e comportamento verificados contra a API v2 oficial da Bitfinex tal como o Stratum a usa em produção, agosto de 2026. A documentação oficial da Bitfinex é a referência autoritativa.
Explorador ao vivo da API de funding Bitfinex
Escolha endpoint e moeda e execute uma solicitação real sem autenticação. O endpoint da Stratum normaliza FRR, médias, funding disponível e níveis fixos.
https://app.stratum.money/api/v1/public/funding-rates.json{
"generatedAt": "2026-09-18T10:52:06.372800327Z",
"updatedAt": "2026-09-18T10:05:00Z",
"source": "Bitfinex Public REST API",
"currency": {
"code": "USD",
"bitfinexSymbol": "fUSD",
"current": {
"timestamp": "2026-09-18T10:05:00Z",
"dailyRatePercent": "0.031025",
"annualizedAprPercent": "11.324125",
"averagePeriodDays": "88.530000",
"fundingAmount": "6066177617.253881",
"fundingAmountUsed": "5963820711.655769",
"fundingAvailable": "102356905.598112",
"fundingBelowThreshold": "205791994.9034347"
},
"averages": {
"hours24": {
"dailyRatePercent": "0.030718",
"annualizedAprPercent": "11.212216",
"observations": 25
},
"days7": {
"dailyRatePercent": "0.030755",
"annualizedAprPercent": "11.225586",
"observations": 169
},
"days30": {
"dailyRatePercent": "0.031022",
"annualizedAprPercent": "11.323016",
"observations": 721
}
},
"market": {
"bestFixedBid": {
"dailyRatePercent": "0.027397",
"annualizedAprPercent": "10.000000",
"periodDays": 120,
"amount": "4127249.58937109"
},
"bestFixedAsk": {
"dailyRatePercent": "0.024000",
"annualizedAprPercent": "8.760000",
"periodDays": 2,
"amount": "1000.0"
},
"fixedBids": [
{
"dailyRatePercent": "0.027397",
"annualizedAprPercent": "10.000000",
"periodDays": 120,
"amount": "4127249.58937109"
},
{
"dailyRatePercent": "0.017125",
"annualizedAprPercent": "6.250600",
"periodDays": 117,
"amount": "508118.25425112"
},
{
"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.016100",
"annualizedAprPercent": "5.876500",
"periodDays": 120,
"amount": "100000.0"
},
{
"dailyRatePercent": "0.016030",
"annualizedAprPercent": "5.851000",
"periodDays": 120,
"amount": "20000.0"
},
{
"dailyRatePercent": "0.016010",
"annualizedAprPercent": "5.843700",
"periodDays": 30,
"amount": "12882.7"
},
{
"dailyRatePercent": "0.016000",
"annualizedAprPercent": "5.840000",
"periodDays": 120,
"amount": "10009162.66122322"
},
{
"dailyRatePercent": "0.015111",
"annualizedAprPercent": "5.515500",
"periodDays": 117,
"amount": "560000.0"
},
{
"dailyRatePercent": "0.015030",
"annualizedAprPercent": "5.486000",
"periodDays": 90,
"amount": "20000.0"
},
{
"dailyRatePercent": "0.015001",
"annualizedAprPercent": "5.475400",
"periodDays": 5,
"amount": "20000.0"
}
],
"fixedAsks": [
{
"dailyRatePercent": "0.024000",
"annualizedAprPercent": "8.760000",
"periodDays": 2,
"amount": "1000.0"
},
{
"dailyRatePercent": "0.024371",
"annualizedAprPercent": "8.895500",
"periodDays": 2,
"amount": "421.47"
},
{
"dailyRatePercent": "0.024500",
"annualizedAprPercent": "8.942500",
"periodDays": 2,
"amount": "1000.0"
},
{
"dailyRatePercent": "0.024658",
"annualizedAprPercent": "9.000200",
"periodDays": 2,
"amount": "416.49"
},
{
"dailyRatePercent": "0.024802",
"annualizedAprPercent": "9.052700",
"periodDays": 7,
"amount": "416.49"
},
{
"dailyRatePercent": "0.024897",
"annualizedAprPercent": "9.087500",
"periodDays": 2,
"amount": "308.03735178"
},
{
"dailyRatePercent": "0.024946",
"annualizedAprPercent": "9.105300",
"periodDays": 30,
"amount": "416.49"
},
{
"dailyRatePercent": "0.025000",
"annualizedAprPercent": "9.125000",
"periodDays": 2,
"amount": "1000.0"
},
{
"dailyRatePercent": "0.025090",
"annualizedAprPercent": "9.157900",
"periodDays": 2,
"amount": "416.49"
},
{
"dailyRatePercent": "0.025234",
"annualizedAprPercent": "9.210400",
"periodDays": 7,
"amount": "416.49"
},
{
"dailyRatePercent": "0.025271",
"annualizedAprPercent": "9.223900",
"periodDays": 2,
"amount": "618.20522837"
},
{
"dailyRatePercent": "0.025360",
"annualizedAprPercent": "9.256300",
"periodDays": 2,
"amount": "154.01867589"
}
],
"fixedBidDepth": "37361253.62211114",
"fixedAskDepth": "1113019.83454529",
"frrBidDepth": "0",
"frrOfferDepth": "0",
"sampledLevels": 367
},
"historyPreview": [
{
"timestamp": "2026-09-18T10:05:00Z",
"dailyRatePercent": "0.031025",
"annualizedAprPercent": "11.324125",
"averagePeriodDays": "88.530000",
"fundingAmount": "6066177617.253881",
"fundingAmountUsed": "5963820711.655769",
"fundingAvailable": "102356905.598112",
"fundingBelowThreshold": "205791994.9034347"
},
{
"timestamp": "2026-09-18T09:05:00Z",
"dailyRatePercent": "0.031025",
"annualizedAprPercent": "11.324125",
"averagePeriodDays": "88.440000",
"fundingAmount": "6069528229.823523",
"fundingAmountUsed": "5966358964.963753",
"fundingAvailable": "103169264.859770",
"fundingBelowThreshold": "202948622.9664151"
},
{
"timestamp": "2026-09-18T08:05:00Z",
"dailyRatePercent": "0.030660",
"annualizedAprPercent": "11.190900",
"averagePeriodDays": "87.030000",
"fundingAmount": "6091172678.716536",
"fundingAmountUsed": "5926870017.376207",
"fundingAvailable": "164302661.340329",
"fundingBelowThreshold": "137001443.643518"
}
]
}
}GET /v2/ticker/{symbol} · tBTCUSD / fUSD
Ticker de funding — o FRR (índice 0, uma taxa diária), melhor bid/ask com seus períodos, volume diário. O endpoint de lending mais útil de todos.
| 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
Crie uma chave de API com escopo restrito (saques desativados)
Tudo abaixo só precisa de uma chave de API para os endpoints autenticados — taxas, candles e livros são públicos. Quando você criar uma chave (Bitfinex → API Keys → Create New Key), restrinja o escopo ao que um credor realmente precisa: Margin Funding leitura + escrita (para ver e colocar ofertas), Wallets leitura (para ver saldos) e Account History leitura (para o livro razão). Deixe saques, trading e transferências desativados.
Um bot de funding nunca precisa da capacidade de mover seu dinheiro para fora da exchange. Uma chave sem permissões de saque e trade pode, na pior das hipóteses, emprestar sua carteira de funding a uma taxa ruim — ela não pode esvaziá-la. É o mesmo escopo que o Stratum impõe: chaves com capacidade de saque ou trade são rejeitadas no momento da adição.
Ticker, book e funding/stats não usam a mesma unidade FRR
As taxas de ticker e book são frações diárias. O campo FRR de funding/stats é 1/365 da FRR diária exibida. Aplique a fórmula correta antes de comparar.
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 × 100curl 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"Os endpoints que importam para o funding
Públicos (sem chave, api-pub.bitfinex.com)
GET /v2/ticker/fUSD
Ticker de funding — o FRR (índice 0, uma taxa diária), melhor bid/ask com seus períodos, volume diário. O endpoint de lending mais útil de todos.
GET /v2/candles/{key}/hist
Candles históricos de taxa de funding por tenor, p. ex. a chave trade:1h:fUSD:p2 para funding USD de 2 dias. Esta é a série contra a qual você faz backtests.
GET /v2/book/fUSD/P2 e /R0
O livro de funding ao vivo — níveis de preço agregados (P0–P3) ou ordens brutas (R0). Taxa, período e tamanho de cada bid e oferta em espera.
GET /v2/funding/stats/fUSD/hist
Estatísticas horárias de funding: FRR, período médio, funding total em uso. Pegadinha: a coluna FRR é armazenada como FRR/365 — multiplique por 365 para bater com o ticker.
Autenticados (api.bitfinex.com, assinados com HMAC)
POST /v2/auth/r/wallets
Saldos das carteiras, incluindo a carteira de funding da qual um bot empresta.
POST /v2/auth/r/funding/offers/fUSD
Suas ofertas de funding abertas; a variante /hist retorna as executadas e canceladas.
POST /v2/auth/r/funding/credits/fUSD
O funding atualmente emprestado (créditos ativos): taxa, período, horário de abertura. A variante /hist é seu histórico de empréstimos encerrados.
POST /v2/auth/w/funding/offer/submit
Coloque uma oferta de funding: símbolo, valor, taxa diária, período (2–120 dias). Cancele com offer/cancel ou offer/cancel/all.
POST /v2/auth/r/ledgers/USD/hist
O livro razão — cada pagamento de juros e sua dedução da taxa de 15%, por empréstimo por dia. A única base correta para números de ganhos e impostos.
POST /v2/auth/w/funding/keep
Controle a renovação automática por crédito — o equivalente via API do botão de auto-renovação na interface.
Exemplos em Python
Leia o FRR e o livro de funding (sem chave)
import requests
PUB = "https://api-pub.bitfinex.com"
# Ticker de funding: o índice 0 é o FRR, cotado como taxa DIÁRIA
ticker = requests.get(f"{PUB}/v2/ticker/fUSD", timeout=10).json()
frr_daily = ticker[0]
print(f"FRR: {frr_daily * 365 * 100:.2f}% APR")
# Topo do livro de funding ao vivo (agregado)
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}")Coloque uma oferta de funding (autenticado)
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)) # deve crescer estritamente por chave
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()
# Oferte $150 (mínimo da Bitfinex) a 0.03% ao dia (~10.95% APR) por 2 dias
result = auth_post("v2/auth/w/funding/offer/submit", {
"type": "LIMIT", "symbol": "fUSD",
"amount": "150", "rate": "0.0003", "period": 2,
})
print(result)As taxas na API são sempre diárias — multiplique por 365 para o APR — e sempre brutas, antes da taxa de 15% da Bitfinex sobre os juros ganhos. A oferta mínima é o equivalente a $150; os períodos vão de 2 a 120 dias. Se você preferir um cliente mantido em vez de assinar na mão, a Bitfinex publica uma biblioteca oficial de Python (bfxapi).
Limites de requisições e as pegadinhas que custam horas de verdade
Nonces devem crescer estritamente
Cada requisição assinada precisa de um bfx-nonce maior que o anterior para aquela chave. Dois processos compartilhando uma chave vão colidir com erros "nonce: small" — use uma chave por processo.
Limites de requisições por endpoint
Os endpoints públicos permitem cerca de 10–90 requisições/minuto dependendo da rota; os autenticados são semelhantes. Excedê-los retorna HTTP 429 com um corpo ERR_RATE_LIMIT — recue exponencialmente e faça cache das leituras.
funding/stats armazena FRR/365
A coluna FRR de /v2/funding/stats é o FRR diário dividido por 365, enquanto /v2/ticker cota a taxa diária diretamente. Multiplique o valor de stats por 365 antes de comparar — caso contrário isso distorce os backtests silenciosamente.
Tudo é bruto de taxas
As taxas do livro, os candles e o FRR são todos pré-taxa. Sua carteira recebe 85% dos juros ganhos (82% para ofertas ocultas). Reconcilie contra o livro razão, não contra a taxa cotada.
Empréstimos encerram antes do prazo
Um crédito de 120 dias não significa 120 dias de juros — os tomadores pagam quando fecham posições, e os créditos podem retornar em dias. Modele a duração esperada, não o período nominal.
Se você prefere não operar isso por conta própria
Tudo acima é o que o Stratum opera em produção: os mesmos endpoints, assinaturas, backoff e reconciliação de livro razão, além de 11 estratégias testadas em backtest sobre três anos de candles de funding, modo paper e exportações fiscais — atrás de uma chave sem permissão de saque com o escopo exato descrito no passo zero. Construa seu próprio bot se você gosta de ser dono do stack (este guia mais os projetos open-source são um caminho real); use um hospedado se preferir pular os bugs de nonce e os 429 às 3 da manhã.
FAQ da API da Bitfinex
Quais permissões de API um bot de lending da Bitfinex precisa?
Margin Funding leitura e escrita, Wallets leitura e Account History leitura. Saques, trading e transferências devem permanecer desativados — um bot de lending nunca precisa mover fundos para fora da exchange, e uma chave com escopo restrito limita o dano se ela algum dia vazar.
A API da Bitfinex é gratuita?
Sim. Tanto a API pública (taxas, candles, livros) quanto a autenticada (ofertas, carteiras, livros razão) são gratuitas; você só precisa de uma conta e de uma chave de API para a parte autenticada. Os endpoints públicos em api-pub.bitfinex.com não precisam de chave alguma.
Existe uma biblioteca oficial de Python da Bitfinex?
Sim — a bfxapi, publicada pela Bitfinex, cobre tanto REST quanto WebSocket. Os exemplos desta página usam requests puro mais assinatura HMAC feita à mão para você ver exatamente o que acontece no fio; para código de produção a biblioteca oficial economiza boilerplate.
As taxas da API da Bitfinex são diárias ou anuais?
Diárias. Uma taxa de 0.0003 significa 0.03% ao dia, cerca de 10.95% APR simples. Multiplique por 365 para o APR, e lembre que toda taxa cotada é bruta — a Bitfinex fica com 15% dos juros ganhos, então multiplique por 0.85 para o que chega à sua carteira.
Preciso da API WebSocket para um bot de lending?
Não para começar. Polling via REST cobre um bot simples. O WebSocket (wss://api-pub.bitfinex.com/ws/2 público, wss://api.bitfinex.com/ws/2 autenticado) importa quando você quer atualizações do livro ao vivo ou notificações instantâneas de execução sem queimar seu limite de requisições REST — é assim que o Stratum acompanha eventos de carteira, oferta e crédito em tempo real.
Quais são os limites de requisições da API da Bitfinex?
Variam por endpoint, cerca de 10–90 requisições por minuto nas rotas públicas e orçamentos comparáveis nas autenticadas. Exceder um limite retorna HTTP 429 (ERR_RATE_LIMIT); clientes bem-comportados fazem cache das leituras públicas e recuam exponencialmente nos 429. Os números exatos estão listados por endpoint na documentação oficial.
A API é a parte fácil
Colocar uma oferta são vinte linhas de Python; saber qual taxa e tenor oferecer é o problema de verdade. O Stratum roda estratégias testadas em backtest sobre a mesma API descrita acima — ou pegue o código desta página e construa o seu.