Funding settlements
GET /v2/funding/settlements returns funding as events: one row for each time a venue settled a listing’s funding. The sampled funding layer says what a venue’s rate is now; a settlement row says what the venue charged at an instant, the figure a backtest or a cost estimate needs.
Rates are as the venue published them, for the listing’s own interval, never rescaled; the 8 hour restatement and the cap sit beside them on the basis of Funding normalisation.
| field | what it is |
|---|---|
time |
the settlement instant as the venue states it, to the second (a venue’s own time carries milliseconds of jitter after the hour). The window of a request is (from, to]. |
rate, rate_8h |
the rate that settled, exactly as published (a fraction: 0.0001 is 0.01%), for the listing’s own interval; and the same rate restated over 8 hours, rate × 8 h / interval. |
rate_source |
where the rate was read: venue_history (the venue’s own funding-history endpoint), last_sample (the last rate the platform received before the instant), first_sample_after (OKX: the first record after the instant names the rate that has just settled), unsampled (none: status: missing, rate null, never a zero). |
interval |
the interval in force at that print: the gap to the listing’s previous print where it is one of 1, 2, 4 or 8 hours; the interval of the print before where it is not. interval_source is gap, or venue where there is no previous print and the venue’s published interval stands in. |
interval_published, interval_check |
the interval the venue publishes for the listing at the print, and match, mismatch or unchecked. A mismatch is flagged on the row and never corrected. |
origin |
live: recorded as it settled, from the venue’s funding data. backfill: read afterwards from the venue’s own history. |
cap, floor, cap_8h, floor_8h, at_cap |
the bounds the venue’s API published for the listing at the print, and whether rate sits on one. Null where the venue’s API publishes none, or none had been observed by then: a print is never judged against a cap that came later. |
Rows are selected with where like every other /v2 endpoint, bounded with from and to (a week back by default), ordered by order (desc newest first, the default, or asc) and paged by cursor: follow next_cursor until it is null; the cursor pins the window of the first page. Depth is the plan’s history, exactly as for POST /v2/snapshots/history: an older from is refused with PLAN_LIMIT, naming earliest_from and the request to send instead (retry_with). A venue of the selection the platform holds no prints for is named under not_recorded, with the reason, so an empty page is never mistaken for a quiet venue.
How a print is recorded live
Section titled “How a print is recorded live”The Writer reads the funding records each connector publishes. A venue carries the next settlement instant with its rate; when that instant moves forward, the one it moved from has settled. The rate of the print is the venue’s own rate (the field the venue’s funding column names) from the sample its rule names: the last one received at or before the instant, or the first one after it. A rate that stands more than five minutes from the instant is not used: the print is recorded without a rate (unsampled) and the backfill fills it. A process that restarts across a settlement misses that print; the backfill adds it as origin: backfill, which says it was not recorded live.
A venue is recorded live only where its next time is shown to be the settlement instant. The others are not recorded live yet, for the reason in the table.
| venue | recorded live | how, or why not |
|---|---|---|
ASTER-PERP |
yes | last rate before the instant: the same frames as Binance USD-M (the venue is a fork of its API): r and T of the mark-price stream. |
AVANTIS-PERP |
no | the venue accrues funding continuously, there is no settlement |
BINANCE-USDM |
yes | last rate before the instant: markPrice stream: r is the live funding rate and T the next funding time; T moves forward when the period settles, so the rate that settled is the last one received before it. |
BITGET-PERP |
no | the next time the funding data carries is not yet shown, by a recorded fixture, to be the settlement instant |
BYBIT-PERP |
yes | last rate before the instant: ticker stream: fundingRate is the live rate and nextFundingTime the next settlement; the rate that settled is the last one received before it. |
COINBASE-INTX |
no | the funding data carries no next settlement instant, so nothing in it says when a print happened |
DERIBIT-PERP |
no | the venue accrues funding continuously, there is no settlement |
DYDX-PERP |
no | the funding data carries no next settlement instant, so nothing in it says when a print happened |
EDGEX-PERP |
no | the next time the funding data carries is not yet shown, by a recorded fixture, to be the settlement instant |
GATE-PERP |
no | the next time the funding data carries is not yet shown, by a recorded fixture, to be the settlement instant |
GMX-PERP |
no | the venue accrues funding continuously, there is no settlement |
HYPERLIQUID |
yes | last rate before the instant: predictedFundings carries the next funding time (the next hour); activeAssetCtx.funding is the hourly rate in progress. The next time is read from a polled cache, so a record after the hour can still name the old instant: only a rate received at or before the instant counts as its rate. |
KRAKEN-FUTURES |
yes | last rate before the instant: ticker stream: next_funding_rate_time moves forward each hour; relative_funding_rate is the venue’s predicted rate for the hour in progress (a fraction), not the rate that settles: live samples taken before the hour differed from the venue’s settled figure on 95 of 98 prints. The last sample before the instant (rate_source: last_sample) is therefore only a stand-in; the rate of the row is the settled figure from the venue’s funding history (historicalfundingrates, rate_source: venue_history), which the backfill writes over it. |
LIGHTER-PERP |
no | the funding data carries no next settlement instant, so nothing in it says when a print happened |
MEXC-PERP |
no | the next time the funding data carries is not yet shown, by a recorded fixture, to be the settlement instant |
NADO-PERP |
no | the funding data carries no next settlement instant, so nothing in it says when a print happened |
OKX-PERP |
yes | first rate after the instant: funding-rate channel: fundingTime moves forward at settlement, and settFundingRate is, once settState is settled, the rate that was used for the last settlement; the first record after the move carries it. (fundingRate is the forecast of the next one and is never read.) |
SYNTHETIX-PERP |
no | the next time the funding data carries is not yet shown, by a recorded fixture, to be the settlement instant |
WEEX-FUTURES |
no | the next time the funding data carries is not yet shown, by a recorded fixture, to be the settlement instant |
The backfill
Section titled “The backfill”The operator’s settlement-backfill command reads each venue’s own funding history for the last 90 days, from these five, and writes the prints the table does not have. It is journalled and resumable (funding_settlement_backfill: a rerun goes on at the listings that are not complete), and paced below each venue’s limit: a 429 waits for Retry-After, a 418 stops the run.
| venue | request | the rate | pace |
|---|---|---|---|
BINANCE-USDM |
GET /fapi/v1/fundingRate |
fundingRate |
one request per 800 ms (the venue’s 500 per 5 minutes per IP is shared with fundingInfo) |
BYBIT-PERP |
GET /v5/market/funding/history |
fundingRate |
one request per 200 ms |
OKX-PERP |
GET /api/v5/public/funding-rate-history |
realizedRate, the one that settled |
one request per 250 ms; the venue keeps about three months |
KRAKEN-FUTURES |
GET /derivatives/api/v4/historicalfundingrates |
relativeFundingRate, the figure the platform stores as the venue’s funding |
one request per 500 ms, one per listing |
HYPERLIQUID |
POST /info fundingHistory |
fundingRate, per hour |
one request per 1.1 s (weight 20 of the venue’s 1 200 a minute) |
A live print is never replaced by a backfilled row: it stays origin: live, and where its rate came from a sample the backfill replaces the rate with the venue’s own figure (rate_source: venue_history). Each run reports how many live prints it confirmed and by how much the venue’s figure differed, so the live recording is measured against the venue every time a backfill passes over it.
The interval, and the cross-check
Section titled “The interval, and the cross-check”The interval of a print is derived from the venue’s own settlement times: a print four hours after the previous one settled a 4 h period. Only 1, 2, 4 and 8 hours count (the gap rounded to the minute); a longer gap is a halted listing, and a single gap of twice the interval between runs of the same interval is a missed settlement; neither says anything about the interval, and the print keeps the interval before it.
It is then compared with the interval the venue publishes for the listing at the print: the newest word the platform recorded from the venue (listing_funding_interval, source venue) that began before it, the first of them for an older print, the venue’s current word where none was recorded. A venue can change a listing’s interval without notice and the platform watched only since it began collecting, so a mismatch on an old print may be a change the platform never saw. The row says so and keeps both figures; nothing is corrected silently.
Anchoring
Section titled “Anchoring”The prints are in a table of their own that no anchor covers (ADR-034, ADR-036): a settlement row is not a leaf of any day’s root, no frozen day can refuse it, and a backfilled print neither changes a root nor needs a proof. The sampled funding layer is anchored as before.