lp-agent

name	lp-agent
description	Run automated liquidity provision strategies on concentrated liquidity (CLMM) DEXs using Hummingbot API.
metadata	{"author":"hummingbot"}
commands	{"start":{"description":"Onboarding wizard — check setup status and get started"},"deploy-hummingbot-api":{"description":"Deploy Hummingbot API trading infrastructure"},"setup-gateway":{"description":"Start Gateway and configure network RPC endpoints"},"add-wallet":{"description":"Add or import a Solana wallet for trading"},"explore-pools":{"description":"Find and explore Meteora DLMM pools"},"select-strategy":{"description":"Choose between LP Executor or Rebalancer Controller strategy"},"run-strategy":{"description":"Run, monitor, and manage LP strategies"},"analyze-performance":{"description":"Export data and visualize LP position performance"}}

lp-agent

This skill helps you run automated liquidity provision strategies on concentrated liquidity (CLMM) DEXs using Hummingbot API.

Commands (run as /lp-agent <command>):

Command	Description
start	Onboarding wizard — check setup status and get started
deploy-hummingbot-api	Deploy Hummingbot API trading infrastructure
setup-gateway	Start Gateway, configure network RPC endpoints
add-wallet	Add or import a Solana wallet
explore-pools	Find and explore Meteora DLMM pools
select-strategy	Choose LP Executor or Rebalancer Controller
run-strategy	Run, monitor, and manage LP strategies
analyze-performance	Visualize LP position performance

New here? Run /lp-agent start to check your setup and get a guided walkthrough.

Typical workflow: start → deploy-hummingbot-api → setup-gateway → add-wallet → explore-pools → select-strategy → run-strategy → analyze-performance

---

Command: start

Welcome the user and guide them through setup. This is a conversational onboarding wizard — check infrastructure state, interpret results, and walk them through each step.

Step 1: Welcome & Explain

Introduce yourself and explain what lp-agent does:

I'm your LP agent — I help you run automated liquidity provision strategies on Meteora DLMM pools (Solana). I can:

• Deploy infrastructure — Hummingbot API + Gateway for DEX trading
• Manage wallets — Add Solana wallets, check balances
• Explore pools — Search Meteora DLMM pools, compare APR/volume/TVL
• Run strategies — Auto-rebalancing LP controller or single-position executor
• Analyze performance — Dashboards with PnL, fees, and position history

Step 2: Check Infrastructure Status

Run these scripts and interpret the JSON output:

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?

Interpreting Results:

Script	Success Output	Failure Output
check_api.sh --json	{"running": true, "url": "http://localhost:8000", ...}	{"running": false, ...} or connection error
check_gateway.sh --json	{"running": true, ...}	{"running": false, ...}
add_wallet.py list	Shows wallet addresses like [solana] ABC123...	No wallets found. or empty list []

Step 3: Show Progress

Present a checklist showing what's done and what's remaining based on the script outputs:

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.

Adapt the checklist to the actual state. If everything is unchecked, start from the top. If everything is checked, skip to the LP lifecycle overview.

Step 4: Guide Next Action

Based on the first unchecked item, offer to help:

Missing	What to say
Hummingbot API	"Let's deploy the API first — it's the trading backend. Need Docker installed. Want me to run the installer?" → /lp-agent deploy-hummingbot-api
Gateway	"API is running! Now we need Gateway for DEX connectivity. Want me to start it?" → /lp-agent setup-gateway
Wallet	See Adding a Wallet below
All ready	Move to Step 5

Adding a Wallet:

When wallet is the next step, tell the user:

Infrastructure is ready. You need a Solana wallet with SOL for transaction fees (~0.06 SOL per LP position).

To add a wallet, run:

python scripts/add_wallet.py add

You'll be prompted to paste your private key (secure, not saved in shell history).

Interpreting add_wallet.py output:

Output	Meaning
✓ Wallet added successfully + address	Success — wallet is connected
Enter private key (base58): then ✓ Wallet added	Success after prompt
Error: HTTP 400 or validation error	Invalid private key format
Error: Cannot connect to API	API not running — run check_api.sh first

