Okx Cex Market

OKX CEX Market Data CLI

Compliance notice: This skill provides raw market data only. No strategy, recommendation, or optimization logic is embedded. All indicator outputs are objective numerical values; interpretation and trading decisions remain solely with the user.

Public market data for OKX: prices, order books, candles, funding rates, open interest, instrument info, and technical indicators. All commands are read-only and require no API credentials.

Skill routing

• Market data / indicators → okx-cex-market (this skill)
• Account balance / positions → okx-cex-portfolio
• Place / cancel orders → okx-cex-trade
• Grid / DCA bots → okx-cex-bot

Preflight

Before running any command, follow `../_shared/preflight.md`. Use metadata.version from this file's frontmatter as the reference for Step 2.

Install

npm install -g @okx_ai/okx-trade-cli
okx market ticker BTC-USDT   # verify

Market data commands return the same public data regardless of demo/live mode — no API credentials required. If the user's profile has demo=true set and they want live data context, they can use --live to confirm they are in live mode (it has no effect on public market data but clarifies environment). Always inform the user which environment is active (demo or live) when it is relevant to their query. No confirmation needed before running any market command. Add --json to any command for raw OKX API v5 response. Add --env to wrap the output as {"env", "profile", "data"}.

---

Command Index

---

Operation Flow

Step 1 — Identify data type and load reference

Step 2 — Run commands immediately

All market data commands are read-only — no confirmation needed.

Step 3 — No writes, no verification needed

All commands in this skill are read-only.

---

Edge Cases

• instId format: SPOT BTC-USDT · SWAP BTC-USDT-SWAP · FUTURES BTC-USDT-250328 · OPTION BTC-USD-250328-95000-C · Index BTC-USD · Stock token TSLA-USDT-SWAP · Metals/Commodities/Forex/Bonds: use instruments-by-category to discover valid instIds first
• OPTION listing: instruments --instType OPTION requires --uly BTC-USD; if unknown, run open-interest --instType OPTION first to discover active instIds
• funding-rate / price-limit: SWAP only · mark-price: SWAP / FUTURES / OPTION only
• candles `--bar`: uppercase — 1H not 1h; use --after <ts> to paginate back into historical data (back to 2021); index-candles supports --history for extended history
• ⚠️ Large historical range: before fetching with --after/--before, estimate candle count = time_range_ms / bar_interval_ms. If estimate > 500, tell the user the estimated count and ask for confirmation before proceeding. This prevents silently filling the context window.
• indicator `--bar`: uses 1Dutc not 1D, 1Wutc not 1W — different from candle bar values
• `market filter` sortBy values: last chg24hPct marketCapUsd volUsd24h fundingRate oiUsd listTime — default volUsd24h
• `market filter` ctType: linear or inverse (SWAP/FUTURES only); omit for SPOT
• `market filter` quoteCcy: comma-separated list supported, e.g. --quoteCcy USDT,USDC
• `market filter` SPOT + quoteCcy: when --instType SPOT, the API returns instruments across all quote currencies (USDT, USDC, BTC, ETH, etc.) mixed together — this pollutes sort order and bloats results. Always pass --quoteCcy USDT by default unless the user explicitly asks for other quote currencies.
• `market filter` chg24hPct: value is a percentage number — --minChg24hPct -5 means -5%, --maxChg24hPct 10 means 10%
• `market oi-history` ts: Unix ms timestamp; returns bars with ts ≤ this value for historical pagination
• `market oi-history` / `oi-change` bar: valid values 5m 15m 1H 4H 1D — default 1H. Server accepts case variants (1h == 1H) but prefer canonical casing.
• `market oi-history` limit: 1–500 (default 50)
• `market oi-change` instType: only SWAP or FUTURES supported (not SPOT)
• `market oi-change` minAbsOiDeltaPct: filters by absolute OI change — 1.0 keeps only rows where |oiDeltaPct| ≥ 1%
• `market oi-change` sortBy values: oiUsd oiDeltaUsd oiDeltaPct absOiDeltaPct volUsd24h fundingRate last — default oiDeltaPct (signed). Use absOiDeltaPct to rank by |oiDeltaPct| (largest magnitude regardless of direction).
• `market oi-change` limit: 1–100 (default 20). For deeper than 100 rows, fetch oi-history per instId.
• indicator `--bar` valid values: 3m 5m 15m 1H 4H 12Hutc 1Dutc 3Dutc 1Wutc — 1m is not supported for indicators (use candles for 1-minute data)
• indicator `--limit`: 1–100 (only used with returnList, i.e. when a historical series is requested)
• indicator arg order: indicator name before instId — okx market indicator rsi BTC-USDT
• indicator `--params`: comma-separated, no spaces — --params 5,20
• BTC-only indicators: ahr999, rainbow — BTC-USDT only
• Unknown indicator name: returns a ValidationError with similar-name suggestions before the API is called — use market_list_indicators / okx market indicator list to see all valid names
• Stock token hours: US stocks trade Mon–Fri ~09:30–16:00 ET; verify live price before acting
• No data returned: instrument may be delisted — verify with okx market instruments
• `boll` is an alias for bb

