Skip to content
Back to search

okx-market-guard

Read-only OKX public market data MCP server + CLI (OKX AI Builder submission)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mavis-codee/okx-market-guard with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mavis-codee/okx-market-guard'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mavis-codee--okx-market-guard/badge.svg)](/listings/mavis-codee--okx-market-guard)

HTML

<a href="/listings/mavis-codee--okx-market-guard"><img src="/api/listings/mavis-codee--okx-market-guard/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 183 lines
  1. # OKX Market Guard
  2. Read-only OKX public market data for AI agents, plus **demo-first trading** composed from the **official** `@okx_ai/okx-trade-cli`. Ships as an **MCP server** (stdio, JSON-RPC 2.0) and a **CLI**. Market tools have zero runtime npm dependencies. TypeScript source runs directly on Node 22.6+ / Node 24 (type stripping).
  3. > **Safety first.** Market tools talk **only** to official OKX **public** market REST on `https://www.okx.com`. They have **no API key**, cannot place or cancel orders, and cannot read account or wallet data. Alerts are stateless. Trade tools are a thin spawn of the official OKX CLI: **`--demo` is the default**, live is an explicit opt-in, and this process never reads or stores your keys.
  4. ## Tools
  5. | Tool | What it does | OKX endpoint (public GET) |
  6. | --- | --- | --- |
  7. | `market_ticker` | Latest ticker + 24h change % + spread % | `/api/v5/market/ticker` |
  8. | `market_candles` | OHLCV candles, newest first, `bar` 1m–3M, limit 1–300 | `/api/v5/market/candles` |
  9. | `funding_rate` | Current funding rate for a perpetual (`-SWAP` instId) | `/api/v5/public/funding-rate` |
  10. | `oi_summary` | Open interest by `instId` or by `instType`/`ccy` | `/api/v5/public/open-interest` |
  11. | `alert_check` | One-shot threshold vs latest data (stateless) | same public endpoints |
  12. `alert_check` metrics: `last`, `changePercent24h`, `high24h`, `low24h`, `bidAskSpreadPct`, `fundingRate` (SWAP only), `openInterest` (SWAP/FUTURES). Operators: `gt`, `gte`, `lt`, `lte`.
  13. ## Trading via the official CLI (demo by default)
  14. Market tools stay read-only. Trading is **composition**: we spawn the official [`@okx_ai/okx-trade-cli`](https://www.npmjs.com/package/@okx_ai/okx-trade-cli) (verified on **1.5.1**) as a child process. Order logic, signing, and profile handling live in the official package. This repo only validates input, rate-limits, builds argv, and friendlies errors.
  15. | Tool | Official command | `--aiBuilderCode` (per official `--help` 1.5.1) |
  16. | --- | --- | --- |
  17. | `trade_spot_place` | `okx spot place` | yes |
  18. | `trade_spot_batch_place` | `okx spot batch --action place` | yes (place only) |
  19. | `trade_swap_place` | `okx swap place` | yes |
  20. | `trade_swap_close` | `okx swap close` | yes |
  21. | `trade_swap_batch_place` | `okx swap batch --action place` | yes (place only) |
  22. | `trade_futures_place` | `okx futures place` | yes |
  23. | `trade_futures_close` | `okx futures close` | yes |
  24. | `trade_futures_batch_place` | `okx futures batch --action place` | yes (place only) |
  25. | `trade_option_place` | `okx option place` | yes |
  26. We do **not** wrap `cancel`, `amend`, or query commands. Their official `--help` does not expose `--aiBuilderCode`, and attribution must follow the official help, not a raw tag. Raw `tag` is never passed to the CLI.
  27. **Mode.** Default is `--demo`. Live requires `--trade-live` (CLI) **and** a valid `OKX_AI_BUILDER_CODE`. Empty code + live = rejected. Code rule: 1–16 alphanumeric (official AI Builder rule).
  28. **Credentials.** Keys stay in the user's `~/.okx/config.toml`. This process never reads, stores, or prints `api_key` / `secret_key` / `passphrase`. The child CLI reads that file. We spawn with an env allowlist (`PATH`, proxy, …) and strip `OKX_API_KEY` / `OKX_SECRET_KEY` / `OKX_PASSPHRASE`. `OKX_AI_BUILDER_CODE` is a builder attribution code, not a credential; the bridge may read it.
  29. **Profiles.** `--profile demo` is the default profile name. Create a demo profile yourself:
  30. ```bash
  31. npx @okx_ai/okx-trade-cli profile add --name demo --demo
  32. # or: okx profile add --name demo --demo
  33. ```
  34. **Install.** The official CLI is not a hard dependency of this repo. Resolution order: `OKX_TRADE_CLI` path → `node_modules/@okx_ai/okx-trade-cli/dist/index.js` → `npx -y @okx_ai/okx-trade-cli@1.5.1`.
  35. ```bash
  36. # optional, pins the official CLI locally
  37. npm install --no-save @okx_ai/okx-trade-cli@1.5.1
  38. ```
  39. **Try without trading (plan only, nothing spawned):**
  40. ```bash
  41. node src/cli.ts trade-tools --pretty
  42. node src/cli.ts trade-plan trade_spot_place --instId BTC-USDT --side buy --ordType limit --sz 0.001 --px 50000 --pretty
  43. # live plan (fails without OKX_AI_BUILDER_CODE)
  44. OKX_AI_BUILDER_CODE=yourcode node src/cli.ts trade-plan trade_swap_place --instId BTC-USDT-SWAP --side buy --ordType market --sz 1 --trade-live --pretty
  45. ```
  46. **MCP:** `serve` includes trade tools by default (demo). `--no-trade` gives the old market-only server. `--trade-live` is the live opt-in.
  47. ## Safety rails
  48. - **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.
  49. - **No credentials, ever.** Passing `apiKey` / `secret` / `passphrase` / `token` as options throws. Requests carry no `Authorization` header. `redirect: 'error'` blocks redirect-based SSRF.
  50. - **Read-only MCP annotations on market tools.** Every market tool advertises `readOnlyHint: true`, `destructiveHint: false`. Trade tools advertise `readOnlyHint: false`, `destructiveHint: true`.
  51. - **Input validation.** instId shape, bar enum, limit range, extra-key rejection, SWAP-required checks for funding.
  52. - **Rate limit.** Token bucket, default 8 req/s, burst 16 (OKX public limits are ~20 req / 2 s per IP). Trade spawns are separately throttled (2/s, burst 4).
  53. - **aiBuilderCode whitelist.** The flag is attached only to commands whose official `--help` on 1.5.1 exposes it. Help does not expose it → we do not add it and we do not claim attribution.
  54. - **No real-funds testing in CI.** Tests mock the child process. Live/demo order placement is not part of `npm test`.
  55. - **Friendly OKX errors.** Envelope `code !== '0'` becomes a message with a hint (wrong instId type, rate limit, timeout, DNS/proxy).
  56. - **Stateless alerts.** `alert_check` compares one number to one threshold and returns. No watchlists, no notifications, no writes.
  57. ## Quick start
  58. Node.js **>= 22.6** (24 recommended). No `npm install` needed.
  59. ```bash
  60. node src/cli.ts --help
  61. node src/cli.ts ticker BTC-USDT --pretty
  62. node src/cli.ts candles BTC-USDT --bar 1H --limit 24 --pretty
  63. node src/cli.ts funding BTC-USDT-SWAP --pretty
  64. node src/cli.ts oi BTC-USDT-SWAP --pretty
  65. node src/cli.ts alert BTC-USDT --metric last --op gt --threshold 100000 --pretty
  66. ```
  67. 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:
  68. ```powershell
  69. # Windows PowerShell
  70. $env:NODE_USE_ENV_PROXY = "1"
  71. $env:HTTPS_PROXY = "http://127.0.0.1:7890" # your local proxy
  72. node src/cli.ts ticker BTC-USDT --pretty
  73. ```
  74. ```bash
  75. # macOS / Linux
  76. NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://127.0.0.1:7890 node src/cli.ts ticker BTC-USDT --pretty
  77. ```
  78. `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.
  79. ## MCP client config
  80. Point any MCP client at the stdio server:
  81. ```json
  82. {
  83. "mcpServers": {
  84. "okx-market-guard": {
  85. "command": "node",
  86. "args": ["<absolute-path>/src/cli.ts", "serve"],
  87. "env": {
  88. "NODE_USE_ENV_PROXY": "1",
  89. "HTTPS_PROXY": "http://127.0.0.1:7890"
  90. }
  91. }
  92. }
  93. }
  94. ```
  95. Market-only (no trade tools advertised):
  96. ```json
  97. {
  98. "mcpServers": {
  99. "okx-market-guard-readonly": {
  100. "command": "node",
  101. "args": ["<absolute-path>/src/cli.ts", "serve", "--no-trade"]
  102. }
  103. }
  104. }
  105. ```
  106. Live trading is **not** a tool argument. The agent cannot upgrade the server to live. Restart with `--trade-live` and `OKX_AI_BUILDER_CODE` in the **host** env if the owner wants live.
  107. 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**.
  108. ## Tests
  109. ```bash
  110. npm test # unit tests (mocked fetch) + live tests (skip if OKX unreachable)
  111. ```
  112. Live tests hit real public endpoints with `BTC-USDT` / `BTC-USDT-SWAP`. Force-skip them with `OKX_SKIP_LIVE=1`.
  113. Demo (real REST, prints a full transcript):
  114. ```bash
  115. node demo/demo.ts
  116. # transcript of a recent run: docs/demo-output.txt
  117. ```
  118. ## Layout
  119. ```
  120. src/
  121. okx-client.ts allowlisted public REST client
  122. tools/index.ts the five market tools
  123. trade-cli-bridge.ts official CLI composition (spawn, whitelist, code)
  124. mcp/server.ts JSON-RPC 2.0 stdio server
  125. cli.ts CLI + serve
  126. validate.ts input validation
  127. ratelimit.ts token bucket + credential guard
  128. errors.ts friendly errors
  129. test/ node:test unit + live
  130. demo/demo.ts live market demo
  131. docs/ demo transcript, help evidence, AI Builder application draft
  132. ```
  133. ## What this is not
  134. - Not a trading-strategy bot. Not a key manager. Not a WebSocket feed. Not a mirror of okx.com.
  135. - Trading is the **official** OKX CLI, not our reimplementation. We do not sign requests.
  136. - 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.
  137. ## License
  138. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.