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>):

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:

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:

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:

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

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

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

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:

Listing Wallets

python scripts/add_wallet.py list

Interpreting Output:

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.

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.

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

Quick Comparison

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:

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:

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?

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

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

Error Troubleshooting

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:

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

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 |