lp-agent

lp-agent

这项技能可帮助你通过 Hummingbot API，在集中流动性（CLMM）DEX 上运行自动化流动性提供策略。

命令（以 /lp-agent <command> 的形式运行）：

命令	说明
start	入门向导 — 检查设置状态并开始使用
deploy-hummingbot-api	部署 Hummingbot API 交易基础设施
setup-gateway	启动 Gateway，配置网络 RPC 端点
add-wallet	添加或导入 Solana 钱包
explore-pools	查找并探索 Meteora DLMM 流动性池
select-strategy	选择 LP Executor 或 Rebalancer Controller
run-strategy	运行、监控和管理 LP 策略
analyze-performance	可视化 LP 持仓表现

刚开始使用？ 运行 /lp-agent start，检查设置状态并获取引导式操作说明。

典型工作流： start → deploy-hummingbot-api → setup-gateway → add-wallet → explore-pools → select-strategy → run-strategy → analyze-performance

---

命令：start

欢迎用户并引导他们完成设置。这是一个对话式入门向导 — 检查基础设施状态、解读结果，并逐步指导用户完成各项操作。

步骤 1：欢迎并说明

自我介绍并说明 lp-agent 的功能：

我是你的 LP Agent，可帮助你在 Meteora DLMM 流动性池（Solana）上运行自动化流动性提供策略。我可以：

• 部署基础设施 — 使用 Hummingbot API 和 Gateway 进行 DEX 交易
• 管理钱包 — 添加 Solana 钱包、查看余额
• 探索流动性池 — 搜索 Meteora DLMM 流动性池、比较 APR/交易量/TVL
• 运行策略 — 自动再平衡 LP 控制器或单仓位执行器
• 分析表现 — 显示盈亏、手续费和持仓历史的仪表板

步骤 2：检查基础设施状态

运行这些脚本并解读 JSON 输出：

bash scripts/check_api.sh --json      # Is Hummingbot API running?
bash scripts/check_gateway.sh --json  # Is Gateway running?
python scripts/add_wallet.py list     # Any wallets connected?

结果解读：

脚本	成功输出	失败输出
check_api.sh --json	{"running": true, "url": "http://localhost:8000", ...}	{"running": false, ...} 或连接错误
check_gateway.sh --json	{"running": true, ...}	{"running": false, ...}
add_wallet.py list	显示钱包地址，例如 [solana] ABC123...	No wallets found. 或空列表 []

步骤 3：显示进度

根据脚本输出，展示已完成和待完成事项的清单：

Setup Progress:
  [x] Hummingbot API    — Running at http://localhost:8000
  [x] Gateway           — Running
  [ ] Wallet            — No wallet connected

Next step: Add a Solana wallet so you can start trading.

根据实际状态调整清单。如果所有事项都未勾选，就从头开始。如果所有事项都已勾选，就跳到 LP 生命周期概述。

步骤 4：指导下一步操作

根据第一个未勾选事项，提出帮助：

缺少项	说明内容
Hummingbot API	“我们先部署 API — 它是交易后端。需要安装 Docker。要我运行安装程序吗？” → /lp-agent deploy-hummingbot-api
Gateway	“API 已运行！现在需要 Gateway 来连接 DEX。要我启动它吗？” → /lp-agent setup-gateway
钱包	参见下文添加钱包
全部就绪	进入步骤 5

添加钱包：

钱包是下一步时，告诉用户：

基础设施已就绪。你需要一个带有 SOL 的 Solana 钱包来支付交易手续费（每个 LP 仓位约需 0.06 SOL）。

要添加钱包，请运行：

python scripts/add_wallet.py add

系统会提示你粘贴私钥（安全，不会保存到 Shell 历史记录中）。

解读 add_wallet.py 的输出：

输出	含义
✓ Wallet added successfully + 地址	成功 — 钱包已连接
Enter private key (base58): 然后出现 ✓ Wallet added	成功，已响应提示
Error: HTTP 400 或验证错误	私钥格式无效
Error: Cannot connect to API	API 未运行 — 请先运行 check_api.sh

添加钱包后，使用 python scripts/add_wallet.py list 验证 — 应显示新地址。

第 5 步：LP 生命周期概览

基础设施准备就绪后（或者用户想先了解整个流程时），说明 LP 生命周期：

LP 策略的运作方式：

1. 探索池（/lp-agent explore-pools）— 查找 Meteora DLMM 池。查看交易量、APR 和手续费/TVL 比率，选出合适的池。

