# Derivatives & Contract Data Commands

These commands apply to SWAP, FUTURES, and/or OPTION instruments. Not applicable to SPOT unless noted.

---

## funding-rate — Funding Rate

```bash
okx market funding-rate <instId> [--history] [--limit <n>] [--json]
```

| Param | Required | Default | Description |
|---|---|---|---|
| `instId` | Yes | - | Perpetual swap instrument ID, **must end with `-SWAP`** (e.g., `BTC-USDT-SWAP`). Spot IDs like `BTC-USDT` will be rejected. |
| `--history` | No | false | Return historical funding rates |
| `--limit` | No | 100 | Number of historical records (only with `--history`) |

**Current rate** (no `--history`):
Returns: `fundingRate` · `nextFundingRate` · `fundingTime` · `nextFundingTime`

**Historical** (`--history`):
Returns table: `fundingRate` · `realizedRate` · `fundingTime`

```bash
okx market funding-rate BTC-USDT-SWAP
okx market funding-rate BTC-USDT-SWAP --history --limit 10
```

> **IMPORTANT**: `instId` must end with `-SWAP` (e.g., `BTC-USDT-SWAP`). Spot IDs like `BTC-USDT` are **NOT** valid and will be rejected. Funding rate applies only to perpetual swap instruments.

---

## mark-price — Mark Price

```bash
okx market mark-price --instType <type> [--instId <id>] [--json]
```

| Param | Required | Values |
|---|---|---|
| `--instType` | Yes | `SWAP` `FUTURES` `OPTION` |
| `--instId` | No | Filter to a single instrument |

Returns: `instId` · `instType` · `markPx` · `ts`

Used for liquidation price calculation and contract fair-value reference.

```bash
okx market mark-price --instType SWAP --instId BTC-USDT-SWAP
okx market mark-price --instType FUTURES
```

---

## price-limit — Upper / Lower Price Limits

```bash
okx market price-limit <instId> [--json]
```

Returns: `buyLmt` (max buy price) · `sellLmt` (min sell price)

Applies to SWAP and FUTURES only. Used to check whether a limit order price is within allowed range.

```bash
okx market price-limit BTC-USDT-SWAP
```

---

## open-interest — Open Interest

```bash
okx market open-interest --instType <type> [--instId <id>] [--json]
```

| Param | Required | Values |
|---|---|---|
| `--instType` | Yes | `SWAP` `FUTURES` `OPTION` |
| `--instId` | No | Filter to a single instrument |

Returns: `instId` · `oi` (contracts) · `oiCcy` (base currency amount) · `ts`

```bash
okx market open-interest --instType SWAP --instId BTC-USDT-SWAP
okx market open-interest --instType SWAP
```

> For OPTION: use `--instId BTC-USD` (underlying, not a specific strike/expiry) to list all active option series OI.

---

## index-ticker — Index Price

```bash
okx market index-ticker [--instId <id>] [--quoteCcy <ccy>] [--json]
```

| Param | Required | Default | Description |
|---|---|---|---|
| `--instId` | Cond. | - | Index ID (e.g., `BTC-USD`). Either this or `--quoteCcy` required. |
| `--quoteCcy` | Cond. | - | Filter all indices by quote currency (e.g., `USD`, `USDT`) |

Returns: `instId` · `idxPx` · `high24h` · `low24h`

> Use `BTC-USD` format for index IDs (not `BTC-USDT`).

```bash
okx market index-ticker --instId BTC-USD
okx market index-ticker --quoteCcy USD
```

## Pair Spread

`okx market pair-spread` — spread statistics between two instruments.

| Param | Required | Default | Description |
|---|---|---|---|
| `<instIdA>` | Yes | - | First instrument (positional), e.g. `BTC-USDT-SWAP` |
| `<instIdB>` | Yes | - | Second instrument (positional); must differ from instIdA |
| `--bar` | No | `15m` | Bar size: `5m` or `15m` (1m not supported) |
| `--window` | No | `1W` | Lookback window. Format `<n><unit>`, units m/H/D/W (case-sensitive), max 1W |
| `--backtest-time` | No | - | Anchor timestamp (ms epoch) for backtest mode; omits realtime block |

Returns: `mode` · `realtime` (lastPriceA/B, spreadAbs, spreadRatio) · `statistics` (absolute + ratio: mean/stdDev/median/min/max) · `meta` (requestedBars, alignedBars, droppedBars, truncated)

```bash
# Live spread between two perpetuals, default bar=15m, window=1W
okx market pair-spread BTC-USDT-SWAP ETH-USDT-SWAP

# Tight window for fast mean-reversion setups
okx market pair-spread BTC-USDT-SWAP BTC-USDT --bar 5m --window 4H

# Backtest anchor (ms epoch). When set, realtime block is omitted.
okx market pair-spread BTC-USDT-SWAP ETH-USDT-SWAP --bar 15m --window 1D --backtest-time 1715000000000 --json
```

> Constraints: bar must be 5m or 15m; window ≤ 1W (units case-sensitive: m/H/D/W); requires ≥80% bar coverage (otherwise returns error 41020).

> **Demo market data**: All commands above support `--demo` (CLI) or `demo: true` (MCP) to query OKX's simulated trading market data. Default is live data.