> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sharpe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Funding Spread History & Backtest API

> A spot-perp or cross-exchange pair's funding spread at its real settlement times, and a 1-90 day carry backtest net of each venue's fees.

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

**mode** `string`

`spot-perp` (default) or `cross-exchange`.

**coin** `string` *required*

Base coin, for example BTC. Required.

**venue** `string`

Spot-perp: Binance, OKX, Bybit, Bitget, Gate.io, KuCoin, MEXC, BingX or HTX.

**contract** `string`

Spot-perp: the perp contract symbol, for example `BTCUSDT`. Optional.

**direction** `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.

**longVenue** `string`

Cross-exchange: the long perp's venue.

**longContract** `string`

Cross-exchange: the long perp's contract symbol. Optional.

**shortVenue** `string`

Cross-exchange: the short perp's venue.

**shortContract** `string`

Cross-exchange: the short perp's contract symbol. Optional.

**days** `integer`

Backtest window, 1-90 days. Defaults to 30.

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/arbitrage/funding-spread-history \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d mode=cross-exchange \
  -d coin=BTC \
  -d longVenue=Hyperliquid \
  -d shortVenue=Binance \
  -d shortContract=BTCUSDT \
  -d days=2
```

```json title="Response (trimmed: 2 of 40 series points)" theme={null}
{
  "data": {
    "mode": "cross-exchange",
    "coin": "BTC",
    "direction": null,
    "days": 2,
    "legs": [
      {
        "role": "long",
        "venue": "Hyperliquid",
        "contract": "BTC-USD",
        "contractSource": "resolved",
        "side": "long",
        "intervalHours": 1,
        "settlements": 47,
        "firstSettledAt": "2026-09-28T09:00:00.000Z",
        "lastSettledAt": "2026-09-30T00:00:00.000Z",
        "takerFee": 0.00045
      },
      {
        "role": "short",
        "venue": "Binance",
        "contract": "BTCUSDT",
        "contractSource": "given",
        "side": "short",
        "intervalHours": 8,
        "settlements": 5,
        "firstSettledAt": "2026-09-28T16:00:00.000Z",
        "lastSettledAt": "2026-09-30T00:00:00.000Z",
        "takerFee": 0.0005
      }
    ],
    "spot": null,
    "roundTripFees": 0.0019,
    "requiresBorrow": false,
    "borrowCostIncluded": false,
    "borrowApr": null,
    "windowEnd": "2026-09-30T00:00:00.000Z",
    "series": [
      {
        "at": "2026-09-28T09:00:00.000Z",
        "spreadApr": -0.022912218,
        "legAprs": [0.094098168, 0.07118595],
        "cashflow": -0.0000107418,
        "cumulativeCarry": -0.0000107418,
        "estimated": false
      },
      {
        "at": "2026-09-30T00:00:00.000Z",
        "spreadApr": 0.024279654,
        "legAprs": [0.060002496, 0.08428215],
        "cashflow": 0.0000701204,
        "cumulativeCarry": -0.0000693462,
        "estimated": false
      }
    ],
    "backtests": [
      {
        "days": 1,
        "start": "2026-09-29T00:00:00.000Z",
        "end": "2026-09-30T00:00:00.000Z",
        "coveredDays": 1,
        "complete": true,
        "coverageRatio": 1,
        "estimatedSettlements": 0,
        "fundingCollected": -0.0000302706,
        "fees": 0.0019,
        "netReturn": -0.0019302706,
        "grossApr": -0.011048769,
        "netApr": -0.704548769,
        "negativeCarryDays": 1,
        "daysObserved": 1,
        "maxDrawdown": 0.0001354009,
        "breakEvenDays": null
      },
      {
        "days": 2,
        "start": "2026-09-28T08:00:00.000Z",
        "end": "2026-09-30T00:00:00.000Z",
        "coveredDays": 1.6666666666666667,
        "complete": false,
        "coverageRatio": 1,
        "estimatedSettlements": 0,
        "fundingCollected": -0.0000693462,
        "fees": 0.0019,
        "netReturn": -0.0019693462,
        "grossApr": -0.0151868178,
        "netApr": -0.4312868178,
        "negativeCarryDays": 1,
        "daysObserved": 1,
        "maxDrawdown": 0.0001394666,
        "breakEvenDays": null
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-09-30T13:30:00.000Z",
    "elapsed_ms": 42
  }
}
```

***

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.