2. 选择策略（/lp-agent select-strategy）— 在以下选项中选择：

   • Rebalancer Controller（推荐）— 当价格移出范围时自动调整仓位。设置后无需操心。
   • LP Executor — 单个固定仓位。由你决定何时平仓或重新开仓。适合测试或类似限价单的 LP。

3. 运行策略（/lp-agent run-strategy）— 配置参数（金额、宽度、价格限制）并部署。监控状态，完成后停止。

4. 分析（/lp-agent analyze-performance）— 查看 PnL 仪表板、赚取的手续费和仓位历史。运行中或已停止的策略均适用。

想从探索一些池开始吗？

---

命令：deploy-hummingbot-api

部署 Hummingbot API 交易基础设施。这是使用任何 LP 功能前的第一步。

安装内容

Hummingbot API — 个人交易服务，提供用于交易、市场数据以及在 CEX 和 DEX 上部署机器人策略的 REST API。

• 仓库：hummingbot/hummingbot-api

用法

# Check if already installed
bash scripts/deploy_hummingbot_api.sh status

# Install (interactive, prompts for credentials)
bash scripts/deploy_hummingbot_api.sh install

# Install with defaults (non-interactive: admin/admin)
bash scripts/deploy_hummingbot_api.sh install --defaults

# Upgrade existing installation
bash scripts/deploy_hummingbot_api.sh upgrade

# View container logs
bash scripts/deploy_hummingbot_api.sh logs

# Reset (stop and remove everything)
bash scripts/deploy_hummingbot_api.sh reset

先决条件

• Docker 和 Docker Compose
• Git

解读输出

输出	含义	下一步
✓ Hummingbot API deployed successfully	成功	继续执行 setup-gateway
✓ Already installed and running	已完成设置	继续执行 setup-gateway
Error: Docker not found	未安装 Docker	请先安装 Docker
Error: Port 8000 already in use	端口被其他服务占用	停止冲突的服务或使用其他端口

安装后

API 运行后：

1. Swagger UI 位于 http://localhost:8000/docs
2. 默认凭据：admin/admin
3. 继续执行 setup-gateway 以启用 DEX 交易

---

命令：setup-gateway

启动 Gateway 服务、检查其状态，并配置 RPC 节点 URL 等关键网络参数。在 DEX 上执行所有 LP 操作都需要 Gateway。

先决条件： Hummingbot API 必须正在运行（deploy-hummingbot-api）。脚本会自动检查。

⚠️ 必须配置自定义 RPC，不可省略。 公共 Solana RPC 有速率限制，会导致交易失败，错误看起来可能是“余额不足”或“交易模拟失败”。部署任何机器人前，请务必配置自定义 RPC。可在 https://helius.dev 免费获取密钥。

用法

# Check Gateway status
bash scripts/setup_gateway.sh --status

# Start Gateway with defaults
bash scripts/setup_gateway.sh

# Start Gateway with custom image (e.g., development build)
bash scripts/setup_gateway.sh --image hummingbot/gateway:development

# Start with custom Solana RPC (recommended to avoid rate limits)
bash scripts/setup_gateway.sh --rpc-url https://your-rpc-endpoint.com

# Configure RPC for a different network
bash scripts/setup_gateway.sh --network ethereum-mainnet --rpc-url https://your-eth-rpc.com

# Start with custom passphrase and port
bash scripts/setup_gateway.sh --passphrase mypassword --port 15888

选项

选项	默认值	说明
--status		仅检查 Gateway 状态（不启动）
--image IMAGE	hummingbot/gateway:development	要使用的 Docker 镜像
--passphrase TEXT	hummingbot	Gateway 密码短语
--rpc-url URL		--network 对应的自定义 RPC 端点
--network ID	solana-mainnet-beta	要配置 RPC 的网络
--port PORT	15888	Gateway 端口

高级用法：manage_gateway.py

如需更精细的控制（停止、重启、查看日志、按网络配置），请使用 manage_gateway.py：

python scripts/manage_gateway.py status                    # Check status
python scripts/manage_gateway.py start                     # Start Gateway
python scripts/manage_gateway.py stop                      # Stop Gateway
python scripts/manage_gateway.py restart                   # Restart Gateway
python scripts/manage_gateway.py logs                      # View logs
python scripts/manage_gateway.py networks                  # List all networks
python scripts/manage_gateway.py network solana-mainnet-beta                          # Get network config
python scripts/manage_gateway.py network solana-mainnet-beta --node-url https://...   # Set RPC node

