mirror of https://github.com/discountry/ritmex-bot.git synced 2026-09-09 08:18:07 +00:00

T

discountry 9538ecf265 refactor(strategy): collapse six strategy lists into one registry

Adding a strategy meant editing six places that had to agree: the StrategyId
union and a parallel Set in args.ts, STRATEGY_LABELS and a nine-branch
STRATEGY_FACTORIES in strategy-runner.ts, plus an inline id union and
BASE_STRATEGIES in App.tsx. runEngine's type parameter was additionally bounded
by a union of all nine snapshot types.

They had already drifted: the CLI gated basis on isBasisSupportedExchangeId
while the menu checked only isBasisStrategyEnabled, so the menu offered basis
on exchanges where startStrategy would throw.

- strategy-ids.ts: the id list and alias parsing, dependency-free so CLI arg
  parsing does not pull in every engine.
- registry.ts: one definition per strategy (labels, symbol, engine factory, and
  a single unavailableReason both the menu and the runner consult), keyed by a
  total Record so a new id will not compile until it is defined.
- StrategyEngine/StrategySnapshot interfaces replace the snapshot union;
  runEngine now depends only on the contract. All nine engines already satisfied
  it — no engine changed.
- App.tsx keeps only the id -> Ink view map, also a total Record.

Menu order preserved. 8 new tests, one pinning menu/CLI availability agreement.
234 pass; tsc clean. -242 lines.

2026-07-29 20:36:55 +08:00

.cursor/rules

init

2025-09-23 01:26:49 +08:00

bin

