用 Hummingbot API 在 Meteora…

需要一套可复用的流程，在 Solana 的 Meteora DLMM 等集中流动性 DEX 上自动化部署、运行、监控和复盘 LP 做市策略。

适用场景

解决思路

1. 先运行引导向导 `/lp-agent start`：依次执行 `bash scripts/check_api.sh --json`、`bash scripts/check_gateway.sh --json`、`python scripts/add_wallet.py list`，并解读 JSON 输出（`running: true/false`、是否列出 `[solana] ABC...` 地址）。
2. 根据上述脚本输出生成 setup 进度清单（Hummingbot API / Gateway / Wallet 三项打勾），再按第一个未完成项给出下一步引导命令。
3. 部署 Hummingbot API：`bash scripts/deploy_hummingbot_api.sh status` 检查，`install` 交互安装，`install --defaults`（admin/admin）非交互安装，`upgrade` 升级，`logs` 看日志，`reset` 清空重置；前置条件是 Docker、Docker Compose 和 Git。安装后 Swagger UI 在 http://localhost:8000/docs，默认凭据 admin/admin。
4. 启动并配置 Gateway：`bash scripts/setup_gateway.sh --status` 只查状态；直接运行以默认值启动；可用 `--image`（默认 `hummingbot/gateway:development`）、`--passphrase`（默认 `hummingbot`）、`--port`（默认 `15888`）、`--network`（默认 `solana-mainnet-beta`）和 `--rpc-url` 定制。
5. 需要用更细控制时改用 `python scripts/manage_gateway.py`：`status` / `start` / `stop` / `restart` / `logs` / `networks` / `network <网络名>` / `network solana-mainnet-beta --node-url https://...`。
6. 必须提前配置自定义 RPC（不是可选）：编辑 `$GATEWAY_DIR/conf/chains/solana/mainnet-beta.yml` 里的 `nodeURL`（如在 https://helius.dev 申请免费 key），然后重启 Gateway；公共 Solana RPC 会被限流并伪装成 “Insufficient funds” 或 “Transaction simulation failed”。
7. 添加 Solana 钱包：运行 `python scripts/add_wallet.py add`，按提示粘贴 base58 私钥（不进 shell history）；成功后用 `python scripts/add_wallet.py list` 验证，出现 `[solana] ABC...` 即成功，`Error: HTTP 400` 说明私钥格式错误，`Error: Cannot connect to API` 说明 API 未启动。
8. 查询钱包余额：`python scripts/add_wallet.py balances`，可用 `--account master_account` 按账户过滤、`--all` 显示零余额；部署前务必确认具体 SPL token 账户里的可用余额（可能与链上总额不同）。
9. 使用非标准代币（如 memecoin）时先加入 Gateway：`python scripts/add_wallet.py add-token --symbol Percolator --address <mint> --decimals 6`，symbol 必须与池中完全一致（否则报 “No CLMM pool found”），之后重启 Gateway 才生效。
10. 确认钱包有足够 SOL 支付手续费（每个 LP 仓位约 0.06 SOL 作为 rent），默认链为 Solana mainnet-beta。
11. 探索池子（无需前置条件，直接查 Meteora API）：`python scripts/list_meteora_pools.py` 看 24h 成交量排行；用 `--query SOL` / `--query SOL-USDC` 按代币或池名搜索；用 `--sort tvl|apr|fees` 排序；用 `--limit 50 --page 2` 分页；关注 TVL、24h 成交量、24h 手续费、APR、fee、bin step 等列，并用 token mint 区分同名代币。
12. 查看池子详情：`python scripts/get_meteora_pool.py <pool_address>`（可加 `--json` 供程序消费，`--no-gateway` 跳过 Gateway 以加快速度）；数据来自 Meteora API（历史成交量/手续费/APR/token 信息/市值）和 Gateway（实时价格、按 bin 的流动性分布）。
13. 选池时综合看四点：TVL（越高越稳但竞争越激烈）、成交量（越高手续费机会越多）、Fee/TVL 比率（越高每美元流动性越赚）、bin step 决定最大区间宽度（bin_step=1 → 约 0.69%，10 → 约 6.9%，100 → 约 69%）。
14. 选择策略：默认推荐 LP Rebalancer Controller（价格出区间自动平仓重开、支持 BUY/SELL 价格上下限与锚点、KEEP 逻辑避免无谓再平衡、hands-off），参考 `references/lp_rebalancer_guide.md`；单仓位场景用 LP Executor（固定上下界、手动平开、可当限价单自动平仓），参考 `references/lp_executor_guide.md`。
15. 用 Rebalancer Controller 部署：先 `python scripts/manage_controller.py create-config my_lp_config --pool <pool_address> --pair SOL-USDC --amount 10 --side 0 --width 10 --offset 1 --rebalance-seconds 300 --rebalance-threshold 1`，再 `python scripts/manage_controller.py deploy my_lp_bot --configs my_lp_config`，然后用 `status` 监控；停止用 `python scripts/manage_controller.py stop my_lp_bot`。
16. 务必记住 Controller 参数规则：`total_amount_quote` 永远是交易对中第二个 token（quote 资产，如 Percolator-SOL → SOL、SOL-USDC → USDC），即使是 `--side 2`（只卖 base）也用 quote 计价（base 数量 × 以 quote 计的价格）；所有 `*_pct` 参数本身就是百分比，`position_width_pct: 10` 就是 10%，不要写成 0.10；价格上下限（`--buy-min/max`、`--sell-min/max`）默认 `null` 表示不限制；`--strategy-type` 取 0=Spot（均匀）、1=Curve（中间重）、2=Bid-Ask（边缘重）。
17. 用 LP Executor 部署单仓位：`python scripts/manage_executor.py create --pool <pool_address> --pair SOL-USDC --quote-amount 100 --lower 180 --upper 185 --side 1`；`--connector` 必须带 `/clmm` 后缀（默认 `meteora/clmm`）；单边仓位把另一边的 amount 设为 0；用 `--auto-close-above` / `--auto-close-below` 实现限价单式自动平仓。
18. 监控与管理：`python scripts/manage_controller.py status` 看 bot；`python scripts/manage_executor.py list --type lp_executor`、`get <executor_id>`、`summary` 看执行器；执行器状态有 OPENING、IN_RANGE、OUT_OF_RANGE、CLOSING、FAILED。
19. 停止策略：`python scripts/manage_controller.py stop my_lp_bot` 停 bot（同时停其所有 controller）；`python scripts/manage_executor.py stop <executor_id>` 平掉仓位，加 `--keep-position` 则保留链上仓位。
20. 分析业绩前必须先判断仓位是怎么部署的：通过 `manage_executor.py create` 或直接 `POST /executors/` 部署的用 `visualize_lp_executor.py --id <executor_id>`；通过 `manage_controller.py deploy`（bot 容器 + SQLite）部署的用 `visualize_lp_positions.py --pair <pair>`；不确定时用 `curl -s -u admin:admin -X POST http://localhost:8000/executors/search -H "Content-Type: application/json" -d '{"type":"lp_executor"}'` 查执行器是否存在。executor id 在创建时会打印为 `Executor ID: <id>`。
21. 可视化 SQLite 历史仓位（运行中和已停止的 bot 都适用）：`python scripts/visualize_lp_positions.py --pair SOL-USDC`，可用 `--db data/my_bot.sqlite` 指定库、`--connector meteora/clmm` 过滤、`--hours 24` 只看最近 24 小时；导 CSV 用 `python scripts/export_lp_positions.py --pair SOL-USDC --output exports/positions.csv`，只看摘要用 `--summary`。
22. 用 REST API 直接导出/可视化单个 executor（不依赖 SQLite）：`python scripts/export_lp_executor.py --id <executor_id> [--output exports/my_run.csv] [--print]`，以及 `python scripts/visualize_lp_executor.py --id <executor_id> [--output report.html] [--no-open]`；脚本认证自动从 `.env`、`~/.hummingbot/.env` 或 `~/.env` 读取 `HUMMINGBOT_API_URL`、`API_USER`、`API_PASS`。
23. 部署前检查钱包余额再算 `--amount`：`python scripts/add_wallet.py balances`，因为钱包可能有多个 SPL 账户，只有特定账户里的可用余额才能部署。
24. 在 macOS 上 Gateway 必须以 Docker（`--network host`）方式运行，不能用 dev 模式（`pnpm start`），因为容器访问不到宿主机进程；对应 bot 的 `conf_client.yml` 里设 `gateway_api_host: localhost`。
25. 部署 bot 使用 `hummingbot/hummingbot:development` 镜像而非 `latest`（`manage_controller.py` 默认就是 development），否则可能没有 LP executor 支持。
26. 需要平掉某池所有仓位时用 Gateway API：先 `curl -s "http://localhost:15888/connectors/meteora/clmm/positions-owned?network=mainnet-beta&walletAddress=<WALLET>"` 列出，再对每个仓位 `curl -s -X POST http://localhost:15888/connectors/meteora/clmm/close-position -H "Content-Type: application/json" -d '{"network":"mainnet-beta","address":"<WALLET>","positionAddress":"<POSITION>"}'`。
27. 按错误对照表排障：InvalidRealloc → 减小 `--width`（注意 bin_step 上限）；卡在 OPENING → 停掉 executor、缩小区间重试；“Insufficient funds”/“Transaction simulation failed” → 配自定义 RPC，并确认 `--amount` 单位是 quote；“No CLMM pool found for X-Y” → 用池中完全一致的 token symbol（如 `Percolator` 而非 `PRCLT`）；`'meteora/clmm' KeyError` → 需 hummingbot-api PR #120+（`feat/lp-executor` 分支）；“meteora/clmm is not ready” → Gateway 以 Docker `--network host` 运行；“Failed to load strategy”/密码错误 → 把 `bots/credentials/master_account/.password_verification` 拷到 `bots/bots/instances/<bot>/conf/`；`candles_config / markets extra inputs` → 用只含 `controllers_config` 和 `script_file_name` 的最小配置；API 显示 stopped 但 Docker 仍在跑 → MQTT 未连上，直接看 bot 日志。

适用边界 · 注意事项

• 不使用 Hummingbot API + Gateway 基础设施、不愿意用 Docker 部署这两个服务时，本流程不适用。
• 目标不是 Solana 上的 Meteora DLMM（或其他 CLMM DEX）而是普通 AMM 或其他链、或只想一次性手动操作而不跑自动化策略时，不适用。
• 没有 Solana 钱包与 SOL 手续费预算（每个 LP 仓位约 0.06 SOL rent）、也没有自建 RPC key（Helius/QuickNode/Alchemy/Triton 等）时，不要部署 bot，否则会因公共 RPC 限流而频繁失败。