From 98c58727c788ba3d6db8ea477b7a0e8d226fec33 Mon Sep 17 00:00:00 2001
From: discountry <feibilanceon@gmail.com>
Date: Fri, 27 Feb 2026 11:23:45 +0800
Subject: [PATCH] Enhance README with detailed Binance exchange configuration

- Added comprehensive instructions for setting up Binance as an exchange option.
- Included environment variable specifications for API keys, market types, and trading symbols.
- Provided examples for both perpetual and spot trading strategies.
- Clarified the use of WebSocket and REST for the Binance adapter.
---
 README.md    | 32 ++++++++++++++++++++++++++++++++
 README_en.md | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+)

diff --git a/README.md b/README.md
index 761eea4..58c1e91 100644
--- a/README.md
+++ b/README.md
@@ -111,6 +111,38 @@ curl -fsSL https://github.com/discountry/ritmex-bot/raw/refs/heads/main/setup.sh
 3. 根据交易对调整 `TRADE_SYMBOL`、`PRICE_TICK`、`QTY_STEP` 等精度参数。
 4. 一键脚本会自动写入这些变量，手动部署时需自行维护。
 
+### Binance
+1. 设置 `EXCHANGE=binance`。
+2. 填写 `BINANCE_API_KEY`、`BINANCE_API_SECRET`。
+3. 设置市场模式 `BINANCE_MARKET_TYPE`：
+   - `perp`：永续（默认）
+   - `spot`：现货
+   - `auto`：按符号自动匹配（同名现货/永续并存时建议不要使用）
+4. 设置交易符号 `BINANCE_SYMBOL`（或使用 `TRADE_SYMBOL`）：
+   - 永续建议写 `BTCUSDT_PERP`（或直接 `BTCUSDT` + `BINANCE_MARKET_TYPE=perp`）
+   - 现货建议写 `BTCUSDT`（也支持 `BTCUSDT_SPOT`）
+5. 需要做期现套利（Basis）时，建议显式拆分：
+   - `BASIS_FUTURES_SYMBOL=BTCUSDT_PERP`
+   - `BASIS_SPOT_SYMBOL=BTCUSDT`
+6. 可选测试网/自定义端点：
+   - `BINANCE_SANDBOX=true`
+   - `BINANCE_SPOT_REST_URL` / `BINANCE_FUTURES_REST_URL`
+   - `BINANCE_SPOT_WS_URL` / `BINANCE_FUTURES_WS_URL`
+
+> Binance 适配器默认优先使用 WebSocket（盘口、ticker、kline、账户/订单用户流），仅在必要时使用 REST 补偿与兜底。
+>
+> 若使用现货模式，部分“仅合约可用”的保护单能力会受交易所限制，策略会按交易所能力自动降级。
+
+**示例（永续做市）**
+```bash
+EXCHANGE=binance BINANCE_MARKET_TYPE=perp BINANCE_SYMBOL=BTCUSDT_PERP bun run index.ts --strategy maker
+```
+
+**示例（现货网格）**
+```bash
+EXCHANGE=binance BINANCE_MARKET_TYPE=spot BINANCE_SYMBOL=BTCUSDT bun run index.ts --strategy grid
+```
+
 ### StandX
 
 * [StandX 做市策略教程](docs/standx/maker-points-guide.md)
diff --git a/README_en.md b/README_en.md
index 5e372aa..ab46635 100644
--- a/README_en.md
+++ b/README_en.md
@@ -108,6 +108,38 @@ The script installs Bun, project dependencies, collects Aster API credentials, g
 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)**
+```bash
+EXCHANGE=binance BINANCE_MARKET_TYPE=perp BINANCE_SYMBOL=BTCUSDT_PERP bun run index.ts --strategy maker
+```
+
+**Example (spot grid)**
+```bash
+EXCHANGE=binance BINANCE_MARKET_TYPE=spot BINANCE_SYMBOL=BTCUSDT bun run index.ts --strategy grid
+```
+
 ### StandX
 
 * [StandX Maker Points Strategy Guide](docs/standx/maker-points-guide.md)