Global Notes

• No API key required for any command in this skill
• Rate limit: 20 req / 2 s per IP
• Candle data is sorted newest-first
• vol24h is in base currency (e.g., BTC for BTC-USDT)
• --demo/--live and --profile do not affect market data results via CLI (public endpoints); they only determine the active trading environment context

Derivatives & Contract Data Commands

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

---

funding-rate — Funding Rate

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

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

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

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

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

Returns: instId · instType · markPx · ts

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

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

---

price-limit — Upper / Lower Price Limits

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.

okx market price-limit BTC-USDT-SWAP

---

open-interest — Open Interest

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

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

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

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

Returns: instId · idxPx · high24h · low24h

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

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

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.

Technical Indicator Command Reference

Discover Supported Indicators

okx market indicator list          # print all supported indicator names and descriptions
okx market indicator list --json   # machine-readable format

Use this before calling market_get_indicator (MCP) or okx market indicator (CLI) to confirm a name is supported. The API returns empty data silently for unknown indicator names.

---

Command Syntax

okx market indicator <indicator> <instId> [--bar <bar>] [--params <n1,n2,...>] [--list] [--limit <n>] [--backtest-time <ms>] [--json]

Argument order: <indicator> comes before <instId> — e.g., okx market indicator rsi BTC-USDT, not the reverse.

--bar Supported Values

3m 5m 15m 1H 4H 12Hutc 1Dutc 3Dutc 1Wutc

These differ from candle --bar values: daily is 1Dutc not 1D, weekly is 1Wutc not 1W.

---

Supported Indicators

Run okx market indicator list for the authoritative full list. Common indicators by category:

boll is accepted as an alias for bb.

BTC On-Chain indicators only work with BTC-USDT; applying to other assets returns no data.

---

Return Fields

All indicators return ts (Unix ms timestamp) plus indicator-specific fields:

---

Examples

# Discover all supported indicator names first
okx market indicator list

# Latest RSI on 4H
okx market indicator rsi BTC-USDT --bar 4H --params 14

# EMA 5 and EMA 20 trend check on 1H
okx market indicator ema BTC-USDT --bar 1H --params 5,20
# ts: 3/20/2026, 10:00 AM | ema5: 87420.5 | ema20: 86910.2

# MACD on daily
okx market indicator macd BTC-USDT --bar 1Dutc

# Bollinger Bands on 1H
okx market indicator bb ETH-USDT --bar 1H
# upper: 2050 | middle: 2000 | lower: 1950

# SuperTrend direction signal
okx market indicator supertrend BTC-USDT --bar 4H
# supertrend: 84200 | direction: buy

# Historical RSI series (last 20 values)
okx market indicator rsi ETH-USDT --bar 1H --params 14 --list --limit 20
# → table: ts, rsi (20 rows, newest first)

# BTC on-chain cycle check
okx market indicator ahr999 BTC-USDT
# ahr999: 0.87  (DCA zone: 0.45–1.2)

okx market indicator rainbow BTC-USDT
# band: "HODL"

# Backtesting point-in-time value
okx market indicator rsi BTC-USDT --bar 4H --params 14 --backtest-time 1711008000000

---

BTC On-Chain Interpretation Guide

Instrument Discovery Commands

instruments — List Tradeable Instruments

okx market instruments --instType <type> [--instId <id>] [--json]

Returns: instId · ctVal · lotSz · minSz · tickSz · state. Displays up to 50 rows.

okx market instruments --instType SPOT
okx market instruments --instType SWAP --instId BTC-USDT-SWAP --json
okx market instruments --instType OPTION --uly BTC-USD

OPTION instruments cannot be listed without `--uly`. If the underlying is unknown, use open-interest --instType OPTION first to discover active instIds, then query instruments with the known underlying.

---

stock-tokens — List All Stock Token Perpetuals (Deprecated)

Deprecated: use okx market instruments-by-category --instCategory 3 instead. This command is kept for backward compatibility and will be removed in a future major version.

okx market stock-tokens [--json]

Returns: instId · ctVal · lotSz · minSz · tickSz · state for all active stock token SWAP instruments (instCategory=3).

Examples: TSLA-USDT-SWAP, NVDA-USDT-SWAP, AAPL-USDT-SWAP, MSFT-USDT-SWAP