解读输出

输出	含义	下一步
✓ Gateway is running 或 ✓ Gateway started	成功	继续执行 add-wallet
✓ Gateway is already running	已完成设置	继续执行 add-wallet
✗ Cannot connect to Hummingbot API	API 未运行	请先运行 /lp-agent deploy-hummingbot-api
✗ Failed to start Gateway	Docker 问题	检查 Docker 是否正在运行，并查看日志
✓ RPC configured + ✓ Gateway restarted	自定义 RPC 已设置	可以开始使用

自定义 RPC 节点

Gateway 默认使用公共 RPC 节点，可能会触发速率限制。为每个网络设置自定义 nodeUrl 即可避免此问题。

热门的 Solana RPC 服务提供商：

• Helius — 提供免费套餐
• QuickNode
• Alchemy
• Triton

---

命令：add-wallet

添加用于交易的 Solana 钱包。

需要： 请先完成 deploy-hummingbot-api 和 setup-gateway。

添加钱包

python scripts/add_wallet.py add

系统会提示你粘贴私钥（base58 格式）。输入密钥时会受到安全保护，且不会出现在 shell 历史记录中。

输出说明：

输出	含义	下一步
✓ Wallet added successfully + Address: ABC...	成功	使用 list 命令验证
Error: HTTP 400 - Bad Request	私钥格式无效	检查密钥是否以 base58 编码
Error: HTTP 503	Gateway 不可用	运行 bash scripts/check_gateway.sh
Error: Cannot connect to API	API 未运行	运行 /lp-agent deploy-hummingbot-api

列出钱包

python scripts/add_wallet.py list

输出说明：

输出	含义
[solana] ABC123...XYZ	已连接 Solana 钱包
No wallets found.	尚未添加钱包
空列表 []（使用 --json 时）	尚未添加钱包

查看余额

# Check all balances
python scripts/add_wallet.py balances

# Filter by account
python scripts/add_wallet.py balances --account master_account

# Show zero balances too
python scripts/add_wallet.py balances --all

向 Gateway 添加自定义代币

使用非标准代币（例如 memecoin）时，请先将其添加到 Gateway：

# Use exact symbol from the pool (check with get_meteora_pool.py)
python scripts/add_wallet.py add-token \
  --symbol Percolator \
  --address 8PzFWyLpCVEmbZmVJcaRTU5r69XKJx1rd7YGpWvnpump \
  --decimals 6

⚠️ 代币符号必须与池中的完全一致。 使用 get_meteora_pool.py 查找准确的代币符号。如果池中显示 Percolator，就使用 Percolator，不要使用 PRCLT 或任何缩写。符号不匹配会导致机器人获取价格数据时出现“No CLMM pool found”错误。

然后重启 Gateway，以便识别该代币。

要求

• 用于支付手续费的 SOL：钱包需要 SOL 来支付交易手续费（每个 LP 仓位约需 0.06 SOL 作为租金）
• 部署前检查实际余额：使用 balances 命令——SPL 代币账户中的可用金额可能与链上总额不同（例如存在多个账户、已质押等情况）
• 默认链：Solana mainnet-beta

---

命令：explore-pools

在创建 LP 仓位前查找并探索 Meteora DLMM 池。

**注意：**无需任何前置条件即可列出池（list_meteora_pools.py），该命令会直接查询 Meteora API。获取池详情（get_meteora_pool.py）时，可选择使用 Gateway 查看实时价格和流动性图表。

列出池

按名称、代币或地址搜索并列出池：

# Top pools by 24h volume
python scripts/list_meteora_pools.py

# Search by token symbol
python scripts/list_meteora_pools.py --query SOL
python scripts/list_meteora_pools.py --query USDC

# Search by pool name
python scripts/list_meteora_pools.py --query SOL-USDC

# Sort by different metrics
python scripts/list_meteora_pools.py --query SOL --sort tvl
python scripts/list_meteora_pools.py --query SOL --sort apr
python scripts/list_meteora_pools.py --query SOL --sort fees

# Pagination
python scripts/list_meteora_pools.py --query SOL --limit 50 --page 2

输出列：

