ForgeX CLI

Solana 链上做市系统命令行工具。

ForgeX CLI 提供完整的 Solana 链上做市操作能力，包括多钱包组管理、批量交易、专业做市工具（换手/刷量/价格机器人）、代币创建与查询、批量转账等功能。支持多 DEX 协议和 Jito MEV 保护。

功能特性

• 多钱包组管理 -- 创建/删除钱包组，批量生成钱包，靓号地址生成（自定义后缀/前缀），CSV/JSON 导入导出，AES 加密存储私钥
• 批量交易 -- 多钱包同时买入/卖出，支持百分比卖出、全部卖出、狙击买入
• 专业做市工具 -- 换手交易（Jito Bundle 零滑点）、刷量工具（5 种模式）、价格机器人（自动拉升/砸盘）
• 多 DEX 支持 -- Pump.fun、PumpSwap、Raydium V4/CPMM、LaunchLab
• Jito MEV 保护 -- 交易捆绑发送，防止夹子攻击
• 代币创建 -- 支持 Pump.fun / LaunchLab 发币，IPFS 元数据上传，开盘狙击
• 链上查询 -- 余额、价格、K 线、交易记录、持仓监控
• 批量转账 -- 收集（多对一）、分发（一对多）、多对多转账
• 交易追踪 -- 自动追踪交易结果，持久化持仓和盈亏数据
• 灵活输出 -- 支持 JSON / Table / Minimal 三种输出格式

安装

环境要求

• Node.js >= 22.14.0
• npm
• solana-keygen（仅靓号生成功能需要，可选）

安装步骤

cd cli
npm install
npm run build

安装完成后可通过以下方式运行：

# 开发模式（tsx 直接运行 TypeScript）
npm run dev -- <command>

# 编译后运行
node dist/bin/forgex.js <command>

# 全局链接后
npm link
forgex <command>

快速上手

1. 初始化配置

# 创建默认配置文件 (~/.forgex/config.json)
forgex config init

# 设置 RPC 节点（推荐付费节点）
forgex config set rpcUrl https://your-rpc-url.com

# 设置 Codex API Key（代币信息和价格查询）
forgex config set codexApiKey your-codex-api-key

# 查看当前配置
forgex config list

2. 创建钱包组并生成钱包

# 创建本地钱包组
forgex wallet create-group --name "做市组A"

# 生成 5 个新钱包（首次使用需设置加密密码）
forgex wallet generate --group 1 --count 5

# 查看钱包组详情
forgex wallet group-info --id 1

# 列出所有钱包组
forgex wallet list-groups --format table

3. 分发 SOL 到钱包

# 从主钱包向钱包组每个钱包分发 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

4. 执行交易

# 批量买入（每个钱包买入 0.01 SOL 的代币）
forgex trade buy --group 1 --token <代币CA> --amount 0.01

# 全部卖出
forgex trade sell --group 1 --token <代币CA> --amount all

# 卖出 50%
forgex trade sell --group 1 --token <代币CA> --amount 50%

# 狙击买入（指定每个钱包不同金额）
forgex trade sniper --group 1 --token <代币CA> --amounts 0.1,0.2,0.15

5. 使用做市工具

# 刷量（1买1卖模式，执行 3 轮）
forgex tools volume --group 1 --token <代币CA> --mode 1b1s --amount 0.01 --rounds 3

# 换手交易（组A -> 组B）
forgex tools turnover --from-group 1 --to-group 2 --token <代币CA>

# 价格机器人（拉升到目标价格）
forgex tools robot-price --group 1 --token <代币CA> --direction up --target-price 0.001

6. 收集 SOL

# 将钱包组所有钱包的 SOL 收集到一个地址
forgex transfer in --to <目标地址> --from-group 1 --amount all

命令参考

全局选项

| 选项 | 说明 | 默认值 | |------|------|--------| | --password <password> | 钱包加密密码（跳过交互式输入，适合脚本/Agent 自动化） | - | | --format <format> | 输出格式: json | table | minimal | json | | --help | 显示帮助信息 | - | | --version | 显示版本号 | - |

所有交易类命令均支持 --dry-run（模拟执行）、--priority-fee（优先费 SOL）、--slippage（滑点 bps）。

config -- 配置管理

| 命令 | 说明 | |------|------| | config init | 初始化配置文件，支持 --rpc-url、--network | | config set <key> <value> | 设置配置项，支持点号路径 | | config get [key] | 查看配置项，不指定 key 显示全部 | | config list | 列出所有配置 |

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+ 字符可能数分钟）

trade -- 交易操作

| 命令 | 主要参数 | 说明 | |------|----------|------| | 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 | | trade sniper | --group, --token, --amounts | 狙击买入，amounts 逗号分隔，数量须匹配钱包数 |

tools -- 专业做市工具

| 命令 | 主要参数 | 说明 | |------|----------|------| | 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(砸盘) |

换手 (turnover) 额外参数:

• --amount: 金额类型，固定数量 / 百分比(50%) / all(默认)
• --daemon: 后台持续执行
• --rounds: 轮数（0=无限）
• --interval: 间隔毫秒

刷量 (volume) 额外参数:

• --mode: 1b1s(1买1卖) / 1b2s / 1b3s / 2b1s / 3b1s
• --daemon: 后台持续执行
• --rounds: 轮数（0=无限）
• --interval: 间隔毫秒

价格机器人 (robot-price) 额外参数:

