대출자의 눈으로 풀어낸 Bitfinex API
Bitfinex의 API 문서는 수백 개의 엔드포인트를 다루지만, 대출 봇에 필요한 것은 열두어 개뿐입니다. 이 가이드는 정확히 그것들만 다룹니다: 출금이 비활성화된 API 키 만들기, 공개 API로 펀딩 금리와 호가창 읽기, 인증 API로 펀딩 오퍼 제출과 취소, 그리고 실전에서 반드시 마주치게 될 속도 제한과 데이터의 기벽까지 — 실제 동작하는 Python 예제와 함께.
엔드포인트 경로와 동작은 Stratum이 프로덕션에서 사용하는 공식 Bitfinex v2 API를 기준으로 검증했습니다(2026년 8월). 권위 있는 참고 자료는 공식 Bitfinex 문서입니다.
실시간 Bitfinex 펀딩 API 탐색기
Endpoint와 통화를 선택해 인증 없는 실제 요청을 실행하세요. Stratum endpoint는 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
펀딩 티커 — FRR(인덱스 0, 일 단위 금리), 최우선 매수/매도 호가와 그 기간, 일일 거래량. 대출에 가장 유용한 단 하나의 엔드포인트.
| 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 키 만들기 (출금 끄기)
아래 내용 중 API 키가 필요한 것은 인증 엔드포인트뿐입니다 — 금리, 캔들, 호가창은 모두 공개입니다. 키를 만들 때는(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 × 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"펀딩에 중요한 엔드포인트
공개 (키 불필요, api-pub.bitfinex.com)
GET /v2/ticker/fUSD
펀딩 티커 — FRR(인덱스 0, 일 단위 금리), 최우선 매수/매도 호가와 그 기간, 일일 거래량. 대출에 가장 유용한 단 하나의 엔드포인트.
GET /v2/candles/{key}/hist
만기별 과거 펀딩 금리 캔들. 예: 2일물 USD 펀딩이라면 key는 trade:1h:fUSD:p2. 백테스트의 기준이 되는 시계열입니다.
GET /v2/book/fUSD/P2 및 /R0
실시간 펀딩 호가창 — 집계된 가격 레벨(P0–P3) 또는 원시 주문(R0). 대기 중인 모든 매수·오퍼의 금리, 기간, 규모.
GET /v2/funding/stats/fUSD/hist
시간별 펀딩 통계: FRR, 평균 기간, 총 사용 펀딩. 함정: FRR 열은 FRR/365로 저장됩니다 — 티커와 맞추려면 365를 곱하세요.
인증 (api.bitfinex.com, HMAC 서명)
POST /v2/auth/r/wallets
지갑 잔고. 봇이 대출에 사용하는 펀딩 지갑 포함.
POST /v2/auth/r/funding/offers/fUSD
열려 있는 펀딩 오퍼. /hist 변형은 체결·취소된 오퍼를 반환합니다.
POST /v2/auth/r/funding/credits/fUSD
현재 대출 중인 펀딩(활성 크레딧): 금리, 기간, 개시 시각. /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
크레딧별 자동 갱신 제어 — UI의 자동 갱신 토글에 해당하는 API.
Python 예제
FRR과 펀딩 호가창 읽기 (키 불필요)
import requests
PUB = "https://api-pub.bitfinex.com"
# 펀딩 티커: 인덱스 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()
# $150(Bitfinex 최소 금액)를 일 0.03%(~연 10.95% APR)로 2일간 오퍼
result = auth_post("v2/auth/w/funding/offer/submit", {
"type": "LIMIT", "symbol": "fUSD",
"amount": "150", "rate": "0.0003", "period": 2,
})
print(result)API의 금리는 항상 일 단위이며 — APR로 환산하려면 365를 곱하세요 — 항상 총액(gross), 즉 Bitfinex가 발생 이자에서 떼는 15% 수수료 이전 값입니다. 최소 오퍼는 $150 상당이고, 기간은 2–120일입니다. 직접 서명 코드를 짜는 대신 유지 관리되는 클라이언트를 원한다면, Bitfinex가 공식 Python 라이브러리(bfxapi)를 배포합니다.
속도 제한, 그리고 실제로 몇 시간을 잡아먹는 함정들
nonce는 단조 증가해야 합니다
서명된 모든 요청에는 해당 키의 직전 값보다 큰 bfx-nonce가 필요합니다. 하나의 키를 공유하는 두 프로세스는 "nonce: small" 오류로 충돌합니다 — 프로세스마다 별도의 키를 쓰세요.
엔드포인트별 속도 제한
공개 엔드포인트는 경로에 따라 분당 약 10–90회의 요청을 허용하고, 인증 엔드포인트도 비슷합니다. 초과하면 ERR_RATE_LIMIT 본문과 함께 HTTP 429가 반환됩니다 — 지수적으로 백오프하고 읽기는 캐시하세요.
funding/stats는 FRR/365를 저장합니다
/v2/funding/stats의 FRR 열은 일 FRR을 365로 나눈 값이지만, /v2/ticker는 일 금리를 그대로 고시합니다. 비교하기 전에 stats 값에 365를 곱하세요 — 그러지 않으면 백테스트가 조용히 왜곡됩니다.
모든 값은 수수료 공제 전입니다
호가창 금리, 캔들, FRR은 모두 수수료 이전 값입니다. 지갑에 들어오는 것은 발생 이자의 85%(숨김 오퍼는 82%)입니다. 고시 금리가 아니라 원장을 기준으로 대사하세요.
대출은 조기 상환됩니다
120일 크레딧이 120일치 이자를 뜻하지 않습니다 — 차입자는 포지션을 닫을 때 상환하며, 크레딧은 며칠 만에 돌아올 수 있습니다. 명목 기간이 아니라 기대 보유 기간을 모델링하세요.
직접 운영하고 싶지 않다면
위의 모든 것이 Stratum이 프로덕션에서 운영하는 그대로입니다: 동일한 엔드포인트, 서명, 백오프, 원장 대사에 더해 3년치 펀딩 캔들로 백테스트한 11개 전략, 페이퍼 모드, 세금 리포트 내보내기 — 0단계에서 설명한 대로 권한을 제한한, 출금이 비활성화된 키 뒤에서 동작합니다. 스택 전체를 직접 소유하는 게 즐겁다면 봇을 직접 만드세요(이 가이드와 오픈소스 프로젝트들이 실제로 가능한 길입니다); nonce 버그와 새벽 3시의 429를 건너뛰고 싶다면 호스팅형 봇을 쓰세요.
Bitfinex API FAQ
Bitfinex 대출 봇에는 어떤 API 권한이 필요한가요?
Margin Funding 읽기·쓰기, Wallets 읽기, Account History 읽기입니다. 출금, 트레이딩, 이체는 비활성화 상태로 두어야 합니다 — 대출 봇은 자금을 거래소 밖으로 옮길 필요가 전혀 없고, 권한을 제한한 키는 유출되더라도 피해를 제한합니다.
Bitfinex API는 무료인가요?
네. 공개 API(금리, 캔들, 호가창)와 인증 API(오퍼, 지갑, 원장) 모두 무료입니다. 인증이 필요한 부분에만 계정과 API 키가 필요합니다. api-pub.bitfinex.com의 공개 엔드포인트에는 키가 전혀 필요 없습니다.
공식 Bitfinex Python 라이브러리가 있나요?
네 — Bitfinex가 배포하는 bfxapi가 REST와 WebSocket을 모두 지원합니다. 이 페이지의 예제는 통신 과정에서 무슨 일이 일어나는지 정확히 볼 수 있도록 순수 requests와 직접 구현한 HMAC 서명을 사용합니다. 프로덕션 코드라면 공식 라이브러리가 반복 코드를 줄여 줍니다.
Bitfinex API의 금리는 일 단위인가요, 연 단위인가요?
일 단위입니다. 0.0003이라는 금리는 하루 0.03%, 단리로 대략 연 10.95% APR을 뜻합니다. APR을 구하려면 365를 곱하고, 고시되는 모든 금리는 총액이라는 점을 기억하세요 — Bitfinex가 발생 이자의 15%를 가져가므로, 지갑에 실제로 들어오는 금액은 0.85를 곱한 값입니다.
대출 봇에 WebSocket API가 필요한가요?
처음에는 필요 없습니다. 단순한 봇은 REST 폴링으로 충분합니다. WebSocket(공개 wss://api-pub.bitfinex.com/ws/2, 인증 wss://api.bitfinex.com/ws/2)은 REST 속도 제한을 소모하지 않으면서 실시간 호가창 업데이트나 즉각적인 체결 알림을 받고 싶을 때 의미가 있습니다 — Stratum이 지갑, 오퍼, 크레딧 이벤트를 실시간으로 추적하는 방식이 바로 이것입니다.
Bitfinex API의 속도 제한은 어떻게 되나요?
엔드포인트마다 다릅니다. 공개 경로는 분당 약 10–90회, 인증 경로도 비슷한 수준입니다. 제한을 초과하면 HTTP 429(ERR_RATE_LIMIT)가 반환됩니다. 잘 만든 클라이언트는 공개 읽기를 캐시하고 429에 지수 백오프로 대응합니다. 정확한 수치는 공식 문서에 엔드포인트별로 명시되어 있습니다.
API는 쉬운 부분입니다
오퍼를 제출하는 건 Python 스무 줄이면 됩니다. 어떤 금리와 만기를 제시할지 아는 것이 진짜 문제죠. Stratum은 위에서 설명한 바로 그 API 위에서 백테스트된 전략을 운영합니다 — 아니면 이 페이지의 코드를 가져가 직접 봇을 만드세요.