RapidX CLI & MCP Reference

CLI and MCP are two independent integration paths — choose either or both:

• CLI path: call rapidx <domain> <action> --input '...' --json from any shell, script, or exec-capable language. No agent host required.
• MCP path: register rapidx mcp serve as an MCP server in Claude Code, Codex, Cursor, or any MCP-capable host. Your agent calls rapidx/order/place, rapidx/market/get-ticker, etc. as structured tools — no shell commands in your agent code.

Both paths use the same credentials, the same capabilities, and the same preview-then-submit safety model.

Risk Levels

Every capability has a risk level that agents should use to scope confirmation behavior:

---

Response Envelope

Every CLI command and MCP tool returns:

{
  "ok": true,
  "status": "PASS",
  "data": {},
  "auditId": "optional-audit-id",
  "evidence": [
    {
      "source": "real_tool_call",
      "toolOrCommandEvidence": "rapidx market get-ticker",
      "timestamp": "2026-06-08T00:00:00.000Z"
    }
  ]
}

Failure uses the same shape:

{
  "ok": false,
  "status": "INVALID_INPUT",
  "code": "RCLI30001",
  "message": "Input schema validation failed: unknown field: foo.",
  "evidence": []
}

Read ok, status, code, message, and data. Do not infer success from process output text alone.

---

Preview, Confirmation, and Automation

All write operations require preview before submission. Preview and submit must use the same runtime (both CLI or both MCP).

Manual Confirmation (default)

The agent creates a preview, shows the result to the user, and submits only after the user confirms.

Preview response includes:

{
  "previewId": "rpv_xxx",
  "businessParams": { "symbol": "...", "side": "BUY", ... },
  "riskNotes": [],
  "expiresAt": "2026-06-08T00:05:00.000Z",
  "confirmation": {
    "submitToken": "confirm_rpv_xxx",
    "requiredFields": ["previewId", "continueConsentId"]
  }
}

Preview records expire after ~5 minutes. If expired or if submit parameters differ from preview, RapidX returns BLOCKED — create a new preview.

Automation Mode

Automation mode lets an agent submit without a per-order chat confirmation. It is valid only when the human user explicitly enables it in chat.

Enable on the preview request (not on submit):

{
  "automationMode": true,
  "automationConsentText": "I enable RapidX automation mode for BINANCE_PERP_BTC_USDT with maxNotional 100 and accept automated preview-submit execution.",
  "automationScope": "single-preview"
}

Rules:

• Pass the user's exact authorization text through automationConsentText — do not rewrite or broaden it.
• automationConsentText must include the exact symbol and maxNotional.
• The text must clearly express automation intent (automation, automated).
• Submit still requires previewId and continueConsentId; automation changes confirmation mode, not the API shape.

When accepted, the preview response includes:

{
  "automation": {
    "enabled": true,
    "confirmationMode": "automation-preview",
    "scope": "single-preview",
    "maxNotional": "100"
  }
}

---

MCP Reference

Reference implementation: ltp-ai-hub / rapidx-mcp-cli — A production-quality example showing how to integrate RapidX MCP into an AI agent workflow. Uses the same @liquiditytech/rapidx-cli npm package; MCP is not a separate package.

Start the server:

rapidx mcp serve

MCP config:

{
  "mcpServers": {
    "rapidx": {
      "command": "rapidx",
      "args": ["mcp", "serve"],
      "env": {
        "LTP_ACCESS_KEY": "<your-access-key>",
        "LTP_SECRET_KEY": "<your-secret-key>",
        "LTP_API_HOST": "https://api.ltp-contest.com"
      }
    }
  }
}

If the agent host cannot resolve rapidx, set command to the absolute path from which rapidx.

Schema Discovery

After startup, agents should call rapidx/tools first:

rapidx/tools

Response structure:

{
  "schemaVersion": "2026-05-23",
  "inputSchemas": { "PreviewOrderInput": { ... }, ... },
  "tools": [
    {
      "name": "rapidx/order/place-preview",
      "riskLevel": "trade-write",
      "inputSchema": "PreviewOrderInput",
      "outputSchema": "PreviewOrderResult",
      "previewRequired": false,
      "containsRealOrder": false,
      "requiresExplicitHumanConfirmation": false
    }
  ]
}

To construct a tool input:

1. Find the tool by name.
2. Read its inputSchema.
3. Look up that schema in inputSchemas.
4. Send only fields allowed by the schema.

MCP Tool Groups

Discovery & Diagnostics

