@liquiditytech/rapidx-cli 1.0.26

package/packages/distribution/docs/index.md

@@ -0,0 +1,58 @@
+# RapidX External Service
+
+RapidX provides three layers:
+
+- CLI: atomic `rapidx` operations.
+- MCP: best-practice tool surface through `rapidx mcp serve`.
+- Skills: agent-facing playbooks for configuration, review, self-check, and trading.
+
+All layers share the same canonical capability registry from Core.
+
+Use `tools.md` for the published capability summary.
+
+Install the agent skills from the dedicated skills repository. Choose the command for the target agent host.
+
+Codex:
+
+```bash
+npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git \
+  --skill ltp-rapidx-config \
+  --skill ltp-rapidx-trading \
+  -a codex -y
+```
+
+Claude Code:
+
+```bash
+npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git \
+  --skill ltp-rapidx-config \
+  --skill ltp-rapidx-trading \
+  -a claude-code -y
+```
+
+Gemini CLI:
+
+```bash
+npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git \
+  --skill ltp-rapidx-config \
+  --skill ltp-rapidx-trading \
+  -a gemini-cli -y
+```
+
+Use this only when the Gemini environment supports Agent Skills through the general skills installer.
+
+OpenClaw:
+
+```bash
+openclaw skills install ltp-rapidx-config
+openclaw skills install ltp-rapidx-trading
+```
+
+Hermes Agent:
+
+```bash
+hermes skills install LiquidityTech/ltp-rapidx-skill/skills/ltp-rapidx-config
+hermes skills install LiquidityTech/ltp-rapidx-skill/skills/ltp-rapidx-trading
+```
+
+Use `skills.md` for the full Agent install matrix and manual install paths.

package/packages/distribution/docs/mcp.md

@@ -0,0 +1,36 @@
+# MCP
+
+MCP server mode is started by the CLI:
+
+```bash
+rapidx mcp serve
+```
+
+The registry metadata must use:
+
+```json
+{
+  "command": "rapidx",
+  "args": ["mcp", "serve"],
+  "env": {
+    "LTP_ACCESS_KEY": "<your-access-key>",
+    "LTP_SECRET_KEY": "<your-secret-key>",
+    "LTP_API_HOST": "<provided-api-host>"
+  }
+}
+```
+
+Public tool names use the `rapidx/` prefix.
+
+Key trading tools:
+
+- `rapidx/update/check` reads the RapidX release manifest and returns current/latest CLI version, minimum write version, skills update advice, and upgrade commands.
+- `rapidx/self-check` can include update state when called with `{"checkUpdates": true}`.
+- `rapidx/order/preview` creates preview tokens for `order.place`.
+- `rapidx/order/place-preview`, `rapidx/order/amend-preview`, and `rapidx/order/cancel-preview` are concrete order preview aliases. Preview responses include `confirmation.submitToken`; pass it as `continueConsentId` when submitting the matching write tool.
+- `rapidx/trade/preview` creates preview tokens for non-place trade writes by `targetCapabilityId`, including position, account, and algo writes.
+- `rapidx/position/history` reads historical positions.
+- `rapidx/account/set-position-mode` changes account position mode and requires preview plus explicit continuation consent.
+- `rapidx/trade/verify-live` runs the optional small real-trade verification flow with `explicitUserConsent`; it creates its own internal preview and does not accept an external `previewId`. `rapidx/trading-verification` remains supported as a compatibility alias.
+
+Agents must discover the full tool list through `rapidx/tools` and must not invent tool names.

package/packages/distribution/docs/quickstart.md