• 池：交易对名称
• 池地址：池合约地址（缩短显示；使用 get_meteora_pool.py 获取完整地址）
• Base (mint)：基础代币符号及缩短显示的 mint 地址
• Quote (mint)：计价代币符号及缩短显示的 mint 地址
• TVL：锁定总价值
• Vol 24h：24 小时交易量
• Fees 24h：过去 24 小时赚取的手续费
• APR：年化收益率
• Fee：基础手续费率
• Bin：Bin 步长（影响仓位最大宽度）

**注意：**当多个代币名称相同时，代币 mint 有助于识别正确的代币（例如存在多个名为“PERCOLATOR”的代币）。

获取池详情

获取指定池的详细信息。数据来自 Meteora API（历史数据）和 Gateway（实时数据）：

python scripts/get_meteora_pool.py <pool_address>

# Example
python scripts/get_meteora_pool.py ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms

# Output as JSON for programmatic use
python scripts/get_meteora_pool.py ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms --json

# Skip Gateway (faster, no bin distribution)
python scripts/get_meteora_pool.py ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms --no-gateway

数据来源：

• Meteora API：历史交易量、手续费、APR、代币信息、市值
• Gateway（需要 Gateway 正在运行）：实时价格、按 bin 显示的流动性分布

显示的详情：

• 代币信息（符号、mint、精度、小数位数、价格）
• 池配置（bin 步长、手续费、最大范围宽度）
• 来自 Gateway 的实时价格（SOL/代币比率）
• 显示当前价格附近各 bin 的流动性分布图
• 流动性和储备金
• 各时间范围的交易量（30m、1h、4h、12h、24h）
• 各时间范围赚取的手续费
• 收益率（APR、APY、农场奖励）
• Fee/TVL 比率（盈利能力指标）

选择池

选择池时，请考虑：

1. TVL：TVL 越高，稳定性越强，但竞争也越激烈
2. 交易量：交易量越高，手续费机会越多
3. 手续费/TVL 比率：比率越高，每单位流动性资金的盈利能力越强
4. Bin 步长：决定仓位的最大宽度
   • bin_step=1 → 最大宽度约为 0.69%（窄区间）
   • bin_step=10 → 最大宽度约为 6.9%（中等区间）
   • bin_step=100 → 最大宽度约为 69%（宽区间）

---

命令：select-strategy

帮助用户选择合适的 LP 策略。详细指南请参阅 references/。

LP Rebalancer Controller（推荐）

参考： references/lp_rebalancer_guide.md

一种通过再平衡逻辑自动管理 LP 仓位的控制器。

功能	说明
自动再平衡	当价格超出区间时，平仓并重新开仓
价格限制	使用锚定点配置 BUY/SELL 区域
KEEP 逻辑	仓位处于最佳状态时，避免不必要的再平衡
免手动操作	设置后即可不再过问，由控制器管理一切

最适合： 长期 LP 策略、区间震荡市场、自动收取手续费。

LP Executor（单一仓位）

参考： references/lp_executor_guide.md

以固定价格边界创建一个流动性仓位。不支持自动再平衡。

功能	说明
固定边界	仓位保持在配置的价格区间内
手动控制	用户决定何时平仓或重新开仓
限价单	价格超出区间时可自动平仓（类似限价单）
简单易用	可直接控制单一仓位

最适合： 短期仓位、限价单式 LP、手动管理、测试。

快速比较

方面	Rebalancer Controller	LP Executor
再平衡	自动	手动
仓位数量	一次一个，自动管理	一个，固定
价格限制	有（锚定点）	无（但支持自动平仓）
复杂度	较高（配置更多）	较低（更简单）
使用场景	设置后无需操心	精确控制

---

命令：run-strategy

运行、监控和管理 LP 策略。

需要： 请先完成 deploy-hummingbot-api、setup-gateway 和 add-wallet。

LP 再平衡控制器（推荐）

**参考：**完整配置详情、再平衡逻辑以及 KEEP 与 REBALANCE 场景，请参阅 references/lp_rebalancer_guide.md。

当价格超出区间时自动再平衡仓位。最适合免操作的 LP 管理。

关键概念：

• --amount（total_amount_quote）= 报价资产的数量（交易对中的第 2 个代币）。对于 Percolator-SOL，即 SOL；对于 SOL-USDC，即 USDC。始终使用报价资产，与方向无关。
• 所有 *_pct 参数的值都已是百分比。position_width_pct: 10 = 10% 的宽度。不要传入小数（不能是 0.10）。
• 价格限制（--buy-min/max、--sell-min/max）默认值为 null = 不设限制。仅在需要设置止损区间时才设置。

