mirror of
https://github.com/discountry/ritmex-bot.git
synced 2026-09-09 08:18:07 +00:00
Enhance CLI command mode for ritmex-bot (#23)
- Introduced a new command mode for `ritmex-bot`, allowing agent-friendly structured trading operations without entering the Ink interactive menu. - Updated `package.json` to include versioning and set the project as public with a new CLI entry point. - Enhanced documentation in both English and Chinese to provide comprehensive usage instructions for the new command mode. - Added a new executable script for `ritmex-bot` to facilitate command execution. - Improved error handling and command parsing for better user experience and clarity in command execution.
This commit is contained in:
Disney
@@ -0,0 +1,306 @@
|
||||
---
|
||||
name: use-ritmex-bot
|
||||
description: Use when the task requires operating exchanges with the ritmex-bot CLI, including capability checks, market/account/position queries, order operations, strategy run, dry-run simulation, and JSON output parsing.
|
||||
---
|
||||
|
||||
# Use ritmex-bot CLI
|
||||
|
||||
This skill is for running `ritmex-bot` in an agent-safe, exchange-compatible way.
|
||||
|
||||
## Use This Skill When
|
||||
|
||||
- The user asks to use `ritmex-bot` commands directly.
|
||||
- The user wants market data, account/position, or order operations from supported exchanges.
|
||||
- The user wants AI-agent-friendly CLI execution with `--json` output.
|
||||
- The user wants simulation with `--dry-run` before real writes.
|
||||
|
||||
## Hard Rules
|
||||
|
||||
1. Do not change environment-variable names and do not invent new env keys.
|
||||
2. Read config from the current shell environment as-is.
|
||||
3. Do not normalize or rewrite `--symbol`; pass it through exactly.
|
||||
4. If a feature is not supported by an exchange, return it as unsupported (`UNSUPPORTED`), do not fake behavior.
|
||||
5. For write actions (`order create`, `order cancel`, `order cancel-all`), prefer `--dry-run` first unless the user explicitly asks to skip simulation.
|
||||
6. Use `--json` whenever output must be consumed by another agent/tool.
|
||||
|
||||
## Command Entry Options
|
||||
|
||||
Use one of these:
|
||||
|
||||
```bash
|
||||
ritmex-bot <command>
|
||||
npx ritmex-bot <command>
|
||||
bunx ritmex-bot <command>
|
||||
bun run index.ts <command>
|
||||
```
|
||||
|
||||
If `ritmex-bot` is unavailable, use `bun run index.ts <command>` from repo root.
|
||||
|
||||
## Default Agent Workflow
|
||||
|
||||
1. Determine exchange and symbol from user request.
|
||||
2. If missing, rely on existing env resolution; do not create fallback env variables.
|
||||
3. Run capability precheck:
|
||||
- `exchange list`
|
||||
- `exchange capabilities --exchange <id>`
|
||||
4. For read operations, run command directly (prefer `--json`).
|
||||
5. For write operations:
|
||||
- Run the exact command with `--dry-run --json`.
|
||||
- Validate payload and dry-run actions.
|
||||
- Run live command only when user confirmed or explicitly requested live execution.
|
||||
6. Post-check with `order open`, `position list`, or `account snapshot` as needed.
|
||||
|
||||
## Global Flags
|
||||
|
||||
| Flag | Short | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `--exchange` | `-e` | Exchange override |
|
||||
| `--symbol` | - | Trading symbol (pass-through) |
|
||||
| `--json` | `-j` | JSON output |
|
||||
| `--dry-run` | `-d` | Simulate write ops |
|
||||
| `--timeout` | `-t` | Timeout in ms (default 25000) |
|
||||
| `--help` | `-h` | Show help |
|
||||
|
||||
## Root Commands
|
||||
|
||||
- `help`
|
||||
- `doctor`
|
||||
- `exchange`
|
||||
- `market`
|
||||
- `account`
|
||||
- `position`
|
||||
- `order`
|
||||
- `strategy`
|
||||
|
||||
## Command Reference
|
||||
|
||||
### `doctor`
|
||||
|
||||
```bash
|
||||
ritmex-bot doctor
|
||||
ritmex-bot doctor --exchange binance --symbol BTCUSDT --json
|
||||
```
|
||||
|
||||
Returns effective setup and runtime capabilities.
|
||||
|
||||
### `exchange`
|
||||
|
||||
```bash
|
||||
ritmex-bot exchange list
|
||||
ritmex-bot exchange capabilities --exchange standx
|
||||
```
|
||||
|
||||
If runtime adapter cannot initialize, capabilities may fallback to static metadata.
|
||||
|
||||
### `market`
|
||||
|
||||
```bash
|
||||
ritmex-bot market ticker --exchange <id> --symbol <symbol>
|
||||
ritmex-bot market depth --exchange <id> --symbol <symbol> --levels 10
|
||||
ritmex-bot market kline --exchange <id> --symbol <symbol> --interval 1m --limit 100
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `kline` requires `--interval`.
|
||||
- `depth --levels` is optional.
|
||||
- `kline --limit` is optional.
|
||||
|
||||
### `account`
|
||||
|
||||
```bash
|
||||
ritmex-bot account snapshot --exchange <id>
|
||||
ritmex-bot account summary --exchange <id>
|
||||
```
|
||||
|
||||
`summary` is an alias of `snapshot`.
|
||||
|
||||
### `position`
|
||||
|
||||
```bash
|
||||
ritmex-bot position list --exchange <id>
|
||||
ritmex-bot position list --exchange <id> --symbol <symbol>
|
||||
```
|
||||
|
||||
### `order`
|
||||
|
||||
### Query open orders
|
||||
|
||||
```bash
|
||||
ritmex-bot order open --exchange <id> --symbol <symbol>
|
||||
```
|
||||
|
||||
### Create order
|
||||
|
||||
```bash
|
||||
ritmex-bot order create --exchange <id> --symbol <symbol> --side buy --type limit --quantity 0.01 --price 90000
|
||||
```
|
||||
|
||||
Required:
|
||||
|
||||
- `--side` = `buy|sell`
|
||||
- `--type` = `limit|market|stop|trailing-stop|close`
|
||||
- `--quantity` or `--qty`
|
||||
|
||||
Conditional required:
|
||||
|
||||
- `limit`: `--price`
|
||||
- `stop`: `--stop-price`
|
||||
- `trailing-stop`: `--activation-price` and `--callback-rate`
|
||||
|
||||
Optional:
|
||||
|
||||
- `--time-in-force` (`GTC|IOC|FOK|GTX`)
|
||||
- `--reduce-only` (`true|false`)
|
||||
- `--close-position` (`true|false`)
|
||||
- `--trigger-type` (`UNSPECIFIED|TAKE_PROFIT|STOP_LOSS`)
|
||||
- `--sl-price`
|
||||
- `--tp-price`
|
||||
|
||||
### Cancel one order
|
||||
|
||||
```bash
|
||||
ritmex-bot order cancel --exchange <id> --symbol <symbol> --order-id <id>
|
||||
```
|
||||
|
||||
### Cancel all
|
||||
|
||||
```bash
|
||||
ritmex-bot order cancel-all --exchange <id> --symbol <symbol>
|
||||
```
|
||||
|
||||
### `strategy`
|
||||
|
||||
```bash
|
||||
ritmex-bot strategy run --strategy maker --exchange standx --silent
|
||||
ritmex-bot strategy run --strategy offset --exchange binance --dry-run
|
||||
```
|
||||
|
||||
Supported strategy IDs:
|
||||
|
||||
- `trend`
|
||||
- `swing`
|
||||
- `guardian`
|
||||
- `maker`
|
||||
- `maker-points`
|
||||
- `offset-maker`
|
||||
- `liquidity-maker`
|
||||
- `basis`
|
||||
- `grid`
|
||||
|
||||
Aliases:
|
||||
|
||||
- `offset` -> `offset-maker`
|
||||
- `makerpoints` / `maker_points` -> `maker-points`
|
||||
- `liquidity` / `liquiditymaker` / `liquidity_maker` -> `liquidity-maker`
|
||||
|
||||
Extra flags:
|
||||
|
||||
- `--silent` (short alias `-q`)
|
||||
- `--dry-run`
|
||||
|
||||
## Dry-Run First Patterns
|
||||
|
||||
### Create order safely
|
||||
|
||||
```bash
|
||||
# 1) Simulate
|
||||
ritmex-bot order create --exchange <id> --symbol <symbol> --side buy --type limit --quantity 0.01 --price 90000 --dry-run --json
|
||||
|
||||
# 2) Execute live only after confirmation
|
||||
ritmex-bot order create --exchange <id> --symbol <symbol> --side buy --type limit --quantity 0.01 --price 90000 --json
|
||||
```
|
||||
|
||||
### Cancel safely
|
||||
|
||||
```bash
|
||||
# 1) Simulate
|
||||
ritmex-bot order cancel --exchange <id> --symbol <symbol> --order-id <id> --dry-run --json
|
||||
|
||||
# 2) Execute live
|
||||
ritmex-bot order cancel --exchange <id> --symbol <symbol> --order-id <id> --json
|
||||
```
|
||||
|
||||
## Agent Output Handling
|
||||
|
||||
Prefer `--json` and parse:
|
||||
|
||||
- `success` (boolean)
|
||||
- `command` (executed command kind)
|
||||
- `exchange`
|
||||
- `symbol`
|
||||
- `dryRun`
|
||||
- `data` (success payload)
|
||||
- `error.code`, `error.message`, `error.retryable` (failure payload)
|
||||
|
||||
Human-readable mode is fine for manual terminal use; `--json` is preferred for automation.
|
||||
|
||||
## Error Codes and Exit Codes
|
||||
|
||||
Map failures by code/exit code:
|
||||
|
||||
- `INVALID_ARGS` -> exit `2`
|
||||
- `MISSING_ENV` -> exit `3`
|
||||
- `UNSUPPORTED` -> exit `5`
|
||||
- `EXCHANGE_ERROR` -> exit `6`
|
||||
- `TIMEOUT` -> exit `7`
|
||||
|
||||
Handling policy:
|
||||
|
||||
1. `INVALID_ARGS`: fix command arguments and retry once.
|
||||
2. `MISSING_ENV`: report missing configuration; do not invent env keys.
|
||||
3. `UNSUPPORTED`: return clearly as unsupported for that exchange.
|
||||
4. `EXCHANGE_ERROR`: return details and retry only if user requests.
|
||||
5. `TIMEOUT`: optionally retry with larger `--timeout` once.
|
||||
|
||||
## Symbol and Exchange-Specific Behavior
|
||||
|
||||
- Never apply cross-exchange symbol mapping inside the skill.
|
||||
- Respect user-provided symbols exactly (examples: `BTCUSDT`, `BTCUSDC`, `BTC_USD_PERP`, `BTC-PERP`).
|
||||
- If no `--symbol` is provided, let existing exchange config resolve it.
|
||||
- If no `--exchange` is provided, let existing env resolution decide it.
|
||||
|
||||
## Ready-to-Use Recipes
|
||||
|
||||
### Preflight
|
||||
|
||||
```bash
|
||||
ritmex-bot exchange list --json
|
||||
ritmex-bot exchange capabilities --exchange <id> --json
|
||||
ritmex-bot doctor --exchange <id> --symbol <symbol> --json
|
||||
```
|
||||
|
||||
### Read-only market/account state
|
||||
|
||||
```bash
|
||||
ritmex-bot market ticker --exchange <id> --symbol <symbol> --json
|
||||
ritmex-bot market depth --exchange <id> --symbol <symbol> --levels 20 --json
|
||||
ritmex-bot market kline --exchange <id> --symbol <symbol> --interval 1m --limit 120 --json
|
||||
ritmex-bot account snapshot --exchange <id> --json
|
||||
ritmex-bot position list --exchange <id> --symbol <symbol> --json
|
||||
```
|
||||
|
||||
### Write flow (safe)
|
||||
|
||||
```bash
|
||||
ritmex-bot order create --exchange <id> --symbol <symbol> --side buy --type market --qty 0.01 --dry-run --json
|
||||
ritmex-bot order create --exchange <id> --symbol <symbol> --side buy --type market --qty 0.01 --json
|
||||
ritmex-bot order open --exchange <id> --symbol <symbol> --json
|
||||
```
|
||||
|
||||
### Strategy flow
|
||||
|
||||
```bash
|
||||
ritmex-bot strategy run --strategy trend --exchange <id> --dry-run
|
||||
ritmex-bot strategy run --strategy trend --exchange <id> --silent
|
||||
```
|
||||
|
||||
## Completion Checklist
|
||||
|
||||
Before returning results to user:
|
||||
|
||||
1. Confirm command and parameters used.
|
||||
2. Confirm whether run was `dryRun` or live.
|
||||
3. For live writes, provide immediate post-check output (`order open` / `position list`).
|
||||
4. If unsupported, explicitly name exchange + unsupported method.
|
||||
5. If failed, return error code/message and next corrective action.
|
||||
Reference in New Issue
Block a user