After wallet is added, verify with python scripts/add_wallet.py list — should show the new address.

Step 5: LP Lifecycle Overview

Once infrastructure is ready (or if user wants to understand the flow first), explain the LP lifecycle:

How LP strategies work:

1. Explore pools (/lp-agent explore-pools) — Find a Meteora DLMM pool. Look at volume, APR, and fee/TVL ratio to pick a good one.

2. Select strategy (/lp-agent select-strategy) — Choose between:

   • Rebalancer Controller (recommended) — Automatically repositions when price moves out of range. Set-and-forget.
   • LP Executor — Single fixed position. You control when to close/reopen. Good for testing or limit-order-style LP.

3. Run strategy (/lp-agent run-strategy) — Configure parameters (amount, width, price limits) and deploy. Monitor status and stop when done.

4. Analyze (/lp-agent analyze-performance) — View PnL dashboard, fees earned, position history. Works for both running and stopped strategies.

Want to explore some pools to get started?

---

Command: deploy-hummingbot-api

Deploy the Hummingbot API trading infrastructure. This is the first step before using any LP features.

What Gets Installed

Hummingbot API — A personal trading server that exposes a REST API for trading, market data, and deploying bot strategies across CEXs and DEXs.

• Repository: hummingbot/hummingbot-api

Usage

# 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

Prerequisites

• Docker and Docker Compose
• Git

Interpreting Output

Output	Meaning	Next Step
✓ Hummingbot API deployed successfully	Success	Proceed to setup-gateway
✓ Already installed and running	Already set up	Proceed to setup-gateway
Error: Docker not found	Docker not installed	Install Docker first
Error: Port 8000 already in use	Another service on port	Stop conflicting service or use different port

After Installation

Once the API is running:

1. Swagger UI is at http://localhost:8000/docs
2. Default credentials: admin/admin
3. Proceed to setup-gateway to enable DEX trading

---

Command: setup-gateway

Start the Gateway service, check its status, and configure key network parameters like RPC node URLs. Gateway is required for all LP operations on DEXs.

Prerequisite: Hummingbot API must be running (deploy-hummingbot-api). The script checks this automatically.

⚠️ Custom RPC is required — not optional. The public Solana RPC is rate-limited and will cause transaction failures that look like "Insufficient funds" or "Transaction simulation failed". Always configure a custom RPC before deploying any bot. Get a free key at https://helius.dev.

Usage

# 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

Options

