# Funding rates

> Every funding event of each crypto perpetual, since its first month.

Source: https://getmarkethistory.com/docs/funding

`crypto-futures` carries the funding rates of its perpetuals: **every funding event** of each
contract from its first month on, delisted contracts included. A funding event is the periodic
payment between longs and shorts that keeps a perpetual near its index. Most contracts fund
every 8 hours; some move to 4 or 1 hours, and each row says which.

New funding events of the contracts still trading are added every night, so the newest row is
under a day old. Each month is checked again, row by row, against the exchange's monthly file
when it is posted; a published row is never changed afterwards.

## Query

curl:

```bash
curl -sD - "https://getmarkethistory.com/query/v1/funding?symbol=BTCUSDT&start=2024-01-01&end=2024-12-31" \
  -H "Authorization: Bearer $MARKET_HISTORY_KEY"
```

Python client:

```python
from markethistory import Client

mh = Client()  # reads MARKET_HISTORY_KEY

rates = list(mh.each(mh.funding, "BTCUSDT", start="2024-01-01", end="2024-12-31"))
rates[0]  # {"interval_h": 8, "rate": 0.00037409, "timestamp": "2024-01-01T00:00:00.004Z"}
```

Plain `requests`:

```python
import json
import os

import requests

url = "https://getmarkethistory.com/query/v1/funding"
params = {"symbol": "BTCUSDT", "start": "2024-01-01", "end": "2024-12-31"}
headers = {"Authorization": f"Bearer {os.environ['MARKET_HISTORY_KEY']}"}

rows = []
while True:
    r = requests.get(url, params=params, headers=headers, timeout=60)
    r.raise_for_status()  # see /docs/errors for what each status means
    rows += [json.loads(line) for line in r.text.splitlines() if line]
    print(r.headers["X-Row-Count"], "rows,", r.headers["X-Bars-Charged"], "bars")
    if "X-Next-Cursor" not in r.headers:
        break
    params["cursor"] = r.headers["X-Next-Cursor"]
```

Response (shape and headers as served; values illustrative):

```http
HTTP/2 200
content-type: application/x-ndjson
x-row-count: 1000
x-bars-charged: 1000
x-next-cursor: eyJ…
x-query-ms: 12

{"interval_h":8,"rate":0.00037409,"timestamp":"2024-01-01T00:00:00.004Z"}
{"interval_h":8,"rate":0.00051283,"timestamp":"2024-01-01T08:00:00.002Z"}
{"interval_h":8,"rate":0.00046110,"timestamp":"2024-01-01T16:00:00.001Z"}
```

One symbol per request, spelled as `/api/v1/symbols?source=crypto-futures&timeframe=1m` lists
it.

| Parameter      | Meaning                                                                      |
| -------------- | ---------------------------------------------------------------------------- |
| `symbol`       | The perpetual (`BTCUSDT`). Required.                                         |
| `source`       | Optional: `crypto-futures`, the only source with funding rates.              |
| `start`, `end` | Time range, inclusive (RFC 3339 or a bare date). Default: all of it.         |
| `limit`        | Rows per page: default 1,000, maximum 100,000.                               |
| `cursor`       | `X-Next-Cursor` from the previous page.                                      |
| `format`       | `jsonl` (default), `csv`, `json`, `parquet` or `arrow`. `mbt1` is bars only. |

Pages run oldest first. Follow `X-Next-Cursor` (or the `Link` header) until it is absent: the
cursor holds no server state. A symbol listed with no funding rates is a 404.

## Columns

| Column       | Type      | Meaning                                                                                   |
| ------------ | --------- | ----------------------------------------------------------------------------------------- |
| `timestamp`  | timestamp | when the rate was computed, UTC, to the millisecond (a few ms after the hour, as stamped) |
| `rate`       | float     | the funding rate as a fraction: 0.0001 is 0.01%; positive, longs pay shorts               |
| `interval_h` | integer   | the contract's funding interval at that time, in hours (8, 4 or 1)                        |

Rates are stored exactly as published (to 10⁻⁸, finer when a rate has more digits) and are
served as the nearest float.

## Price

Billed like bars: **one row is one bar**, a page rounds up to a block of 100 rows, and an empty
page is free. Funding rates need bought bars: the free plan's monthly bars do not pay for them. A year of one 8-hour
contract is about 1,100 rows.