# 1. Create LP Rebalancer config (pool and pair are required)
python scripts/manage_controller.py create-config my_lp_config \
    --pool <pool_address> \
    --pair SOL-USDC \
    --amount 10 \       # 10 USDC (quote asset for SOL-USDC)
    --side 0 \          # 0=BOTH, 1=BUY (quote only), 2=SELL (base only)
    --width 10 \        # 10% range around current price
    --offset 1 \        # center range 1% from current price
    --rebalance-seconds 300 \
    --rebalance-threshold 1

# Side=2 example: deploy base token only (e.g. 110k PRCLT ≈ 1.33 SOL)
python scripts/manage_controller.py create-config percolator_sell \
    --pool ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms \
    --pair Percolator-SOL \
    --amount 1.33 \     # 1.33 SOL worth (quote for Percolator-SOL pair)
    --side 2

# 2. Deploy bot with the config
python scripts/manage_controller.py deploy my_lp_bot --configs my_lp_config

# 3. Monitor status
python scripts/manage_controller.py status

关键参数：

参数	字段	默认值	说明
--amount	total_amount_quote	必填	报价资产的数量（第 2 个代币）。对于 X-SOL 交易对使用 SOL，对于 X-USDC 交易对使用 USDC。
--side	side	0	0=两侧，1=买入（仅报价资产），2=卖出（仅基础资产）
--width	position_width_pct	10	区间宽度（%）（例如，10 = 价格上下各 ±10%）。值已是百分比，不要使用小数。
--offset	position_offset_pct	0.1	相对当前价格的中心偏移（%）。值已是百分比。
--rebalance-seconds	rebalance_seconds	300	超出区间后等待多少秒再平仓并重新开仓
--rebalance-threshold	rebalance_threshold_pct	1	触发再平衡所需的最小价格变动（%）。值已是百分比。
--sell-max/--sell-min	sell_price_max/min	null	卖出方向的价格限制（null = 不设限制）
--buy-max/--buy-min	buy_price_max/min	null	买入方向的价格限制（null = 不设限制）
--strategy-type	strategy_type	0	Meteora 形状：0=现货（均匀分布），1=曲线（中心密集），2=买卖价差（边缘密集）

单一 LP 执行器（替代方案）

**参考：**状态机、单边／双边仓位以及限价区间订单，请参阅 references/lp_executor_guide.md。

创建一个具有固定边界的仓位。不会自动再平衡。

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）
--lower/--upper	仓位价格边界
--base-amount/--quote-amount	代币数量（单边仓位时，将其中一个设为 0）
--side	0=两侧，1=买入，2=卖出
--auto-close-above	价格高于区间时自动平仓（用于限价订单）
--auto-close-below	价格低于区间时自动平仓（用于限价订单）

监控与管理

检查状态：

# Bot status
python scripts/manage_controller.py status

# Executor list
python scripts/manage_executor.py list --type lp_executor

# Executor details
python scripts/manage_executor.py get <executor_id>

# Executor summary
python scripts/manage_executor.py summary

执行器状态：

• OPENING - 正在链上创建仓位
• IN_RANGE - 仓位有效，正在赚取手续费
• OUT_OF_RANGE - 价格超出仓位边界
• CLOSING - 正在移除仓位
• FAILED - 交易失败

停止：

# Stop bot (stops all its controllers)
python scripts/manage_controller.py stop my_lp_bot

# Stop individual executor (closes position)
python scripts/manage_executor.py stop <executor_id>

# Stop executor but keep position on-chain
python scripts/manage_executor.py stop <executor_id> --keep-position

停止后 — 分析结果

如果用户运行了 LP 执行器（通过 manage_executor.py create 或直接调用 API），请立即主动提出为其分析：

执行器已停止。要我生成绩效仪表板吗？

然后运行：

python scripts/visualize_lp_executor.py --id <executor_id>

创建执行器时会返回执行器 ID（输出为 Executor ID: <id>）。如果用户手边没有该 ID，可从 API 获取：

curl -s -u admin:admin -X POST http://localhost:8000/executors/search \
  -H "Content-Type: application/json" \
  -d '{"type":"lp_executor"}' | python3 -c "
import json,sys
data=json.load(sys.stdin)
items=data.get('data',data) if isinstance(data,dict) else data
for ex in (items if isinstance(items,list) else [items]):
    print(ex.get('executor_id') or ex.get('id'), ex.get('trading_pair'), ex.get('status'))
