forgex-cli 1.0.58 → 1.0.61

package/README.md

@@ -1,513 +1,520 @@
 # ForgeX CLI
 
-Solana 链上做市系统命令行工具。
+### Launch tokens. Bundle buy. Manage wallets — Just talk to your agent.
 
-ForgeX CLI 提供完整的 Solana 链上做市操作能力，包括多钱包组管理、批量交易、专业做市工具（换手/刷量/价格机器人）、代币创建与查询、批量转账等功能。支持多 DEX 协议和 Jito MEV 保护。
+On-chain market making, from a single command line to your OpenClaw agent.<br/>No programming required.
 
-## 功能特性
-
-- **多钱包组管理** -- 创建/删除钱包组，批量生成钱包，靓号地址生成（自定义后缀/前缀），CSV/JSON 导入导出，AES 加密存储私钥
-- **批量交易** -- 多钱包同时买入/卖出，支持百分比卖出、全部卖出、狙击买入
-- **专业做市工具** -- 换手交易（Jito Bundle 零滑点）、刷量工具（5 种模式）、价格机器人（自动拉升/砸盘）
-- **多 DEX 支持** -- Pump.fun、PumpSwap、Raydium V4/CPMM、LaunchLab
-- **Jito MEV 保护** -- 交易捆绑发送，防止夹子攻击
-- **代币创建** -- 支持 Pump.fun / LaunchLab 发币，IPFS 元数据上传，开盘狙击
-- **链上查询** -- 余额、价格、K 线、交易记录、持仓监控
-- **批量转账** -- 收集（多对一）、分发（一对多）、多对多转账
-- **交易追踪** -- 自动追踪交易结果，持久化持仓和盈亏数据
-- **灵活输出** -- 支持 JSON / Table / Minimal 三种输出格式
+---
 
-## 安装
+⛓️ Supported Platforms
 