Option	Default	Description
--status		Check Gateway status only (don't start)
--image IMAGE	hummingbot/gateway:development	Docker image to use
--passphrase TEXT	hummingbot	Gateway passphrase
--rpc-url URL		Custom RPC endpoint for --network
--network ID	solana-mainnet-beta	Network to configure RPC for
--port PORT	15888	Gateway port

Advanced: manage_gateway.py

For finer control (stop, restart, logs, per-network config), use 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

Interpreting Output

Output	Meaning	Next Step
✓ Gateway is running or ✓ Gateway started	Success	Proceed to add-wallet
✓ Gateway is already running	Already set up	Proceed to add-wallet
✗ Cannot connect to Hummingbot API	API not running	Run /lp-agent deploy-hummingbot-api first
✗ Failed to start Gateway	Docker issue	Check Docker is running, check logs
✓ RPC configured + ✓ Gateway restarted	Custom RPC set	Ready to use

Custom RPC Nodes

Gateway uses public RPC nodes by default, which can hit rate limits. Set a custom nodeUrl per network to avoid this.

Popular Solana RPC providers:

• Helius — Free tier available
• QuickNode
• Alchemy
• Triton

---

Command: add-wallet

Add a Solana wallet for trading.

Requires: deploy-hummingbot-api and setup-gateway completed first.

Adding a Wallet

python scripts/add_wallet.py add

You'll be prompted to paste your private key (base58 format). The key is entered securely and won't appear in shell history.

Interpreting Output:

Output	Meaning	Next Step
✓ Wallet added successfully + Address: ABC...	Success	Verify with list command
Error: HTTP 400 - Bad Request	Invalid private key format	Check key is base58 encoded
Error: HTTP 503	Gateway not available	Run bash scripts/check_gateway.sh
Error: Cannot connect to API	API not running	Run /lp-agent deploy-hummingbot-api

Listing Wallets

python scripts/add_wallet.py list

Interpreting Output:

Output	Meaning
[solana] ABC123...XYZ	Wallet connected on Solana
No wallets found.	No wallets added yet
Empty list [] (with --json)	No wallets added yet

Checking Balances

# 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

Adding a Custom Token to Gateway

When using non-standard tokens (e.g. memecoins), add them to Gateway first:

# 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

⚠️ Symbol must match the pool exactly. Use get_meteora_pool.py to find the exact token symbol. If the pool shows Percolator, use Percolator — not PRCLT or any abbreviation. A mismatch causes "No CLMM pool found" errors when the bot tries to fetch price data.

Then restart Gateway for the token to be recognized.

Requirements

• SOL for fees: Wallet needs SOL for transaction fees (~0.06 SOL per LP position for rent)
• Check actual balance before deploying: Use balances command — the available amount in the SPL token account may differ from on-chain total (multiple accounts, staked, etc.)
• Default chain: Solana mainnet-beta

---

Command: explore-pools

Find and explore Meteora DLMM pools before creating LP positions.

Note: Pool listing (list_meteora_pools.py) works without any prerequisites — it queries the Meteora API directly. Pool details (get_meteora_pool.py) optionally uses Gateway for real-time price and liquidity charts.

List Pools

Search and list pools by name, token, or address:

# 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

Output columns:

• Pool: Trading pair name
• Pool Address: Pool contract address (shortened, use get_meteora_pool.py for full address)
• Base (mint): Base token symbol with shortened mint address
• Quote (mint): Quote token symbol with shortened mint address
• TVL: Total value locked
• Vol 24h: 24-hour trading volume
• Fees 24h: Fees earned in last 24 hours
• APR: Annual percentage rate
• Fee: Base fee percentage
• Bin: Bin step (affects max position width)

Note: Token mints help identify the correct token when multiple tokens share the same name (e.g., multiple "PERCOLATOR" tokens).

Get Pool Details

Get detailed information about a specific pool. Fetches from both Meteora API (historical data) and Gateway (real-time data):

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

Data sources:

• Meteora API: Historical volume, fees, APR, token info, market caps
• Gateway (requires running Gateway): Real-time price, liquidity distribution by bin

Details shown:

• Token info (symbols, mints, decimals, prices)
• Pool configuration (bin step, fees, max range width)
• Real-time price from Gateway (SOL/token ratio)
• Liquidity distribution chart showing bins around current price
• Liquidity and reserves
• Volume across time windows (30m, 1h, 4h, 12h, 24h)
• Fees earned across time windows
• Yield (APR, APY, farm rewards)
• Fee/TVL ratio (profitability indicator)

Choosing a Pool

When selecting a pool, consider:

1. TVL: Higher TVL = more stable, but also more competition
2. Volume: Higher volume = more fee opportunities
3. Fee/TVL Ratio: Higher = more profitable per $ of liquidity
4. Bin Step: Determines max position width
   • bin_step=1 → max ~0.69% width (tight ranges)
   • bin_step=10 → max ~6.9% width (medium ranges)
   • bin_step=100 → max ~69% width (wide ranges)

---

Command: select-strategy

Help the user choose the right LP strategy. See references/ for detailed guides.

LP Rebalancer Controller (Recommended)

Reference: references/lp_rebalancer_guide.md

A controller that automatically manages LP positions with rebalancing logic.

Feature	Description
Auto-rebalance	Closes and reopens positions when price exits range
Price limits	Configure BUY/SELL zones with anchor points
KEEP logic	Avoids unnecessary rebalancing when at optimal position
Hands-off	Set and forget - controller manages everything

Best for: Longer-term LP strategies, range-bound markets, automated fee collection.

LP Executor (Single Position)

Reference: references/lp_executor_guide.md

Creates ONE liquidity position with fixed price bounds. No auto-rebalancing.

Feature	Description
Fixed bounds	Position stays at configured price range
Manual control	User decides when to close/reopen
Limit orders	Can auto-close when price exits range (like limit orders)
Simple	Direct control over single position

Best for: Short-term positions, limit-order-style LP, manual management, testing.

Quick Comparison

Aspect	Rebalancer Controller	LP Executor
Rebalancing	Automatic	Manual
Position count	One at a time, auto-managed	One, fixed
Price limits	Yes (anchor points)	No (but has auto-close)
Complexity	Higher (more config)	Lower (simpler)
Use case	Set-and-forget	Precise control

---

Command: run-strategy

Run, monitor, and manage LP strategies.

Requires: deploy-hummingbot-api, setup-gateway, and add-wallet completed first.

LP Rebalancer Controller (Recommended)

Reference: See references/lp_rebalancer_guide.md for full configuration details, rebalancing logic, and KEEP vs REBALANCE scenarios.

Auto-rebalances positions when price moves out of range. Best for hands-off LP management.

Key concepts:

• --amount (total_amount_quote) = amount in quote asset (2nd token in pair). For Percolator-SOL → SOL. For SOL-USDC → USDC. Always quote, regardless of side.
• All *_pct params are already in percent. position_width_pct: 10 = 10% width. Do NOT pass decimals (not 0.10).
• Price limits (--buy-min/max, --sell-min/max) default to null = no limit. Only set if you want a stop zone.

# 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

Key Parameters:

Parameter	Field	Default	Description
--amount	total_amount_quote	required	Amount in quote asset (2nd token). SOL for X-SOL pairs, USDC for X-USDC pairs.
--side	side	0	0=BOTH, 1=BUY (quote only), 2=SELL (base only)
--width	position_width_pct	10	Range width in % (e.g. 10 = ±10% around price). Already in pct — do not use decimals.
--offset	position_offset_pct	0.1	Center offset from current price in %. Already in pct.
--rebalance-seconds	rebalance_seconds	300	Seconds out-of-range before closing and reopening
--rebalance-threshold	rebalance_threshold_pct	1	Min price move % to trigger rebalance. Already in pct.
--sell-max/--sell-min	sell_price_max/min	null	Price limits for SELL side (null = no limit)
--buy-max/--buy-min	buy_price_max/min	null	Price limits for BUY side (null = no limit)
--strategy-type	strategy_type	0	Meteora shape: 0=Spot (uniform), 1=Curve (center-heavy), 2=Bid-Ask (edge-heavy)

Single LP Executor (Alternative)

Reference: See references/lp_executor_guide.md for state machine, single/double-sided positions, and limit range orders.

Creates ONE position with fixed bounds. Does NOT auto-rebalance.

python scripts/manage_executor.py create \
    --pool <pool_address> \
    --pair SOL-USDC \
    --quote-amount 100 \
    --lower 180 \
    --upper 185 \
    --side 1

Key Parameters:

Parameter	Description
--connector	Must include /clmm suffix (default: meteora/clmm)
--lower/--upper	Position price bounds
--base-amount/--quote-amount	Token amounts (set one to 0 for single-sided)
--side	0=BOTH, 1=BUY, 2=SELL
--auto-close-above	Auto-close when price above range (for limit orders)
--auto-close-below	Auto-close when price below range (for limit orders)

Monitor & Manage

Check Status:

# 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

Executor States:

• OPENING - Creating position on-chain
• IN_RANGE - Position active, earning fees
• OUT_OF_RANGE - Price outside position bounds
• CLOSING - Removing position
• FAILED - Transaction failed

Stop:

# 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

After Stopping — Analyze Results

If the user ran an LP Executor (via manage_executor.py create or direct API), immediately offer to analyze it:

Your executor has been stopped. Want me to generate a performance dashboard?

Then run:

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

The executor ID is returned when the executor is created (printed as Executor ID: <id>). If the user doesn't have it handy, fetch it from the 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'))
"

