> For the complete documentation index, see [llms.txt](https://docs.koinju.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.koinju.io/data/funding-rate.md).
# Funding rate
## SQL API
### `api.funding_rate`
Funding-rate history for perpetual swaps across supported exchanges. Markets are exposed under their **universal symbol** (e.g. `BTC-USD-PERP-INV` for the BTC-margined inverse perp, `BTC-USDT-PERP` for the USDT-margined linear), with the originating exchange and contract type recorded alongside the rate. Inverse perps carry an `-INV` suffix to keep them distinct from any linear product with the same `(base, quote)` pair.
The settlement period varies per exchange. Deribit publishes funding **hourly** with continuous accrual; Binance, OKX, and Bybit publish **discrete 8-hour events** (some markets settle every 4h or 1h). Consumers should infer the period from the gap between consecutive timestamps for the same `(exchange, market)` pair.
> The REST `/funding-rate` endpoint requires both `market` and `exchange`. For cross-exchange comparisons in a single query, use the SQL API.
#### Columns
| Column | Type | Description |
| --------------- | ---------------------- | -------------------------------------------------------------------------------- |
| `exchange` | LowCardinality(String) | Exchange that published the funding event (`binance`, `bybit`, `okx`, `deribit`) |
| `contract_type` | LowCardinality(String) | `LINEAR_PERPETUAL` (USDT/USDC-margined) or `INVERSE_PERPETUAL` (coin-margined) |
| `market` | LowCardinality(String) | Universal perpetual symbol (e.g. `BTC-USD-PERP-INV`, `ETH-USDT-PERP`) |
| `timestamp` | DateTime64(9, 'UTC') | Settlement timestamp |
| `funding_rate` | Decimal(76, 20) | Rate that accrued in the period ending at `timestamp` |
### Example Queries
#### 1. Latest BTC-USD-PERP-INV funding across exchanges
```sql
SELECT
timestamp,
exchange,
contract_type,
funding_rate
FROM api.funding_rate
WHERE market = 'BTC-USD-PERP-INV'
AND timestamp >= now() - INTERVAL 24 HOUR
ORDER BY timestamp DESC, exchange ASC
LIMIT 50
```
Functions used: [`now`](https://clickhouse.com/docs/sql-reference/functions/date-time-functions#now).
#### 2. Cross-exchange funding spread
Compare the most recent settled funding rate per exchange for one market:
```sql
SELECT
exchange,
argMax(funding_rate, timestamp) AS last_rate,
max(timestamp) AS last_settled_at
FROM api.funding_rate
WHERE market = 'BTC-USD-PERP-INV'
AND timestamp >= now() - INTERVAL 7 DAY
GROUP BY exchange
ORDER BY last_rate DESC
```
Functions used: [`argMax`](https://clickhouse.com/docs/sql-reference/aggregate-functions/reference/argmax).
#### 3. Realized 24h funding cost on a long position
```sql
SELECT
market,
exchange,
sum(funding_rate) AS realized_24h_funding
FROM api.funding_rate
WHERE timestamp >= now() - INTERVAL 24 HOUR
AND market IN ('BTC-USD-PERP-INV', 'ETH-USD-PERP-INV', 'SOL-USD-PERP-INV')
GROUP BY market, exchange
ORDER BY market, exchange
```
A long pays funding when `funding_rate > 0` and receives it when `funding_rate < 0`. Multiply by position notional to convert to fiat.
## REST API
## Get funding rates for a perpetual market
> Funding-rate history for perpetual swaps across supported exchanges.\
> \
> The settlement period is exchange-specific. Deribit publishes funding\
> hourly (continuous accrual); Binance, OKX, and Bybit publish discrete\
> funding events every 8 hours (sometimes 4h or 1h on select markets).\
> Consumers should infer the period from the gap between consecutive\
> timestamps for the same \`(exchange, market)\` pair.\
> \
> Supported \`exchange\` values: \`binance\`, \`bybit\`, \`okx\`, \`deribit\`.\
> For cross-exchange queries, use the SQL API.\
> \
> This endpoint is limited to 10000 records per request.
```json
{"openapi":"3.1.1","info":{"title":"Koinju Market Data API","version":"1.0.0"},"servers":[{"url":"https://api.koinju.io","description":"Koinju API Server"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Required for /ohlcv and /trade endpoints.\nPass your API key in the x-api-key header.\nPublic /market/* endpoints do not require authentication.\n"}}},"paths":{"/funding-rate":{"get":{"summary":"Get funding rates for a perpetual market","description":"Funding-rate history for perpetual swaps across supported exchanges.\n\nThe settlement period is exchange-specific. Deribit publishes funding\nhourly (continuous accrual); Binance, OKX, and Bybit publish discrete\nfunding events every 8 hours (sometimes 4h or 1h on select markets).\nConsumers should infer the period from the gap between consecutive\ntimestamps for the same `(exchange, market)` pair.\n\nSupported `exchange` values: `binance`, `bybit`, `okx`, `deribit`.\nFor cross-exchange queries, use the SQL API.\n\nThis endpoint is limited to 10000 records per request.\n","tags":["market_data"],"parameters":[{"name":"market","in":"query","required":true,"description":"Koinju canonical perpetual symbol. Inverse perps carry the `-INV`\nsuffix (e.g. `BTC-USD-PERP-INV` for the BTC-margined USD-quoted\nperp); linear perps don't (`BTC-USDT-PERP`). Use `/market/future`\nto enumerate available perpetual symbols.\n","schema":{"type":"string"}},{"name":"exchange","in":"query","required":true,"description":"Exchange to filter by — one of `binance`, `bybit`, `okx`, `deribit`.\nFor cross-exchange queries, use the SQL API.\n","schema":{"type":"string","enum":["binance","bybit","okx","deribit"]}},{"name":"start_datetime","in":"query","required":true,"description":"Window start. Accepts any format parseable by `parseDateTime64BestEffort`\n— e.g. a plain date (`2026-05-01`, treated as midnight UTC) or a full\nISO 8601 timestamp (`2026-05-01T12:00:00Z`).\n","schema":{"type":"string","format":"date-time"}},{"name":"end_datetime","in":"query","required":true,"description":"Window end. Same format as `start_datetime`. Returned rows satisfy\n`start_datetime <= timestamp < end_datetime`.\n","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string","format":"date-time","description":"Settlement timestamp (UTC)"},"exchange":{"type":"string","description":"Exchange that published this funding event"},"market":{"type":"string","description":"Koinju canonical perpetual symbol"},"funding_rate":{"type":"number","format":"decimal","description":"Funding rate that accrued in the period ending at `time`.\nPeriod varies per exchange (8h for Binance/OKX/Bybit, 1h for Deribit).\n"}}}}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.koinju.io/data/funding-rate.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.