From b45539b7c2d19e6722bb7297e6d11fee15048da4 Mon Sep 17 00:00:00 2001 From: discountry Date: Sat, 27 Sep 2025 22:46:32 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E8=8B=B1=E6=96=87?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=8C=E6=9B=B4=E6=96=B0=E4=B8=AD=E6=96=87?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E4=BB=A5=E6=8F=90=E5=8D=87=E7=94=A8=E6=88=B7?= =?UTF-8?q?=E4=BD=93=E9=AA=8C=E5=92=8C=E4=BD=BF=E7=94=A8=E6=8C=87=E5=8D=97?= =?UTF-8?q?=E7=9A=84=E6=B8=85=E6=99=B0=E5=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 254 +++++++++++--------------------------- README_en.md | 99 +++++++++++++++ simple-readme.md | 309 ++++++++++++++++++++--------------------------- 3 files changed, 297 insertions(+), 365 deletions(-) create mode 100644 README_en.md diff --git a/README.md b/README.md index 7db8fef..a6ccc57 100644 --- a/README.md +++ b/README.md @@ -1,220 +1,102 @@ # ritmex-bot -一个基于 Bun 的 Aster 永续合约终端机器人，内置趋势跟随（SMA30）与做市策略，使用 websocket 实时行情，命令行界面由 Ink 驱动，可在断线后自动恢复运行。 +基于 Bun 的 Aster 永续合约量化终端，内置趋势跟随（SMA30）与做市策略，支持快速恢复、实时行情订阅与日志追踪。 -## 快速上手 +* [Aster 30% 手续费优惠注册链接](https://www.asterdex.com/zh-CN/referral/4665f3) +* [GRVT 手续费优惠注册链接](https://grvt.io/exchange/sign-up?ref=sea) -使用优惠码获取 30% 手续费折扣：[注册 Aster 获取手续费优惠](https://www.asterdex.com/zh-CN/referral/4665f3) +## 文档索引 +- [English README](README_en.md) +- [简明上手指南（零基础）](simple-readme.md) +- `legacy/docs/`：旧版策略与架构说明 -如果你完全不懂代码，可以查看 **[小白教程](simple-readme.md) 了解使用方法。** +## 项目亮点 +- **实时行情与风控**：Websocket + REST 自动同步账户、挂单与仓位。 +- **趋势策略**：SMA30 穿越入场，内置止损、移动止盈、布林带带宽过滤与步进锁盈。 +- **做市策略**：支持双边追价、风险阈值与订单自愈。 +- **模块化设计**：适配器、策略引擎与 CLI 解耦，方便扩展新交易所或策略。 -遇到Bug，反馈问题，请到 [Telegram群组](https://t.me/+4fdo0quY87o4Mjhh) +## 环境要求 +- Bun ≥ 1.2（含 `bun`、`bunx` 命令） +- macOS、Linux 或 Windows (WSL 推荐) +- Node.js 仅在某些安装路径需要，可选 -### 一键脚本 - -一键安装并启动（macOS / Linux）： +## 快速启动脚本（macOS / Linux / WSL） ```bash curl -fsSL https://github.com/discountry/ritmex-bot/raw/refs/heads/main/setup.sh | bash ``` -脚本会自动安装 Bun、安装依赖、引导输入 API Key/Secret，生成 `.env` 并启动程序。 +脚本会安装 Bun、依赖，收集 Aster API Key/Secret，生成 `.env` 并启动 CLI。运行前请准备好 API 凭证。 -Windows 使用 WSL（推荐）： -1. 先安装并启用 WSL，参考微软官方文档：[在 Windows 上安装 WSL](https://learn.microsoft.com/zh-cn/windows/wsl/install) -2. 在命令行或者 PowerShell 输入 `wsl` 并按下回车打开 WSL。 -3. 在 WSL 中运行一键脚本： +## 手动安装步骤 +1. **获取代码** ```bash - curl -fsSL https://github.com/discountry/ritmex-bot/raw/refs/heads/main/setup.sh | bash + git clone https://github.com/discountry/ritmex-bot.git + cd ritmex-bot ``` - 按提示输入 ASTER_API_KEY / ASTER_API_SECRET，脚本将自动安装 Bun、依赖并启动程序。 - -## 手动安装 - -1. **下载代码** - - 如果会使用 Git：`git clone https://github.com/discountry/ritmex-bot.git` - - 如果不会使用 Git：点击仓库页面的 `Code` → `Download ZIP`，将压缩包解压到如 `桌面/ritmex-bot` 的目录。 -2. **打开命令行并进入项目目录** - - macOS：通过 Spotlight (`⌘ + 空格`) 搜索 “Terminal” 并打开。 - - Windows：在开始菜单搜索 “PowerShell” 或 “Windows Terminal” 并打开。 - - 使用 `cd` 切换到项目目录，例如： - ```bash - # macOS / Linux - cd ~/Desktop/ritmex-bot - # Windows - cd C:\Users\用户名\Desktop\ritmex-bot - ``` -3. **安装 [Bun](https://bun.com) ≥ 1.2** - - macOS / Linux： - ```bash - curl -fsSL https://bun.sh/install | bash - ``` - - Windows（PowerShell）： - ```powershell - powershell -c "irm bun.sh/install.ps1 | iex" - ``` - 安装完成后关闭并重新打开终端，运行 `bun -v` 确认命令可用。 - - 如果上述命令无法完成安装，请尝试 [bun官网](https://bun.com/get) 提供的各种安装方式。 - - Windows 用户如果无法正常安装，可以尝试先[安装 nodejs](https://nodejs.org/en/download) - - 然后使用 `npm` 安装 `bun`： - ```bash - npm install -g bun - ``` -4. **安装依赖** + 不方便使用 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` 正常输出版本号。 +3. **安装依赖** ```bash bun install ``` -5. **配置环境变量** - 复制 `.env.example` 为 `.env` 并填入你的 Aster API Key/Secret： +4. **复制环境变量模板并填写** ```bash cp .env.example .env ``` - 然后根据需要修改 `.env` 中的配置项： - - API KEY 获取地址 [https://www.asterdex.com/zh-CN/api-management](https://www.asterdex.com/zh-CN/api-management) - - `ASTER_API_KEY` / `ASTER_API_SECRET`：Aster 交易所提供的 API 凭证。 - - `TRADE_SYMBOL`：策略运行的交易对（默认 `BTCUSDT`），需与 API 权限范围一致。 - - `TRADE_AMOUNT`：单次下单数量（合约张数折算后单位为标的货币，例如 BTC）。 - - `LOSS_LIMIT`：单笔允许的最大亏损（USDT），触发即强制平仓。 - - `TRAILING_PROFIT` / `TRAILING_CALLBACK_RATE`：趋势策略的动态止盈触发值（单位 USDT）与回撤百分比（百分数，如 0.2 表示 0.2%）。 - - `PROFIT_LOCK_TRIGGER_USD` / `PROFIT_LOCK_OFFSET_USD`：达到一定浮盈后，将基础止损上调（做多）或下调（做空）到开仓价的偏移量（单位 USDT）。 - - `BOLLINGER_LENGTH` / `BOLLINGER_STD_MULTIPLIER` / `MIN_BOLLINGER_BANDWIDTH`：布林带宽度过滤参数，默认使用 20 根 1 分钟 K 线及 2 倍标准差，仅当带宽比例 ≥ 0.1 时允许入场。 - - `PRICE_TICK` / `QTY_STEP`：交易对的最小价格变动单位与最小下单数量步长（例如 BTCUSDT 分别为 0.1 与 0.001）。 - - `MAKER_*` 参数：做市策略追价阈值、报价偏移、刷新频率等，可按流动性需求调节。 -6. **运行机器人** + 按下文说明修改 `.env`，至少需要正确配置 Aster 或 GRVT 的 API。 +5. **运行 CLI** ```bash bun run index.ts ``` - 在终端中按 ↑/↓ 选择 “趋势策略” 或 “做市策略”，回车启动。按 `Esc` 可返回选择菜单，`Ctrl+C` 退出。 -7. **风险提示** - 建议先在小额或仿真环境中测试策略；真实资金操作前请确认 API 仅开启必要权限，并逐步验证配置。 + 方向键选择策略，回车启动；`Esc` 返回菜单，`Ctrl+C` 退出。 -A Bun-powered trading workstation for Aster perpetual contracts. The project ships two production strategies—an SMA30 trend follower and a dual-sided maker—that share a modular gateway, UI, and runtime state derived entirely from the exchange. Everything runs in the terminal via Ink, with live websocket refresh and automatic recovery from restarts or network failures. +## 环境变量配置指南 +核心变量在 `.env.example` 中给出默认值： -## Features -- **Live data over websockets** with REST fallbacks and automatic re-sync after reconnects. -- **Trend strategy**: SMA30 crossover entries, automated stop-loss / trailing-stop, and P&L tracking. -- **Maker strategy**: adaptive bid/ask chasing, risk stops, and target order introspection. -- **Extensibility**: exchange gateway, engines, and UI components are modular for new venues or strategies. +| 变量 | 说明 | +| --- | --- | +| `ASTER_API_KEY` / `ASTER_API_SECRET` | Aster API 凭证，运行策略必填 | +| `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` | 仅当带宽 ≥ 此比例时才触发入场信号 | +| `PRICE_TICK` / `QTY_STEP` | 交易所要求的最小报价与数量精度 | +| `POLL_INTERVAL_MS` | 趋势策略循环间隔（毫秒） | +| `MAX_CLOSE_SLIPPAGE_PCT` | 平仓时相对标记价允许的最大偏差 | +| `MAKER_*` 系列 | 做市策略独有参数（追价阈值、报价偏移、刷新频率等） | -## Requirements -- [Bun](https://bun.com) ≥ 1.2 -- Node.js (optional, only if you prefer `npm` tooling) -- Valid Aster API credentials with futures access +切换到 GRVT 时，将 `EXCHANGE=grvt` 并补齐 `GRVT_API_KEY`、`GRVT_API_SECRET`、`GRVT_SUB_ACCOUNT_ID` 等变量；详情见 `.env.example`。 -## Installation +## 常用命令 ```bash -bun install +bun run index.ts # 启动 CLI（默认） +bun run start # 同上 +bun run dev # 调试模式，等价于运行 index.ts +bun x vitest run # 执行单元测试 ``` -## Configuration -Create an `.env` (or export environment variables) with at least: +## 测试 +项目使用 Vitest： ```bash -ASTER_API_KEY=your_key -ASTER_API_SECRET=your_secret -TRADE_SYMBOL=BTCUSDT # optional, defaults to BTCUSDT -TRADE_AMOUNT=0.001 # position size used by both strategies -LOSS_LIMIT=0.03 # per-trade USD loss cap -TRAILING_PROFIT=0.2 # trailing activation profit in USDT -TRAILING_CALLBACK_RATE=0.2 # trailing callback in percent, e.g. 0.2 => 0.2% -PROFIT_LOCK_TRIGGER_USD=0.1 # profit threshold to start moving base stop (USDT) -PROFIT_LOCK_OFFSET_USD=0.05 # base stop offset from entry after trigger (USDT) -PRICE_TICK=0.1 # price tick size; set per symbol -QTY_STEP=0.001 # quantity step size; set per symbol -``` -Additional maker-specific knobs (`MAKER_*`) live in `src/config.ts` and may be overridden via env vars: -```bash -# Maker-specific (units in USDT unless noted) -MAKER_LOSS_LIMIT=0.03 # override maker risk stop; defaults to LOSS_LIMIT -MAKER_PRICE_CHASE=0.3 # chase threshold -MAKER_BID_OFFSET=0 # bid offset from top bid (USDT) -MAKER_ASK_OFFSET=0 # ask offset from top ask (USDT) -MAKER_REFRESH_INTERVAL_MS=1500 # maker refresh cadence (ms) -MAKER_MAX_CLOSE_SLIPPAGE_PCT=0.05 # allowed deviation vs mark when closing -MAKER_PRICE_TICK=0.1 # maker tick size; defaults to PRICE_TICK +bun run test # 运行全部测试 +bun x vitest --watch ``` -To switch the entire CLI to GRVT instead of Aster, set `EXCHANGE=grvt` and provide the programmable API credentials: +## 常见问题 +- `.env` 未读取：确认文件位于项目根目录且变量名无误。 +- API 拒绝访问：检查交易所后台权限，确保开启合约读写。 +- 精度错误：同步交易对的最小价格与数量步长。 +更多排查步骤可参考 [简明上手指南](simple-readme.md)。 -```bash -EXCHANGE=grvt -GRVT_API_KEY=your_api_key -GRVT_API_SECRET=0xabc123... # private key used for EIP-712 order signatures -GRVT_SUB_ACCOUNT_ID=your_sub_account # sub account that actually trades -GRVT_INSTRUMENT=BTC_USDT_Perp # instrument as defined by GRVT -GRVT_SYMBOL=BTCUSDT # optional display symbol; defaults to instrument sans underscores -GRVT_ENV=prod # optional environment switch (prod/testnet/staging/dev) -# Optional overrides -# GRVT_SIGNER_PATH=./grvt-signer.cjs # replace the built-in signer if you run an external service -# GRVT_COOKIE="gravity=..." # pre-provisioned session cookie (auto-fetched via API key when absent) -# GRVT_ACCOUNT_ID=... # populated automatically after login -``` +## 社区与支持 +- Telegram 交流群：[https://t.me/+4fdo0quY87o4Mjhh](https://t.me/+4fdo0quY87o4Mjhh) +- 反馈或新特性建议请提交 Issue 或 PR -The adapter logs in with `GRVT_API_KEY`, refreshes cookies automatically, and signs orders locally using `GRVT_API_SECRET` following GRVT's EIP‑712 schema. If you prefer to delegate signing to another process, set `GRVT_SIGNER_PATH`; the module should export a function (default export also works) that receives a context object (unsigned order, nonce/expiration, instrument metadata, chain id, etc.) and returns `{ signer, r, s, v, expiration, nonce }`. If you leave `GRVT_SIGNER_PATH` unset, the built-in signer uses `GRVT_API_SECRET` directly. - -### 切换到 GRVT 交易所 - -将环境变量 `EXCHANGE` 设为 `grvt` 后，所有策略会改用 GRVT 适配器： - -```bash -EXCHANGE=grvt -GRVT_API_KEY=你的APIKey -GRVT_API_SECRET=0xabc123... # 用于订单签名的私钥 -GRVT_SUB_ACCOUNT_ID=your_sub_account_id # 具体交易子账号 -GRVT_INSTRUMENT=BTC_USDT_Perp # 交易品种，需与策略一致 -GRVT_SYMBOL=BTCUSDT # 可选，内部用于展示，默认由 instrument 推导 -GRVT_ENV=prod # 可选：prod / testnet / staging / dev，默认 prod -# 可选覆盖项 -# GRVT_SIGNER_PATH=./grvt-signer.cjs # 如果你希望由外部服务签名 -# GRVT_COOKIE="gravity=..." # 预先获取到的 Cookie（若未提供，将使用 API Key 自动登录） -# GRVT_ACCOUNT_ID=... # 登录后自动填充 -``` - -适配器会基于 `GRVT_API_SECRET` 自动完成 EIP‑712 签名并提交订单。如果你需要自定义签名流程，可通过 `GRVT_SIGNER_PATH` 指定模块（CommonJS 或 ESM 均可）。模块需导出一个函数，接收签名上下文（未签名订单、nonce/expiration、合约元信息、链 ID 等）并返回包含 `signer/r/s/v/expiration/nonce` 字段的对象，例如： - -```js -// grvt-signer.cjs -module.exports = async function signOrder(context) { - // 调用你自己的签名服务，或者使用本地私钥完成签名 - const signature = await mySigner(context); - return { - signer: signature.signer, - r: signature.r, - s: signature.s, - v: signature.v, - expiration: signature.expiration, - nonce: signature.nonce, - }; -}; -``` - -如未自定义 `GRVT_SIGNER_PATH`，适配器会直接使用 `GRVT_API_SECRET` 完成签名。 - -## Running the CLI -```bash -bun run index.ts # or: bun run dev / bun run start -``` -Pick a strategy with the arrow keys. Press `Esc` to return to the menu. The dashboard shows live order books, holdings, pending orders, and recent events. 状态完全以交易所数据为准，重新启动时会自动同步账户和挂单。 - -## Testing -```bash -bun run test # bun x vitest run -bun run test:watch # stay in watch mode -``` -Current tests cover the order coordinator utilities and strategy helpers; add unit tests beside new modules as you extend the system. - -## Project Layout -- `src/config.ts` – shared runtime configuration -- `src/core/` – trend & maker engines plus order coordination -- `src/exchanges/` – Aster REST/WS gateway and adapters -- `src/ui/` – Ink components and strategy dashboards -- `src/utils/` – math helpers and strategy utilities -- `tests/` – Vitest suites for critical modules - -## Troubleshooting -- **Websocket reconnect loops**: ensure outbound access to `wss://fstream.asterdex.com/ws` and REST endpoints. -- **429 or 5xx responses**: the gateway backs off automatically, but check your rate limits and credentials. -- **CLI input errors**: run in a real TTY; non-interactive shells disable keyboard shortcuts but the UI still renders. - -## Contributing -Issues and PRs are welcome. When adding strategies or exchanges, follow the modular patterns in `src/core` and add tests under `tests/`. +## 风险提示 +量化交易具备风险。建议在仿真或小额账户中验证策略表现，妥善保管 API 密钥，仅开启必要权限。 diff --git a/README_en.md b/README_en.md new file mode 100644 index 0000000..953e339 --- /dev/null +++ b/README_en.md @@ -0,0 +1,99 @@ +# 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. + +## Documentation Map +- [中文 README](README.md) +- [Beginner-friendly Quick Start](simple-readme.md) +- `legacy/docs/`: in-depth architecture notes for the historical workspace + +## 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. + +## Requirements +- Bun ≥ 1.2 (`bun`, `bunx` available 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 + +## 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. + +## 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. +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. +3. **Install dependencies** + ```bash + bun install + ``` +4. **Create your environment file** + ```bash + cp .env.example .env + ``` + Edit `.env` with your exchange credentials and overrides. +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. + +## Environment Variables +The most important settings shipped in `.env.example` are summarised below: + +| Variable | Purpose | +| --- | --- | +| `ASTER_API_KEY` / `ASTER_API_SECRET` | Required Aster exchange credentials | +| `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 | +| `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. | + +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`. + +## Common Commands +```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 +``` + +## Testing +Vitest powers the unit tests: +```bash +bun run test +bun x vitest --watch +``` + +## Troubleshooting +- **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). + +## Community & Support +- Telegram: [https://t.me/+4fdo0quY87o4Mjhh](https://t.me/+4fdo0quY87o4Mjhh) +- Issues and PRs are welcome for bug reports and feature ideas + +## 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. diff --git a/simple-readme.md b/simple-readme.md index 5c09416..a4f718c 100644 --- a/simple-readme.md +++ b/simple-readme.md @@ -1,203 +1,154 @@ -# 简明上手指南（给零基础小白） +# 简明上手指南（零基础） -这份文档一步一步教你在 Windows 或 macOS 本地把项目跑起来：从下载代码、安装工具、配置环境变量（.env）、获取 Aster API，到运行项目。每一步都尽量写得很直白。 +这份指南面向完全没有开发经验的用户，手把手带你在 Windows、macOS（或 WSL）上运行 **ritmex-bot**。每个步骤都尽量写得直观，出现问题也能快速定位。 --- -## 1. 下载代码（两种方式） +## 0. 你需要准备什么？ +- **Git（推荐）**：从 [git-scm.com](https://git-scm.com/download) 安装；macOS 在终端输入 `git --version` 会提示安装 Xcode Command Line Tools。 +- **VS Code**：前往 [code.visualstudio.com](https://code.visualstudio.com/) 下载。用它编辑 `.env` 与查看文件最方便。 +- **终端/命令行**： + - macOS：Spotlight 搜索 “Terminal” + - Windows：开始菜单搜索 “PowerShell” 或 “Windows Terminal” + - WSL：运行 `wsl` 后进入 Linux 子系统 -- 方式 A：使用 Git（推荐） - 1) 安装 Git： - - Windows：到 `https://git-scm.com/download/win` 下载并安装，一路“下一步”。 - - macOS：打开“终端”（Terminal），输入 `git --version` 看是否已自带。如果提示未安装，会引导你安装 Xcode Command Line Tools，按提示安装即可。 - 2) 打开命令行： - - Windows：开始菜单搜索“PowerShell”或“Windows Terminal”→ 打开。 - - macOS：按 `⌘ + 空格` 搜索“Terminal”→ 打开。 - 3) 在命令行输入（会把代码下载到当前目录下的 ritmex-bot 文件夹）： - ```bash - git clone https://github.com/discountry/ritmex-bot.git - ``` - -- 方式 B：不用 Git，直接下压缩包 - 1) 打开项目页面：`https://github.com/discountry/ritmex-bot` - 2) 点绿色的 `Code` 按钮 → `Download ZIP` - 3) 下载后解压到一个好找的位置，例如： - - Windows：`C:\Users\你的用户名\Desktop\ritmex-bot` - - macOS：`~/Desktop/ritmex-bot` +如果暂时无法使用 Git，可以在 GitHub 上下载 ZIP，后面步骤相同。 --- -## 2. 安装 VS Code（代码编辑器） -- 下载地址：`https://code.visualstudio.com/` -- Windows/macOS 都可以一路“下一步”安装。 -- 安装完成后，打开 VS Code，点“文件 → 打开文件夹（Open Folder）”，选中你刚下载/解压的 `ritmex-bot` 文件夹。 - ---- - -## 3. 安装 Bun（运行环境） -项目使用 Bun 作为运行环境（类似 Node.js，但更快，命令更简单）。 - -- macOS / Linux：在“终端”输入： - ```bash - curl -fsSL https://bun.sh/install | bash - ``` - 安装后请关闭并重新打开终端，再输入 `bun -v`，能看到版本号就说明成功。 - -- Windows（PowerShell）： - ```powershell - powershell -c "irm bun.sh/install.ps1 | iex" - ``` - 安装后关闭并重新打开 PowerShell，输入 `bun -v` 出现版本号即成功。 - -- 如果上述办法不行，去 Bun 官网查看其他方式：`https://bun.com/get` - -- 首次进入项目目录后，安装依赖： - ```bash - bun install - ``` - ---- - -## 4. 找到项目目录，并在命令行跳转过去 -- 你需要知道 `ritmex-bot` 文件夹具体在哪。 - - Windows 常见路径：`C:\Users\你的用户名\Desktop\ritmex-bot` - - macOS 常见路径：`~/Desktop/ritmex-bot` -- 命令行使用 `cd` 跳转： - ```bash - # macOS 示例 - cd ~/Desktop/ritmex-bot - - # Windows 示例（注意替换“你的用户名”） - cd C:\Users\你的用户名\Desktop\ritmex-bot - ``` -- 成功进入后，输入 `ls`（macOS）或 `dir`（Windows）应能看到 `package.json`、`index.ts` 等文件。 - ---- - -## 5. 配置环境变量（.env 文件） -项目运行需要你的 Aster API 密钥，以及一些策略参数。Bun 会自动读取根目录的 `.env` 文件。 - -1) 在项目根目录创建 `.env` 文件（如果没有的话）。可以先复制下面这份最小示例： - ```bash - # 复制以下内容到 .env（用记事本/VS Code 打开也可以） - ASTER_API_KEY=在这里填你的Key - ASTER_API_SECRET=在这里填你的Secret - - # 可选参数（都有默认值，不填也能跑） - TRADE_SYMBOL=BTCUSDT - TRADE_AMOUNT=0.001 - LOSS_LIMIT=0.03 - TRAILING_PROFIT=0.2 - TRAILING_CALLBACK_RATE=0.2 - PROFIT_LOCK_TRIGGER_USD=0.1 - PROFIT_LOCK_OFFSET_USD=0.05 - PRICE_TICK=0.1 - QTY_STEP=0.001 - ``` - -2) 在 Windows 下怎么编辑 `.env`？ - - 方法 A：在 VS Code 左侧资源管理器里右键新建文件，命名为 `.env`，然后把上面的内容粘贴进去保存。 - - 方法 B：在资源管理器勾选“查看 → 显示文件扩展名”，然后新建文本文件，重命名为 `.env`（注意不要叫 `.env.txt`）。用记事本或 VS Code 打开，把内容粘贴进去保存。 - -3) 这些变量的作用（知道大概即可）： - - `ASTER_API_KEY` / `ASTER_API_SECRET`：你在 Aster 交易所申请的 API 凭证（必填）。 - - `TRADE_SYMBOL`：交易对，默认 `BTCUSDT`。 - - `TRADE_AMOUNT`：每次下单的数量。 - - `LOSS_LIMIT`：每笔最大允许亏损（美元计）。 - - `TRAILING_PROFIT` / `TRAILING_CALLBACK_RATE`：移动止盈的触发值与回撤百分比。 - - `PROFIT_LOCK_*`：达到一定浮盈后，自动把基础止损往有利方向移动的参数。 - - `PRICE_TICK` / `QTY_STEP`：该交易对的最小价格变动单位和最小下单步长。 - -> 进阶：做市策略还有一些 `MAKER_*` 参数（如 `MAKER_PRICE_CHASE`、`MAKER_REFRESH_INTERVAL_MS` 等），需要时可在 `src/config.ts` 查到名称并按需加到 `.env` 重写默认值。 - ---- - -## 6. 去哪里获取 Aster 的 API Key/Secret？ -- 打开 Aster 的 API 管理页面：`https://www.asterdex.com/zh-CN/api-management` -- 登录后创建新的 API，记录下 `API Key` 和 `Secret` 并填入 `.env`。 -- 权限仅勾选你需要的，谨慎保管。不要把 `.env` 上传到任何地方。 - ---- - -## 7. 运行项目（命令） -确保你已在项目根目录，并且 `.env` 已配置好： - +## 1. 获取项目代码 +### 方式 A：Git（推荐） ```bash -bun install # 第一次运行需要安装依赖 -bun run index.ts # 启动程序（等同于 npm run start，但我们用 Bun） +git clone https://github.com/discountry/ritmex-bot.git +cd ritmex-bot ``` -启动后，终端里会出现一个交互界面： -- 使用键盘 ↑ / ↓ 选择“趋势策略”或“做市策略”，回车启动。 -- 按 `Esc` 返回菜单。 -- 按 `Ctrl + C` 退出程序。 +### 方式 B：下载压缩包 +1. 打开仓库页面： +2. 点击绿色的 `Code` → `Download ZIP` +3. 解压到易于找到的路径，例如： + - Windows：`C:\Users\你的用户名\Desktop\ritmex-bot` + - macOS：`~/Desktop/ritmex-bot` +4. 打开终端，使用 `cd` 进入该目录： + ```bash + cd ~/Desktop/ritmex-bot # macOS 示例 + cd C:\Users\你\Desktop\ritmex-bot # Windows 示例 + ``` -如果你更喜欢用脚本，也可以： +进入项目后，执行 `ls`（macOS/Linux）或 `dir`（Windows）应能看到 `package.json`、`index.ts` 等文件。 + +--- + +## 2. 安装 Bun（项目运行环境） +### macOS / Linux +```bash +curl -fsSL https://bun.sh/install | bash +``` +安装完关闭并重新打开终端，输入 `bun -v`，出现版本号表示成功。 + +### Windows PowerShell +```powershell +powershell -c "irm bun.sh/install.ps1 | iex" +``` +同样重新打开 PowerShell，确认 `bun -v` 正常。 + +> 其他安装方式详见 [bun.com/get](https://bun.com/get)。 + +--- + +## 3. 安装依赖 +在项目目录执行： +```bash +bun install +``` +首次运行会下载所有依赖包。 + +--- + +## 4. 配置环境变量（.env） +### 复制模板 +```bash +cp .env.example .env +``` +若在 Windows 无法使用 `cp`，可以在资源管理器中复制 `.env.example` 并重命名为 `.env`。 + +### 编辑 `.env` +用 VS Code 或记事本打开 `.env`，至少填入： +```bash +ASTER_API_KEY=你的AsterKey +ASTER_API_SECRET=你的AsterSecret +``` +其他常用参数已有默认值，需要个性化时修改即可： +- `TRADE_SYMBOL` / `TRADE_AMOUNT` +- `LOSS_LIMIT`、`TRAILING_PROFIT`、`TRAILING_CALLBACK_RATE` +- `PROFIT_LOCK_TRIGGER_USD` / `PROFIT_LOCK_OFFSET_USD` +- `BOLLINGER_LENGTH` / `BOLLINGER_STD_MULTIPLIER` / `MIN_BOLLINGER_BANDWIDTH` +- `PRICE_TICK` / `QTY_STEP` +- `MAKER_*` 系列（若要启用做市策略） + +如需切换到 GRVT，请将 `EXCHANGE=grvt` 并补充 `GRVT_API_KEY`、`GRVT_API_SECRET`、`GRVT_SUB_ACCOUNT_ID` 等变量，详细说明见 `.env.example`。 + +### 获取 GRVT API Key/Secret +1. 打开 +2. 点击 **Generate** 创建新的 API 组合，保存系统生成的 **API Key** 与 **钱包密钥（Wallet Secret）** +3. 页面同时会显示 **Trading Account ID**，请一并记录备用（填入 `GRVT_SUB_ACCOUNT_ID`） +4. 将上述值写入 `.env`，并妥善保管： + ```bash + EXCHANGE=grvt + GRVT_API_KEY=你的GRVTKey + GRVT_API_SECRET=你的GRVT钱包密钥 + GRVT_SUB_ACCOUNT_ID=你的TradingAccountID + ``` +5. 仍需保留 `TRADE_SYMBOL`、`PRICE_TICK` 等核心参数，确保与 GRVT 合约规则一致 + +> GRVT 的 API Key 和钱包密钥生成后只显示一次，请立即保存。Trading Account ID 用于区分子账户。 + +> 保存 `.env` 后无需手动刷新，只要重新运行命令即可生效。 + +--- + +## 5. 获取 Aster API Key/Secret +1. 打开 +2. 登录后创建新的 API，记录 `API Key` 与 `Secret` +3. 仅勾选必要权限，并将值填入 `.env` + +切记：不要把 `.env` 上传或分享给他人。 + +--- + +## 6. 启动程序 +确保仍在项目根目录： +```bash +bun run index.ts +``` +- 上下方向键选择“趋势策略”或“做市策略” +- `Enter` 启动策略，`Esc` 返回菜单 +- `Ctrl + C` 结束程序 + +常用别名： ```bash bun run start -# 或 bun run dev ``` --- -## 8. 常见问题（简单排查） -- 运行时报错“缺少 ASTER_API_KEY/SECRET”：说明 `.env` 没正确配置或没被读取。确认 `.env` 在项目根目录，变量名拼写无误。 -- 终端显示连不上：检查你的网络是否能访问 `wss://fstream.asterdex.com/ws` 和 `https://fapi.asterdex.com`。 -- 显示权限错误/下单失败：到 Aster 后台检查 API 权限，确认已开启合约交易相关权限。 -- 界面卡着没反应：请在“真”终端里运行（Windows Terminal、PowerShell、macOS Terminal），不要在只读的输出窗口里运行。 +## 7. 常见问题与排查 +- **提示缺少 ASTER_API_KEY/SECRET**：`.env` 未生效。确认文件在项目根目录且变量无额外空格或中文字符。 +- **签名或时间戳错误**：同步电脑时间。 + - macOS：系统设置 → 通用 → 日期与时间 → 开启自动设置 + - Windows：设置 → 时间和语言 → 日期和时间 → 开启自动同步并“立即同步” +- **网络连接失败**：检查能否访问 `https://fapi.asterdex.com` 与 `wss://fstream.asterdex.com/ws`。如需代理，先在终端设置 `HTTP_PROXY` / `HTTPS_PROXY`。 +- **订单被拒绝（精度/步长）**：调整 `PRICE_TICK`、`QTY_STEP` 与交易所规则一致。 +- **终端界面无反应**：请在真实终端中运行，不要在只读输出窗口执行。 -- API 填写错误（Key/Secret 格式问题）： - - 确认 `.env` 中没有多余空格、引号或换行。示例： - ```bash - ASTER_API_KEY=你的Key - ASTER_API_SECRET=你的Secret - ``` - - 避免中文标点或全角字符；从网页复制后，先粘到纯文本再粘回。 - - 修改 `.env` 后，重新打开终端或重新运行命令以生效。 +更多细节请参考主仓库的 [README](README.md)。 -- 本地时间与交易所时间不同步（签名/时间戳错误）： - - 现象：HTTP 4xx 提示 `timestamp expired` / `invalid signature`。 - - macOS：系统设置 → 通用 → 日期与时间 → 开启“自动设置日期与时间”。 - - Windows：设置 → 时间和语言 → 日期和时间 → 开启“自动设置时间”，并点击“立即同步”。 - - 命令行快速同步（可选）： - - macOS： - ```bash - sudo sntp -sS time.apple.com - ``` - - Windows（管理员 PowerShell）： - ```powershell - w32tm /resync - ``` - - Linux： - ```bash - sudo timedatectl set-ntp true - ``` - -- 无法访问外网/需要代理： - - 现象：`curl https://bun.sh` 超时、连接 `fapi.asterdex.com` / `fstream.asterdex.com` 失败。 - - 临时为当前终端配置代理（按本地代理端口调整 7890/1080 等）： - - macOS / Linux： - ```bash - export HTTP_PROXY=http://127.0.0.1:7890 - export HTTPS_PROXY=http://127.0.0.1:7890 - ``` - - Windows PowerShell： - ```powershell - $env:HTTP_PROXY="http://127.0.0.1:7890" - $env:HTTPS_PROXY="http://127.0.0.1:7890" - ``` - - 验证连通性： - ```bash - curl -I https://fapi.asterdex.com - ``` - - 公司/校园网络可能屏蔽 WebSocket（wss://）；必要时切换到个人网络或 VPN。 - -- 下单精度/步长或交易对不匹配： - - 现象：下单被拒，提示精度/步长错误。 - - 处理：在 `.env` 中调整 `TRADE_SYMBOL`、`PRICE_TICK`、`QTY_STEP` 与交易所规则一致。 --- -## 9. 风险提示 +## 8. 继续深入 +- 高级策略说明：`legacy/docs/` +- 英文文档：`README_en.md` +- 社区支持：Telegram 群组 -量化策略并非稳赚不赔。请从小额开始，先在仿真或小资金环境验证，逐步加大。务必妥善保管 API 密钥，并只开启必要权限。 +祝你部署顺利，交易安全！