Skip to main content
How a funding carry actually paid: the historical funding spread of a pair at its legs’ real settlement times, and what holding it for 1 to 90 days returned after fees. A pair is a spot-perp carry on one venue (buy spot, short the perp, or the reverse) or a cross-exchange carry (long one perp, short another).

Get a pair’s spread history and backtest

GET /v1/arbitrage/funding-spread-history Reads stored settlements (funding_rates_history); no exchange is called. The answer is dated by the funding cron’s last run, stale after 10 minutes. An unknown venue, a missing leg or a contract of another coin is 400; a leg with no settlements in the window is 404. Without a contract, a leg uses the venue’s contract for the coin with the largest current open interest (then the most settlements in the window), and says so (contractSource: "resolved", plus a warning in meta).

Query parameters

string
spot-perp (default) or cross-exchange.
string
required
Base coin, for example BTC. Required.
string
Spot-perp: Binance, OKX, Bybit, Bitget, Gate.io, KuCoin, MEXC, BingX or HTX.
string
Spot-perp: the perp contract symbol, for example BTCUSDT. Optional.
string
Spot-perp: short (default) buys spot and shorts the perp; long sells spot and longs the perp, charged the venue’s current borrow APR where it publishes one.
string
Cross-exchange: the long perp’s venue.
string
Cross-exchange: the long perp’s contract symbol. Optional.
string
Cross-exchange: the short perp’s venue.
string
Cross-exchange: the short perp’s contract symbol. Optional.
integer
Backtest window, 1-90 days. Defaults to 30.
Response (trimmed: 2 of 40 series points)

Formula

Every figure is a fraction of one leg’s notional (multiply by 100 for percent), the convention of the funding boards. A settlement at time t pays the venue’s rate for the interval (t − h, t]. The interval h of each settlement is read from the gap to the contract’s previous settlement (1, 2, 4, 8, 12 or 24 hours), else the stored interval; it is never assumed to be 8 hours. Alignment. The legs are aligned by time, not by index. The series has a point at every settlement of either leg; at each point, a leg is read at the settlement whose interval covers it. A 1-hour leg against an 8-hour leg reads the 8-hour settlement for each of the eight hours it covers, and the spread is null where a leg has no covering settlement (a gap, or an interval that has not settled yet). spreadApr = Σ ± rate × 8760 / h over the legs: + for a short leg (it receives positive funding), − for a long leg. A spot-perp pair has one leg; spot pays no funding. legAprs are each leg’s own rate × 8760 / h with the venue’s sign. cashflow is what the position received at the instant (the settlements that settle then), and cumulativeCarry its running sum. Backtest. A window of days ends at windowEnd, the earliest of the legs’ last settlements (the latest instant both legs are realised), and starts days earlier, or later when a leg’s history begins inside the window (complete: false).
  • fundingCollected = the sum of the position’s settlements in (start, end]. Funding is paid to the position held at the settlement instant, so a settlement counts in full.
  • fees = entry plus exit taker fees at each venue’s standard rate: 2 × spot + 2 × perp on the venue (spot-perp), 2 × long perp + 2 × short perp (cross-exchange).
  • netReturn = fundingCollected − fees; grossApr = fundingCollected × 365 / coveredDays; netApr = netReturn × 365 / coveredDays.
  • negativeCarryDays: 24-hour periods counted back from end (not UTC days) whose settlements summed below zero, out of daysObserved.
  • maxDrawdown: the largest fall of cumulative funding from its running peak, starting at 0; fees excluded.
  • breakEvenDays = fees / (fundingCollected / coveredDays), only when funding was positive (net of borrowApr / 365 when the borrow is charged).
  • coverageRatio: the least-covered leg’s Σ h / covered span, at most 1. A missing settlement lowers it and is never read as zero funding; below 0.9 the backtest is not complete.
  • estimatedSettlements: settlements in (start, end] that are still the funding cron’s pre-settlement estimate (the last rate seen before the boundary) rather than the venue’s own record. Until the reconcile job replaces them, the series points they price carry estimated: true and the figures can still move. complete speaks to coverage only.
A short-spot leg (spot-perp long, requiresBorrow) is charged the venue’s current spot-margin borrow APR (borrowApr, the rate the spot-perp board nets) pro rata in every backtest: netReturn less borrowApr × coveredDays / 365, netApr less borrowApr; grossApr stays funding only. Stored history keeps no borrow rates, so a past window is charged today’s rate. Binance, OKX, Bybit and Gate.io publish one; elsewhere, or when the read fails or takes longer than 8 seconds (a first Gate.io read after a cold start can), borrowCostIncluded is false and a warning says why. Not modelled: entry and exit price gaps, and moving collateral between venues.