List calendar spread rows
GET /v1/arbitrage/futures-calendar-spread
The board covers Binance (USDT-M and COIN-M), OKX, Bybit (linear and inverse) and Deribit; both legs share one venue and one margin type. While a venue’s quotes in the 5-minute dated-quotes snapshot (dataset arbitrage_dated_quotes, written by the arbitrage-boards cron with top-20 book walks and VWAP fills at the default $10,000 notional) are at most 10 minutes old, the board prices that venue from it, so rows can be executable at any minute of the hour; the answer is then dated by the snapshot (dataset_id: "arbitrage_dated_quotes", stale after 10 minutes) and cached up to s-maxage=100, stale-while-revalidate=200. A venue the snapshot lacks, or holds only older quotes for, is served from the hourly term-structure snapshot (written at :03 UTC, stale after 2 hours), its pairs indicative. When the stored snapshot is past its 2-hour SLA, empty, or holds only reference quotes, the scanner reads the venues live (meta.source: "live") and merges per venue: a venue that answered replaces its stored rows, a venue that failed keeps its stored rows. A failed data-store read returns 503 (service_unavailable, Retry-After: 30).
Order: pairs meeting both tenor floors (near leg at least 3 days out, legs at least 7 days apart) first, then belowTenorFloor pairs; within each group executable pairs with a positive netRollApy, then positive pairs executable on a live read (indicativeReason: snapshot_quote), then every other pair, each by netRollApy, highest first. An executable pair at a post-fee loss never ranks above a positive spread.
Query parameters
Position notional in USD. Defaults to 10000. A pair is
executable only when the depth behind both legs, the smaller leg’s reported open interest and the thinner leg’s 24h volume are at least this notional; a smaller notional widens the executable set. minDepthUsd filters rows out instead.Response
Formula
referenceForwardYield = (F_far / F_near − 1) × 365 / gapDays, on each contract’s mark price, else its book mid (priceReference); never the last trade, which goes stale on an illiquid contract. It sets curve and direction: a far contract above the near one buys near and sells far.
forwardYield = (sellBid / buyAsk − 1) × 365 / gapDays: the executable sides the direction trades (contango buys the near ask and sells the far bid; backwardation buys the far ask and sells the near bid).
fees = 4 × futures taker fee + 2 × spot taker fee: the lock-in’s fills at the venue’s standard rates (0.004 on OKX). Not annualized.
netRollApy = (sellBid / buyAsk − 1 − fees) × 365 / gapDays. A losing post-fee spread stays negative rather than being clamped to zero.
Every yield, basis and fee is a fraction (0.05 is 5%).
gapDays is the fractional gap between the expiries, nearDays the fractional days from the request to the near expiry. nearBasis and farBasis are each contract’s reference price against the venue’s spot reference. minDepthUsd is the smaller depth behind the two legs (the top 20 levels where level 1 is thinner than $10,000); market impact within those levels is not modelled.
A pair is executable only when all of these hold; otherwise it is indicative and indicativeReason names the first check that failed:
Tenor floors: a pair whose near leg is under 3 days from expiry, or whose legs expire under 7 days apart, is served with
belowTenorFloor: true and ranked after every pair meeting both floors (a 1-day Deribit daily spread annualizes a few basis points into −70% or worse).