Enhance CLI command mode for ritmex-bot (#23 )

2026-02-27 12:42:20 +08:00

docs

docs: update README and add bilingual configuration guides for exchanges

2026-07-12 11:51:45 +08:00

scripts

fix(exchanges): restore type-check safety net and repair dead balance guards

2026-07-29 20:27:40 +08:00

skills/use-ritmex-bot

Enhance CLI command mode for ritmex-bot (#23 )

2026-02-27 12:42:20 +08:00

src

refactor(strategy): collapse six strategy lists into one registry

2026-07-29 20:36:55 +08:00

tests

refactor(strategy): collapse six strategy lists into one registry

2026-07-29 20:36:55 +08:00

.env.example

Feat/grid (#26 )

2026-07-21 15:30:45 +08:00

.gitignore

Add .factory to .gitignore and ensure proper newline at end of file

2026-04-06 17:58:57 +08:00

.npmignore

Add CLI user guides and .npmignore file

2026-02-27 12:47:32 +08:00

.oxlintrc.json

Add Oxlint configuration and integrate linting commands

2026-03-12 22:40:18 +08:00

AGENTS.md

docs: update repository guidelines and project structure details

2026-04-06 20:18:54 +08:00

bun.lock

fix(exchanges): restore type-check safety net and repair dead balance guards

2026-07-29 20:27:40 +08:00

CLAUDE.md

docs: update repository guidelines and project structure details

2026-04-06 20:18:54 +08:00

cli-guide.en.md

Add CLI user guides and .npmignore file

2026-02-27 12:47:32 +08:00

cli-guide.md

Add CLI user guides and .npmignore file

2026-02-27 12:47:32 +08:00

grid-trading.md

Feat/grid (#26 )

2026-07-21 15:30:45 +08:00

index.ts

init

2025-09-23 01:26:49 +08:00

package.json

fix(exchanges): restore type-check safety net and repair dead balance guards

2026-07-29 20:27:40 +08:00

README_en.md

docs: update Lighter referral link in README files

2026-07-29 19:01:53 +08:00

README.md

docs: update Lighter referral link in README files

2026-07-29 19:01:53 +08:00

setup.sh

feat: 更新 Maker 刷新间隔配置，将间隔时间从 1500ms 修改为 500ms

2025-10-03 06:59:24 +08:00

simple-readme.md

feat: 添加英文文档，更新中文文档以提升用户体验和使用指南的清晰度

2025-09-27 22:46:32 +08:00

tsconfig.json

fix(exchanges): restore type-check safety net and repair dead balance guards

2026-07-29 20:27:40 +08:00

README_en.md

ritmex-bot

Language Setting: Set LANG=en in your .env file to display the CLI interface in English.

A Bun-powered multi-exchange perpetuals workstation that ships an SMA30 trend engine, a Guardian stop sentinel, and two market-making modes. It offers instant restarts, realtime market data, structured logging, and an Ink-based CLI dashboard.

If you'd like to support this project and get fee discounts, please consider using these referral links:

CLI Command Mode (`ritmex-bot`)

ritmex-bot provides an agent-friendly command interface for exchange capability checks, market data, account/position queries, order operations, and strategy execution.

It keeps the current environment-variable system intact: no renaming and no new required keys.
--symbol is passed through exactly as provided (no symbol normalization).
It supports --dry-run simulation and --json structured output for automation.

Install This Project Skill (`skills add`)

bunx skills add https://github.com/discountry/ritmex-bot --skill use-ritmex-bot

If you need a specific branch/tag, append --ref <branch-or-tag>.

Full guide: ritmex-bot CLI User Guide (English)

Documentation Map

Highlights

Live data & risk sync via websockets with REST fallbacks and full reconciliation on restart.
Trend strategy featuring SMA30 entries, fixed stop loss, trailing stop, Bollinger bandwidth gate, and profit-lock stepping.
Guardian strategy that never opens trades but mirrors your live exposure, ensuring every position has a synced stop loss and trailing stop.
Market-making loop with dual-sided quote chasing, loss caps, and automatic order healing.
Modular architecture decoupling engines, exchange adapters, and the Ink CLI for easy venue or strategy extensions.

Supported Exchanges

Exchange	Market Type	Standard Required Settings	Notes
Aster	USDT perpetuals	`ASTER_API_KEY`, `ASTER_API_SECRET`	Production; default exchange
Binance	Spot + USDⓈ-M perpetuals	`BINANCE_API_KEY`, `BINANCE_API_SECRET`	`BINANCE_MARKET_TYPE` selects the market
StandX	USD perpetuals	`STANDX_TOKEN`, `STANDX_REQUEST_PRIVATE_KEY`	JWT authentication + Ed25519 trade signing
GRVT	USDT perpetuals	`GRVT_API_KEY`, `GRVT_API_SECRET`, `GRVT_SUB_ACCOUNT_ID`, `GRVT_INSTRUMENT`	`GRVT_ENV` supports `prod`/`testnet`
Lighter	Perpetuals + selected Spot markets	`LIGHTER_ACCOUNT_INDEX`, `LIGHTER_API_KEY_INDEX`, `LIGHTER_API_PRIVATE_KEY`	Defaults to `LIGHTER_ENV=testnet`
Backpack	Spot + USDC perpetuals	`BACKPACK_API_KEY`, `BACKPACK_API_SECRET`	Use an explicit `*_PERP` symbol for perpetuals
Paradex	USD perpetuals	`PARADEX_PRIVATE_KEY`, `PARADEX_WALLET_ADDRESS`	`PARADEX_SANDBOX=true` selects testnet
Nado	USDC perpetuals	`NADO_SIGNER_PRIVATE_KEY`, `NADO_SUBACCOUNT_OWNER`	`NADO_ENV` supports `inkMainnet`/`inkTestnet`
Ondo Perps	Crypto/equity/commodity perpetuals	`ONDOPERPS_API_KEY_ID`, `ONDOPERPS_API_SECRET`	HMAC authentication with production and sandbox endpoints

Requirements

Bun >= 1.2 (both bun and bunx on PATH)
macOS, Linux, or Windows via WSL (native Windows works but WSL is recommended)
Node.js is optional unless your tooling requires it

Quick Start

One-line bootstrap (macOS / Linux / WSL)

curl -fsSL https://github.com/discountry/ritmex-bot/raw/refs/heads/main/setup.sh | bash

The script installs Bun, project dependencies, collects Aster API credentials, generates .env, and launches the CLI. Prepare the relevant exchange API keys before running it.

Manual installation

Clone the repository
```
git clone https://github.com/discountry/ritmex-bot.git
cd ritmex-bot
```
Alternatively, download the ZIP from GitHub and extract it manually.
Install Bun
- macOS / Linux: curl -fsSL https://bun.sh/install | bash
- Windows PowerShell: powershell -c "irm bun.sh/install.ps1 | iex" Re-open the terminal and verify bun -v prints a version.
Install dependencies
```
bun install
```
Create your environment file
```
cp .env.example .env
```
Edit .env with the exchange credentials and overrides you plan to use.
Launch the CLI
```
bun run index.ts
```
Use the arrow keys to pick a strategy, Enter to start, Esc to go back, and Ctrl+C to exit.

Shared Configuration

.env.example captures all defaults; the most common settings are summarised below.

Variable	Purpose
`EXCHANGE`	Choose the venue (`aster` / `binance` / `standx` / `grvt` / `lighter` / `backpack` / `paradex` / `nado` / `ondoperps`)
`TRADE_SYMBOL`	Contract symbol (defaults to `BTCUSDT`)
`TRADE_AMOUNT`	Order size in base asset units
`LOSS_LIMIT`	Max per-trade loss in USDT before forced close
`TRAILING_PROFIT` / `TRAILING_CALLBACK_RATE`	Trailing stop trigger (USDT) and pullback percentage
`PROFIT_LOCK_TRIGGER_USD` / `PROFIT_LOCK_OFFSET_USD`	Profit lock trigger and offset thresholds
`BOLLINGER_*`	Bollinger bandwidth filters for the trend engine
`PRICE_TICK` / `QTY_STEP`	Exchange precision filters for price and quantity
`POLL_INTERVAL_MS`	Trend engine polling cadence in milliseconds
`MAX_CLOSE_SLIPPAGE_PCT`	Allowed deviation vs mark price when closing
`MAKER_*`	Maker-specific knobs (quote offsets, refresh cadence, slippage guard, etc.)

CLI flags override environment variables at runtime:
bun run index.ts --exchange grvt --strategy maker
bun run index.ts -e lighter -s offset-maker --silent

Exchange Setup Guides

Each supported exchange has a standalone Chinese and English configuration guide covering credential creation, required variables, environment selection, symbol formats, read-only verification, and security controls.

Exchange	English Guide	中文教程
Aster	Configuration Guide	配置教程
Binance	Configuration Guide	配置教程
StandX	Configuration Guide	配置教程
GRVT	Configuration Guide	配置教程
Lighter	Configuration Guide	配置教程
Backpack	Configuration Guide	配置教程
Paradex	Configuration Guide	配置教程
Nado	Configuration Guide	配置教程
Ondo Perps	Configuration Guide	配置教程

Command Cheatsheet

bun run index.ts   # Launch the CLI (default entrypoint)
bun run start      # Alias for bun run index.ts
bun run dev        # Development entrypoint
bun run lint       # Run Oxlint checks
bun run lint:fix   # Apply safe Oxlint fixes
bun x vitest run   # Execute the full Vitest suite

ritmex-bot Command Mode (Agent-friendly)

The project now supports a standalone command mode with the command name ritmex-bot:

ritmex-bot doctor
ritmex-bot exchange list
ritmex-bot market ticker --exchange binance --symbol BTCUSDT
ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000 --dry-run
ritmex-bot strategy run --strategy maker --exchange standx --silent --dry-run

Run Modes

# Global install
bun add -g ritmex-bot
ritmex-bot doctor

# No install
bunx ritmex-bot doctor

Global Flags

--exchange: picks exchange using the existing env/config logic
--symbol: passed through as-is (no symbol normalization)
--dry-run: simulation mode (no real create/cancel side effects)
--json: structured JSON output for AI agents
--timeout: command timeout in milliseconds

Silent & Background Execution

Direct silent launch

Skip the Ink menu and start a strategy directly:

bun run index.ts --strategy trend --silent
bun run index.ts --strategy maker --silent
bun run index.ts --strategy offset-maker --silent

Combine with --exchange/-e to pin the venue for that run.

Package scripts

Convenience aliases exposed via package.json:

bun run start:trend:silent
bun run start:maker:silent
bun run start:offset:silent

Daemonising with pm2

Install pm2 locally (e.g. bun add -d pm2) and launch the process:

bunx pm2 start bun --name ritmex-trend --cwd . --restart-delay 5000 -- run index.ts --strategy trend --silent

You can also call the bundled scripts:

bun run pm2:start:trend
bun run pm2:start:maker
bun run pm2:start:offset

Run pm2 save afterwards if you want the process list to survive reboots.

Testing

bun run lint
bun run lint:fix
bun run test
bun x vitest --watch

Troubleshooting

Keep at least 50-100 USDT in the account before deploying a live strategy.
Configure leverage on the exchange manually (~50x is recommended); the bot will not change it.
Ensure your server or workstation clock is in sync to avoid signature errors.
Accounts must run in one-way position mode.
Env not loading: make sure .env lives in the repo root and variable names are spelled correctly.
Permission rejected: confirm the API key has perpetual trading scopes enabled.
Precision errors: align PRICE_TICK, QTY_STEP, and TRADE_SYMBOL with the exchange filters. See simple-readme.md for more detailed walkthroughs.

Community & Support

Telegram: https://t.me/+4fdo0quY87o4Mjhh
Issues and PRs are welcome for bug reports and feature requests

Disclaimer

Algorithmic trading carries risk. Validate strategies with paper trading or small capital first, safeguard your API keys, and only grant the minimum required permissions.

README_en.md

ritmex-bot

CLI Command Mode (ritmex-bot)

Install This Project Skill (skills add)

Documentation Map

Highlights

Supported Exchanges

Requirements

Quick Start

One-line bootstrap (macOS / Linux / WSL)

Manual installation

Shared Configuration

Exchange Setup Guides

Command Cheatsheet

ritmex-bot Command Mode (Agent-friendly)

Run Modes

Global Flags

Silent & Background Execution

Direct silent launch

Package scripts

Daemonising with pm2

Testing

Troubleshooting

Community & Support

Disclaimer

CLI Command Mode (`ritmex-bot`)

Install This Project Skill (`skills add`)