• --amount-type: fixed / random
• --amount-max: random 模式最大金额
• --max-cost: 总消耗 SOL 上限
• 默认持续运行直到达到目标价格或成本上限，Ctrl+C 停止

transfer -- 转账操作

| 命令 | 主要参数 | 说明 | |------|----------|------| | 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 |

token -- 代币操作

| 命令 | 主要参数 | 说明 | |------|----------|------| | token create | --dex, --name, --symbol, --image | 创建代币，dex: pump / launchlab | | token info | --ca | 查询代币信息（名称、符号、价格、交易对等） | | token pool | --ca | 查询代币池子信息 |

代币创建额外参数:

• --description, --twitter, --website, --telegram: 元数据
• --dev-wallet: 开发者钱包组 ID，--dev-buy: 开发者买入金额
• --snipers: 狙击者钱包组 ID，--sniper-amounts: 狙击金额
• --bundle-time: T0(同区块) / T1_T5
• --use-suffix: 使用自定义后缀地址

T0 同区块狙击规则:

• 当 --bundle-time T0 时，sniper 买入必须通过 Jito Bundle 在同一区块完成，不允许使用普通 trade buy 补单（那样会落在后续区块，失去 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 要求较低

query -- 查询操作

| 命令 | 主要参数 | 说明 | |------|----------|------| | 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(可选) | 持仓监控（余额/均价/已实现&未实现盈亏） |

配置

配置文件位置

~/.forgex/config.json，通过 forgex config init 创建。

配置项

| 配置项 | 说明 | 默认值 | |--------|------|--------| | 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 |

环境变量

以下环境变量会覆盖配置文件中的对应值（优先级最高）：

| 环境变量 | 对应配置项 | |----------|-----------| | FORGEX_RPC_URL | rpcUrl | | FORGEX_CODEX_API_KEY | codexApiKey | | FORGEX_PASSWORD | 钱包加密密码（避免交互式输入，适合脚本自动化） |

安全

私钥加密

所有钱包私钥使用 AES 加密存储。首次创建或导入钱包时，CLI 要求设置加密密码。之后每次涉及私钥的操作（交易、导出等）都需要验证密码。

加密流程：

1. 用户设置主密码
2. 私钥通过 CryptoJS.AES.encrypt(privateKey, password) 加密后写入磁盘
3. 使用时通过 CryptoJS.AES.decrypt(encrypted, password) 临时解密到内存
4. 明文私钥仅在内存中使用，不持久化
5. 旧版明文存储会自动检测并迁移到加密格式

安全建议

• 使用强密码保护钱包
• 通过 --password 全局参数或环境变量 FORGEX_PASSWORD 设置密码，适合脚本/Agent 自动化场景（优先级: --password > FORGEX_PASSWORD > 交互式输入）
• 定期使用 wallet export-group --encrypt --password <pwd> 加密备份钱包数据
• 不要在公共环境或共享屏幕时使用 wallet group-info --show-keys
• 所有交易命令支持 --dry-run 预检，建议大额操作前先模拟验证
• 配置文件权限为 600（仅所有者可读写），目录权限为 700

文件存储

~/.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/                        # 运行日志

架构

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 适配

核心模块说明

• 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，提供买入/卖出/换手/刷量等交易构建和执行能力

输出系统

所有命令通过统一的 output() 函数输出数据，支持三种格式：

• json (默认): 结构化 JSON，适合程序解析和 Agent 集成
• table: cli-table3 表格，适合终端人工查看
• minimal: 简洁文本，仅输出关键信息

forgex wallet list-groups --format json
forgex wallet list-groups --format table
forgex wallet list-groups --format minimal

开发

开发环境

# 安装依赖
npm install

# 开发模式运行
npm run dev -- config list
npm run dev -- wallet list-groups --format table

# 编译 TypeScript
npm run build

# 清除编译产物
npm run clean

测试

# 运行全部测试
npm test

# 监听模式（文件变更自动重跑）
npm run test:watch

测试框架使用 vitest，测试文件位于 tests/ 目录，超时时间 30 秒。

项目结构

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/sniper)
      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 配置

技术栈

| 类别 | 技术 | |------|------| | 语言 | 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 |

Agent 集成

ForgeX CLI 支持 AI Agent（如 OpenClaw）无交互式调用。

密码传递

涉及私钥的操作需要 master password，有三种传递方式（按优先级）：

1. --password 全局参数（推荐）: 放在子命令之前

   forgex --password "your-password" trade buy --group 1 --token "CA..." --amount 0.01
   forgex --password="your-password" wallet list-groups

2. FORGEX_PASSWORD 环境变量:

   export FORGEX_PASSWORD="your-password"
   forgex trade buy --group 1 --token "CA..." --amount 0.01

3. 交互式输入: 不传密码时会弹出 inquirer 提示（Agent 环境下会阻塞，不推荐）

注意事项

• --password 是全局参数，必须放在子命令名之前（如 forgex --password "pwd" wallet ...）
• wallet import-group 和 wallet export-group 的 --password 是子命令参数（用于加密导入/导出文件），与全局 --password 不冲突
• Agent 应始终使用 --format json（默认值），以便解析结构化输出
• 首次执行高风险操作前应使用 --dry-run 模拟验证

T0 同区块发币规则（Agent 必须遵守）

1. T0 模式下 sniper 必须通过 Jito Bundle 买入，禁止使用 trade buy 补单（会落在后续区块，失去同区块狙击的意义）
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. 如果达到上限仍失败，应停止重试并告知用户，而非自动切换到普通交易

示例工作流

# 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

License

MIT