# Funding rate

## SQL API

### `api.funding_rate`

Funding-rate history for perpetual swaps across supported exchanges. Markets are exposed under their **Koinju canonical symbol** (e.g. `BTC-USD-PERP`), with the originating exchange and contract type recorded alongside the rate.

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) | Koinju canonical perpetual symbol (e.g. `BTC-USD-PERP`, `ETH-USDT-PERP`)         |
| `timestamp`     | DateTime64(9, 'UTC')   | Settlement timestamp                                                             |
| `funding_rate`  | Decimal(76, 20)        | Rate that accrued in the period ending at `timestamp`                            |

#### Example: latest BTC-USD-PERP funding across exchanges

```sql
SELECT
    timestamp,
    exchange,
    contract_type,
    funding_rate
FROM api.funding_rate
WHERE market = 'BTC-USD-PERP'
  AND timestamp >= now() - INTERVAL 24 HOUR
ORDER BY timestamp DESC, exchange ASC
LIMIT 50
```

#### Example: 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'
  AND timestamp >= now() - INTERVAL 7 DAY
GROUP BY exchange
ORDER BY last_rate DESC
```

#### Example: 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', 'ETH-USD-PERP', 'SOL-USD-PERP')
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, e.g. `BTC-USD-PERP`, `ETH-USDT-PERP`.\nUse `/market/future` to 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 in ISO 8601 (e.g. `2026-05-01T00:00:00Z`) or any format\nparseable by `parseDateTime64BestEffort`.\n","schema":{"type":"string","format":"date-time"}},{"name":"end_datetime","in":"query","required":true,"description":"Window end in ISO 8601. 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: 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=<question>
```

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.