@@ -0,0 +1,129 @@
+# Quickstart
+
+You can install RapidX skills in two ways:
+
+- Run the commands yourself.
+- Send the install instructions to your agent and let the agent run the commands in its own workspace.
+
+Send this to your agent if you want it to handle installation:
+
+```text
+Install RapidX skills into your current workspace.
+Use the installation method that matches your agent host.
+Install ltp-rapidx-config and ltp-rapidx-trading.
+Then follow ltp-rapidx-config to install @liquiditytech/rapidx-cli, configure credentials, choose MCP or CLI mode, and run read-only self-check.
+```
+
+1. To install the skills yourself, choose the command for your agent host.
+
+Codex:
+
+```bash
+npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git \
+  --skill ltp-rapidx-config \
+  --skill ltp-rapidx-trading \
+  -a codex -y
+```
+
+Claude Code:
+
+```bash
+npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git \
+  --skill ltp-rapidx-config \
+  --skill ltp-rapidx-trading \
+  -a claude-code -y
+```
+
+Gemini CLI:
+
+```bash
+npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git \
+  --skill ltp-rapidx-config \
+  --skill ltp-rapidx-trading \
+  -a gemini-cli -y
+```
+
+Use this command only when your Gemini environment supports Agent Skills through the general skills installer. Verified Gemini CLI builds may expose `gemini extensions`, not `gemini skills`.
+
+OpenClaw:
+
+```bash
+openclaw skills install ltp-rapidx-config
+openclaw skills install ltp-rapidx-trading
+```
+
+Hermes Agent:
+
+```bash
+hermes skills install LiquidityTech/ltp-rapidx-skill/skills/ltp-rapidx-config
+hermes skills install LiquidityTech/ltp-rapidx-skill/skills/ltp-rapidx-trading
+```
+
+For Cursor or OpenCode, use `npx skills add` with `-a cursor` or `-a opencode`. For manual installation, copy `skills/ltp-rapidx-config` and `skills/ltp-rapidx-trading` into the target agent's skills directory.
+
+2. Install the RapidX CLI package from the official npm registry.
+
+```bash
+npm install -g @liquiditytech/rapidx-cli
+```
+
+3. Verify the bin:
+
+```bash
+rapidx schema --json
+rapidx update check --json
+```
+
+4. Configure credentials through the agent host secret mechanism or environment:
+
+```bash
+LTP_ACCESS_KEY=<your-access-key>
+LTP_SECRET_KEY=<your-secret-key>
+LTP_API_HOST=<provided-api-host>
+```
+
+5. Configure the agent workspace MCP server with:
+
+```json
+{
+  "command": "rapidx",
+  "args": ["mcp", "serve"],
+  "env": {
+    "LTP_ACCESS_KEY": "<your-access-key>",
+    "LTP_SECRET_KEY": "<your-secret-key>",
+    "LTP_API_HOST": "<provided-api-host>"
+  }
+}
+```
+
+6. Run:
+
+```bash
+rapidx self-check --read-only --json
+rapidx self-check --read-only --check-updates --json
+```
+
+Do not treat a missing real call as success. The correct status is `NOT_VERIFIED`.
+
+7. Discover the canonical tool surface:
+
+```bash
+rapidx schema --json
+```
+
+For trade writes, create a preview before submit. Use `rapidx order place-preview` for `order.place`, `rapidx order amend-preview` for `order.amend`, and `rapidx order cancel-preview` for `order.cancel`. Use flat JSON with `rapidx trade preview` and `targetCapabilityId` for non-order writes such as `position.set-leverage`, `position.close`, or `account.set-position-mode`.
+
+For clearer order flows, prefer the explicit aliases:
+
+```bash
+rapidx order place-preview --input '{"symbol":"BINANCE_PERP_BTC_USDT","side":"BUY","orderType":"LIMIT","price":"65000","quantity":"0.001","maxNotional":"100","clientOrderId":"example-001"}' --json
+rapidx order amend-preview --input '{"orderId":"<order-id>","price":"64900"}' --json
+rapidx order cancel-preview --input '{"orderId":"<order-id>"}' --json
+rapidx trade preview --input '{"targetCapabilityId":"position.set-leverage","symbol":"BINANCE_PERP_BTC_USDT","leverage":5}' --json
+```
+
+When submitting the actual write, pass the returned `previewId` and use `confirmation.submitToken` as `continueConsentId`.
+
+`maxNotional` is a safety upper bound, not the target order amount. If a requested amount is below the symbol `minNotional`, ask the user to confirm the larger amount before submitting. For `position.close`, do not pass `side` or `quantity`; RapidX determines the close side from the current position and closes the target symbol/positionSide. Use a reduce-only order flow for partial closes, then check final exposure with `position list`.
+
+Use `rapidx trade verify-live --json` only when the user explicitly authorizes a small real-trade verification. The older `rapidx self-check trade-verify --json` command remains supported for compatibility.

package/packages/distribution/docs/self-check.md

@@ -0,0 +1,7 @@
+# Self-check
+
+Read-only self-check verifies discovery, schema compatibility, public market access, credential auth, account or balance read, order list, and position list when probes are available.
+
+The self-check must never submit an order.
+
+If a required real call cannot be made, return `NOT_VERIFIED`.