To also export the raw data to CSV:

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

If the user ran a Rebalancer Controller bot, the data lives in a SQLite file — use analyze-performance with the SQLite-based scripts instead.

---

Command: analyze-performance

Export data and generate visual dashboards from LP position events. Scripts are in this skill's scripts/ directory.

Which Script to Use?

Always ask yourself: was this position deployed as an LP Executor (via manage_executor.py or direct API) or via a Rebalancer Controller bot?

How it was deployed	Script to use
LP Executor — manage_executor.py create or direct POST /executors/ API	visualize_lp_executor.py --id <executor_id> ✅
Rebalancer Controller — manage_controller.py deploy (bot container, SQLite)	visualize_lp_positions.py --pair <pair>
Not sure?	Run curl -s -u admin:admin -X POST http://localhost:8000/executors/search -H "Content-Type: application/json" -d '{"type":"lp_executor"}' — if the executor ID appears, use the executor scripts

If the user has been running an LP Executor in this session (executor ID is known from context), skip the question and go straight to:

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

Available Scripts

Script	Purpose
scripts/export_lp_positions.py	Export LP position events to CSV (SQLite/bot-container based)
scripts/visualize_lp_positions.py	Generate HTML dashboard from position events (SQLite/bot-container based)
scripts/export_lp_executor.py	Export a single LP executor to CSV by --id (REST API, no SQLite)
scripts/visualize_lp_executor.py	Generate HTML dashboard for a single LP executor by --id (REST API)

