Futures Calendar Spread

Pair active dated futures by coin and exchange, then rank adjacent near/far contracts by forward yield and net roll APY.

GET/v1/arbitrage/futures-calendar-spread

List calendar spread rows

The main scanner grid shows Rank, Coin, Exchange, Near/Far, Expiries, Direction, Forward Yield, Net Roll APY, Curve, Liquidity, and Updated. Row details include the near/far contract inputs, basis values, min OI/depth, source timestamps, and the heatmap breakdown.

Query parameters

Name
coin
Type
string
Description
Optional base coin. Supported launch coins: BTC, ETH, SOL, XRP, DOGE, MNT, XAUT.
Name
exchanges
Type
string
Description
Comma-separated exchange filter.
Name
minApr
Type
number
Description
Minimum netRollApyPct in percentage points.
Name
minOiUsd
Type
number
Description
Minimum of near/far open interest in USD.
Name
minVolumeUsd
Type
number
Description
Minimum of near/far 24h futures volume in USD.
Name
minDepthUsd
Type
number
Description
Minimum of near/far depth in USD when depth is available.
Name
marginType
Type
string
Description
Futures margin filter: linear, inverse, or both.
Name
notional
Type
number
Description
Position notional echoed in scanner metadata. Defaults to 10000; use minDepthUsd to enforce executable capacity.
Name
limit
Type
integer
Description
Rows per page. Defaults to 100.
Name
cursor
Type
string
Description
Opaque cursor from the previous page.

Request

GET

/v1/arbitrage/futures-calendar-spread

curl -G https://www.sharpe.ai/api/v1/arbitrage/futures-calendar-spread \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d exchanges=Binance,OKX

Response

{
  "data": {
    "rows": [
      {
        "rank": 1,
        "coin": "ETH",
        "exchange": "OKX",
        "nearContract": "ETH-USDT-260626",
        "nearExpiry": "2026-06-26T08:00:00.000Z",
        "farContract": "ETH-USDT-260925",
        "farExpiry": "2026-09-25T08:00:00.000Z",
        "nearBasisPct": 1.8,
        "farBasisPct": 4.6,
        "forwardYieldPct": 11.23,
        "curve": "Contango",
        "direction": "Buy Near / Sell Far",
        "netRollApyPct": 10.43,
        "minOpenInterestUsd": 32000000,
        "minDepthUsd": 64000,
        "executionStatus": "executable",
        "updatedAt": "2026-05-23T10:30:00.000Z"
      }
    ],
    "scannerMeta": {
      "kind": "futures-calendar-spread",
      "status": "ok",
      "source": "supabase",
      "notionalUsd": 10000
    },
    "pagination": { "cursor": null, "has_more": false, "total": 1 }
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-05-23T10:30:00.000Z",
    "elapsed_ms": 17
  }
}

Formula

For contango:

forwardYieldPct = (farBid - nearAsk) / nearAsk * 100 * 365 / (farDays - nearDays)

Backwardation reverses the executable sides (nearBid versus farAsk).

netRollApyPct = forwardYieldPct - annualizedRoundTripFees

direction is selected from the reference curve, but the returned yield and ranking use executable quotes. A losing post-fee spread remains negative rather than being clamped to zero. Market impact beyond the displayed top levels is not modeled; use minDepthUsd to require capacity on both contracts.

executionStatus is executable when the row's snapshot is inside the freshness SLA and indicative when it is not. An indicative row keeps every figure — the quote was real when it was taken — but it is too old to act on, so indicative rows sort below executable ones and should not be treated as a live opportunity. Cross-check updatedAt and isStale.