okx market stock-tokens

Fallback (if command not yet available):

```bash

okx market instruments --instType SWAP --json | jq '[.[] | select(.instCategory == "3")]'

```

Requires jq installed.

---

instruments-by-category — Discover Metals, Commodities, Forex, and Bond Instruments

OKX supports non-crypto asset categories distinguished by the instCategory field:

okx market instruments-by-category --instCategory <3|4|5|6|7> [--instType <SPOT|SWAP>] [--instId <id>] [--json]

Returns: instId · instCategory · ctVal · lotSz · minSz · tickSz · state.

# Discover stock token perpetuals (replaces the deprecated stock-tokens command)
okx market instruments-by-category --instCategory 3

# Discover all gold/silver instruments
okx market instruments-by-category --instCategory 4

# Discover all forex perpetuals
okx market instruments-by-category --instCategory 6

# Discover commodities
okx market instruments-by-category --instCategory 5

# Inspect a specific bond instrument
okx market instruments-by-category --instCategory 7 --instId US30Y-USDT-SWAP --json

Fallback (if command not yet available):

```bash

okx market instruments --instType SWAP --json | jq '[.[] | select(.instCategory == "3")]'

```

Replace "3" with "4", "5", "6", or "7" as needed. Requires jq installed.

Discovery workflow: always run instruments-by-category first to get valid instIds, then use ticker / orderbook / candles to get price data.

Trading Hours Notes

• Forex (category 6): follows FX market hours (Mon 00:00 – Fri 22:00 UTC, closed weekends)
• Metals (category 4): generally trades with FX hours; verify with ticker before placing orders
• Commodities (category 5): session-based hours; check state=live in instruments list
• Bonds (category 7): US bond instruments follow US market hours

Always run okx market ticker <instId> to confirm a live last price before placing any order on these instruments.

---

Notes

• ctVal — contract value (e.g., 0.01 BTC per contract for BTC-USDT-SWAP). Required for sz ↔ coin quantity conversion.
• lotSz — order size increment. sz must be a multiple of lotSz.
• minSz — minimum order size.
• tickSz — minimum price increment.
• state — live means currently tradeable.

Stock Token Trading Hours

Stock tokens follow underlying exchange hours:

• US stocks (TSLA, NVDA, AAPL, etc.): Mon–Fri ~09:30–16:00 ET
• Orders outside trading hours may be queued or rejected

Always run okx market ticker <instId> to confirm a live last price before placing any stock token order.

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.

Price & Market Data Commands

ticker — Single Instrument

okx market ticker <instId> [--json]

Returns: last · high24h · low24h · vol24h (base currency) · sodUtc8 (24h change %)

okx market ticker BTC-USDT
# instId: BTC-USDT | last: 95000.5 | 24h change%: +1.2% | high: 96000 | low: 93000

---

tickers — All Instruments of a Type

okx market tickers <instType> [--json]

Returns table: instId · last · high24h · low24h · vol24h

okx market tickers SWAP
# → table of all perpetual contracts

---

orderbook — Order Book Depth

okx market orderbook <instId> [--sz <n>] [--json]

Returns: top asks (ascending) and bids (descending) with price and size. Display shows top 5 per side regardless of --sz.

okx market orderbook BTC-USDT-SWAP --sz 20
# Asks: 95100.0 / 2.5 · 95050.0 / 1.2 ...
# Bids: 95000.0 / 3.1 · 94950.0 / 0.8 ...

---

trades — Recent Public Trades

okx market trades <instId> [--limit <n>] [--json]

Returns: tradeId · px · sz · side (buy/sell) · ts

okx market trades BTC-USDT --limit 20

---

candles — OHLCV Candlestick Data

okx market candles <instId> [--bar <bar>] [--limit <n>] [--after <ts>] [--before <ts>] [--json]

--bar values: 1m 3m 5m 15m 30m 1H 2H 4H 6H 12H 1D 1W 1M

Use uppercase for hour/day/week/month — 1H not 1h.

The command automatically routes to the historical endpoint when --after is older than ~2 days, supporting data back to 2021.

OKX API pagination direction: --after <ts> returns candles with timestamp earlier than ts (go further back in time). --before <ts> returns candles with timestamp later than ts (go toward the present).

Returns columns: time · open · high · low · close · vol (base currency). Sorted newest-first.

okx market candles BTC-USDT --bar 4H --limit 30
okx market candles ETH-USDT-SWAP --bar 1H --limit 100
okx market candles BTC-USDT --bar 1D --after 1672531200000   # candles before 2023-01-01

---

index-candles — Index OHLCV