Visualize LP Positions

Shows position ADD/REMOVE events from the blockchain. Works for both running and stopped bots.

# 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

Dashboard Features:

• KPI cards (total PnL, fees, IL, win/loss counts)
• Cumulative PnL & fees chart
• Price at open/close with LP range bounds
• Per-position PnL bar chart
• Duration vs PnL scatter plot
• Sortable positions table with Solscan links

Export to 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

Executor Performance (API-based)

These scripts work directly from the Hummingbot REST API — no SQLite database needed. Use them when executors were deployed via the API directly (e.g., via manage_executor.py), because those do not always produce SQLite records the way bot containers do.

Export a single LP executor to 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 columns (LP executor schema):

• Identity: id, account_name, controller_id, connector_name, trading_pair
• State: status, close_type, is_active, is_trading, error_count
• Timing: created_at, closed_at, close_timestamp, duration_seconds
• PnL: net_pnl_quote, net_pnl_pct, cum_fees_quote, filled_amount_quote
• Config (deployment): 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 (live/final): 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

Visualize a single LP executor (HTML dashboard):

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

Dashboard panels:

• KPI cards: status, net PnL, fees earned, duration, LP range
• Price chart with LP lower/upper bounds + open/close markers (5m KuCoin candles; auto-skipped for exotic pairs)
• Token balance bar: initial vs final base + quote amounts
• PnL breakdown: fees earned vs IL/price impact vs net PnL
• Full position summary table with Solscan links for pool and position addresses
• Dark theme (#0d1117 / #161b27), responsive layout, Chart.js from CDN
• Auth auto-loaded from .env or ~/.hummingbot/.env or ~/.env (keys: HUMMINGBOT_API_URL, API_USER, API_PASS)

---

Quick Reference

Common Workflows

Full Setup (first time):

# 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

Analyze LP Positions:

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

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

Checking Prerequisites

Before running commands that need the API or Gateway, verify they're running:

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

Both support --json output. These scripts are also used internally by setup_gateway.sh and can be sourced by other shell scripts.

Scripts Reference

Script	Purpose
check_api.sh	Check if Hummingbot API is running (shared)
check_gateway.sh	Check if Gateway is running (shared)
deploy_hummingbot_api.sh	Install/upgrade/manage Hummingbot API
setup_gateway.sh	Start Gateway and configure RPC
add_wallet.py	Add wallets and check balances
manage_gateway.py	Advanced Gateway management
list_meteora_pools.py	Search and list pools
get_meteora_pool.py	Get pool details with liquidity chart
manage_executor.py	Create, list, stop LP executors
manage_controller.py	Create configs, deploy bots, get status
export_lp_positions.py	Export position events to CSV (SQLite/bot-container)
visualize_lp_positions.py	Generate HTML dashboard (SQLite/bot-container)
export_lp_executor.py	Export single LP executor to CSV by --id (REST API)
visualize_lp_executor.py	HTML dashboard for single LP executor by --id (REST API)

Error Troubleshooting

Error	Cause	Solution
"InvalidRealloc"	Position range too wide	Reduce --width (check bin_step limits)
State stuck "OPENING"	Transaction failed	Stop executor, reduce range, retry
"Insufficient funds" (wallet has funds)	RPC rate limit or wrong amount units	Add custom RPC key; verify --amount is in quote asset
"Transaction simulation failed"	RPC rate limit masking as sim failure	Add custom RPC key (Helius/QuickNode)
'meteora/clmm' KeyError	Gateway connector not registered yet	Use hummingbot-api PR #120+ (feat/lp-executor branch)
"No CLMM pool found for X-Y"	Token symbol mismatch	Use exact symbol from pool (e.g. Percolator not PRCLT)
"meteora/clmm is not ready"	Bot can't reach Gateway	Run Gateway as Docker container with --network host; dev-mode Gateway on macOS not reachable from containers
"Failed to load strategy" / password error	Missing .password_verification in bot conf	Copy from bots/credentials/master_account/.password_verification to bots/bots/instances/<bot>/conf/
candles_config / markets extra inputs	Stale script config format	Use minimal config: only controllers_config and script_file_name
Bot shows "stopped" in API but running in Docker	MQTT not connected	Bot is running but API can't see it via MQTT; check bot logs directly

---

Critical Gotchas

These caused real confusion in production — read before deploying.

1. total_amount_quote is ALWAYS in quote asset

The quote asset is the 2nd token in the trading pair:

Pair	Quote Asset	Example: deploy 100k base tokens worth ~$100
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)

