diff --git a/README.md b/README.md index 99d7c27..2212d95 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # ritmex-bot -基于 Bun 的 DEX 永续合约量化终端,内置趋势跟随(SMA30)与做市策略,支持快速恢复、实时行情订阅与日志追踪。 +基于 Bun 的多交易所永续合约量化终端,内置趋势跟随(SMA30)与做市策略,支持快速恢复、实时行情订阅、日志追踪与 CLI 仪表盘。 + +如果您希望获取优惠并支持本项目,请考虑使用以下注册链接: * [Aster 30% 手续费优惠注册链接](https://www.asterdex.com/zh-CN/referral/4665f3) * [Binance 手续费优惠注册链接](https://www.binance.com/join?ref=KNKCA9XC) @@ -13,34 +15,44 @@ - [English README](README_en.md) - [简明上手指南(零基础)](simple-readme.md) -## 项目亮点 -- **实时行情与风控**:Websocket + REST 自动同步账户、挂单与仓位。 +## 核心特性 +- **实时行情与风控**:Websocket + REST 自动同步账户、挂单与仓位,断线后自动恢复。 - **趋势策略**:SMA30 穿越入场,内置止损、移动止盈、布林带带宽过滤与步进锁盈。 -- **做市策略**:支持双边追价、风险阈值与订单自愈。 -- **模块化设计**:适配器、策略引擎与 CLI 解耦,方便扩展新交易所或策略。 +- **做市策略**:支持双边追价、风险阈值控制与订单自愈。 +- **模块化架构**:策略引擎、交易所适配器与 Ink CLI 相互解耦,新增交易所或策略更容易。 -## 环境要求 -- Bun ≥ 1.2(含 `bun`、`bunx` 命令) -- macOS、Linux 或 Windows (WSL 推荐) -- Node.js 仅在某些安装路径需要,可选 +## 支持的交易所 +| 交易所 | 合约类型 | 必填环境变量 | 备注 | +| --- | --- | --- | --- | +| Aster | USDT 永续 | `ASTER_API_KEY`, `ASTER_API_SECRET` | 默认交易所;兼容脚本引导 +| GRVT | USDT 永续 | `GRVT_API_KEY`, `GRVT_API_SECRET`, `GRVT_SUB_ACCOUNT_ID` | `GRVT_ENV` 可切换 `prod`/`testnet` +| Lighter | zkLighter 永续 | `LIGHTER_ACCOUNT_INDEX`, `LIGHTER_API_PRIVATE_KEY` | 默认 `LIGHTER_ENV=testnet` +| Backpack | USDC 永续 | `BACKPACK_API_KEY`, `BACKPACK_API_SECRET`, `BACKPACK_PASSWORD` | `BACKPACK_SANDBOX=true` 启用沙盒 +| Paradex | StarkEx 永续 | `PARADEX_PRIVATE_KEY`, `PARADEX_WALLET_ADDRESS` | `PARADEX_SANDBOX=true` 使用测试网 -## 快速启动脚本(macOS / Linux / WSL) +## 系统要求 +- Bun ≥ 1.2(需同时包含 `bun`、`bunx` 命令) +- macOS、Linux 或 Windows (推荐 WSL) +- Node.js 仅在部分工具链场景需要,可选 + +## 快速上手 +### 一键脚本(macOS / Linux / WSL) ```bash curl -fsSL https://github.com/discountry/ritmex-bot/raw/refs/heads/main/setup.sh | bash ``` -脚本会安装 Bun、依赖,收集 Aster API Key/Secret,生成 `.env` 并启动 CLI。运行前请准备好 API 凭证。 +脚本会安装 Bun、项目依赖,收集 Aster API 凭证,生成 `.env` 并启动 CLI。运行前请准备好对应交易所的 API Key/Secret。 -## 手动安装步骤 +### 手动安装 1. **获取代码** ```bash git clone https://github.com/discountry/ritmex-bot.git cd ritmex-bot ``` - 不方便使用 Git 时,可在仓库页面下载 ZIP 并手动解压。 + 不便使用 Git 时,可在仓库页面下载 ZIP 后手动解压。 2. **安装 Bun** - macOS / Linux:`curl -fsSL https://bun.sh/install | bash` - Windows PowerShell:`powershell -c "irm bun.sh/install.ps1 | iex"` - 安装后重新打开终端,确认 `bun -v` 正常输出版本号。 + 安装完成后重新打开终端,确认 `bun -v` 正常输出版本号。 3. **安装依赖** ```bash bun install @@ -49,67 +61,87 @@ curl -fsSL https://github.com/discountry/ritmex-bot/raw/refs/heads/main/setup.sh ```bash cp .env.example .env ``` - 按下文说明修改 `.env`,至少需要正确配置 Aster 或 GRVT 的 API。 + 按下文指南修改 `.env`,至少需要正确配置一个交易所的凭证。 5. **运行 CLI** ```bash bun run index.ts ``` - 方向键选择策略,回车启动;`Esc` 返回菜单,`Ctrl+C` 退出。 + 方向键选择策略并回车启动;`Esc` 返回菜单,`Ctrl+C` 退出。 -## 环境变量配置指南 -核心变量在 `.env.example` 中给出默认值: +## 通用环境变量 +`.env.example` 提供了所有默认键值,下表概括最常用参数: | 变量 | 说明 | | --- | --- | -| `ASTER_API_KEY` / `ASTER_API_SECRET` | Aster API 凭证,运行策略必填 | +| `EXCHANGE` | 选择交易所(`aster`/`grvt`/`lighter`/`backpack`/`paradex`) | | `TRADE_SYMBOL` | 交易对(默认 `BTCUSDT`) | | `TRADE_AMOUNT` | 单笔下单数量(标的资产计) | | `LOSS_LIMIT` | 单笔最大亏损触发的强平额度(USDT) | | `TRAILING_PROFIT` / `TRAILING_CALLBACK_RATE` | 动态止盈触发值(USDT)与回撤百分比 | | `PROFIT_LOCK_TRIGGER_USD` / `PROFIT_LOCK_OFFSET_USD` | 浮盈超过阈值后上调止损的触发金额与偏移 | -| `BOLLINGER_LENGTH` / `BOLLINGER_STD_MULTIPLIER` | 布林带宽度判定的窗口长度与标准差倍数 | -| `MIN_BOLLINGER_BANDWIDTH` | 仅当带宽 ≥ 此比例时才触发入场信号 | +| `BOLLINGER_*` | 趋势策略布林带过滤参数 | | `PRICE_TICK` / `QTY_STEP` | 交易所要求的最小报价与数量精度 | | `POLL_INTERVAL_MS` | 趋势策略循环间隔(毫秒) | | `MAX_CLOSE_SLIPPAGE_PCT` | 平仓时相对标记价允许的最大偏差 | -| `MAKER_*` 系列 | 做市策略独有参数(追价阈值、报价偏移、刷新频率等) | +| `MAKER_*` | 做市策略专属参数(追价阈值、报价偏移、刷新频率等) | -切换到 GRVT 时,将 `EXCHANGE=grvt` 并补齐 `GRVT_API_KEY`、`GRVT_API_SECRET`、`GRVT_SUB_ACCOUNT_ID` 等变量;详情见 `.env.example`。 - -> 提示:你也可以通过命令行参数临时指定交易所(优先级高于环境变量): +> 可通过命令行临时覆盖交易所与策略(优先级高于 `.env`): > ```bash -> bun run index.ts --exchange grvt -> bun run index.ts -e lighter +> bun run index.ts --exchange grvt --strategy maker +> bun run index.ts -e lighter -s offset-maker --silent > ``` -## 常用命令 +## 交易所配置指南 +### Aster +1. 将 `EXCHANGE` 保持为 `aster`(默认值)。 +2. 填写 `ASTER_API_KEY` 与 `ASTER_API_SECRET`。 +3. 根据交易对调整 `TRADE_SYMBOL`、`PRICE_TICK`、`QTY_STEP` 等精度参数。 +4. 一键脚本会自动写入这些变量,手动部署时需自行维护。 + +### GRVT +1. 在 `.env` 中设置 `EXCHANGE=grvt`。 +2. 填写 `GRVT_API_KEY`、`GRVT_API_SECRET`、`GRVT_SUB_ACCOUNT_ID`。 +3. 若使用测试网,可将 `GRVT_ENV=testnet` 并调整 `GRVT_INSTRUMENT`/`GRVT_SYMBOL`。 +4. 可选:提供 `GRVT_COOKIE` 或自定义 `GRVT_SIGNER_PATH` 以复用已有登录态。 + +### Lighter +1. 设置 `EXCHANGE=lighter`。 +2. 填写 `LIGHTER_ACCOUNT_INDEX` 与 `LIGHTER_API_PRIVATE_KEY`(40 字节十六进制私钥),其中`LIGHTER_ACCOUNT_INDEX`是你的账户索引,需要你在官网按F12观察接口请求获取,`LIGHTER_API_PRIVATE_KEY`是你的API私钥。 +3. 如需切换环境,将 `LIGHTER_ENV` 改为 `mainnet`/`staging`/`dev`;必要时指定 `LIGHTER_BASE_URL`。 +4. 交易对默认为 `LIGHTER_SYMBOL=BTCUSDT`,也可按需重写价格与数量小数位。 + +### Backpack +1. 设置 `EXCHANGE=backpack`。 +2. 填写 `BACKPACK_API_KEY`、`BACKPACK_API_SECRET`、`BACKPACK_PASSWORD`;如有分账户,补充 `BACKPACK_SUBACCOUNT`,默认填写主账户ID。 +3. 使用测试环境时将 `BACKPACK_SANDBOX=true`,并确认 `BACKPACK_SYMBOL` 与实际符号一致(默认 `BTC_USD_PERP`)。 +4. 可通过 `BACKPACK_DEBUG=true` 观察适配器详细日志。 + +### Paradex +1. 设置 `EXCHANGE=paradex`。 +2. 提供 `PARADEX_PRIVATE_KEY`(EVM 私钥)与 `PARADEX_WALLET_ADDRESS` 注意这是你EVM钱包的地址和私钥,建议创建全新钱包,不要放置无关资产。 +3. 默认连接主网,若需测试网,将 `PARADEX_SANDBOX=true` 并根据需要调整 `PARADEX_SYMBOL`。 +4. 复杂环境可额外设置 `PARADEX_USE_PRO`、`PARADEX_RECONNECT_DELAY_MS` 或调试开关。 + +## 命令速查 ```bash -bun run index.ts # 启动 CLI(默认) -bun run start # 同上 -bun run dev # 调试模式,等价于运行 index.ts -bun x vitest run # 执行单元测试 +bun run index.ts # 启动 CLI(默认入口) +bun run start # 等价于运行 index.ts +bun run dev # 调试模式 +bun x vitest run # 执行全部测试 ``` ## 静默启动与后台运行 ### 直接静默启动 无需进入 Ink 菜单,可用命令行直接拉起指定策略: - ```bash -bun run index.ts --strategy trend --silent # 启动趋势策略 -bun run index.ts --strategy maker --silent # 启动做市策略 -bun run index.ts --strategy offset-maker --silent # 启动偏移做市策略 -``` - -如需同时指定交易所,可叠加 `--exchange/-e`(将覆盖 `.env` 中的 `EXCHANGE`/`TRADE_EXCHANGE`): - -```bash -bun run index.ts --exchange grvt --strategy maker --silent -bun run index.ts -e lighter -s offset-maker --silent +bun run index.ts --strategy trend --silent +bun run index.ts --strategy maker --silent +bun run index.ts --strategy offset-maker --silent ``` +如需同时指定交易所,可叠加 `--exchange/-e` 参数。 ### 项目内置脚本 `package.json` 提供了便捷脚本: - ```bash bun run start:trend:silent bun run start:maker:silent @@ -117,43 +149,38 @@ bun run start:offset:silent ``` ### 使用 pm2 守护并自动重启 -将 `pm2` 安装到项目中(示例:`bun add -d pm2`),之后即可在不安装全局 pm2 的情况下运行: - +安装 `pm2`(示例:`bun add -d pm2`)后,可在项目内直接运行: ```bash bunx pm2 start bun --name ritmex-trend --cwd . --restart-delay 5000 -- run index.ts --strategy trend --silent ``` - -亦可直接调用脚本: - +或调用预置脚本: ```bash bun run pm2:start:trend bun run pm2:start:maker bun run pm2:start:offset ``` - -根据需要调整 `--name`、`--cwd`、`--restart-delay` 等参数,完成后可执行 `pm2 save` 持久化进程列表。 +完成配置后可执行 `pm2 save` 持久化进程列表。 ## 测试 项目使用 Vitest: ```bash -bun run test # 运行全部测试 +bun run test bun x vitest --watch ``` ## 常见问题 - -- 你需要至少 50-100 USDT 的资金才能运行策略 -- 请在交易所自行设置 50 倍左右的杠杆,本策略不包含杠杆设置 -- 请确保你电脑/服务器的时间是准确的真实世界时间 -- 持仓方式需要保持单向持仓 +- 至少准备 50–100 USDT 资金以覆盖策略运行需求。 +- 杠杆需在交易所提前设置(建议 ~50 倍),程序不会自动调整。 +- 请确保服务器/电脑时间同步真实世界时间,避免签名过期。 +- 账户需保持单向持仓模式。 - `.env` 未读取:确认文件位于项目根目录且变量名无误。 - API 拒绝访问:检查交易所后台权限,确保开启合约读写。 - 精度错误:同步交易对的最小价格与数量步长。 -更多排查步骤可参考 [简明上手指南](simple-readme.md)。 +更多排查细节可参见 [简明上手指南](simple-readme.md)。 ## 社区与支持 - Telegram 交流群:[https://t.me/+4fdo0quY87o4Mjhh](https://t.me/+4fdo0quY87o4Mjhh) -- 反馈或新特性建议请提交 Issue 或 PR +- 欢迎通过 Issue 或 PR 提交反馈、特性建议 ## 风险提示 -量化交易具备风险。建议在仿真或小额账户中验证策略表现,妥善保管 API 密钥,仅开启必要权限。 +量化交易具备风险。请先在仿真或小额账户中验证策略表现,妥善保管 API 密钥,仅开启必要权限。 diff --git a/README_en.md b/README_en.md index 5d2c50f..f1f9f6c 100644 --- a/README_en.md +++ b/README_en.md @@ -1,39 +1,56 @@ # ritmex-bot -A Bun-powered trading workstation for Aster perpetual contracts that ships two production-ready agents: an SMA30 trend follower and a dual-sided market maker. The CLI is built with Ink, synchronises risk state from the exchange, and automatically recovers from restarts or disconnects. +A Bun-powered multi-exchange perpetuals workstation that ships an SMA30 trend engine and two market-making modes. It offers instant restarts, realtime market data, structured logging, and an Ink-based CLI dashboard. + +* [Aster referral (30% fee discount)](https://www.asterdex.com/en/referral/4665f3) +* [Binance referral link](https://www.binance.com/join?ref=KNKCA9XC) +* [GRVT referral link](https://grvt.io/exchange/sign-up?ref=sea) +* [Backpack referral link](https://backpack.exchange/join/41d60948-2a75-4d16-b7e9-523df74f2904) +* [edgex referral link](https://pro.edgex.exchange/referral/BULL) +* [Paradex referral link](https://paradex.io/ref/xingxingjun) ## Documentation Map - [中文 README](README.md) - [Beginner-friendly Quick Start](simple-readme.md) ## Highlights -- **Live market data & risk sync** via websocket feeds with REST fallbacks, full reconciliation on restart. -- **Trend engine** featuring SMA30 entries, fixed stop loss, trailing stop, Bollinger bandwidth gate, and profit-lock stepping. -- **Market-making loop** with adaptive quote chasing, loss caps, and automatic order healing. -- **Extensible architecture** decoupling exchange adapters, engines, and the Ink CLI for easy venue or strategy additions. +- **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. +- **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 | +| 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 | ## Requirements -- Bun ≥ 1.2 (`bun`, `bunx` available on PATH) +- 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 environment requires it for tooling +- Node.js is optional unless your tooling requires it -## One-Line Bootstrap (macOS / Linux / WSL) +## Quick Start +### One-line bootstrap (macOS / Linux / WSL) ```bash 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 your API Key/Secret before running. +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 +### Manual installation 1. **Clone the repository** ```bash git clone https://github.com/discountry/ritmex-bot.git cd ritmex-bot ``` - Alternatively download the ZIP from GitHub and extract it manually. + 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 confirm `bun -v` prints a version. + Re-open the terminal and verify `bun -v` prints a version. 3. **Install dependencies** ```bash bun install @@ -42,67 +59,87 @@ The script installs Bun, project dependencies, collects Aster API credentials, g ```bash cp .env.example .env ``` - Edit `.env` with your exchange credentials and overrides. + Edit `.env` with the exchange credentials and overrides you plan to use. 5. **Launch the CLI** ```bash bun run index.ts ``` - Use the arrow keys to pick a strategy, `Enter` to start, `Esc` to return to the menu, and `Ctrl+C` to exit. + Use the arrow keys to pick a strategy, `Enter` to start, `Esc` to go back, and `Ctrl+C` to exit. -## Environment Variables -The most important settings shipped in `.env.example` are summarised below: +## Shared Configuration +`.env.example` captures all defaults; the most common settings are summarised below. | Variable | Purpose | | --- | --- | -| `ASTER_API_KEY` / `ASTER_API_SECRET` | Required Aster exchange credentials | -| `TRADE_SYMBOL` | Contract symbol, defaults to `BTCUSDT` | +| `EXCHANGE` | Choose the venue (`aster` / `grvt` / `lighter` / `backpack` / `paradex`) | +| `TRADE_SYMBOL` | Contract symbol (defaults to `BTCUSDT`) | | `TRADE_AMOUNT` | Order size in base asset units | -| `LOSS_LIMIT` | Max per-trade loss (USDT) before forced close | -| `TRAILING_PROFIT` / `TRAILING_CALLBACK_RATE` | Trailing stop trigger amount (USDT) and pullback percentage | -| `PROFIT_LOCK_TRIGGER_USD` / `PROFIT_LOCK_OFFSET_USD` | Move the base stop once unrealised PnL exceeds this trigger | -| `BOLLINGER_LENGTH` / `BOLLINGER_STD_MULTIPLIER` | Window size and std-dev multiplier for bandwidth filtering | -| `MIN_BOLLINGER_BANDWIDTH` | Minimum bandwidth ratio required before opening a new position | +| `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 strategy knobs: chase threshold, quote offsets, refresh cadence, etc. | +| `MAKER_*` | Maker-specific knobs (quote offsets, refresh cadence, slippage guard, etc.) | -To trade on GRVT, set `EXCHANGE=grvt` and populate `GRVT_API_KEY`, `GRVT_API_SECRET`, `GRVT_SUB_ACCOUNT_ID`, plus any optional overrides documented in `.env.example`. - -> Tip: you can temporarily override the exchange via CLI flags (takes precedence over environment): +> CLI flags override environment variables at runtime: > ```bash -> bun run index.ts --exchange grvt -> bun run index.ts -e lighter +> bun run index.ts --exchange grvt --strategy maker +> bun run index.ts -e lighter -s offset-maker --silent > ``` -## Common Commands +## 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. + +### 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). +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. +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`. +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. + +## Command Cheatsheet ```bash -bun run index.ts # Launch the CLI -bun run start # Same as above -bun run dev # Development entry point -bun x vitest run # Execute the Vitest suite +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 ``` ## Silent & Background Execution ### Direct silent launch -Skip the Ink menu and start a strategy straight from the CLI: - +Skip the Ink menu and start a strategy directly: ```bash -bun run index.ts --strategy trend --silent # Trend engine -bun run index.ts --strategy maker --silent # Maker engine -bun run index.ts --strategy offset-maker --silent # Offset maker engine -``` - -Combine with `--exchange/-e` to explicitly choose the venue (overrides `EXCHANGE`/`TRADE_EXCHANGE` from `.env`): - -```bash -bun run index.ts --exchange grvt --strategy maker --silent -bun run index.ts -e lighter -s offset-maker --silent +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 are exposed in `package.json`: - +Convenience aliases exposed via `package.json`: ```bash bun run start:trend:silent bun run start:maker:silent @@ -110,42 +147,38 @@ bun run start:offset:silent ``` ### Daemonising with pm2 -Install `pm2` locally (e.g. `bun add -d pm2`) and launch without a global install: - +Install `pm2` locally (e.g. `bun add -d pm2`) and launch the process: ```bash bunx pm2 start bun --name ritmex-trend --cwd . --restart-delay 5000 -- run index.ts --strategy trend --silent ``` - -You can also reuse the bundled scripts: - +You can also call the bundled scripts: ```bash bun run pm2:start:trend bun run pm2:start:maker bun run pm2:start:offset ``` - -Adjust `--name`, `--cwd`, or `--restart-delay` to suit your environment and run `pm2 save` if you want the process to auto-start after reboot. +Run `pm2 save` afterwards if you want the process list to survive reboots. ## Testing -Vitest powers the unit tests: +Powered by Vitest: ```bash bun run test bun x vitest --watch ``` ## Troubleshooting -- You need at least 50–100 USDT of capital before deploying a live strategy. -- Set leverage on the exchange beforehand (around 50x is recommended); the bot does not change it for you. -- Keep server/desktop time in sync with real-world time to avoid signature errors. -- Make sure the exchange account is in one-way position mode. -- **Env not loading**: ensure `.env` resides in the repository root and variable names are spelled correctly. -- **Order rejected for precision**: align `PRICE_TICK`, `QTY_STEP`, and `TRADE_SYMBOL` with the exchange filters. -- **Permission or auth errors**: double-check exchange API scopes. -More step-by-step guidance is available in [simple-readme.md](simple-readme.md). +- 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](simple-readme.md) for more detailed walkthroughs. ## Community & Support - Telegram: [https://t.me/+4fdo0quY87o4Mjhh](https://t.me/+4fdo0quY87o4Mjhh) -- Issues and PRs are welcome for bug reports and feature ideas +- Issues and PRs are welcome for bug reports and feature requests ## Disclaimer -Algorithmic trading carries risk. Validate strategies with paper accounts or small capital first, safeguard your API keys, and only grant the minimum required permissions. +Algorithmic trading carries risk. Validate strategies with paper trading or small capital first, safeguard your API keys, and only grant the minimum required permissions.