LP Executor Guide

LP Executor Guide

Manages liquidity provider positions on CLMM DEXs (Meteora, Raydium). Opens positions within price bounds, monitors range status, tracks fees.

When to Use

Use when:

• Providing liquidity on Solana DEXs
• Want automated position monitoring and fee tracking
• Earning trading fees from LP positions

Avoid when:

• Trading on CEX (use other executors)
• Want directional exposure only
• Not familiar with impermanent loss risks

State Machine

NOT_ACTIVE -> OPENING -> IN_RANGE <-> OUT_OF_RANGE -> CLOSING -> COMPLETE

Key Parameters

Required

Liquidity

Auto-Close (Limit Range Orders)

Set to null (default) to disable auto-close.

Single-Sided vs Double-Sided Positions

Single-sided (one asset only)

Base token only (e.g., 0.2 SOL): Creates a SELL position (side=2) with range ABOVE current price

• Position starts out-of-range, enters range when price rises
• SOL converts to USDC as price moves up through the range

Quote token only (e.g., 50 USDC): Creates a BUY position (side=1) with range BELOW current price

• Position starts out-of-range, enters range when price falls
• USDC converts to SOL as price moves down through the range

Double-sided (both assets)

When user specifies both base_amount and quote_amount, options:

1. Centered range around current price (±50% of position width above/below current price)
2. Custom range (user specifies exact lower/upper bounds)

Set side=0 (BOTH) for double-sided positions.

Position Management

Limit Range Orders (Auto-Close Feature)

Use auto_close_above_range_seconds and auto_close_below_range_seconds to create limit-order-style LP positions that automatically close when price moves through the range.

SELL Limit (Take Profit on Long)

side=2, base_amount=X, quote_amount=0
lower_price > current_price (range above current price)
auto_close_above_range_seconds=60

• Position starts OUT_OF_RANGE (price below range)
• When price rises into range: base -> quote conversion, fees earned
• When price rises above range for 60s: position auto-closes with quote tokens

BUY Limit (Accumulate on Dip)

side=1, base_amount=0, quote_amount=X
upper_price < current_price (range below current price)
auto_close_below_range_seconds=60

• Position starts OUT_OF_RANGE (price above range)
• When price falls into range: quote -> base conversion, fees earned
• When price falls below range for 60s: position auto-closes with base tokens

Key Benefits

• Earn LP fees while price moves through your target range
• Automatic execution without monitoring
• Better fills than traditional limit orders (continuous conversion vs single fill)

Meteora Strategy Types

Set via extra_params.strategyType:

Managing Positions

Always use the executor tool (manage_executors) to open and close LP positions - NOT the gateway CLMM tool directly.

• Opening/closing via manage_gateway_clmm bypasses the executor state machine and leaves the database out of sync
• Use manage_executors with action="stop" to properly close positions and update executor status
• If a position is closed externally (via gateway or UI), manually mark the executor as TERMINATED in the database

Verifying Position Status

• If uncertain about position status, use manage_gateway_clmm with action="get_positions" to check on-chain state
• Compare on-chain positions with executor custom_info.position_address
• If position is closed on-chain but executor still shows RUNNING, manually update executor status in database to TERMINATED
• If position is open on-chain but executor still shows OPENING, the executor should eventually sync - if stuck, check API logs for errors

Exception: Executor not found in API (404 error)

• If API was restarted, executors may no longer exist in memory but positions remain on-chain
• In this case, use manage_gateway_clmm with action="close_position" to close the on-chain position directly
• Then manually update the executor status in the database to TERMINATED