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:

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

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.

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

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:

Swagger UI is at http://localhost:8000/docs
Default credentials: admin/admin
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:

TVL: Higher TVL = more stable, but also more competition
Volume: Higher volume = more fee opportunities
Fee/TVL Ratio: Higher = more profitable per $ of liquidity
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 |

lp-agent

lp-agent

Command: start

Step 1: Welcome & Explain

Step 2: Check Infrastructure Status

Step 3: Show Progress

Step 4: Guide Next Action

Step 5: LP Lifecycle Overview

Command: deploy-hummingbot-api

What Gets Installed

Usage

Prerequisites

Interpreting Output

After Installation

Command: setup-gateway

Usage

Options

Advanced: manage_gateway.py

Interpreting Output

Custom RPC Nodes

Command: add-wallet

Adding a Wallet

Listing Wallets

Checking Balances

Adding a Custom Token to Gateway

Requirements

Command: explore-pools

List Pools

Get Pool Details

Choosing a Pool

Command: select-strategy

LP Rebalancer Controller (Recommended)

LP Executor (Single Position)

Quick Comparison

Command: run-strategy

LP Rebalancer Controller (Recommended)

Single LP Executor (Alternative)

Monitor & Manage

After Stopping — Analyze Results

Command: analyze-performance

Which Script to Use?

Available Scripts

Visualize LP Positions

Export to CSV

Executor Performance (API-based)

Quick Reference

Common Workflows

Checking Prerequisites

Scripts Reference

Error Troubleshooting

Critical Gotchas

1. total_amount_quote is ALWAYS in quote asset

2. All *_pct params are already in percent

3. Token symbol must match pool exactly

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

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

6. Use hummingbot:development image, not latest

7. Check wallet balance BEFORE calculating --amount

8. Closing positions

1. `total_amount_quote` is ALWAYS in quote asset

2. All `*_pct` params are already in percent

6. Use `hummingbot:development` image, not `latest`

7. Check wallet balance BEFORE calculating `--amount`