okx market index-candles <instId> [--bar <bar>] [--limit <n>] [--history] [--json]

Same params as candles. Use index instrument IDs: BTC-USD (not BTC-USDT).

--history: return historical candles beyond the default 1440-candle window.

Returns: same columns as candles.

okx market index-candles BTC-USD --bar 1Dutc --limit 50
okx market index-candles BTC-USD --bar 1Wutc --history --limit 200

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.

Cross-Skill Workflows & MCP Tool Reference

Cross-Skill Workflows

All market commands are read-only. Decisions and order placement remain with the user.

---

Price lookup before order placement

okx market ticker BTC-USDT                    → last price, 24h range
okx-cex-portfolio: okx account balance USDT   → available funds
okx-cex-trade: okx spot place ...             → user decides px/sz

---

Funding rate analysis for perp positions

okx market funding-rate BTC-USDT-SWAP          → current rate + next funding time
okx market funding-rate BTC-USDT-SWAP --history --limit 10  → recent trend
okx-cex-portfolio: okx account positions       → check existing exposure

---

Market data lookup before grid bot setup

okx market candles BTC-USDT --bar 4H --limit 50   → recent OHLCV for range estimation
okx market ticker BTC-USDT                         → current price
okx market orderbook BTC-USDT --sz 20              → liquidity check
okx-cex-bot: okx bot grid create ...               → user decides minPx/maxPx

---

Spot vs perp price comparison (premium check)

okx market ticker BTC-USDT
okx market ticker BTC-USDT-SWAP
okx market mark-price --instType SWAP --instId BTC-USDT-SWAP

---

Non-crypto asset discovery before trading (Metals / Commodities / Forex / Bonds)

# Step 1 — discover valid instIds for the asset class
okx market instruments-by-category --instCategory 4   → Metals: find XAUUSDT-USDT-SWAP, XAGUSDT-USDT-SWAP
okx market instruments-by-category --instCategory 5   → Commodities: find OIL-USDT-SWAP, GAS-USDT-SWAP
okx market instruments-by-category --instCategory 6   → Forex: find EURUSDT-USDT-SWAP, GBPUSDT-USDT-SWAP
okx market instruments-by-category --instCategory 7   → Bonds: find US30Y-USDT-SWAP

# Step 2 — verify live price and check trading session is open
okx market ticker XAUUSDT-USDT-SWAP                   → last price, 24h range (state must show active)
okx market orderbook XAUUSDT-USDT-SWAP                → bid/ask spread and liquidity

# Step 3 — get instrument specs for order sizing
okx market instruments --instType SWAP --instId XAUUSDT-USDT-SWAP --json
                                                       → ctVal, minSz, lotSz for quantity conversion

# okx-cex-trade: user places order after confirming market is open

Important: non-crypto instruments have trading-hour restrictions. Always confirm state=live in the instruments response and a non-zero last price in ticker before proceeding to order placement.

---

Stock token discovery before trading

okx market instruments-by-category --instCategory 3            → list instIds and specs (preferred)
okx market ticker TSLA-USDT-SWAP                               → current price and 24h range
okx market instruments --instType SWAP --instId TSLA-USDT-SWAP --json
                                                                → ctVal, minSz, lotSz for sz conversion

okx market stock-tokens is deprecated — use instruments-by-category --instCategory 3 instead.

---

Option discovery and pricing

okx market open-interest --instType OPTION --instId BTC-USD    → find active option instIds
okx market ticker BTC-USD-250328-95000-C                       → option last price and stats
okx market orderbook BTC-USD-250328-95000-C                    → bid/ask spread

---

Multi-indicator trend analysis

Run in parallel — no ordering dependency:

okx market indicator ema BTC-USDT --bar 4H --params 5,20       → EMA5 vs EMA20 alignment
okx market indicator macd BTC-USDT --bar 4H                    → MACD histogram + DIF/DEA cross
okx market indicator rsi BTC-USDT --bar 4H --params 14         → RSI overbought/oversold
okx market indicator bb BTC-USDT --bar 4H                      → Bollinger Bands position
okx market indicator supertrend BTC-USDT --bar 4H              → direction signal (buy/sell)

---

BTC macro cycle analysis

Run in parallel — no ordering dependency:

okx market indicator ahr999 BTC-USDT    → accumulate / DCA / bubble zone
okx market indicator rainbow BTC-USDT   → Rainbow Chart valuation band

---

MCP Tool Reference

When using MCP tools directly (instead of CLI), the tool names map as follows:

`demo` parameter (MCP only): All market MCP tools (except market_list_indicators and market_get_indicator) accept an optional demo: true parameter to query OKX's simulated trading market data environment. Default is false (live data). CLI equivalent: --demo global flag.