"

如需同时将原始数据导出为 CSV：

python scripts/export_lp_executor.py --id <executor_id>

如果用户运行了再平衡控制器机器人，数据存储在 SQLite 文件中——请使用基于 SQLite 的脚本运行 analyze-performance。

---

命令：analyze-performance

从 LP 仓位事件中导出数据并生成可视化仪表板。脚本位于此技能的 scripts/ 目录中。

应该使用哪个脚本？

务必先确认：此头寸是通过 LP Executor（使用 manage_executor.py 或直接调用 API）部署的，还是通过 Rebalancer Controller 机器人部署的？

部署方式	应使用的脚本
LP Executor — manage_executor.py create 或直接调用 POST /executors/ API	visualize_lp_executor.py --id <executor_id> ✅
Rebalancer Controller — manage_controller.py deploy（机器人容器、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"}' — 如果出现执行器 ID，请使用执行器脚本

如果用户在当前会话中一直运行 LP Executor（上下文中已知执行器 ID），请跳过提问，直接执行：

python scripts/visualize_lp_executor.py --id <executor_id>

可用脚本

脚本	用途
scripts/export_lp_positions.py	将 LP 头寸事件导出为 CSV（基于 SQLite／机器人容器）
scripts/visualize_lp_positions.py	根据头寸事件生成 HTML 仪表板（基于 SQLite／机器人容器）
scripts/export_lp_executor.py	按 --id 将单个 LP 执行器导出为 CSV（REST API，无需 SQLite）
scripts/visualize_lp_executor.py	按 --id 为单个 LP 执行器生成 HTML 仪表板（REST API）

可视化 LP 头寸

显示区块链上的头寸 ADD／REMOVE 事件。运行中和已停止的机器人均适用。

# Basic usage (auto-detects database in data/)
python scripts/visualize_lp_positions.py --pair SOL-USDC

# Specify database explicitly
python scripts/visualize_lp_positions.py --db data/my_bot.sqlite --pair SOL-USDC

# Filter by connector
python scripts/visualize_lp_positions.py --pair SOL-USDC --connector meteora/clmm

# Last 24 hours only
python scripts/visualize_lp_positions.py --pair SOL-USDC --hours 24

仪表板功能：

• KPI 卡片（总 PnL、手续费、IL、盈亏次数）
• 累计 PnL 和手续费图表
• 开仓／平仓时的价格及 LP 区间边界
• 按头寸显示的 PnL 柱状图
• 持续时间与 PnL 散点图
• 可排序的头寸表格，含 Solscan 链接

导出为 CSV

# Export all position events
python scripts/export_lp_positions.py --db data/my_bot.sqlite

# Filter by trading pair
python scripts/export_lp_positions.py --pair SOL-USDC --output exports/positions.csv

# Show summary without exporting
python scripts/export_lp_positions.py --summary

执行器表现（基于 API）

这些脚本直接通过 Hummingbot REST API 工作，无需 SQLite 数据库。 当执行器是通过 API 直接部署时（例如使用 manage_executor.py），请使用这些脚本， 因为这类部署不一定会像机器人容器那样生成 SQLite 记录。

将单个 LP 执行器导出为 CSV：

python scripts/export_lp_executor.py --id <executor_id>
python scripts/export_lp_executor.py --id <executor_id> --output exports/my_run.csv
python scripts/export_lp_executor.py --id <executor_id> --print   # JSON to stdout

CSV 列（LP 执行器架构）：

• 标识信息： id, account_name, controller_id, connector_name, trading_pair
• 状态： status, close_type, is_active, is_trading, error_count
• 时间： created_at, closed_at, close_timestamp, duration_seconds
• PnL： net_pnl_quote, net_pnl_pct, cum_fees_quote, filled_amount_quote
• 配置（部署）： pool_address, lower_price, upper_price, base_amount_config, quote_amount_config, side, position_offset_pct, auto_close_above_range_seconds, auto_close_below_range_seconds, keep_position
• custom_info（实时／最终）： state, position_address, current_price, lower_price_actual, upper_price_actual, base_amount_current, quote_amount_current, base_fee, quote_fee, fees_earned_quote, total_value_quote, unrealized_pnl_quote, position_rent, position_rent_refunded, tx_fee, out_of_range_seconds, max_retries_reached, initial_base_amount, initial_quote_amount

可视化单个 LP 执行器（HTML 仪表板）：