package/packages/distribution/docs/skills.md

@@ -0,0 +1,140 @@
+# Skills
+
+RapidX skills are distributed through GitHub, not through the CLI npm package.
+
+Install them with the path that matches the target agent host. `npx skills add` is one supported installer, not the only installation method.
+
+## Installation Paths
+
+You can install RapidX skills in two ways:
+
+- Run the install commands yourself.
+- Send the install instructions to your agent and let the agent run the commands in its own workspace.
+
+## Option A: Run Commands Yourself
+
+## Agent Install Matrix
+
+| Agent | Recommended install path | Skill locations or discovery path |
+|-------|--------------------------|-----------------------------------|
+| Codex | `$skill-installer` in Codex, or `npx skills add ... -a codex`. | `$skill-installer` installs into `$CODEX_HOME/skills`, default `~/.codex/skills`. Workspace skills may use `.agents/skills/`; admin installs may use `/etc/codex/skills`. |
+| Claude Code | Copy to `.claude/skills/<name>/SKILL.md` or `~/.claude/skills/<name>/SKILL.md`, or use `npx skills add ... -a claude-code`. | `.claude/skills/`, `~/.claude/skills/`. |
+| Cursor | `npx skills add ... -a cursor`, or copy to `.agents/skills/`, `.cursor/skills/`, or `~/.cursor/skills/`. | `.agents/skills/`, `.cursor/skills/`, `~/.cursor/skills/`. |
+| Gemini CLI | Use `npx skills add ... -a gemini-cli` only if your environment supports the general skills installer. Current verified Gemini CLI builds expose `gemini extensions`, not `gemini skills`. | If native skills are unavailable, use RapidX CLI or MCP directly. |
+| OpenCode | Copy to `.opencode/skills/`, `~/.config/opencode/skills/`, `.claude/skills/`, or `.agents/skills/`; or use `npx skills add ... -a opencode`. | Native, Claude-compatible, and agent-compatible paths. |
+| OpenClaw | Install the published ClawHub skills by slug with `openclaw skills install <slug>`. | Workspace: `<workspace>/skills`; project-agent: `<workspace>/.agents/skills`; user: `~/.agents/skills`; managed: `~/.openclaw/skills`. |
+| Hermes Agent | Install each skill by GitHub path with `hermes skills install LiquidityTech/ltp-rapidx-skill/skills/<name>`. | Default: `~/.hermes/skills/`; external skill dirs are also supported. |
+
+## Codex
+
+```bash
+npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git \
+  --skill ltp-rapidx-config \
+  --skill ltp-rapidx-trading \
+  -a codex -y
+```
+
+Codex also supports installing from another repo through `$skill-installer`. Ask Codex to install both skills from `git@github.com:LiquidityTech/ltp-rapidx-skill.git`.
+
+## Claude Code
+
+```bash
+npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git \
+  --skill ltp-rapidx-config \
+  --skill ltp-rapidx-trading \
+  -a claude-code -y
+```
+
+Manual install paths:
+
+```text
+.claude/skills/ltp-rapidx-config/SKILL.md
+.claude/skills/ltp-rapidx-trading/SKILL.md
+~/.claude/skills/ltp-rapidx-config/SKILL.md
+~/.claude/skills/ltp-rapidx-trading/SKILL.md
+```
+
+## Cursor
+
+```bash
+npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git \
+  --skill ltp-rapidx-config \
+  --skill ltp-rapidx-trading \
+  -a cursor -y
+```
+
+## Gemini CLI
+
+```bash
+npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git \
+  --skill ltp-rapidx-config \
+  --skill ltp-rapidx-trading \
+  -a gemini-cli -y
+```
+
+Use this only when your Gemini CLI environment supports Agent Skills through the general skills installer. The verified local Gemini CLI command surface exposes `gemini extensions`, not `gemini skills`.
+
+## OpenCode
+
+```bash
+npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git \
+  --skill ltp-rapidx-config \
+  --skill ltp-rapidx-trading \
+  -a opencode -y
+```
+
+## OpenClaw
+
+```bash
+openclaw skills install ltp-rapidx-config
+openclaw skills install ltp-rapidx-trading
+```
+
+The recommended OpenClaw path is ClawHub slug installation. For local development, clone this repository and install `./skills/ltp-rapidx-config` and `./skills/ltp-rapidx-trading` as local skills.
+
+## Hermes Agent
+
+```bash
+hermes skills install LiquidityTech/ltp-rapidx-skill/skills/ltp-rapidx-config
+hermes skills install LiquidityTech/ltp-rapidx-skill/skills/ltp-rapidx-trading
+```
+
+## Manual Installation
+
+```bash
+git clone git@github.com:LiquidityTech/ltp-rapidx-skill.git
+```
+
+Copy both directories into the target agent's skill directory:
+
+```text
+skills/ltp-rapidx-config
+skills/ltp-rapidx-trading
+```
+
+## Option B: Send This To Your Agent
+
+Use this option when you want the agent to install RapidX skills itself. Send the message below to the agent:
+
+```text
+Install RapidX skills into your current workspace.
+
+Use the installation method that matches your agent host:
+- Codex: use $skill-installer or run npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git --skill ltp-rapidx-config --skill ltp-rapidx-trading -a codex -y
+- Claude Code: run npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git --skill ltp-rapidx-config --skill ltp-rapidx-trading -a claude-code -y, or install both skill folders under .claude/skills/
+- Cursor: run npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git --skill ltp-rapidx-config --skill ltp-rapidx-trading -a cursor -y
+- Gemini CLI: if your environment supports the general skills installer, run npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git --skill ltp-rapidx-config --skill ltp-rapidx-trading -a gemini-cli -y; otherwise use RapidX CLI or MCP directly
+- OpenCode: run npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git --skill ltp-rapidx-config --skill ltp-rapidx-trading -a opencode -y
+- OpenClaw: run openclaw skills install ltp-rapidx-config and openclaw skills install ltp-rapidx-trading
+- Hermes: run hermes skills install LiquidityTech/ltp-rapidx-skill/skills/ltp-rapidx-config and hermes skills install LiquidityTech/ltp-rapidx-skill/skills/ltp-rapidx-trading
+- If none of these match, clone git@github.com:LiquidityTech/ltp-rapidx-skill.git and copy skills/ltp-rapidx-config and skills/ltp-rapidx-trading into your supported skills directory.
+
+After installing the skills, follow ltp-rapidx-config to install @liquiditytech/rapidx-cli, configure RapidX credentials, choose MCP or CLI mode, and run read-only self-check.
+Use the agent host's user-provided secret mechanism for API keys when available. Do not print or store full keys in public files, logs, screenshots, or normal chat output.
+```
+
+The config skill guides the agent to install `@liquiditytech/rapidx-cli`, configure credentials, register `rapidx mcp serve`, review access, and run read-only self-check.
+
+The trading skill guides read flow, preview-first write flow, state confirmation, and small real-trade verification.
+
+For existing installations, run `rapidx update check --json` or call `rapidx/update/check` through MCP before an integration review. Reinstall the GitHub-distributed skills when the update result sets `skillsUpdateRecommended=true`.

