okx-cex-market

This skill should be used when the user asks for 'price of BTC', 'ETH ticker', 'show me the orderbook', 'market depth', 'BTC candles', 'OHLCV chart data', 'f...

OKX CEX Market Data CLI

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

Prerequisites

1. Install okx CLI:

   npm install -g @okx_ai/okx-trade-cli
   

2. No credentials needed for market data — all commands are public.
3. Verify install:

   okx market ticker BTC-USDT
   

Demo vs Live Mode

Market data commands are public and read-only — demo mode has no effect. The same data is returned with or without --demo. No confirmation needed before running any market command.

Skill Routing

• For market data (prices, charts, depth, funding rates) → use okx-cex-market (this skill)
• For account balance, P&L, positions, fees, transfers → use okx-cex-portfolio
• For regular spot/swap/futures/algo orders → use okx-cex-trade
• For grid and DCA trading bots → use okx-cex-bot

Quickstart

# Current BTC spot price
okx market ticker BTC-USDT

# All SWAP (perp) tickers
okx market tickers SWAP

# BTC perp order book (top 5 levels each side)
okx market orderbook BTC-USDT-SWAP

# BTC hourly candles (last 20)
okx market candles BTC-USDT --bar 1H --limit 20

# BTC perp current funding rate
okx market funding-rate BTC-USDT-SWAP

# BTC perp funding rate history
okx market funding-rate BTC-USDT-SWAP --history

# Open interest for all SWAP instruments
okx market open-interest --instType SWAP

# List all active SPOT instruments
okx market instruments --instType SPOT

Command Index

#	Command	Type	Description
1	okx market ticker <instId>	READ	Single instrument: last price, 24h high/low/vol
2	okx market tickers <instType>	READ	All tickers for an instrument type
3	okx market instruments --instType <type>	READ	List tradeable instruments
4	okx market orderbook <instId> [--sz <n>]	READ	Order book top asks/bids
5	okx market candles <instId> [--bar] [--limit]	READ	OHLCV candlestick data
6	okx market index-candles <instId> [--bar] [--limit]	READ	Index OHLCV candles
7	okx market funding-rate <instId> [--history]	READ	Current or historical funding rate
8	okx market trades <instId> [--limit <n>]	READ	Recent public trades
9	okx market mark-price --instType <type> [--instId <id>]	READ	Mark price for contracts
10	okx market index-ticker [--instId <id>] [--quoteCcy <ccy>]	READ	Index price (e.g., BTC-USD)
11	okx market price-limit <instId>	READ	Upper/lower price limits for contracts
12	okx market open-interest --instType <type> [--instId <id>]	READ	Open interest in contracts and coins

Cross-Skill Workflows

Check price before placing an order

User: "What's the current BTC price? I want to place a limit buy."

1. okx-cex-market    okx market ticker BTC-USDT              → check last price and 24h range
        ↓ user decides price
2. okx-cex-portfolio okx account balance USDT                → confirm available funds
        ↓ user approves
3. okx-cex-trade     okx spot place --instId BTC-USDT --side buy --ordType limit --px <px> --sz <sz>

Check funding rate before holding a perp position

User: "Is the BTC perp funding rate high right now?"

1. okx-cex-market    okx market funding-rate BTC-USDT-SWAP   → current rate + next funding time
2. okx-cex-market    okx market funding-rate BTC-USDT-SWAP --history  → trend over recent periods
        ↓ decide whether to hold position
3. okx-cex-portfolio okx account positions                   → check existing exposure

Research market before creating a grid bot

User: "I want to set up a BTC grid bot — what's the recent range?"

1. okx-cex-market    okx market candles BTC-USDT --bar 4H --limit 50  → recent OHLCV for range
2. okx-cex-market    okx market ticker BTC-USDT                        → current price
3. okx-cex-market    okx market orderbook BTC-USDT --sz 20             → liquidity check
        ↓ decide minPx / maxPx
4. okx-cex-bot       okx bot grid create --instId BTC-USDT ...

Compare perp vs spot premium

User: "Is there a premium between BTC spot and BTC perp?"

1. okx-cex-market    okx market ticker BTC-USDT              → spot last price
2. okx-cex-market    okx market ticker BTC-USDT-SWAP         → perp last price
3. okx-cex-market    okx market mark-price --instType SWAP --instId BTC-USDT-SWAP  → mark price

Discover and price an option

User: "What's the price of a BTC call option expiring this week?"

1. okx-cex-market    okx market open-interest --instType OPTION --instId BTC-USD  → list active option instIds
        ↓ pick target instId from the list (e.g., BTC-USD-250328-95000-C)
2. okx-cex-market    okx market ticker BTC-USD-250328-95000-C → option last price and stats
3. okx-cex-market    okx market orderbook BTC-USD-250328-95000-C → bid/ask spread

Note: okx market instruments --instType OPTION requires --uly <underlying> (e.g., --uly BTC-USD). If the underlying is unknown, use open-interest first to discover active option instIds.

Operation Flow

Step 1: Identify the data needed

• Current price → okx market ticker
• All prices for a category → okx market tickers
• Order book depth → okx market orderbook
• Price history/chart → okx market candles
• Funding cost → okx market funding-rate
• Contract valuation → okx market mark-price or okx market price-limit
• Market volume/OI → okx market open-interest
• What instruments exist → okx market instruments

Step 2: Run commands immediately

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

• --instType values: SPOT, SWAP, FUTURES, OPTION
• --bar values: 1m, 3m, 5m, 15m, 30m, 1H, 2H, 4H, 6H, 12H, 1D, 1W, 1M
• --limit: number of results (default varies per endpoint, typically 100)
• --history: for funding-rate, returns historical records instead of current rate

