List spot-perp opportunities
GET /v1/arbitrage/spot-perp
Returns spot-perp arbitrage rows in board order: executable rows first by netApr, then no_spot_depth / no_depth rows, then the other indicative rows, each by netApr where they have one, else gross apr. Each row carries the current funding rate at the market’s own interval, its 7-day cumulative rate, gross and net APR, the entry basis at the quoted sides, the fees charged, the days of carry that pay them back, and why a row is not executable (indicativeReason).
The board is composed every 5 minutes by a scheduled job, never per request, and is stale after 10 minutes. Executability is judged again at the time of the request: a row whose spot or perp quote is older than 10 minutes is served indicative with indicativeReason: stale_quote. Only funding rates inside the 10-minute funding freshness window are ranked, and legs the venue reports as not trading (halted, settling, delisted or pre-launch) are excluded. With no board to serve the endpoint answers 503 (service_unavailable, Retry-After: 30).
Without limit or cursor the answer is every row (about 3,000). With either, it is one page in board order and v1 adds pagination; pass pagination.cursor back as cursor for the next page. The MCP tool get_arbitrage_spot_perp asks for a 100-row page unless given limit or cursor.
Query parameters
Filter by exchange. One of
all, Binance, OKX, Bybit, Bitget, Gate.io, KuCoin, MEXC, BingX, HTX. Defaults to all. A venue the instrument master marks not live has no rows; X-Data-Venues lists the venues a filter can offer, leaving out every venue that is not_live or stale in X-Data-Missing.Filter by portfolio direction. One of
all, long, short. Defaults to all. short means buy spot and short the perp (funding rate ≥ 0); long means sell spot and long the perp (funding rate < 0), which needs the base coin borrowed on margin.Minimum open interest in USD on the perp leg (
perpOpenInterestUsd). Defaults to 0 (no floor). A row whose open interest is unknown fails any floor above 0. The board order is kept.Opaque cursor from the previous page’s
pagination.cursor (100 rows a page when limit is omitted).Response headers
Besides the freshness headers, both the v1 and the free route send:X-Data-Missing: each configured venue that is not a quoted member of the board, comma-separated asVenue:reason.not_live(the instrument master says every contract is halted, so the venue is not asked),stale(no funding row inside the funding SLA),no_ticker(rows are served but unpriced: the venue’s ticker fetch failed). Absent when every venue is a quoted member.X-Data-Venues: the venues a venue filter may offer, comma-separated: the configured venues less thosenot_liveorstale(a venue whose funding rows are all past the funding SLA, such as a halted venue, is not offered).
Response
Formulas
All rates are decimal fractions (0.30 = 30%). A funding rate is per its market’s own interval (intervalHours: 1, 2, 4 or 8 hours), and every APR annualizes it on that interval. A tool that assumes 8-hour funding shows a 1-hour market 8× smaller and a 4-hour market 2× smaller than it pays.
apr = |fundingRate| × 8760 / intervalHours(simple, not compounded).entryBasisRate, positive when favourable: buy spot / short perp(perpBid − spotAsk) / spotAsk; sell spot / long perp(spotBid − perpAsk) / perpAsk. Spot is the venue’s last trade; perp prices are per asset unit (the contract price ÷perpLotMultiplier).roundTripFeeRate = 2 × spot taker fee + 2 × perp taker feeat the venue’s standard (VIP 0) rate.netApr = apr − (roundTripFeeRate + max(−entryBasisRate, 0)) × 365 / 30 − borrowApr. One-time costs are amortized over a 30-day hold. A favourable entry basis is never credited as income.borrowApris the coin’s public spot-margin borrow rate on the row’s venue (Binance, OKX, Bybit or Gate.io, from the Margin Borrow Rates module, annualized × 8,760) and is subtracted only on a sell-spot row; a sell-spot row without one (the other venues, or a coin the venue does not price) hasrequiresBorrow: true,borrowCostIncluded: false, isindicativewithindicativeReason: borrow_unpriced(ranked after executable rows), and itsnetAproverstates the carry by the borrow interest.breakEvenDays = (roundTripFeeRate + max(−entryBasisRate, 0)) ÷ ((apr − borrowApr) / 365);nullwithout anetApr.apr7d = cumRate7d × 365 / 7, sign flipped for a long-perp row: what the last 7 days of settlements paid the row’s direction.carrySignFlip7distruewhen it is negative. The board ranks on the current rate, not onapr7d.
executable when both legs are priced, the instrument master places both legs on one asset, the spot price is within 5% of the perp’s index (else mark, else last) price per asset unit, a sell-spot row’s borrow rate is known and in netApr, both quotes are at most 10 minutes old at the time of the request, and both legs report top-of-book depth of at least $10,000 on the side the trade hits. The board reads spot prices as last trades with no book behind them, so no row is executable today: a row that passes every other check is no_spot_depth, and those rows rank first. Otherwise it is indicative:
Response fields
Each object in thedata array is one spot-perp pair on one exchange.
The base asset ticker (e.g.,
BTC, PEPE). A lot contract trades against its asset’s spot: Binance 1000PEPEUSDT is the PEPE row.Diagnostic basis on last prices:
(perpPrice − spotPrice) / spotPrice. null when a price is missing, never 0.apr after the round-trip fees, the adverse entry basis and a known borrow cost (see Formulas). May be negative. null on an unpriced row or when the legs are more than 20% apart.short (buy spot, short perp) when the funding rate is ≥ 0, long (sell spot, long perp) when it is negative.The venue’s perpetual contract, in the venue’s own spelling (e.g.
BTCUSDT, ETH-USDT-SWAP, 1000PEPEUSDT).Asset units per contract unit (
1000 for 1000PEPEUSDT); null when the instrument master does not know the contract.One-sided open interest of that perp in USD: the venue ticker’s figure, else the contract’s latest stored open interest.
null when neither is known, never 0.Why the row is
indicative: no_spot_depth, no_depth, thin_book, oi_below_notional, unpriced, identity_mismatch, not_live, contract_type, margin_type, price_gap, stale_quote, borrow_unpriced or borrow_limit. null when executable.Whether the legs are one instrument:
eligible, unpriced (a leg has no price to check), else the first check that failed: identity_mismatch, not_live, contract_type, margin_type or price_gap (more than 20% apart).The entry basis at the quoted sides, positive when favourable. Only a negative value is charged in
netApr.Two spot and two perp taker fills at the venue’s standard fee, as a fraction of notional.
true when the borrow interest is subtracted from netApr (the venue publishes the rate: Binance, OKX, Bybit, Gate.io); false when the rate is unknown (the row is then indicative borrow_unpriced), and on rows that need no borrow.true when fundingAsOf is older than the funding book’s 10-minute SLA at the time of the request.Reverse carry (needs a borrow)