Market

Portfolio

Orders (preview required for writes)

Algo Orders (TP/SL — preview required for writes)

Algo orders are conditional trigger orders (Take-Profit / Stop-Loss). Unlike regular orders, a triggered fill is always a MARKET close — there is no limit-price guarantee. Writes use the generic rapidx/trade/preview with targetCapabilityId (no dedicated algo preview tools).

rapidx/algo/cancel-all (mapping to DELETE /api/v1/algo/cancelAll) is not always exposed as a separate tool — use rapidx/algo/cancel per order, or the REST endpoint directly. Full reference: Algo Orders.

Transactions

Positions (preview required for writes)

Automation Sessions

Automation sessions let a user authorize an agent to trade within a bounded scope without per-order chat confirmation. Preview is still required on every write — the session replaces the per-order chat approval, not the preview step.

Pass automationSessionId into preview tools to bind a write to the active session.

Trade Utilities

Use concrete preview tools (rapidx/order/place-preview, etc.) for normal order workflows — not rapidx/trade/preview.

Monitor your daily AI token spend ($10 USD limit) — see AI API Usage.

---

CLI Reference

Schema Discovery

rapidx schema --json

Response contains data.schemaVersion, data.capabilities[], and data.inputSchemas. Each capability entry:

{
  "capabilityId": "order.place-preview",
  "cliCommand": "rapidx order place-preview",
  "mcpTool": "rapidx/order/place-preview",
  "inputSchema": "PreviewOrderInput",
  "outputSchema": "PreviewOrderResult",
  "previewRequired": false
}

Use the schema to construct --input JSON. The live schema from rapidx schema --json is authoritative — never hard-code input shapes.

Diagnostics

rapidx --version
rapidx schema --json              # discover capabilities and input schemas
rapidx auth check --json          # credential resolution check
rapidx doctor --json              # local diagnostics
rapidx update check --json        # CLI, MCP schema, and skills version check
rapidx self-check --json          # read-only integration self-check

Market

rapidx market get-ticker         --input '{"symbol":"BINANCE_PERP_BTC_USDT"}' --json
rapidx market get-orderbook      --input '{"symbol":"BINANCE_PERP_BTC_USDT","level":20}' --json
rapidx market get-klines         --input '{"symbol":"BINANCE_PERP_BTC_USDT","interval":"1h","limit":100}' --json
rapidx market get-funding-rate   --input '{"symbol":"BINANCE_PERP_BTC_USDT"}' --json
rapidx market get-mark-price     --input '{"symbol":"BINANCE_PERP_BTC_USDT"}' --json
rapidx market get-symbol-info    --input '{"symbol":"BINANCE_PERP_BTC_USDT"}' --json
rapidx market get-open-interest  --input '{"symbol":"BINANCE_PERP_BTC_USDT"}' --json

Portfolio

rapidx portfolio overview --json
rapidx portfolio assets --json
rapidx portfolio statement --json
rapidx portfolio user-fee-rate --json
rapidx portfolio position-bracket --input '{"symbol":"BINANCE_PERP_BTC_USDT"}' --json

set-position-mode switches the portfolio position mode between BOTH (hedge mode, the default) and NET (one-way). It is a write operation — preview first. Maps to POST /api/v1/trading/account (Change Portfolio Position Mode).

Prerequisites: close all open positions and cancel all open orders before switching — otherwise the server rejects with 406012 (position mode switch blocked). Position mode applies to perpetuals/contracts only; spot is unaffected.

# Switch to BOTH (hedge mode) — default
rapidx trade preview --input '{"targetCapabilityId":"portfolio.set-position-mode","exchange":"BINANCE","mode":"BOTH"}' --json

# Switch to NET (one-way)
rapidx trade preview --input '{"targetCapabilityId":"portfolio.set-position-mode","exchange":"BINANCE","mode":"NET"}' --json

Orders

# Preview (required before place/replace/cancel)
rapidx order place-preview   --input '{"symbol":"BINANCE_PERP_BTC_USDT","side":"BUY","positionSide":"LONG","orderType":"LIMIT","price":"65000","quantity":"0.001","maxNotional":"100","clientOrderId":"agent-001","postOnly":true}' --json
rapidx order replace-preview --input '{"orderId":"1234567890123456","price":"64000"}' --json
rapidx order cancel-preview  --input '{"orderId":"1234567890123456"}' --json

