Testing Guide: LP Executor Support

[fengtality]

Testing Guide: LP Executor Support

This guide covers testing the new LP Executor functionality that enables creating and managing LP positions via the Hummingbot API.

Related PRs

• hummingbot: feat: LP Executor and Controller for StrategyV2 hummingbot#7948 - LP Executor and Controller
• hummingbot-api: feat: add LP executor support #120 - API support for LP Executor
• gateway: feat: CLMM improvements for LP Position Executor gateway#591 - Meteora CLMM support

Prerequisites

• Solana wallet configured in Gateway
• SOL for gas fees
• Tokens for LP position (e.g., SOL, USDC)

---

Setup Instructions

1. Run Gateway from Source

cd ~/gateway
git fetch origin
git checkout feat/meteora-clmm
pnpm install
pnpm build
pnpm start --passphrase=<your-passphrase> --dev

Ensure your Solana wallet is configured in Gateway.

2. Build and Install Hummingbot Library

cd ~/hummingbot
git fetch origin
git checkout feat/lp-strategy-v2-base

# Activate your hummingbot environment
conda activate hummingbot

# Build wheel
pip wheel . --no-deps -w dist/

# Install wheel (force reinstall to pick up changes)
pip install dist/hummingbot-*.whl --force-reinstall --no-deps

3. Run Hummingbot API

cd ~/hummingbot-api
git fetch origin
git checkout feat/lp-executor

# Copy LP Rebalancer controller to API
cp ~/hummingbot/controllers/generic/lp_rebalancer/lp_rebalancer.py bots/controllers/generic/

# Start the API (uses the same conda env)
make run

---

Testing the LP Executor via API

Use the executor directly via the /executors/ endpoint for fine-grained control over individual positions.

Check Available Executor Types

curl -X 'GET' 'http://localhost:8000/executors/types/available' -H 'accept: application/json'

Should include lp_executor in the response.

Get LP Executor Config Schema

curl -X 'GET' 'http://localhost:8000/executors/types/lp_executor/config' -H 'accept: application/json'

Create an LP Position

Example: Create a SELL position (base-only) on Meteora SOL-USDC pool:

curl -X 'POST' \
  'http://localhost:8000/executors/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_name": "master_account",
    "executor_config": {
      "type": "lp_executor",
      "connector_name": "meteora/clmm",
      "pool_address": "YOUR_POOL_ADDRESS",
      "trading_pair": "SOL-USDC",
      "base_token": "SOL",
      "quote_token": "USDC",
      "lower_price": "230",
      "upper_price": "240",
      "base_amount": "0.1",
      "quote_amount": "0",
      "side": 2,
      "extra_params": {"strategyType": 0}
    }
  }'

Config Parameters:

Parameter	Values	Description
side	0 = both-sided, 1 = BUY (quote only), 2 = SELL (base only)	Position type
strategyType	0 = Spot, 1 = Curve, 2 = Bid-Ask	Meteora-specific strategy
lower_price/upper_price	Decimal strings	Define the price range

List Active Executors

curl -X 'GET' 'http://localhost:8000/executors/' -H 'accept: application/json'

Get Executor Details

curl -X 'GET' 'http://localhost:8000/executors/{executor_id}' -H 'accept: application/json'

Stop an Executor

curl -X 'POST' \
  'http://localhost:8000/executors/{executor_id}/stop' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"keep_position": false}'

Set keep_position: true to keep the on-chain position open after stopping the executor.

---

Testing the LP Rebalancer Controller via API

Use the controller for automated position management with rebalancing logic.

1. Create Controller Configuration

curl -X 'POST' \
  'http://localhost:8000/controllers/configs/lp_rebalancer_sol_usdc' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "lp_rebalancer_sol_usdc",
    "controller_name": "lp_rebalancer",
    "controller_type": "generic",
    "connector_name": "meteora/clmm",
    "network": "solana-mainnet-beta",
    "trading_pair": "SOL-USDC",
    "pool_address": "YOUR_POOL_ADDRESS",
    "total_amount_quote": "10",
    "side": 1,
    "position_width_pct": "0.5",
    "position_offset_pct": "0.1",
    "buy_price_max": "250",
    "buy_price_min": "200",
    "sell_price_max": "280",
    "sell_price_min": "230",
    "rebalance_seconds": 60,
    "rebalance_threshold_pct": "0.1",
    "strategy_type": 0
  }'

2. Deploy Controller as Bot

curl -X 'POST' \
  'http://localhost:8000/bot-orchestration/deploy-v2-controllers' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "instance_name": "lp_bot",
    "controllers_config": ["lp_rebalancer_sol_usdc"],
    "credentials_profile": "master_account",
    "image": "hummingbot/hummingbot:latest"
  }'

3. Check Bot Status

# List running bots
curl -X 'GET' 'http://localhost:8000/bot-orchestration/bots/' -H 'accept: application/json'

# Get specific bot status
curl -X 'GET' 'http://localhost:8000/bot-orchestration/bots/{bot_name}' -H 'accept: application/json'

4. Stop Bot

curl -X 'POST' \
  'http://localhost:8000/bot-orchestration/bots/{bot_name}/stop' \
  -H 'accept: application/json'

Controller Configuration Reference

Parameter	Type	Description
total_amount_quote	string	Total position value in quote currency
side	int	Initial side: 0=BOTH, 1=BUY, 2=SELL
position_width_pct	string	Position width as percentage (e.g., "0.5" = 0.5%)
position_offset_pct	string	Offset to ensure single-sided positions start out-of-range
buy_price_max/min	decimal	BUY zone bounds
sell_price_max/min	decimal	SELL zone bounds
rebalance_seconds	int	Seconds out-of-range before rebalancing
rebalance_threshold_pct	string	Price must be this % beyond bounds before timer starts

See the LP Rebalancer README for full documentation.

---

Troubleshooting

Issue	Solution
"Gateway error: Route not found"	Ensure Gateway is running with Meteora CLMM support
"Connector not found"	Check that meteora/clmm connector is configured
"Insufficient funds"	Verify wallet has enough tokens for the position
"chains/None/balances"	Rebuild hummingbot wheel (includes GatewayBase fixes)
"order_book_tracker" errors	Update hummingbot-api to latest feat/lp-executor branch
Gateway connection refused	Ensure Gateway is running on port 15888

Expected Behavior

LP Executor (Direct)

1. Executor creates position on-chain via Gateway
2. State transitions: NOT_ACTIVE → OPENING → IN_RANGE or OUT_OF_RANGE
3. Position amounts and fees are tracked in real-time
4. On stop (with keep_position: false), position is closed and tokens returned

LP Rebalancer Controller (via Bot)

1. Controller creates LP Executor automatically based on config
2. Monitors position state and tracks out-of-range timer
3. When rebalance triggers:
   • Closes current position
   • Waits for completion
   • Creates new single-sided position anchored at price limit
4. KEEP logic: Avoids unnecessary rebalancing when already at optimal anchor
5. Continues until bot is stopped