lp-agent

What this skill does

# 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
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](https://github.com/hummingbot/hummingbot-api)

### Usage

```bash
# 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

```bash
# 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 s