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
INLINECODE1	Onboarding wizard — check setup status and get started
INLINECODE2

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:

CODEBLOCK0

Interpreting Results:

Script	Success Output	Failure Output
INLINECODE18	INLINECODE19	INLINECODE20 or connection error
INLINECODE21

{"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:

CODEBLOCK1

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?" → INLINECODE28
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
INLINECODE30 + address	Success — wallet is connected
INLINECODE31 then INLINECODE32

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. 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.

1. 3. Run strategy (/lp-agent run-strategy) — Configure parameters (amount, width, price limits) and deploy. Monitor status and stop when done.
2. 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

CODEBLOCK3

Prerequisites

• - Docker and Docker Compose
• Git

Interpreting Output

Output	Meaning	Next Step
INLINECODE41	Success	Proceed to INLINECODE42
INLINECODE43

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. 1. Swagger UI is at INLINECODE47
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.

Usage

CODEBLOCK4

Options

Option	Default	Description
INLINECODE50		Check Gateway status only (don't start)
INLINECODE51

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:

CODEBLOCK5

Interpreting Output

Output	Meaning	Next Step
INLINECODE62 or INLINECODE63	Success	Proceed to INLINECODE64
INLINECODE65

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

CODEBLOCK6

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
INLINECODE74 + INLINECODE75	Success	Verify with list command
INLINECODE77

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

CODEBLOCK7

Interpreting Output:

Output	Meaning
INLINECODE82	Wallet connected on Solana
INLINECODE83

No wallets added yet |
| Empty list [] (with --json) | No wallets added yet |

Checking Balances

CODEBLOCK8

Requirements

• - SOL for fees: Wallet needs SOL for transaction fees (~0.06 SOL per LP position for rent)
• 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:

CODEBLOCK9

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

CODEBLOCK10

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. 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: INLINECODE92

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

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 0 = no limit. Only set if you want a stop zone.

CODEBLOCK11

Key Parameters:

Parameter	Field	Default	Description
INLINECODE107	INLINECODE108	required	Amount in quote asset (2nd token). SOL for X-SOL pairs, USDC for X-USDC pairs.
INLINECODE109

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 | 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 | 0 | Price limits for SELL side (0 = no limit) |
| --buy-max/--buy-min | buy_price_max/min | 0 | Price limits for BUY side (0 = 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.

CODEBLOCK12

Key Parameters:

Parameter	Description
INLINECODE143	Must include /clmm suffix (default: meteora/clmm)
INLINECODE146

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

Executor States:

• - OPENING - Creating position on-chain
• INLINECODE152 - Position active, earning fees
• INLINECODE153 - Price outside position bounds
• INLINECODE154 - Removing position
• INLINECODE155 - Transaction failed

Stop:
CODEBLOCK14

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

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:

CODEBLOCK16

To also export the raw data to CSV:
CODEBLOCK17

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	INLINECODE163 ✅
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:
CODEBLOCK18

Available Scripts

Script	Purpose
INLINECODE167	Export LP position events to CSV (SQLite/bot-container based)
INLINECODE168

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.

CODEBLOCK19

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

CODEBLOCK20

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:

CODEBLOCK21

CSV columns (LP executor schema):

• - Identity: INLINECODE174
• State: INLINECODE175
• Timing: INLINECODE176
• PnL: INLINECODE177
• Config (deployment): INLINECODE178
• custom_info (live/final): INLINECODE179

Visualize a single LP executor (HTML dashboard):

CODEBLOCK22

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

Analyze LP Positions:
CODEBLOCK24

Checking Prerequisites

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

CODEBLOCK25

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
INLINECODE190	Check if Hummingbot API is running (shared)
INLINECODE191

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 balance" | Not enough tokens | Check wallet has tokens + 0.06 SOL for rent |