Even for --side 2 (SELL/base-only), you express the value in quote units. Convert: base_tokens × price_in_quote = total_amount_quote.

2. All *_pct params are already in percent

Param	Correct	Wrong
position_width_pct: 10	10% range	0.10
position_offset_pct: 1	1% offset	0.01
rebalance_threshold_pct: 1	1% threshold	0.01

3. Token symbol must match pool exactly

When adding a token to Gateway and configuring --pair, use the exact symbol from the pool (from get_meteora_pool.py or 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

Example: Percolator token symbol is Percolator (not PRCLT). Use --pair Percolator-SOL.

4. Custom RPC is required before deploying (not optional)

The public Solana RPC (api.mainnet-beta.solana.com) will rate-limit your bot, causing:

• "Insufficient funds" errors (even when wallet has funds)
• "Transaction simulation failed"
• Failed position opens after 10 retries

Always configure a custom RPC before deploying:

# 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

Free key at https://helius.dev. Restart Gateway after.

5. Gateway must run as Docker (not dev mode) on macOS

On macOS, Docker containers cannot reach processes running on the host (even with --network host). The bot container cannot connect to a Gateway running in dev mode (pnpm start).

Always run Gateway as Docker:

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

Then in bot's conf_client.yml: gateway_api_host: localhost (host networking resolves correctly inside Docker on macOS when gateway is also Docker with host network).

6. Use hummingbot:development image, not latest

The latest image may not have LP executor support. Always deploy with:

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

7. Check wallet balance BEFORE calculating --amount

python scripts/add_wallet.py balances

Check which token account has funds — the wallet may have multiple SPL token accounts and balances can differ from expectations. Only the available balance in the specific token account can be deployed.

8. Closing positions

To close all positions on a pool:

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

Note: Gateway must be accessible. On macOS use docker run --rm --network host alpine/curl ... if Gateway is in Docker with host networking. | "Insufficient balance" | Not enough tokens | Check wallet has tokens + 0.06 SOL for rent |