# Submit (include previewId + continueConsentId from preview response)
# continueConsentId = preview response's confirmation.submitToken
rapidx order place  --input '{...same params...,"previewId":"rpv_xxx","continueConsentId":"confirm_rpv_xxx"}' --json
rapidx order replace --input '{"orderId":"...","price":"64000","previewId":"rpv_xxx","continueConsentId":"confirm_rpv_xxx"}' --json
rapidx order cancel  --input '{"orderId":"...","previewId":"rpv_xxx","continueConsentId":"confirm_rpv_xxx"}' --json

# Reads
rapidx order query       --input '{"clientOrderId":"agent-001"}' --json
rapidx order open-orders --json
rapidx order history     --input '{"symbol":"BINANCE_PERP_BTC_USDT"}' --json
rapidx order cancel-all  --input '{"symbol":"BINANCE_PERP_BTC_USDT"}' --json

positionSide (LONG or SHORT) is required in BOTH (hedge) mode — competition accounts default to this mode. In one-way NET mode, omit positionSide unless the API explicitly returns a side value.

orderId must be a 16-digit RapidX order ID. Wrong format → RCORE00002. Valid but missing → NOT_FOUND.

Cancel is asynchronous at the exchange layer. Check cancelAccepted and terminalStateConfirmed; poll rapidx order query until CANCELED if not confirmed.

Algo Orders

Algo orders are conditional trigger orders — primarily Take-Profit / Stop-Loss (TPSL) that fire as MARKET close orders when a trigger price is hit. Writes follow the same preview → submit pattern as regular orders, but use the generic rapidx trade preview with a targetCapabilityId (there are no dedicated algo preview tools).

# 1. Preview (targetCapabilityId selects the algo capability)
rapidx trade preview --input '{"targetCapabilityId":"algo.place","algoOrderType":"TPSL","sym":"BINANCE_PERP_ETH_USDT","side":"SELL","orderQty":"0.566","reduceOnly":true,"positionSide":"LONG","conditionType":"CONDITIONAL","conditionalTriggerType":"MARK_PRICE","conditionalTriggerPrice":"1896.73","tpTriggerPrice":"1896.73","tpPrice":"0","slTriggerPrice":"1716.09","slPrice":"0","clientOrderId":"eth-tpsl-001","maxNotional":"1100"}' --json

# 2. Submit — same params + previewId + continueConsentId from the preview response
rapidx algo place --input '{...same params...,"previewId":"rpv_xxx","continueConsentId":"confirm_rpv_xxx"}' --json

# Reads
rapidx algo query        --input '{"algoOrderId":"2187783984685122"}' --json
rapidx algo open-orders  --input '{"sym":"BINANCE_PERP_ETH_USDT"}' --json
rapidx algo history      --input '{"sym":"BINANCE_PERP_ETH_USDT"}' --json

# Replace / cancel — preview first, same pattern as place
rapidx algo replace --input '{"algoOrderId":"2187783984685122","tpTriggerPrice":"1987.05","tpPrice":"0","previewId":"rpv_xxx","continueConsentId":"confirm_rpv_xxx"}' --json
rapidx algo cancel  --input '{"algoOrderId":"2187783984685122","previewId":"rpv_xxx","continueConsentId":"confirm_rpv_xxx"}' --json

Readback after an algo write:

How algo differs from a regular order: a regular order rests on the book and fills passively; an algo order waits for a trigger (mark/last price crossing tpTriggerPrice / slTriggerPrice) then fires a one-shot MARKET close. If TP and SL are both set on one parent order, triggering either side invalidates the other — to keep both sides active, place two separate parent orders. Full REST reference: Algo Orders.

Positions

rapidx position query        --json
rapidx position history      --input '{"symbol":"BINANCE_PERP_BTC_USDT"}' --json
rapidx position get-leverage --input '{"symbol":"BINANCE_PERP_BTC_USDT"}' --json

# Writes — preview first via rapidx trade preview
rapidx trade preview --input '{"targetCapabilityId":"position.set-leverage","symbol":"BINANCE_PERP_BTC_USDT","leverage":5}' --json
rapidx trade preview --input '{"targetCapabilityId":"position.close","symbol":"BINANCE_PERP_BTC_USDT","reduceOnly":true,"maxNotional":"100"}' --json

rapidx position set-leverage --input '{"previewId":"rpv_xxx","continueConsentId":"confirm_rpv_xxx","symbol":"BINANCE_PERP_BTC_USDT","leverage":5}' --json
rapidx position close        --input '{"previewId":"rpv_xxx","continueConsentId":"confirm_rpv_xxx","symbol":"BINANCE_PERP_BTC_USDT","reduceOnly":true,"maxNotional":"100"}' --json
rapidx position close-all    --input '{"exchange":"BINANCE"}' --json

