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
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.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 timet 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 × perpon 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 fromend(not UTC days) whose settlements summed below zero, out ofdaysObserved.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 ofborrowApr / 365when 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 notcomplete.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 carryestimated: trueand the figures can still move.completespeaks to coverage only.
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.
