OKX Market Guard
Provides read-only access to OKX public market data, enabling AI agents to retrieve tickers, OHLCV candles, funding rates, and open interest, and to perform stateless threshold-based market alerts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OKX Market Guard check whether BTC-USDT is above 100000 and show the 24h change"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OKX Market Guard
Read-only OKX public market data for AI agents. Ships as an MCP server (stdio, JSON-RPC 2.0) and a CLI. Zero runtime npm dependencies. TypeScript source runs directly on Node 22.6+ / Node 24 (type stripping).
Safety first. This project talks only to official OKX public market REST endpoints on
https://www.okx.com. It has no API key, cannot place or cancel orders, cannot withdraw, and cannot read account or wallet data. Alerts are stateless threshold checks — nothing is stored, nothing is pushed.
Tools
Tool | What it does | OKX endpoint (public GET) |
| Latest ticker + 24h change % + spread % |
|
| OHLCV candles, newest first, |
|
| Current funding rate for a perpetual ( |
|
| Open interest by |
|
| One-shot threshold vs latest data (stateless) | same public endpoints |
alert_check metrics: last, changePercent24h, high24h, low24h, bidAskSpreadPct, fundingRate (SWAP only), openInterest (SWAP/FUTURES). Operators: gt, gte, lt, lte.
Related MCP server: aster-agent-gateway
Safety rails
Host + path allowlist. Only
https://www.okx.comand the five public paths above (plus/api/v5/public/time). Private/trade/account paths are rejected in-process, before any HTTP.No credentials, ever. Passing
apiKey/secret/passphrase/tokenas options throws. Requests carry noAuthorizationheader.redirect: 'error'blocks redirect-based SSRF.Read-only MCP annotations. Every tool advertises
readOnlyHint: true,destructiveHint: false.Input validation. instId shape, bar enum, limit range, extra-key rejection, SWAP-required checks for funding.
Rate limit. Token bucket, default 8 req/s, burst 16 (OKX public limits are ~20 req / 2 s per IP).
Friendly OKX errors. Envelope
code !== '0'becomes a message with a hint (wrong instId type, rate limit, timeout, DNS/proxy).Stateless alerts.
alert_checkcompares one number to one threshold and returns. No watchlists, no notifications, no writes.
Quick start
Node.js >= 22.6 (24 recommended). No npm install needed.
node src/cli.ts --help
node src/cli.ts ticker BTC-USDT --pretty
node src/cli.ts candles BTC-USDT --bar 1H --limit 24 --pretty
node src/cli.ts funding BTC-USDT-SWAP --pretty
node src/cli.ts oi BTC-USDT-SWAP --pretty
node src/cli.ts alert BTC-USDT --metric last --op gt --threshold 100000 --prettyIf your network cannot resolve www.okx.com directly (common behind a firewall), restart Node with the built-in proxy flag before the process starts:
# Windows PowerShell
$env:NODE_USE_ENV_PROXY = "1"
$env:HTTPS_PROXY = "http://127.0.0.1:7890" # your local proxy
node src/cli.ts ticker BTC-USDT --pretty# macOS / Linux
NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://127.0.0.1:7890 node src/cli.ts ticker BTC-USDT --prettyNODE_USE_ENV_PROXY is only read at Node bootstrap; setting it inside the script is too late. --env-file=.env does not apply it.
MCP client config
Point any MCP client at the stdio server:
{
"mcpServers": {
"okx-market-guard": {
"command": "node",
"args": ["<absolute-path>/src/cli.ts", "serve"],
"env": {
"NODE_USE_ENV_PROXY": "1",
"HTTPS_PROXY": "http://127.0.0.1:7890"
}
}
}
}Protocol: newline-delimited JSON-RPC 2.0 on stdio. Advertises 2025-06-18 (also accepts 2025-03-26, 2024-11-05). Logs go to stderr; JSON-RPC goes to stdout.
Tests
npm test # unit tests (mocked fetch) + live tests (skip if OKX unreachable)Live tests hit real public endpoints with BTC-USDT / BTC-USDT-SWAP. Force-skip them with OKX_SKIP_LIVE=1.
Demo (real REST, prints a full transcript):
node demo/demo.ts
# transcript of a recent run: docs/demo-output.txtLayout
src/
okx-client.ts allowlisted public REST client
tools/index.ts the five tools
mcp/server.ts JSON-RPC 2.0 stdio server
cli.ts CLI + serve
validate.ts input validation
ratelimit.ts token bucket + credential guard
errors.ts friendly errors
test/ node:test unit + live
demo/demo.ts live demo
docs/ demo transcript, AI Builder application draftWhat this is not
Not a trading bot. Not a key manager. Not a WebSocket feed. Not a mirror of okx.com.
Application to OKX AI Builder is a draft only (
docs/); submitting it is a human action via the official App (Menu → Builder) or okx.com. Do not use mirror/help domains.
License
MIT
Available Tools
5 toolsalert_checkAlert check (stateless, read-only)ARead-onlyIdempotent
Evaluate a one-shot threshold against the latest OKX public market data. No persistent alerts, no notifications, no writes. READ-ONLY: this tool only calls OKX public market REST. No API key, no order, no account access. Metrics last/high24h/low24h/changePercent24h/bidAskSpreadPct use the ticker; fundingRate needs a -SWAP instId; openInterest needs SWAP or FUTURES.
Inputs: op (required), instId (required), metric (required), threshold (required).
funding_rateFunding rateARead-onlyIdempotent
Get the current OKX public funding rate for a perpetual swap. READ-ONLY: this tool only calls OKX public market REST. No API key, no order, no account access. instId must be a SWAP, e.g. BTC-USDT-SWAP.
Inputs: instId (required).
market_candlesMarket candlesARead-onlyIdempotent
Get recent OKX public candlesticks (OHLCV) for one instrument. READ-ONLY: this tool only calls OKX public market REST. No API key, no order, no account access. Returns newest-first, same as OKX. bar examples: 1m, 5m, 1H, 1D.
Inputs: instId (required), bar, after, limit, +1 more.
market_tickerMarket tickerARead-onlyIdempotent
Get the latest OKX public ticker for one instrument (spot or swap). READ-ONLY: this tool only calls OKX public market REST. No API key, no order, no account access. Example instId: BTC-USDT or BTC-USDT-SWAP.
Inputs: instId (required).
oi_summaryOpen interest summaryARead-onlyIdempotent
Get OKX public open interest for one instrument, or aggregated by instType/ccy. READ-ONLY: this tool only calls OKX public market REST. No API key, no order, no account access. Provide instId (e.g. BTC-USDT-SWAP) or instType (SWAP/FUTURES) optionally with ccy.
Inputs: ccy, instId, instType.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool maps to a distinct market data primitive: ticker, candles, funding rate, open interest, and a composite threshold check. The only soft overlap is alert_check, which can evaluate metrics already exposed by market_ticker/funding_rate/oi_summary, but its one-shot evaluation framing keeps it separable.
All names are lowercase snake_case and consistently noun/resource-oriented (market_ticker, market_candles, funding_rate, oi_summary, alert_check). Minor deviation: the market_ prefix appears on only two of five tools, and oi_ is an abbreviation where others spell things out.
Five tools is well-scoped for a read-only market monitoring surface, with each tool covering a distinct data need. Nothing feels padded or redundant.
Covers the core monitoring set (price, OHLCV, funding, OI, threshold alerts) for spot and swaps. Gaps remain: no instrument/symbol discovery tool (agent must already know instIds), and no order book depth, mark/index price, or recent trades, which are common for a 'market guard' use case.
Maintenance
Related MCP Connectors
Read-only educational MCP for CryptoDecentral Sovereign. No auth, trading, custody, or advice.
Read-only MCP for AI usage profiles, leaderboards, stats, and docs; no writes or private data.
Read-only market charts, OHLC, backtests and a view of your connected broker accounts
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to query OKX public market data, including tickers, klines, order books, and trading pairs via MCP tools.-
- AlicenseAqualityBmaintenanceProvides AI agents read-only, keyless access to Aster DEX data, including futures and spot markets, TradFi perpetuals, funding rates, order books, klines, vault deposit flows, and account views through MCP tools.1371 PyPI1MIT
- AlicenseNot gradedqualityCmaintenanceEnables read-only access to Hyperliquid's public market, user, vault, and staking data via 61 MCP tools, covering perpetuals, spot, and borrow-lend information.MIT
- AlicenseBqualityBmaintenanceEnables credential-free, read-only access to selected public market-data routes via 13 typed MCP tools covering asset mapping, metadata, quotes, listings, global metrics, Fear & Greed, Altcoin Season, and CMC index data.13MIT