Skip to main content
Glama
OKX Market Guard

OKX Market Guard

by mavis-codee

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)

market_ticker

Latest ticker + 24h change % + spread %

/api/v5/market/ticker

market_candles

OHLCV candles, newest first, bar 1m–3M, limit 1–300

/api/v5/market/candles

funding_rate

Current funding rate for a perpetual (-SWAP instId)

/api/v5/public/funding-rate

oi_summary

Open interest by instId or by instType/ccy

/api/v5/public/open-interest

alert_check

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.com and 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 / token as options throws. Requests carry no Authorization header. 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_check compares 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 --pretty

If 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 --pretty

NODE_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.txt

Layout

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 draft

What 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 tools
alert_checkAlert check (stateless, read-only)A
Read-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 rateA
Read-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 candlesA
Read-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 tickerA
Read-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 summaryA
Read-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

    A3.9/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to query OKX public market data, including tickers, klines, order books, and trading pairs via MCP tools.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Provides 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.
      13
      71 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      13
      MIT