package/packages/distribution/docs/tools.md

@@ -0,0 +1,35 @@
+# Tool Surface
+
+The canonical source is `rapidx schema --json` or `rapidx/tools`.
+
+## Discovery And Update
+
+- `rapidx/tools`: returns the MCP tool surface and schema metadata.
+- `rapidx/self-check`: verifies discovery, schema, credentials, and optional read-only probes. Pass `checkUpdates=true` to include release manifest status.
+- `rapidx/update/check`: reads the RapidX release manifest, returns version status, minimum write version, skills update advice, and upgrade commands.
+
+## Preview Tools
+
+- `rapidx/order/preview`: preview for `order.place`.
+- `rapidx/order/place-preview`: explicit alias for `order.place` preview. It returns `previewId` plus `confirmation.submitToken`.
+- `rapidx/order/amend-preview`: explicit alias for `order.amend` preview. Submit `rapidx/order/amend` with unchanged parameters, `previewId`, and `continueConsentId=confirmation.submitToken`.
+- `rapidx/order/cancel-preview`: explicit alias for `order.cancel` preview. Submit `rapidx/order/cancel` with unchanged parameters, `previewId`, and `continueConsentId=confirmation.submitToken`.
+- `rapidx/trade/preview`: generic preview for non-place trade writes, including position writes, account writes, and algo writes. Pass `targetCapabilityId`, then submit the target tool with unchanged parameters, `previewId`, and `continueConsentId`.
+
+## Read Tools
+
+- Market reads: ticker, orderbook, klines, funding rate, mark price, symbol info, and open interest.
+- Account reads: overview and balance.
+- Order reads: get, list, and history.
+- Position reads: list and position history.
+- Algo reads: list.
+
+## Write Tools
+
+- Order writes: place, amend, and cancel.
+- Position writes: close and set leverage.
+- Account writes: set position mode.
+- Algo writes: place, amend, and cancel.
+- Live verification: `rapidx/trade/verify-live` is the clearer alias for the small real-trade verification flow. `rapidx/trading-verification` remains supported for compatibility.
+
+All write tools require preview where the schema marks `previewRequired: true`.