python scripts/visualize_lp_executor.py --id <executor_id>
python scripts/visualize_lp_executor.py --id <executor_id> --output report.html
python scripts/visualize_lp_executor.py --id <executor_id> --no-open

仪表板面板：

• KPI 卡片：状态、净 PnL、已赚取手续费、持续时间、LP 区间
• 带有 LP 下限／上限及开仓／平仓标记的价格图表（KuCoin 5 分钟 K 线；遇到特殊交易对时会自动跳过）
• 代币余额柱状图：初始与最终的基础代币和报价代币数量
• PnL 明细：已赚取手续费、IL／价格影响和净 PnL
• 完整的头寸摘要表格，含池和头寸地址的 Solscan 链接
• 深色主题（#0d1117／#161b27）、自适应布局、来自 CDN 的 Chart.js
• 自动从 .env、~/.hummingbot/.env 或 ~/.env 加载身份验证信息（键：HUMMINGBOT_API_URL、API_USER、API_PASS）

---

快速参考

常见工作流

完整设置（首次）：

# 1. Deploy API
bash scripts/deploy_hummingbot_api.sh install

# 2. Start Gateway
bash scripts/setup_gateway.sh --rpc-url https://your-rpc-endpoint.com

# 3. Add wallet
python scripts/add_wallet.py add

# 4. Find pool
python scripts/list_meteora_pools.py --query SOL-USDC

# 5. Check bin_step
python scripts/get_meteora_pool.py <pool_address>

# 6. Create config and deploy
python scripts/manage_controller.py create-config my_lp --pool <pool_address> --pair SOL-USDC --amount 100
python scripts/manage_controller.py deploy my_bot --configs my_lp

# 7. Verify
python scripts/manage_controller.py status

分析 LP 头寸：

# Visualize
python scripts/visualize_lp_positions.py --pair SOL-USDC

# Export CSV
python scripts/export_lp_positions.py --pair SOL-USDC

前提条件检查

运行需要 API 或 Gateway 的命令前，请确认它们正在运行：

bash scripts/check_api.sh       # Is Hummingbot API running?
bash scripts/check_gateway.sh   # Is Gateway running? (also checks API)

两者都支持 --json 输出。这些脚本也由 setup_gateway.sh 在内部使用，其他 Shell 脚本也可以将其作为源文件引入。

脚本参考

脚本	用途
check_api.sh	检查 Hummingbot API 是否正在运行（共享）
check_gateway.sh	检查 Gateway 是否正在运行（共享）
deploy_hummingbot_api.sh	安装、升级和管理 Hummingbot API
setup_gateway.sh	启动 Gateway 并配置 RPC
add_wallet.py	添加钱包并检查余额
manage_gateway.py	高级 Gateway 管理
list_meteora_pools.py	搜索并列出池
get_meteora_pool.py	获取池详情和流动性图表
manage_executor.py	创建、列出和停止 LP 执行器
manage_controller.py	创建配置、部署机器人并获取状态
export_lp_positions.py	将仓位事件导出为 CSV（SQLite/机器人容器）
visualize_lp_positions.py	生成 HTML 仪表板（SQLite/机器人容器）
export_lp_executor.py	按 --id 将单个 LP 执行器导出为 CSV（REST API）
visualize_lp_executor.py	按 --id 为单个 LP 执行器生成 HTML 仪表板（REST API）

错误排查

错误	原因	解决方案
"InvalidRealloc"	仓位范围过宽	减小 --width（检查 bin_step 限制）
状态卡在 "OPENING"	交易失败	停止执行器，缩小范围后重试
"Insufficient funds"（钱包有资金）	RPC 速率限制或金额单位错误	添加自定义 RPC 密钥；确认 --amount 使用报价资产单位
"Transaction simulation failed"	RPC 速率限制导致模拟失败	添加自定义 RPC 密钥（Helius/QuickNode）
'meteora/clmm' KeyError	Gateway 连接器尚未注册	使用 hummingbot-api PR #120+（feat/lp-executor 分支）
"No CLMM pool found for X-Y"	代币符号不匹配	使用池中的准确符号（例如 Percolator 而非 PRCLT）
"meteora/clmm is not ready"	机器人无法连接 Gateway	使用 --network host 将 Gateway 作为 Docker 容器运行；在 macOS 上，容器无法访问开发模式的 Gateway
"Failed to load strategy" / 密码错误	机器人配置中缺少 .password_verification	将 .password_verification 从 bots/credentials/master_account/.password_verification 复制到 bots/bots/instances/<bot>/conf/
candles_config / markets extra inputs	脚本配置格式过时	使用精简配置：仅包含 controllers_config 和 script_file_name
API 显示机器人已“停止”，但 Docker 中仍在运行	MQTT 未连接	机器人正在运行，但 API 无法通过 MQTT 看到它；直接检查机器人日志

