Skip to content

Latest commit

 

History

History
310 lines (262 loc) · 14.6 KB

README_en.md

File metadata and controls

310 lines (262 loc) · 14.6 KB

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)

npx 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 Contract Type Required Environment Variables Notes
Aster USDT perpetuals ASTER_API_KEY, ASTER_API_SECRET Default venue; works with the bootstrap script
StandX USD perpetuals STANDX_TOKEN Uses JWT token auth; prefer websocket streams
GRVT USDT perpetuals GRVT_API_KEY, GRVT_API_SECRET, GRVT_SUB_ACCOUNT_ID Switch GRVT_ENV between prod and testnet
Lighter zkLighter perpetuals LIGHTER_ACCOUNT_INDEX, LIGHTER_API_PRIVATE_KEY Defaults to LIGHTER_ENV=testnet
Backpack USDC perpetuals BACKPACK_API_KEY, BACKPACK_API_SECRET, BACKPACK_PASSWORD Set BACKPACK_SANDBOX=true for the sandbox
Paradex StarkEx perpetuals PARADEX_PRIVATE_KEY, PARADEX_WALLET_ADDRESS Toggle PARADEX_SANDBOX=true for the testnet
Nado USDC perpetuals NADO_SIGNER_PRIVATE_KEY, NADO_SUBACCOUNT_OWNER Switch NADO_ENV between inkMainnet and inkTestnet

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

  1. 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.
  2. 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.
  3. Install dependencies 
    bun install
  4. Create your environment file 
    cp .env.example .env
    Edit .env with the exchange credentials and overrides you plan to use.
  5. 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)
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

Aster

  1. Keep EXCHANGE=aster (default value).
  2. Supply ASTER_API_KEY and ASTER_API_SECRET.
  3. Adjust TRADE_SYMBOL, PRICE_TICK, and QTY_STEP to match the requested market.
  4. The bootstrap script auto-populates these variables; manual installs must maintain them.

Binance

  1. Set EXCHANGE=binance.
  2. Provide BINANCE_API_KEY and BINANCE_API_SECRET.
  3. Set market mode via BINANCE_MARKET_TYPE:
    • perp: perpetual futures (default)
    • spot: spot market
    • auto: resolve by symbol (not recommended when both spot/perp share the same symbol)
  4. Set BINANCE_SYMBOL (or fallback to TRADE_SYMBOL):
    • Perp recommended: BTCUSDT_PERP (or BTCUSDT with BINANCE_MARKET_TYPE=perp)
    • Spot recommended: BTCUSDT (also accepts BTCUSDT_SPOT)
  5. For Basis arbitrage on Binance, explicitly split legs:
    • BASIS_FUTURES_SYMBOL=BTCUSDT_PERP
    • BASIS_SPOT_SYMBOL=BTCUSDT
  6. Optional sandbox/custom endpoints:
    • BINANCE_SANDBOX=true
    • BINANCE_SPOT_REST_URL / BINANCE_FUTURES_REST_URL
    • BINANCE_SPOT_WS_URL / BINANCE_FUTURES_WS_URL

The Binance adapter is WS-first by default (depth/ticker/kline/account/order streams), with REST used only for reconciliation and fallback.

In spot mode, some derivatives-only protective order capabilities are exchange-limited, and the strategy will degrade gracefully based on venue capabilities.

Example (perp maker)

EXCHANGE=binance BINANCE_MARKET_TYPE=perp BINANCE_SYMBOL=BTCUSDT_PERP bun run index.ts --strategy maker

Example (spot grid)

EXCHANGE=binance BINANCE_MARKET_TYPE=spot BINANCE_SYMBOL=BTCUSDT bun run index.ts --strategy grid

StandX

The strategy requires a StandX API Token and signing private key to place orders.