package/packages/distribution/docs/trading-verification.md

@@ -0,0 +1,17 @@
+# Trading Verification
+
+Small real-trade verification is optional and requires explicit user consent.
+
+The expected flow is:
+
+1. read-only self-check
+2. market rule lookup
+3. explicit consent
+4. internal preview with `maxNotional`
+5. post-only limit submit
+6. order query
+7. amend when supported
+8. cancel
+9. cleanup-check
+
+Every step must include evidence.

package/packages/distribution/docs/troubleshooting/index.md

@@ -0,0 +1,27 @@
+# Troubleshooting
+
+## RCLI
+
+`RCLI13001` means the CLI rejected a complex invocation. Use the `rapidx` bin directly.
+
+`RCLI25001` means the agent host preflight blocked execution before RapidX ran. Remove shell chaining or use MCP tools.
+
+## RMCP
+
+`RMCP20001` means trade consent is missing.
+
+`RMCP20002` means preview is missing, expired, or mismatched.
+
+## RCORE
+
+`RCORE01001` means Portfolio credentials are missing.
+
+`RCORE90002` means output or audit may contain secret material and must fail closed.
+
+## RSKILL
+
+`RSKILL12001` means the skill did not require evidence.
+
+## RDIST
+
+`RDIST30001` means registry metadata is not aligned with `rapidx mcp serve`.

package/packages/distribution/manifests/offline-manifest.json

@@ -0,0 +1,26 @@
+{
+  "version": "1.0.26",
+  "artifacts": [
+    {
+      "name": "rapidx-mcp-registry",
+      "path": "packages/distribution/registry/rapidx.mcp.json",
+      "channel": "offline",
+      "checksum": "sha256:a27d7e64537c0b39574b06887e1a0f4a689851901614216a509fd19c04fdbf98",
+      "status": "ready"
+    },
+    {
+      "name": "rapidx-quickstart-doc",
+      "path": "packages/distribution/docs/quickstart.md",
+      "channel": "offline",
+      "checksum": "sha256:7d8f511a5dbe803e7a19ede0be79f6bf1b77942dbafa45d0ce87fb3b098f7829",
+      "status": "ready"
+    },
+    {
+      "name": "rapidx-tools-doc",
+      "path": "packages/distribution/docs/tools.md",
+      "channel": "offline",
+      "checksum": "sha256:ee6adae99a6facfd5f1c3dced86c7a28eafd11ecbe7e2a7eda159a6aa788a245",
+      "status": "ready"
+    }
+  ]
+}

package/packages/distribution/registry/rapidx.mcp.json

@@ -0,0 +1,26 @@
+{
+  "name": "rapidx",
+  "packageName": "@liquiditytech/rapidx-cli",
+  "version": "1.0.26",
+  "command": "rapidx",
+  "args": ["mcp", "serve"],
+  "launchCommand": "rapidx",
+  "launchArgs": ["mcp", "serve"],
+  "toolsPrefix": "rapidx/",
+  "schemaVersion": "2026-05-23",
+  "description": "RapidX production trading tools for MCP-capable agents.",
+  "manualConfigExample": {
+    "mcpServers": {
+      "rapidx": {
+        "command": "rapidx",
+        "args": ["mcp", "serve"],
+        "env": {
+          "LTP_ACCESS_KEY": "<your-access-key>",
+          "LTP_SECRET_KEY": "<your-secret-key>",
+          "LTP_API_HOST": "<provided-api-host>"
+        }
+      }
+    }
+  },
+  "safetyNotice": "Real trading requires explicit user consent, preview, and state confirmation."
+}