Step 3: No writes — no verification needed

All commands in this skill are read-only. No post-execution verification required.

CLI Command Reference

Ticker — Single Instrument

okx market ticker <instId> [--json]

Returns: last, 24h high/low, 24h volume, sodUtc8 (24h change %).

---

Tickers — All Instruments of a Type

okx market tickers <instType> [--json]

Param	Required	Values	Description
instType	Yes	SPOT, SWAP, FUTURES, OPTION	Instrument type

Returns table: instId, last, high24h, low24h, vol24h.

---

Instruments — List Tradeable Instruments

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

Param	Required	Default	Description
--instType	Yes	-	SPOT, SWAP, FUTURES, OPTION
--instId	No	-	Filter to a single instrument

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

---

Order Book

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

Param	Required	Default	Description
instId	Yes	-	Instrument ID (e.g., BTC-USDT-SWAP)
--sz	No	5	Depth levels per side (1–400)

Displays top 5 asks (ascending) and bids (descending) with price and size.

---

Candles — OHLCV

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

Param	Required	Default	Description
instId	Yes	-	Instrument ID
--bar	No	1m	Time granularity (1m, 1H, 4H, 1D, etc.)
--limit	No	100	Number of candles to return

Returns columns: time, open, high, low, close, vol.

---

Index Candles

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

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

---

Funding Rate

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

Param	Required	Default	Description
instId	Yes	-	SWAP instrument (e.g., BTC-USDT-SWAP)
--history	No	false	Return historical funding rates
--limit	No	-	Number of historical records

Current (no --history): returns fundingRate, nextFundingRate, fundingTime, nextFundingTime. Historical (--history): table with fundingRate, realizedRate, fundingTime.

---

Recent Trades

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

Returns: tradeId, px, sz, side, ts.

---

Mark Price

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

Returns: instId, instType, markPx, ts. Used for liquidation price calculation and contract valuation.

---

Index Ticker

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

Param	Required	Default	Description
--instId	Cond.	-	Index ID (e.g., BTC-USD)
--quoteCcy	Cond.	-	Filter by quote currency (e.g., USD, USDT)

Returns: idxPx, high24h, low24h.

---

Price Limit

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

Returns: buyLmt (max buy price), sellLmt (min sell price). Applies to SWAP and FUTURES only.

---

Open Interest

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

Returns: oi (contracts), oiCcy (base currency amount), ts.

---

MCP Tool Reference

Tool	Description
market_get_ticker	Single instrument ticker
market_get_tickers	All tickers for instType
market_get_instruments	List instruments
market_get_orderbook	Order book depth
market_get_candles	OHLCV candles
market_get_index_candles	Index OHLCV candles
market_get_funding_rate	Funding rate (current or history)
market_get_trades	Recent public trades
market_get_mark_price	Mark price for contracts
market_get_index_ticker	Index price ticker
market_get_price_limit	Price limits for contracts
market_get_open_interest	Open interest

---

Input / Output Examples

"What's the price of BTC?"

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

"Show me all SWAP tickers"

okx market tickers SWAP
# → table of all perpetual contracts with last price, 24h high/low/vol

"What's the BTC/USDT order book look like?"

okx market orderbook BTC-USDT
# Asks (price / size):
#          95100.0  2.5
#          95050.0  1.2
# Bids (price / size):
#          95000.0  3.1
#          94950.0  0.8

"Show me BTC 4H candles for the last 30 periods"

okx market candles BTC-USDT --bar 4H --limit 30
# → table: time, open, high, low, close, vol

"What's the current funding rate for BTC perp?"

okx market funding-rate BTC-USDT-SWAP
# → fundingRate: 0.0001 | nextFundingRate: 0.00012 | fundingTime: ... | nextFundingTime: ...

"Show historical funding rates for ETH perp"

okx market funding-rate ETH-USDT-SWAP --history --limit 20
# → table: fundingRate, realizedRate, fundingTime

"What's the open interest on BTC perp?"

okx market open-interest --instType SWAP --instId BTC-USDT-SWAP
# → oi: 125000 | oiCcy: 125000 | ts: ...

"List all available SPOT instruments"

okx market instruments --instType SPOT
# → table: instId, ctVal, lotSz, minSz, tickSz, state (up to 50 rows)

Edge Cases

• instId format: SPOT uses BTC-USDT; SWAP uses BTC-USDT-SWAP; FUTURES uses BTC-USDT-250328; OPTION uses BTC-USD-250328-95000-C; Index uses BTC-USD
• OPTION instruments — cannot list directly: okx market instruments --instType OPTION requires --uly BTC-USD (underlying). If the underlying is unknown, run okx market open-interest --instType OPTION first to discover active option instIds from the results, then use those instIds with okx market ticker <instId>
• No data returned: instrument may be delisted or instId is wrong — verify with okx market instruments
• funding-rate: only applies to SWAP instruments; returns error for SPOT/FUTURES
• price-limit: only applies to SWAP and FUTURES instruments
• mark-price: available for SWAP, FUTURES, OPTION; not applicable to SPOT
• candles --bar: use uppercase H, D, W, M for hour/day/week/month (e.g., 1H not 1h)
• index-ticker: use BTC-USD format (not BTC-USDT) for index IDs
• orderbook --sz: max depth is 400; default display shows top 5 per side regardless of --sz

Global Notes

• All market data commands are public — no API key required
• --json returns raw OKX API v5 response for programmatic use
• --profile <name> has no effect on market commands (no auth needed)
• Rate limit: 20 requests per 2 seconds per IP for market data endpoints
• Candle data is sorted newest-first by default
• vol24h in tickers is in base currency (e.g., BTC for BTC-USDT)