> 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.<br>

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