-### 环境要求
+[![Sonic SVM](https://img.shields.io/badge/Sonic_SVM-purple?style=for-the-badge)](https://sonic.game) [![Solana](https://img.shields.io/badge/Solana-9945FF?style=for-the-badge&logo=solana&logoColor=white)](https://solana.com) [![Pump.fun](https://img.shields.io/badge/Pump.fun-green?style=for-the-badge)](https://pump.fun) [![Jito Bundle](https://img.shields.io/badge/Jito_Bundle-orange?style=for-the-badge)](https://jito.wtf) [![OpenClaw](https://img.shields.io/badge/OpenClaw_Native-blue?style=for-the-badge)](https://openclaw.ai) 
 
-- Node.js >= 22.14.0
-- npm
-- solana-keygen（仅靓号生成功能需要，可选）
+---
 
-### 安装步骤
+[![npm version](https://img.shields.io/npm/v/forgex-cli?color=blue)](https://www.npmjs.com/package/forgex-cli) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Open Source](https://img.shields.io/badge/Open%20Source-✓-brightgreen)](https://github.com) [![Jito Bundle](https://img.shields.io/badge/Jito%20Bundle-✓-orange)](https://jito.wtf) [![Multi-wallet](https://img.shields.io/badge/Multi--wallet-✓-blue)](.) [![Sonic SVM](https://img.shields.io/badge/Sonic%20SVM-✓-purple)](https://sonic.game) [![OpenClaw Native](https://img.shields.io/badge/OpenClaw%20Native-✓-blue)](https://openclaw.ai) [![On-chain Market Making](https://img.shields.io/badge/On--chain%20Market%20Making-✓-green)](.)
 
-```bash
-cd cli
-npm install
-npm run build
-```
+---
 
-安装完成后可通过以下方式运行：
+[Overview](#why-forgex) · [Quick Start](#quick-start-5-minutes) · [Configure](#config--configuration) · [Command Reference](#command-reference) · [Examples](#workflow-examples)
 
-```bash
-# 开发模式（tsx 直接运行 TypeScript）
-npm run dev -- <command>
+---
 
-# 编译后运行
-node dist/bin/forgex.js <command>
+---
 
-# 全局链接后
-npm link
-forgex <command>
-```
+## Why ForgeX?
 
-## 快速上手
+Most on-chain workflows on Solana are painful:
 
-### 1. 初始化配置
+- **Too many manual steps.** Copy-pasting addresses, switching tabs, signing transaction after transaction — every extra step is a chance to make a costly mistake.
+- **Repetitive confirmations waste hours.** Manually confirming the same operations over and over drains time that should go toward strategy, not execution.
+- **Complex tools lock out non-developers.** If you're not writing custom scripts, most market making tooling is simply inaccessible.
 
-```bash
-# 创建默认配置文件 (~/.forgex/config.json)
-forgex config init
+ForgeX packages the full workflow into a clean CLI. One command at a time.
 
-# 设置 RPC 节点（推荐付费节点）
-forgex config set rpcUrl https://your-rpc-url.com
+---
 
-# 设置 Codex API Key（代币信息和价格查询）
-forgex config set codexApiKey your-codex-api-key
+## Install
 
-# 查看当前配置
-forgex config list
+```bash
+npm install -g forgex-cli
 ```
 
-### 2. 创建钱包组并生成钱包
+Requires Node.js >= 22.14.0.
+
+Verify installation:
 
 ```bash
-# 创建本地钱包组
-forgex wallet create-group --name "做市组A"
+forgex --version
+```
 
-# 生成 5 个新钱包（首次使用需设置加密密码）
-forgex wallet generate --group 1 --count 5
+---
 
-# 查看钱包组详情
-forgex wallet group-info --id 1
+## Quick Start (5 minutes)
 
-# 列出所有钱包组
-forgex wallet list-groups --format table
+### Step 1 — Initialize config
+
+```bash
+forgex config init --rpc-url "https://your-rpc-endpoint.com" --network mainnet
 ```
 
-### 3. 分发 SOL 到钱包
+### Step 2 — Create a wallet group
 
 ```bash
-# 从主钱包向钱包组每个钱包分发 0.1 SOL
-forgex transfer out --from <主钱包地址> --to-group 1 --value 0.1
-
-# 模拟分发（不实际执行，检查余额是否充足）
-forgex transfer out --from <主钱包地址> --to-group 1 --value 0.1 --dry-run
+forgex wallet create-group --name "my-group"
+# Returns groupId — note it for subsequent commands
 ```
 
-### 4. 执行交易
+### Step 3 — Generate wallets
 
 ```bash
-# 批量买入（每个钱包买入 0.01 SOL 的代币）
-forgex trade buy --group 1 --token <代币CA> --amount 0.01
+forgex --password "your-password" wallet generate --group 1 --count 10
+```
 
-# 全部卖出
-forgex trade sell --group 1 --token <代币CA> --amount all
+### Step 4 — Fund your wallets
 
-# 卖出 50%
-forgex trade sell --group 1 --token <代币CA> --amount 50%
+Distribute SOL from a source wallet to the group:
 
+```bash
+forgex --password "your-password" transfer out \
+  --from "YourSourceWalletAddress" \
+  --to-group 1 \
+  --value 0.1
 ```
 
-### 5. 使用做市工具
+### Step 5 — Launch a token
 
 ```bash
-# 刷量（1买1卖模式，执行 3 轮）
-forgex tools volume --group 1 --token <代币CA> --mode 1b1s --amount 0.01 --rounds 3
+forgex --password "your-password" token create \
+  --dex pump \
+  --name "MyToken" \
+  --symbol "MYT" \
+  --image ./logo.png \
+  --dev-wallet 1 \
+  --dev-buy 0.5 \
+  --dry-run   # remove --dry-run when ready to go live
+```
 
-# 换手交易（组A -> 组B）
-forgex tools turnover --from-group 1 --to-group 2 --token <代币CA>
+### Step 6 — Start the volume bot
 
-# 价格机器人（拉升到目标价格）
-forgex tools robot-price --group 1 --token <代币CA> --direction up --target-price 0.001
+```bash
+forgex --password "your-password" tools volume \
+  --group 1 \
+  --token "TOKEN_MINT_ADDRESS" \
+  --mode 1b1s \
+  --amount 0.01 \
+  --rounds 20 \
+  --interval 10000
 ```
 
-### 6. 收集 SOL
+> **Tip:** Always run with `--dry-run` first to simulate the operation before executing on-chain.
+
+---
+
+## Command Reference
+
+All commands accept `--format json|table|minimal` (default: `json`).
+
+Commands involving private keys require `--password` before the subcommand name:
 
 ```bash
-# 将钱包组所有钱包的 SOL 收集到一个地址
-forgex transfer in --to <目标地址> --from-group 1 --amount all
+forgex --password "your-password" <command> [subcommand] [options]
 ```
 
-## 命令参考
+---
 
-### 全局选项
+### `config` — Configuration
 
-| 选项 | 说明 | 默认值 |
-|------|------|--------|
-| `--password <password>` | 钱包加密密码（跳过交互式输入，适合脚本/Agent 自动化） | - |
-| `--format <format>` | 输出格式: `json` \| `table` \| `minimal` | `json` |
-| `--help` | 显示帮助信息 | - |
-| `--version` | 显示版本号 | - |
+| Command | Description |
 
-所有交易类命令均支持 `--dry-run`（模拟执行）、`--priority-fee`（优先费 SOL）、`--slippage`（滑点 bps）。
+|---|---|
 
----
+| `forgex config init` | Initialize config file |
 
-### config -- 配置管理
+| `forgex config set <key> <value>` | Set a config value |
 
-| 命令 | 说明 |
-|------|------|
-| `config init` | 初始化配置文件，支持 `--rpc-url`、`--network` |
-| `config set <key> <value>` | 设置配置项，支持点号路径 |
-| `config get [key]` | 查看配置项，不指定 key 显示全部 |
-| `config list` | 列出所有配置 |
+| `forgex config get [key]` | View config values |
 
----
+```bash
+# Initialize with RPC endpoint
+forgex config init --rpc-url "https://my-rpc.com" --network mainnet
 
-### wallet -- 钱包组管理
-
-| 命令 | 主要参数 | 说明 |
-|------|----------|------|
-| `wallet create-group` | `--name` (必填), `--type local\|monitor` | 创建钱包组 |
-| `wallet list-groups` | `--type` | 列出钱包组，可按类型过滤 |
-| `wallet group-info` | `--id` (必填), `--show-keys` | 查看详情，`--show-keys` 显示私钥明文 |
-| `wallet delete-group` | `--id` (必填), `--force` | 删除钱包组 |
-| `wallet generate` | `--group` (必填), `--count` | 批量生成新钱包（上限 100 个/组） |
-| `wallet add` | `--group` (必填), `--private-key` (必填) | 导入已有钱包 |
-| `wallet remove` | `--group` (必填), `--address` (必填) | 从组中移除钱包 |
-| `wallet import` | `--group` (必填), `--file` (必填) | 从 CSV 批量导入钱包 |
-| `wallet export` | `--group` (必填), `--file` (必填) | 导出钱包组为 CSV |
-| `wallet import-group` | `--file` (必填), `--password` | 从 JSON 导入钱包组 |
-| `wallet export-group` | `--file` (必填), `--encrypt`, `--password` | 导出所有钱包组为 JSON |
-| `wallet grind` | `--suffix` (必填), `--prefix`, `--count`, `--threads` | 生成靓号地址（自定义后缀/前缀），需要本地安装 solana-keygen |
-| `wallet grind-list` | `--suffix` | 列出已生成的靓号地址，可按后缀过滤 |
-
-**靓号生成 (grind) 说明:**
-- 依赖本地 `solana-keygen` 工具，未安装时会提示安装方式
-- 后缀/前缀仅支持 Base58 字符（不含 0, O, I, l）
-- 生成的密钥文件保存在 `~/.forgex/vanity/` 目录
-- 后缀越长，生成时间越久（4 字符秒级，5+ 字符可能数分钟）
+# Set Codex API key for market data
+forgex config set codexApiKey "your-api-key"
+
+# Set default slippage (BPS)
+forgex config set defaultSlippage 300
+
+# View all config
+forgex config get
+```
 
 ---
 
-### trade -- 交易操作
+### `wallet` — Wallet Group Management
 
-| 命令 | 主要参数 | 说明 |
-|------|----------|------|
-| `trade buy` | `--group`, `--token`, `--amount`(SOL) | 批量买入，`--slippage` 默认 300bps |
-| `trade sell` | `--group`, `--token`, `--amount` | 批量卖出，amount 支持: 数量 / 百分比(`50%`) / `all` |
-| `trade batch` | `--group`, `--token`, `--type`, `--mode` | 批量交易，type: `buy\|sell\|buyWithSell`，mode: `1b1s\|1b2s\|1b3s\|2b1s\|3b1s` |
+**Create & manage groups**
 
----
+```bash
+# Create a local wallet group
+forgex wallet create-group --name "market-making-group"
+
+# Create with optional remark
+forgex wallet create-group --name "sniper-group" --remark "launch snipers"
 
-### tools -- 专业做市工具
+# List all wallet groups
+forgex wallet list-groups
 
-| 命令 | 主要参数 | 说明 |
-|------|----------|------|
-| `tools turnover` | `--from-group`, `--to-group`, `--token` | 换手交易，使用 Jito Bundle 实现零滑点钱包间换手 |
-| `tools volume` | `--group`, `--token`, `--mode`, `--amount` | 刷量工具，支持 5 种模式，零损失提升交易量 |
-| `tools robot-price` | `--group`, `--token`, `--direction`, `--target-price` | 价格机器人，direction: `up`(拉升) / `down`(砸盘) |
+# View group details (wallet addresses)
+forgex wallet group-info --id 1
 
-**换手 (turnover) 额外参数:**
-- `--amount`: 金额类型，固定数量 / 百分比(`50%`) / `all`(默认)
-- `--daemon`: 后台持续执行
-- `--rounds`: 轮数（0=无限）
-- `--interval`: 间隔毫秒
+# Delete a group
+forgex wallet delete-group --id 1 --force
+```
 
-**刷量 (volume) 额外参数:**
-- `--mode`: `1b1s`(1买1卖) / `1b2s` / `1b3s` / `2b1s` / `3b1s`
-- `--daemon`: 后台持续执行
-- `--rounds`: 轮数（0=无限）
-- `--interval`: 间隔毫秒
+**Generate & import wallets**
 
-**价格机器人 (robot-price) 额外参数:**
-- `--amount-type`: `fixed` / `random`
-- `--amount-max`: random 模式最大金额
-- `--max-cost`: 总消耗 SOL 上限
-- 默认持续运行直到达到目标价格或成本上限，Ctrl+C 停止
+```bash
+# Generate new wallets (max 100 per group)
+forgex --password "pwd" wallet generate --group 1 --count 10
 
----
+# Add an existing wallet by private key
+forgex --password "pwd" wallet add --group 1 --private-key "Base58Key..." --note "main wallet"
 
-### transfer -- 转账操作
+# Remove a wallet from group
+forgex --password "pwd" wallet remove --group 1 --address "WalletAddress..."
 
-| 命令 | 主要参数 | 说明 |
-|------|----------|------|
-| `transfer in` | `--to`, `--from-group` | 批量收集（多对一），`--amount all\|fixed\|reserve` |
-| `transfer out` | `--from`, `--to-group`, `--value` | 批量分发（一对多），`--amount fixed\|random` |
-| `transfer many-to-many` | `--from-group`, `--to-group` | 多对多转账，按索引配对，`--amount all\|fixed\|reserve\|random` |
+# Import from CSV (format: privateKey,note)
+forgex --password "pwd" wallet import --group 1 --file ./wallets.csv
+```
 
----
+**Backup & restore**
 
-### token -- 代币操作
+```bash
+# Export group as CSV
+forgex --password "pwd" wallet export --group 1 --file ./backup.csv
+
+# Export all groups as encrypted JSON
+forgex --password "pwd" wallet export-group \
+  --file ./all-groups.json \
+  --encrypt \
+  --password "file-encryption-password"
+
+# Import all groups from JSON backup
+forgex --password "pwd" wallet import-group \
+  --file ./all-groups.json \
+  --password "file-encryption-password"
+```
 
-| 命令 | 主要参数 | 说明 |
-|------|----------|------|
-| `token create` | `--dex`, `--name`, `--symbol`, `--image` | 创建代币，dex: `pump` / `launchlab` |
-| `token info` | `--ca` | 查询代币信息（名称、符号、价格、交易对等） |
-| `token pool` | `--ca` | 查询代币池子信息 |
+**Vanity addresses**
 
-**代币创建额外参数:**
-- `--description`, `--twitter`, `--website`, `--telegram`: 元数据
-- `--dev-wallet`: 开发者钱包组 ID，`--dev-buy`: 开发者买入金额
-- `--snipers`: 狙击者钱包组 ID，`--sniper-amounts`: 狙击金额
-- `--bundle-time`: `T0`(同区块) / `T1_T5`
-- `--use-suffix`: 使用自定义后缀地址
+```bash
+# Generate address ending in "pump"
+forgex wallet grind --suffix pump
 
-**T0 同区块狙击规则:**
-- Jito tip（`--priority-fee`）默认 0.0001 SOL。如果 Bundle 落地失败，应逐步上调 tip：0.0001 → 0.0003 → 0.0005 → 0.001
-- **Jito tip 上限为 0.001 SOL**，除非用户明确要求设置更高值
-- T1_T5 模式允许跨区块买入，对 Jito tip 要求较低
+# Generate 3 addresses with custom suffix, using 8 threads
+forgex wallet grind --suffix pump --count 3 --threads 8
+```
 
 ---
 
-### query -- 查询操作
+### `trade` — Trading
 
-| 命令 | 主要参数 | 说明 |
-|------|----------|------|
-| `query balance` | `--address`, `--token`(可选) | 查询余额，不填 token 查 SOL |
-| `query price` | `--token` | 查询代币价格（SOL/USD） |
-| `query kline` | `--token`, `--interval`, `--count` | K 线数据，interval: `1m\|5m\|15m\|1h\|4h\|1d` |
-| `query transactions` | `--group`, `--token`(可选) | 查询交易记录，支持分页 `--page` `--page-size` |
-| `query monitor` | `--group`, `--token`(可选) | 持仓监控（余额/均价/已实现&未实现盈亏） |
+> All trade commands support `--dry-run` for simulation.
 
----
+**Buy**
 
-## 配置
+```bash
+# Simulate buy (recommended before first run)
+forgex --password "pwd" trade buy \
+  --group 1 --token "TOKEN_CA" --amount 0.1 --dry-run
 
-### 配置文件位置
+# Batch buy — all wallets in group buy the same amount
+forgex --password "pwd" trade buy \
+  --group 1 --token "TOKEN_CA" --amount 0.1 --slippage 300
+```
 
-`~/.forgex/config.json`，通过 `forgex config init` 创建。
+**Sell**
 
-### 配置项
+```bash
+# Sell all tokens
+forgex --password "pwd" trade sell \
+  --group 1 --token "TOKEN_CA" --amount all
 
-| 配置项 | 说明 | 默认值 |
-|--------|------|--------|
-| `rpcUrl` | Solana RPC 节点 URL | `https://api.mainnet-beta.solana.com` |
-| `codexApiKey` | Codex API Key（市场数据查询） | `""` |
-| `network` | 网络: `mainnet` / `devnet` / `testnet` | `mainnet` |
-| `defaultPriorityFee` | 默认优先费 (SOL) | `0.0001` |
-| `defaultSlippage` | 默认滑点 (bps) | `300` |
-| `outputFormat` | 默认输出格式 | `json` |
-| `solPrice` | SOL 美元价格（估值用） | `130` |
+# Sell 50%
+forgex --password "pwd" trade sell \
+  --group 1 --token "TOKEN_CA" --amount 50%
 
-### 环境变量
+# Sell fixed token quantity
+forgex --password "pwd" trade sell \
+  --group 1 --token "TOKEN_CA" --amount 1000000
+```
 
-以下环境变量会覆盖配置文件中的对应值（优先级最高）：
+**Batch (buy + sell in one bundle)**
 
-| 环境变量 | 对应配置项 |
-|----------|-----------|
-| `FORGEX_RPC_URL` | `rpcUrl` |
-| `FORGEX_CODEX_API_KEY` | `codexApiKey` |
-| `FORGEX_PASSWORD` | 钱包加密密码（避免交互式输入，适合脚本自动化） |
+```bash
+# Execute buy and sell in same Jito Bundle
+forgex --password "pwd" trade batch \
+  --group 1 --token "TOKEN_CA" \
+  --type buyWithSell --mode 1b1s --amount 0.01
+```
 
-## 安全
+Modes: `1b1s` (1 buy + 1 sell), `1b2s`, `1b3s`, `2b1s`, `3b1s`
 
-### 私钥加密
+**Sniper**
 
-所有钱包私钥使用 AES 加密存储。首次创建或导入钱包时，CLI 要求设置加密密码。之后每次涉及私钥的操作（交易、导出等）都需要验证密码。
+```bash
+# Snipe with different amounts per wallet (amounts count must match wallet count)
+forgex --password "pwd" trade sniper \
+  --group 1 --token "TOKEN_CA" \
+  --amounts "0.5,0.3,0.2" --slippage 500
+```
 
-加密流程：
-1. 用户设置主密码
-2. 私钥通过 `CryptoJS.AES.encrypt(privateKey, password)` 加密后写入磁盘
-3. 使用时通过 `CryptoJS.AES.decrypt(encrypted, password)` 临时解密到内存
-4. 明文私钥仅在内存中使用，不持久化
-5. 旧版明文存储会自动检测并迁移到加密格式
+---
 
-### 安全建议
+### `tools` — Market Making
 
-- 使用强密码保护钱包
-- 通过 `--password` 全局参数或环境变量 `FORGEX_PASSWORD` 设置密码，适合脚本/Agent 自动化场景（优先级: `--password` > `FORGEX_PASSWORD` > 交互式输入）
-- 定期使用 `wallet export-group --encrypt --password <pwd>` 加密备份钱包数据
-- 不要在公共环境或共享屏幕时使用 `wallet group-info --show-keys`
-- 所有交易命令支持 `--dry-run` 预检，建议大额操作前先模拟验证
-- 配置文件权限为 `600`（仅所有者可读写），目录权限为 `700`
+> All tools support `--dry-run`. Use `--rounds` to limit execution.
 
-### 文件存储
+**Turnover (wallet cycling)**
 
-```
-~/.forgex/                     # 700 权限
-  config.json                  # 600 权限，全局配置
-  wallets/                     # 钱包加密数据
-    wallet-store.json          # 钱包组和加密私钥
-  vanity/                      # 靓号密钥文件 (solana-keygen grind 生成)
-    {address}.json             # Solana keypair JSON
-  data/                        # DataStore 本地数据
-    tokens/{CA}/               # 按代币组织
-      groups/{groupId}/        # 按钱包组组织
-        transactions.json      # 交易记录
-        holdings.json          # 持仓数据
-        balances.json          # 余额快照
-  logs/                        # 运行日志
+Cycles tokens between two wallet groups via Jito Bundle — zero price impact.
+
+```bash
+# Simulate
+forgex --password "pwd" tools turnover \
+  --from-group 1 --to-group 2 --token "TOKEN_CA" --dry-run
+
+# Run 5 turnover cycles
+forgex --password "pwd" tools turnover \
+  --from-group 1 --to-group 2 --token "TOKEN_CA" \
+  --daemon --rounds 5 --interval 2000
+
+# Turnover 50% of holdings
+forgex --password "pwd" tools turnover \
+  --from-group 1 --to-group 2 --token "TOKEN_CA" \
+  --amount 50%
 ```
 
-## 架构
+**Volume bot**
 
+Generates on-chain trading volume with zero net loss (buy + sell in same bundle).
+
+```bash
+# Simulate
+forgex --password "pwd" tools volume \
+  --group 1 --token "TOKEN_CA" --dry-run
+
+# Run 20 rounds, every 10 seconds
+forgex --password "pwd" tools volume \
+  --group 1 --token "TOKEN_CA" \
+  --mode 1b1s --amount 0.01 \
+  --daemon --rounds 20 --interval 10000
 ```
-CLI 命令层 (commands/)
-    |
-    v
-DataSource (data-source.ts) ---- 统一数据源门面
-    |
-    +---> CodexAdapter    代币信息/价格/K线/池信息 (远程 API + 本地缓存)
-    +---> RpcAdapter      余额/账户信息/交易确认 (链上 RPC)
-    +---> JitoAdapter     Bundle 发送/状态查询 (Jito Block Engine)
-    +---> DataStore       交易记录/持仓/缓存 (本地文件 ~/.forgex/data/)
-    |
-    v
-TxTracker (tx-tracker/) ---- 交易追踪系统
-    +---> TxDetailAdapter   解析链上交易详情
-    +---> DataStore         持久化交易结果和持仓变化
-
-SdkAdapter (adapters/sdk-adapter.ts) ---- 交易执行
-    +---> sol-sdk           前端交易 SDK 适配
+
+**Price robot**
+
+Automatically moves price toward a target by buying (up) or selling (down).
+
+```bash
+# Simulate price push
+forgex --password "pwd" tools robot-price \
+  --group 1 --token "TOKEN_CA" \
+  --direction up --target-price 0.001 --dry-run
+
+# Push price up, max spend 5 SOL
+forgex --password "pwd" tools robot-price \
+  --group 1 --token "TOKEN_CA" \
+  --direction up --target-price 0.001 \
+  --amount 0.05 --max-cost 5 --interval 3000
 ```
 
-### 核心模块说明
+Options: `--direction up|down`, `--target-price <sol>`, `--amount <sol>`, `--max-cost <sol>`, `--interval <ms>`
 
-- **DataSource**: 命令层唯一的数据访问接口。路由请求到正确的适配器，支持缓存穿透（优先读本地，miss 或过期时从远程获取并写入本地）和容错降级（远程不可用时 fallback 到本地缓存）
-- **DataStore**: 基于文件系统的本地数据存储，按 `tokens/{CA}/groups/{groupId}/` 组织数据
-- **CodexAdapter**: 对接 Codex API 获取市场数据（代币信息、实时价格、K 线、交易对）
-- **RpcAdapter**: 对接 Solana RPC 节点进行链上查询（SOL/Token 余额、账户信息、交易确认）
-- **JitoAdapter**: 对接 Jito Block Engine 发送和查询 Bundle 交易
-- **TxTracker**: 交易完成后自动追踪链上结果，解析交易详情，更新持仓和盈亏数据
-- **SdkAdapter**: 封装前端 sol-sdk，提供买入/卖出/换手/刷量等交易构建和执行能力
+---
 
-### 输出系统
+### `transfer` — Fund Management
 
-所有命令通过统一的 `output()` 函数输出数据，支持三种格式：
+> All transfer commands support `--dry-run`.
 
-- **json** (默认): 结构化 JSON，适合程序解析和 Agent 集成
-- **table**: cli-table3 表格，适合终端人工查看
-- **minimal**: 简洁文本，仅输出关键信息
+**Collect (many → one)**
 
 ```bash
-forgex wallet list-groups --format json
-forgex wallet list-groups --format table
-forgex wallet list-groups --format minimal
+# Collect all SOL from group into one wallet
+forgex --password "pwd" transfer in \
+  --to "MainWalletAddress" --from-group 1 --amount all
+
+# Keep 0.01 SOL in each wallet, collect the rest
+forgex --password "pwd" transfer in \
+  --to "MainWalletAddress" --from-group 1 \
+  --amount reserve --value 0.01
+
+# Collect tokens instead of SOL
+forgex --password "pwd" transfer in \
+  --to "MainWalletAddress" --from-group 1 \
+  --token "TOKEN_CA" --amount all
 ```
 
-## 开发
+**Distribute (one → many)**
 
-### 开发环境
+> `--from` address must belong to a wallet group (private key required for signing).
 
 ```bash
-# 安装依赖
-npm install
+# Send 0.1 SOL to each wallet in group
+forgex --password "pwd" transfer out \
+  --from "SourceAddress" --to-group 1 --value 0.1
+
+# Random distribution between 0.05 and 0.15 SOL
+forgex --password "pwd" transfer out \
+  --from "SourceAddress" --to-group 1 \
+  --amount random --value 0.05 --max 0.15
+```
 
-# 开发模式运行
-npm run dev -- config list
-npm run dev -- wallet list-groups --format table
+**Many-to-many (wallet[i] → wallet[i])**
 
-# 编译 TypeScript
-npm run build
+```bash
+# Transfer all from group 1 wallets to matching group 2 wallets
+forgex --password "pwd" transfer many-to-many \
+  --from-group 1 --to-group 2 --amount all
 
-# 清除编译产物
-npm run clean
+# Fixed amount per pair
+forgex --password "pwd" transfer many-to-many \
+  --from-group 1 --to-group 2 --amount fixed --value 0.1
 ```
 
-### 测试
+---
 
-```bash
-# 运行全部测试
-npm test
+### `token` — Token Operations
+
+> Supports `--dry-run` for simulation.
+
+**Create & launch token**
 
-# 监听模式（文件变更自动重跑）
-npm run test:watch
+```bash
+# Simulate token creation
+forgex --password "pwd" token create \
+  --dex pump \
+  --name "MyToken" --symbol "MTK" \
+  --image ./logo.png \
+  --description "My token" \
+  --dry-run
+
+# Launch with dev buy + snipers in same block (T0 bundle)
+forgex --password "pwd" token create \
+  --dex pump \
+  --name "MyToken" --symbol "MTK" \
+  --image ./logo.png \
+  --twitter "https://twitter.com/mytoken" \
+  --website "https://mytoken.io" \
+  --dev-wallet 1 --dev-buy 2.0 \
+  --snipers 2 --sniper-amounts "0.5,0.3,0.2" \
+  --bundle-time T0
 ```
 
-测试框架使用 vitest，测试文件位于 `tests/` 目录，超时时间 30 秒。
+Platforms: `pump` (Pump.fun), `launchlab`
+
+Bundle time: `T0` (dev buy + snipers same block), `T1_T5` (snipers 1-5 blocks after dev)
 
-### 项目结构
+**Query token**
 
+```bash
+# Token info (price, name, dex)
+forgex token info --ca "TOKEN_CA"
+
+# Liquidity pool info
+forgex token pool --ca "TOKEN_CA"
 ```
-cli/
-  bin/
-    forgex.ts                  CLI 入口（密码迁移检测 + 命令解析）
-  src/
-    index.ts                   程序主入口，注册 7 个命令组
-    config.ts                  配置管理（读写 ~/.forgex/config.json）
-    output.ts                  输出格式化（json/table/minimal）
-    wallet-store.ts            钱包加密存储（AES 加密/解密/迁移）
-    data-source.ts             统一数据源门面
-    commands/
-      config/index.ts          配置管理命令 (init/set/get/list)
-      wallet/index.ts          钱包组管理命令 (14 个子命令)
-      trade/index.ts           交易命令 (buy/sell/batch)
-      tools/index.ts           做市工具命令 (turnover/volume/robot-price)
-      transfer/index.ts        转账命令 (in/out/many-to-many)
-      token/index.ts           代币操作命令 (create/info/pool)
-      query/index.ts           查询命令 (balance/price/kline/transactions/monitor)
-    adapters/
-      sdk-adapter.ts           前端 sol-sdk 适配层
-      codex-adapter.ts         Codex API 适配器
-      rpc-adapter.ts           Solana RPC 适配器
-      jito-adapter.ts          Jito Bundle 适配器
-    data-store/
-      index.ts                 本地文件存储实现
-      types.ts                 数据类型定义
-    tx-tracker/
-      index.ts                 交易追踪主逻辑
-      detail-adapter.ts        链上交易详情解析
-  tests/                       测试文件
-  vitest.config.ts             vitest 测试配置
-  package.json                 依赖和脚本
-  tsconfig.json                TypeScript 配置
+
+---
+
+### `query` — Data Queries
+
+```bash
+# SOL balance
+forgex query balance --address "WalletAddress"
+
+# Token balance
+forgex query balance --address "WalletAddress" --token "TOKEN_CA"
+
+# Token price
+forgex query price --token "TOKEN_CA"
+
+# Candlestick data (intervals: 1m, 5m, 15m, 1h, 4h, 1d)
+forgex query kline --token "TOKEN_CA" --interval 5m --count 50
+
+# Transaction history for a group
+forgex query transactions --group 1 --token "TOKEN_CA"
+
+# Holdings and PnL across a group
+forgex query monitor --group 1 --token "TOKEN_CA"
 ```
 
-### 技术栈
+---
 
-| 类别 | 技术 |
-|------|------|
-| 语言 | TypeScript (ESM, type: module) |
-| CLI 框架 | Commander.js 13 |
-| 区块链 SDK | @solana/web3.js, @coral-xyz/anchor 0.31 |
-| 加密 | crypto-js (AES) |
-| 交互 | inquirer 12 |
-| 表格 | cli-table3 |
-| 进度条 | cli-progress |
-| 加载动画 | ora |
-| 颜色 | chalk 5 |
-| 大数 | bignumber.js, bn.js |
-| HTTP | axios |
-| 测试 | vitest 4 |
+## Slippage Reference
 
-## Agent 集成
+| BPS | Percentage | Recommended for |
 
-ForgeX CLI 支持 AI Agent（如 OpenClaw）无交互式调用。
+|---|---|---|
 
-### 密码传递
+| 100 | 1% | Turnover trades |
 
-涉及私钥的操作需要 master password，有三种传递方式（按优先级）：
+| 300 | 3% | Normal buy/sell |
 
-1. **`--password` 全局参数**（推荐）: 放在子命令之前
-   ```bash
-   forgex --password "your-password" trade buy --group 1 --token "CA..." --amount 0.01
-   forgex --password="your-password" wallet list-groups
-   ```
+| 500 | 5% | Sniping / fast entries |
 
-2. **`FORGEX_PASSWORD` 环境变量**:
-   ```bash
-   export FORGEX_PASSWORD="your-password"
-   forgex trade buy --group 1 --token "CA..." --amount 0.01
-   ```
+| 1000 | 10% | High volatility tokens |
 
-3. **交互式输入**: 不传密码时会弹出 inquirer 提示（Agent 环境下会阻塞，不推荐）
+| 2000 | 20% | Extreme conditions |
 
-### 注意事项
+---
 
-- `--password` 是全局参数，必须放在子命令名之前（如 `forgex --password "pwd" wallet ...`）
-- `wallet import-group` 和 `wallet export-group` 的 `--password` 是子命令参数（用于加密导入/导出文件），与全局 `--password` 不冲突
-- Agent 应始终使用 `--format json`（默认值），以便解析结构化输出
-- 首次执行高风险操作前应使用 `--dry-run` 模拟验证
+## Demo
 
-### T0 同区块发币规则（Agent 必须遵守）
+<!-- 📹 30-second demo video — coming soon -->
 
-2. **Jito tip 递增策略**：默认 `--priority-fee 0.0001`，Bundle 落地失败时逐步上调：
-   - 第1次：0.0001 SOL
-   - 第2次：0.0003 SOL
-   - 第3次：0.0005 SOL
-   - 第4次：0.001 SOL（上限）
-3. **Jito tip 硬上限为 0.001 SOL**，除非用户明确要求更高值
-4. 如果达到上限仍失败，应停止重试并告知用户，而非自动切换到普通交易
+---
+
+## Workflow Examples
+
+### Token Launch in 3 commands
+
+```bash
+# 1. Create wallets
+forgex --password "pwd" wallet generate --group 1 --count 5
+
+# 2. Fund them
+forgex --password "pwd" transfer out --from "MainWallet" --to-group 1 --value 0.5
+
+# 3. Launch token with dev buy + snipers
+forgex --password "pwd" token create \
+  --dex pump --name "MyToken" --symbol "MTK" \
+  --image ./logo.png \
+  --dev-wallet 1 --dev-buy 1.0 \
+  --snipers 1 --sniper-amounts "0.3,0.2,0.1,0.1,0.1" \
+  --bundle-time T0
+```
 
-### 示例工作流
+### Run the volume bot
 
 ```bash
-# Agent 批量操作示例
-forgex --password "pwd" wallet list-groups
-forgex --password "pwd" trade buy --group 1 --token "CA..." --amount 0.01 --dry-run
-forgex --password "pwd" trade buy --group 1 --token "CA..." --amount 0.01
-forgex --password "pwd" trade sell --group 1 --token "CA..." --amount all
-forgex --password "pwd" transfer in --to "MainWallet..." --from-group 1 --amount all
+forgex --password "pwd" tools volume \
+  --group 1 --token "TOKEN_CA" \
+  --mode 1b1s --amount 0.01 \
+  --rounds 30 --interval 10000
 ```
 
-## License
+### Collect funds back to main wallet
+
+```bash
+forgex --password "pwd" trade sell --group 1 --token "TOKEN_CA" --amount all
+forgex --password "pwd" transfer in --to "MainWallet" --from-group 1 --amount all
+```
+
+---
+
+## Links
 
-MIT
+- **Twitter:** [@SonicSVM](https://twitter.com/SonicSVM)
+- **npm:** [forgex-cli](https://www.npmjs.com/package/forgex-cli)
+- **Sonic SVM:** [sonic.game](https://sonic.game)