How to obtain (using StandX's official API generation feature):

  1. Open the StandX official API creation page: https://standx.com/user/session
  2. Connect your wallet and log in
  3. Click the "Generate API Token" button
  4. The page will display the following information:
    • Token (JWT string starting with eyJ) → Fill in STANDX_TOKEN
    • Ed25519 Private Key (Base58 format, like HdsyJD7oWgT...) → Fill in STANDX_REQUEST_PRIVATE_KEY
    • Creation date and Validity days → Used to configure token expiry reminders

The Ed25519 Private Key is an auto-generated signing key used only for trade request signatures. Your assets remain in your main wallet and are completely safe.

Please keep these credentials safe and do not share them with anyone.

Configuration steps:

  1. Set EXCHANGE=standx.
  2. Provide STANDX_TOKEN (JWT token for perps API).
  3. Provide STANDX_REQUEST_PRIVATE_KEY (Ed25519 signing private key, Base58 format).
  4. Set STANDX_SYMBOL (defaults to BTC-USD) and align PRICE_TICK / QTY_STEP.
  5. Recommended: configure token expiry settings:
    • STANDX_TOKEN_CREATE_DATE (creation date, format YYYY-MM-DD)
    • STANDX_TOKEN_VALIDITY_DAYS (validity days)
  6. Optional: STANDX_BASE_URL, STANDX_WS_URL, or STANDX_SESSION_ID for custom endpoints.

GRVT

  1. Set EXCHANGE=grvt inside .env.
  2. Fill GRVT_API_KEY, GRVT_API_SECRET, and GRVT_SUB_ACCOUNT_ID.
  3. Use GRVT_ENV=testnet when targeting the test environment, and align GRVT_INSTRUMENT / GRVT_SYMBOL.
  4. Optional: provide GRVT_COOKIE or a custom GRVT_SIGNER_PATH when reusing an existing session.

Lighter

  1. Set EXCHANGE=lighter.
  2. Provide LIGHTER_ACCOUNT_INDEX and LIGHTER_API_PRIVATE_KEY (40-byte hex private key). LIGHTER_ACCOUNT_INDEX is your account index, which you can find by opening DevTools (F12) on the official website and observing API requests. LIGHTER_API_PRIVATE_KEY is your API private key.
  3. Switch LIGHTER_ENV to mainnet, staging, or dev when necessary; override LIGHTER_BASE_URL if endpoints differ.
  4. LIGHTER_SYMBOL defaults to BTCUSDT; override price/size decimals when markets differ.

Backpack

  1. Set EXCHANGE=backpack.
  2. Populate BACKPACK_API_KEY, BACKPACK_API_SECRET, and BACKPACK_PASSWORD; add BACKPACK_SUBACCOUNT if you trade from a subaccount (defaults to main account ID).
  3. Toggle BACKPACK_SANDBOX=true for the sandbox environment and verify BACKPACK_SYMBOL matches the contract (defaults to BTC_USD_PERP).
  4. Enable BACKPACK_DEBUG=true for verbose adapter logging.

Paradex

  1. Set EXCHANGE=paradex.
  2. Provide PARADEX_PRIVATE_KEY (EVM private key) and PARADEX_WALLET_ADDRESS. Note: These are your EVM wallet address and private key. It is recommended to create a brand new wallet and avoid storing unrelated assets in it.
  3. The adapter connects to mainnet by default; enable PARADEX_SANDBOX=true and adjust PARADEX_SYMBOL for testnet usage.
  4. Advanced tuning: use PARADEX_USE_PRO, PARADEX_RECONNECT_DELAY_MS, or debug flags as needed.

Nado

  1. Set EXCHANGE=nado.
  2. On the Nado web app (trading interface), open DevTools (F12) -> switch to the Application tab -> Local Storage, locate nado.userSettings, then grab the privateKey field from its JSON value and paste it into .env as NADO_SIGNER_PRIVATE_KEY.
  3. Provide NADO_SUBACCOUNT_OWNER (or NADO_EVM_ADDRESS).
  4. Select network via NADO_ENV=inkMainnet (mainnet) or inkTestnet (testnet).
  5. Set NADO_SYMBOL using Nado product symbols like BTC-PERP (it also accepts BTCUSDT0 and maps it to BTC-PERP).

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 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
npm install -g ritmex-bot
ritmex-bot doctor

# No install
npx ritmex-bot doctor
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

Powered by Vitest:

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

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.