---

重要注意事项

以下问题在生产环境中曾造成实际困惑——部署前请阅读。

1. total_amount_quote 始终使用报价资产单位

报价资产是交易对中的第 2 个代币：

交易对	报价资产	示例：部署价值约 $100 的 100k 个基础代币
Percolator-SOL	SOL	--amount 1.33（1.33 SOL ≈ $108）
SOL-USDC	USDC	--amount 108（108 USDC）
RAY-SOL	SOL	--amount 2.5（2.5 SOL）

即使使用 --side 2（仅 SELL/基础资产），也要用报价资产单位表示金额。换算公式：基础代币数量 × 以报价资产计价的价格 = total_amount_quote。

2. 所有 *_pct 参数的单位已经是百分比

参数	正确	错误
position_width_pct: 10	10% 范围	0.10
position_offset_pct: 1	1% 偏移	0.01
rebalance_threshold_pct: 1	1% 阈值	0.01

3. 代币符号必须与池中的符号完全一致

向 Gateway 添加代币和配置 --pair 时，请使用池中的准确符号（可通过 get_meteora_pool.py 或 Meteora UI 获取）：

# Check pool token symbols first
python scripts/get_meteora_pool.py <pool_address>
# Look at "Symbol" column — use that exact string in --pair and when adding token to Gateway

示例：Percolator 代币的符号是 Percolator（而非 PRCLT）。请使用 --pair Percolator-SOL。

4. 部署前必须使用自定义 RPC（非可选项）

公共 Solana RPC（api.mainnet-beta.solana.com）会对你的机器人进行速率限制，导致：

• 出现“资金不足”错误（即使钱包有余额）
• 出现“交易模拟失败”
• 重试 10 次后仍无法开仓

部署前务必配置自定义 RPC：

# Edit Gateway conf
GATEWAY_DIR=~/.openclaw/workspace/hummingbot-gateway  # or your gateway dir
nano "$GATEWAY_DIR/conf/chains/solana/mainnet-beta.yml"
# Set: nodeURL: https://mainnet.helius-rpc.com/?api-key=YOUR_KEY

在 https://helius.dev 获取免费密钥。之后重启 Gateway。

5. 在 macOS 上，Gateway 必须以 Docker 方式运行（而非开发模式）

在 macOS 上，Docker 容器无法访问运行在主机上的进程（即使使用 --network host 也不行）。机器人容器无法连接以开发模式运行的 Gateway（pnpm start）。

务必以 Docker 方式运行 Gateway：

docker run -d --name gateway \
  --network host \
  -e GATEWAY_PASSPHRASE=hummingbot \
  -v ~/.openclaw/workspace/hummingbot-gateway/conf:/home/gateway/conf \
  -v ~/.openclaw/workspace/hummingbot-gateway/certs:/home/gateway/certs \
  hummingbot/gateway:development

然后在机器人的 conf_client.yml 中设置：gateway_api_host: localhost（当 Gateway 也以 Docker 和 host network 运行时，主机网络可在 macOS 上的 Docker 内正确解析）。

6. 使用 hummingbot:development 镜像，而非 latest

latest 镜像可能不支持 LP executor。务必使用以下方式部署：

python scripts/manage_controller.py deploy my_bot --configs my_config
# manage_controller.py defaults to hummingbot/hummingbot:development

7. 计算 --amount 之前检查钱包余额

python scripts/add_wallet.py balances

检查哪个代币账户有资金——钱包可能有多个 SPL 代币账户，实际余额可能与预期不同。只有特定代币账户中的可用余额才能用于部署。

8. 平仓

要平掉某个池中的所有仓位：

# List open positions
curl -s "http://localhost:15888/connectors/meteora/clmm/positions-owned?network=mainnet-beta&walletAddress=<WALLET>" 

# Close each position
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>"}'

注意：Gateway 必须可访问。如果 Gateway 在 Docker 中使用 host networking，请在 macOS 上使用 docker run --rm --network host alpine/curl ...。 |“余额不足”|代币不足|检查钱包是否有代币，以及是否有 0.06 SOL 用于租金|