From ffa5b9e6fad47ce41e99a6c6e857dc40c3d7e877 Mon Sep 17 00:00:00 2001
From: discountry <feibilanceon@gmail.com>
Date: Tue, 23 Sep 2025 11:24:14 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README.md=EF=BC=8C?=
 =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E9=A1=B9=E7=9B=AE=E5=8A=9F=E8=83=BD=E3=80=81?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE=E3=80=81=E8=BF=90=E8=A1=8C=E3=80=81=E6=B5=8B?=
 =?UTF-8?q?=E8=AF=95=E5=92=8C=E8=B4=A1=E7=8C=AE=E6=8C=87=E5=8D=97=E7=9A=84?=
 =?UTF-8?q?=E8=AF=A6=E7=BB=86=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 54 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index c1fe211..32bd4b8 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,64 @@
 # ritmex-bot
 
-To install dependencies:
+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 persistence layer. Everything runs in the terminal via Ink, with live websocket refresh and automatic recovery from restarts or network failures.
 
+## 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.
+- **State persistence**: positions, open orders, and logs mirrored under `data/` so restarts continue where you left off.
+- **Extensibility**: exchange gateway, engines, and UI components are modular for new venues or strategies.
+
+## Requirements
+- [Bun](https://bun.com) ≥ 1.2
+- Node.js (optional, only if you prefer `npm` tooling)
+- Valid Aster API credentials with futures access
+
+## Installation
 ```bash
 bun install
 ```
 
-To run:
-
+## Configuration
+Create an `.env` (or export environment variables) with at least:
 ```bash
-bun run index.ts
+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
 ```
+Additional maker-specific knobs (`MAKER_*`) live in `src/config.ts` and may be overridden via env vars.
 
-This project was created using `bun init` in bun v1.2.21. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+## 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. All state is mirrored in `data/trend-*.json` and `data/maker-*.json` so the bot can resume after crashes or manual stops.
+
+## 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, persistence, strategy utilities
+- `tests/` – Vitest suites for critical modules
+
+## Persistence & Recovery Notes
+- Important state is stored in `./data` (git-ignored). Deleting those files forces a fresh start.
+- On reconnect or restart the bot re-pulls account/position/order snapshots and reconciles against local state. Orders on other symbols are ignored so you can trade manually without interference.
+
+## 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/`.