Funding rates

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

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

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"}

requests

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

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"}

Shape and headers as served; the values are illustrative, not copied from a response.

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.