> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Funding history
> Retrieve the public funding rate history for futures and collateral markets via the V4 API.
* [Available futures markets list](/api-reference/market-data/available-futures-markets-list) — futures market details including current predicted funding rate.
## OpenAPI
````yaml /openapi/public/http-v4.yaml GET /api/v4/public/funding-history/{market}
openapi: 3.0.3
info:
title: Public HTTP API V4
description: >
WhiteBIT Public HTTP API V4 for market data and trading information.
Base URL: https://whitebit.com
All endpoints return time in Unix-time format.
All endpoints return either a JSON object or array.
Use HTTP method GET for API calls.
Send parameters as query string when an endpoint requires them.
Rate limit: 2000 requests/10 sec for most endpoints (specific limits noted
per endpoint).
## Caching and data freshness
Most public endpoints serve cached data. The cache is **shared across all
callers** — values are keyed by the resource (market, currency), never by
account — and invalidates on a **time basis only**: an upstream change
becomes visible after the next refresh, not immediately.
Two refresh tiers apply:
- **Reference data** (`markets`, `assets`, `fee`, `collateral/markets`,
`futures`) refreshes from the database on a fixed interval, ranging from
about 10 seconds to about 1 minute depending on the endpoint.
- **Market data** (`trades`, `orderbook`, `orderbook/depth`, `ticker`) uses
a short-lived cache, about 1 second by default.
`time` and `ping` are computed per request and are not cached. Each endpoint
states its own refresh interval. Polling faster than that interval returns
identical data and consumes rate-limit budget without producing fresher
results.
## Error responses
Public V4 endpoints do not share a single error schema. Depending on the
endpoint, an error arrives in one of three shapes (there is no `params`
field on any public error):
- **Flat validation bag (HTTP 422)** — `{ "": [""] }`. No
envelope. Used by the market endpoints (`orderbook`, `orderbook/depth`,
`trades`). Example: `{ "market": ["Market is not available."] }`. On
`funding-history` the values are single strings rather than arrays.
- **Wrapped, HTTP 200 even on validation errors** — `{ "success": false,
"message": { "": [""] }, "result": null }`. Used by the V4
`kline` endpoint (not part of this portal — the documented Kline endpoint is
V1).
- **Wrapped string message (HTTP 4xx)** — `{ "success": false, "message":
"", "errors": [] }`. Used by the margin/futures collateral subset of
endpoints. Parameterless endpoints (`markets`, `ticker`, `assets`, `fee`)
take no input and so produce no validation errors — they fail only at the
infrastructure level below.
Common failures are produced at the infrastructure layer, not by the
application, and do not follow these shapes:
- **Maintenance** — every endpoint returns **HTTP 503** with a non-JSON body
served by the gateway.
- **Rate limit exceeded** — **HTTP 429** with a non-JSON body served by the
gateway/CDN.
- **Internal server error** — **HTTP 500** with a flat body `{ "error":
["Internal server error."] }`.
- **Unknown route** — **HTTP 404** with an empty body.
version: 4.0.0
servers:
- url: https://whitebit.com
description: WhiteBIT Global Server
- url: https://whitebit.eu
description: WhiteBIT EU Server
security: []
tags:
- name: Public API V4
description: Public endpoints for market data, trading information, and platform status
paths:
/api/v4/public/funding-history/{market}:
get:
tags:
- Public API V4
summary: Funding History
description: >
The endpoint returns the funding rate history for a specified futures
market. Use the response to analyze historical funding rate trends and
settlement prices. Results are sorted by funding time in descending
order and support offset-based pagination via `limit` and `offset`
parameters.
Rate limit 2000 requests/10 sec.
This endpoint supports pagination. Use `limit` (default: 100, max: 100)
and `offset` (default: 0, max: 1000000) to page through results.
The response is a plain array with no `total`, `has_more`, or cursor — a
returned count below `limit` marks the last page (an empty array means
no further records).
Funding history is served per request at the API layer, with no
application-level cache.
parameters:
- name: market
in: path
required: true
description: Market name (e.g., BTC_PERP)
schema:
type: string
example: BTC_PERP
- name: startDate
in: query
required: false
description: Start timestamp in seconds
schema:
type: integer
example: 1752480000
- name: endDate
in: query
required: false
description: End timestamp in seconds
schema:
type: integer
example: 1752537600
- name: limit
in: query
required: false
description: 'Number of records to return. Default: 100, Maximum: 100'
schema:
type: integer
minimum: 1
maximum: 100
default: 100
example: 100
- name: offset
in: query
required: false
description: 'Number of records to skip. Maximum: 1000000'
schema:
type: integer
minimum: 0
maximum: 1000000
default: 0
example: 0
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
type: object
required:
- fundingTime
- fundingRate
- market
- settlementPrice
- rateCalculatedTime
properties:
fundingTime:
type: string
description: >-
Unix timestamp in seconds when the funding settlement
executed.
example: '1752537600'
fundingRate:
type: string
description: >-
Funding rate applied at the settlement interval. Each
record represents a historical settlement event.
example: '-0.0001229'
market:
type: string
description: Futures market pair name (e.g., `BTC_PERP`).
example: BTC_PERP
settlementPrice:
type: string
description: >-
Mark price in the quote currency at the time of funding
settlement.
example: '119816.5'
rateCalculatedTime:
type: string
description: >-
Unix timestamp in seconds when the funding rate was
calculated. The rate is computed before the actual
settlement.
example: '1752508800'
'422':
description: >-
Validation or upstream error. Field-keyed like the other public
market endpoints, but on this endpoint each validation value is a
single message string (not an array). The upstream-failure case uses
an `error` key with an array value.
content:
application/json:
schema:
type: object
additionalProperties: true
description: >-
Flat field-keyed error. Validation messages (market, limit,
offset, dates) are single strings; the upstream-failure
`error` value is an array of strings.
examples:
invalidMarket:
summary: Unknown or missing market
value:
market: market is required
invalidLimit:
summary: limit out of range
value:
limit: limit must be less than or equal to 100
invalidOffset:
summary: offset out of range
value:
offset: offset must be less than or equal to 1000000
invalidDateRange:
summary: invalid date range
value:
endDate: endDate must be greater than to startDate
upstreamFailure:
summary: Upstream funding-history service failure
value:
error:
- unable to get funding history
````