Skills
skills/okx/agent-skills/okx-cex-market

okx-cex-market

SKILL.md

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

# List all tradeable stock token perpetuals (TSLA, NVDA, AAPL, etc.)
okx market stock-tokens

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
13 okx market stock-tokens READ List all tradeable stock token perpetuals (TSLA, NVDA, AAPL, etc.)

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 stock tokens before trading

User: "I want to trade TSLA or NVDA — what's available?"

1. okx-cex-market   okx market stock-tokens              → list all stock token instIds and specs
        ↓ pick instId (e.g., TSLA-USDT-SWAP)
2. okx-cex-market   okx market ticker TSLA-USDT-SWAP     → current price and 24h range
3. okx-cex-market   okx market instruments --instType SWAP --instId TSLA-USDT-SWAP --json
                    → get ctVal, minSz, lotSz for sz conversion
        ↓ ready to trade — see okx-cex-trade (max leverage: 5x)

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.

Stock Tokens — List All Stock Token Perpetuals

okx market stock-tokens [--json]

Returns: instId, ctVal, lotSz, minSz, tickSz, state for all active stock token SWAP instruments (instCategory=3, e.g., TSLA-USDT-SWAP, NVDA-USDT-SWAP).

Fallback (if command not yet available): okx market instruments --instType SWAP --json | jq '[.[] | select(.instCategory == "3")]' — requires jq installed.

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)

"What stock tokens can I trade?"

okx market stock-tokens
# → table: instId (TSLA-USDT-SWAP, NVDA-USDT-SWAP, AAPL-USDT-SWAP, ...), ctVal, minSz, tickSz, state

"What's the TSLA price?"

okx market ticker TSLA-USDT-SWAP
# → instId: TSLA-USDT-SWAP | last: 310.5 | 24h change %: +2.1% | 24h high: 315 | 24h low: 302

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; Stock token SWAP uses TSLA-USDT-SWAP (identified by instCategory=3)
  • Stock token trading hours: stock tokens follow underlying exchange hours (US stocks: Mon–Fri ~09:30–16:00 ET). Orders outside trading hours may be queued or rejected — confirm a live last price with okx market ticker before trading
  • 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)
Weekly Installs
596
Repository
okx/agent-skills
GitHub Stars
30
First Seen
8 days ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
opencode592
codex591
gemini-cli586
amp585
github-copilot585
kimi-cli585