position.close does not accept side or quantity. In HEDGE mode pass positionSide: "LONG" or "SHORT"; in NET mode omit positionSide. If no position exists, preview returns BLOCKED with NO_POSITION_TO_CLOSE.

Transactions

rapidx transaction executions --input '{"symbol":"BINANCE_PERP_BTC_USDT"}' --json

Automation Sessions (CLI)

Automation sessions let the user authorize bounded automated trading without per-order chat confirmation. Preview is still required for every write; the session replaces the per-order chat approval.

Start a session:

rapidx automation start --input '{
  "symbols": ["BINANCE_PERP_BTC_USDT"],
  "maxNotionalPerOrder": "100",
  "maxTotalNotional": "1000",
  "expiresInSeconds": 3600,
  "allowedActions": ["order.place", "order.replace", "order.cancel"],
  "allowedOrderTypes": ["LIMIT", "MARKET"],
  "explicitUserConsent": true,
  "acceptedRiskText": "I authorize RapidX automation for BINANCE_PERP_BTC_USDT with max 100 USDT per order and 1000 USDT total for 1 hour."
}' --json

Response returns automationSessionId. Pass it into previews:

rapidx order place-preview --input '{
  "automationSessionId": "ras_xxx",
  "symbol": "BINANCE_PERP_BTC_USDT",
  "side": "BUY",
  "orderType": "LIMIT",
  "price": "65000",
  "quantity": "0.001",
  "maxNotional": "100",
  "clientOrderId": "auto-001"
}' --json

Submit with the same params plus previewId and continueConsentId:

rapidx order place --input '{
  "automationSessionId": "ras_xxx",
  ...same business params...,
  "previewId": "rpv_xxx",
  "continueConsentId": "confirm_rpv_xxx"
}' --json

Manage sessions:

rapidx automation list --json
rapidx automation status --input '{"automationSessionId":"ras_xxx"}' --json
rapidx automation extend --input '{
  "automationSessionId": "ras_xxx",
  "expiresInSeconds": 7200,
  "explicitUserConsent": true,
  "acceptedRiskText": "I authorize extending this RapidX automation session."
}' --json
rapidx automation stop --input '{"automationSessionId":"ras_xxx"}' --json

Agent rules: start only after explicit user authorization; pass automationSessionId into every preview; do not expand scope without a new session; stop when the user ends automation.

Live Trade Verification

rapidx trade verify-live --input '{
  "symbol": "BINANCE_PERP_BTC_USDT",
  "side": "BUY",
  "maxNotional": "10",
  "clientOrderId": "verify-live-001",
  "explicitUserConsent": true,
  "acceptedRiskText": "I authorize a real verification order for BINANCE_PERP_BTC_USDT BUY maxNotional 10 with cancel cleanup."
}' --json

Use rapidx self-check --json for routine read-only checks. Use verify-live only after explicit user consent for a real-order test.

rapidx self-check trade-verify is a CLI compatibility alias for verify-live.

---

Readback Patterns

Do not treat a submit response as final state. Always read back after writes:

---

Troubleshooting

Self-check returns NOT_VERIFIED

Check message, code, and evidence. Common causes: missing credentials, wrong LTP_API_HOST, missing account permission, blocked network.

Write returns BLOCKED

• Was the matching preview called first?
• Is previewId present?
• Does continueConsentId equal the preview's confirmation.submitToken?
• Do submit params match preview params exactly?
• Is the preview expired (>5 min)?

MCP tools not visible

Verify MCP config uses "command": "rapidx", "args": ["mcp", "serve"], then reload the agent host. If the host does not inherit shell PATH, set command to the absolute path from which rapidx.

rapidx mcp serve looks stuck

rapidx mcp serve is a long-running stdio MCP server — configure it in the MCP host, do not run it as a one-shot command. Use rapidx self-check --json for one-shot local verification.

Symbol not recognized

RapidX requires canonical symbols — normalize before calling any tool:

BTCUSDT  →  BINANCE_PERP_BTC_USDT
ETHUSDT  →  BINANCE_PERP_ETH_USDT

---

Upgrade

rapidx update check --json
npm install -g @liquiditytech/rapidx-cli@latest
rapidx schema --json
rapidx self-check --json

Upgrade skills with the same install method used for your agent host.