{
  "schemaVersion": "1.0",
  "item": {
    "slug": "lp-agent",
    "name": "LP Agent",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/fengtality/lp-agent",
    "canonicalUrl": "https://clawhub.ai/fengtality/lp-agent",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/lp-agent",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=lp-agent",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "references/lp_executor_guide.md",
      "references/lp_rebalancer_guide.md",
      "scripts/README.md",
      "scripts/add_wallet.py",
      "scripts/check_api.sh"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/lp-agent"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/lp-agent",
    "agentPageUrl": "https://openagent3.xyz/skills/lp-agent/agent",
    "manifestUrl": "https://openagent3.xyz/skills/lp-agent/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/lp-agent/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "lp-agent",
        "body": "This skill helps you run automated liquidity provision strategies on concentrated liquidity (CLMM) DEXs using Hummingbot API.\n\nCommands (run as /lp-agent <command>):\n\nCommandDescriptionstartOnboarding wizard — check setup status and get starteddeploy-hummingbot-apiDeploy Hummingbot API trading infrastructuresetup-gatewayStart Gateway, configure network RPC endpointsadd-walletAdd or import a Solana walletexplore-poolsFind and explore Meteora DLMM poolsselect-strategyChoose LP Executor or Rebalancer Controllerrun-strategyRun, monitor, and manage LP strategiesanalyze-performanceVisualize LP position performance\n\nNew here? Run /lp-agent start to check your setup and get a guided walkthrough.\n\nTypical workflow: start → deploy-hummingbot-api → setup-gateway → add-wallet → explore-pools → select-strategy → run-strategy → analyze-performance"
      },
      {
        "title": "Command: start",
        "body": "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."
      },
      {
        "title": "Step 1: Welcome & Explain",
        "body": "Introduce yourself and explain what lp-agent does:\n\nI'm your LP agent — I help you run automated liquidity provision strategies on Meteora DLMM pools (Solana). I can:\n\nDeploy infrastructure — Hummingbot API + Gateway for DEX trading\nManage wallets — Add Solana wallets, check balances\nExplore pools — Search Meteora DLMM pools, compare APR/volume/TVL\nRun strategies — Auto-rebalancing LP controller or single-position executor\nAnalyze performance — Dashboards with PnL, fees, and position history"
      },
      {
        "title": "Step 2: Check Infrastructure Status",
        "body": "Run these scripts and interpret the JSON output:\n\nbash scripts/check_api.sh --json      # Is Hummingbot API running?\nbash scripts/check_gateway.sh --json  # Is Gateway running?\npython scripts/add_wallet.py list     # Any wallets connected?\n\nInterpreting Results:\n\nScriptSuccess OutputFailure Outputcheck_api.sh --json{\"running\": true, \"url\": \"http://localhost:8000\", ...}{\"running\": false, ...} or connection errorcheck_gateway.sh --json{\"running\": true, ...}{\"running\": false, ...}add_wallet.py listShows wallet addresses like [solana] ABC123...No wallets found. or empty list []"
      },
      {
        "title": "Step 3: Show Progress",
        "body": "Present a checklist showing what's done and what's remaining based on the script outputs:\n\nSetup Progress:\n  [x] Hummingbot API    — Running at http://localhost:8000\n  [x] Gateway           — Running\n  [ ] Wallet            — No wallet connected\n\nNext step: Add a Solana wallet so you can start trading.\n\nAdapt the checklist to the actual state. If everything is unchecked, start from the top. If everything is checked, skip to the LP lifecycle overview."
      },
      {
        "title": "Step 4: Guide Next Action",
        "body": "Based on the first unchecked item, offer to help:\n\nMissingWhat to sayHummingbot 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-apiGateway\"API is running! Now we need Gateway for DEX connectivity. Want me to start it?\" → /lp-agent setup-gatewayWalletSee Adding a Wallet belowAll readyMove to Step 5\n\nAdding a Wallet:\n\nWhen wallet is the next step, tell the user:\n\nInfrastructure is ready. You need a Solana wallet with SOL for transaction fees (~0.06 SOL per LP position).\nTo add a wallet, run:\npython scripts/add_wallet.py add\n\nYou'll be prompted to paste your private key (secure, not saved in shell history).\n\nInterpreting add_wallet.py output:\n\nOutputMeaning✓ Wallet added successfully + addressSuccess — wallet is connectedEnter private key (base58): then ✓ Wallet addedSuccess after promptError: HTTP 400 or validation errorInvalid private key formatError: Cannot connect to APIAPI not running — run check_api.sh first\n\nAfter wallet is added, verify with python scripts/add_wallet.py list — should show the new address."
      },
      {
        "title": "Step 5: LP Lifecycle Overview",
        "body": "Once infrastructure is ready (or if user wants to understand the flow first), explain the LP lifecycle:\n\nHow LP strategies work:\n\n\nExplore pools (/lp-agent explore-pools) — Find a Meteora DLMM pool. Look at volume, APR, and fee/TVL ratio to pick a good one.\n\n\nSelect strategy (/lp-agent select-strategy) — Choose between:\n\nRebalancer Controller (recommended) — Automatically repositions when price moves out of range. Set-and-forget.\nLP Executor — Single fixed position. You control when to close/reopen. Good for testing or limit-order-style LP.\n\n\n\nRun strategy (/lp-agent run-strategy) — Configure parameters (amount, width, price limits) and deploy. Monitor status and stop when done.\n\n\nAnalyze (/lp-agent analyze-performance) — View PnL dashboard, fees earned, position history. Works for both running and stopped strategies.\n\n\nWant to explore some pools to get started?"
      },
      {
        "title": "Command: deploy-hummingbot-api",
        "body": "Deploy the Hummingbot API trading infrastructure. This is the first step before using any LP features."
      },
      {
        "title": "What Gets Installed",
        "body": "Hummingbot API — A personal trading server that exposes a REST API for trading, market data, and deploying bot strategies across CEXs and DEXs.\n\nRepository: hummingbot/hummingbot-api"
      },
      {
        "title": "Usage",
        "body": "# Check if already installed\nbash scripts/deploy_hummingbot_api.sh status\n\n# Install (interactive, prompts for credentials)\nbash scripts/deploy_hummingbot_api.sh install\n\n# Install with defaults (non-interactive: admin/admin)\nbash scripts/deploy_hummingbot_api.sh install --defaults\n\n# Upgrade existing installation\nbash scripts/deploy_hummingbot_api.sh upgrade\n\n# View container logs\nbash scripts/deploy_hummingbot_api.sh logs\n\n# Reset (stop and remove everything)\nbash scripts/deploy_hummingbot_api.sh reset"
      },
      {
        "title": "Prerequisites",
        "body": "Docker and Docker Compose\nGit"
      },
      {
        "title": "Interpreting Output",
        "body": "OutputMeaningNext Step✓ Hummingbot API deployed successfullySuccessProceed to setup-gateway✓ Already installed and runningAlready set upProceed to setup-gatewayError: Docker not foundDocker not installedInstall Docker firstError: Port 8000 already in useAnother service on portStop conflicting service or use different port"
      },
      {
        "title": "After Installation",
        "body": "Once the API is running:\n\nSwagger UI is at http://localhost:8000/docs\nDefault credentials: admin/admin\nProceed to setup-gateway to enable DEX trading"
      },
      {
        "title": "Command: setup-gateway",
        "body": "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.\n\nPrerequisite: Hummingbot API must be running (deploy-hummingbot-api). The script checks this automatically."
      },
      {
        "title": "Usage",
        "body": "# Check Gateway status\nbash scripts/setup_gateway.sh --status\n\n# Start Gateway with defaults\nbash scripts/setup_gateway.sh\n\n# Start Gateway with custom image (e.g., development build)\nbash scripts/setup_gateway.sh --image hummingbot/gateway:development\n\n# Start with custom Solana RPC (recommended to avoid rate limits)\nbash scripts/setup_gateway.sh --rpc-url https://your-rpc-endpoint.com\n\n# Configure RPC for a different network\nbash scripts/setup_gateway.sh --network ethereum-mainnet --rpc-url https://your-eth-rpc.com\n\n# Start with custom passphrase and port\nbash scripts/setup_gateway.sh --passphrase mypassword --port 15888"
      },
      {
        "title": "Options",
        "body": "OptionDefaultDescription--statusCheck Gateway status only (don't start)--image IMAGEhummingbot/gateway:developmentDocker image to use--passphrase TEXThummingbotGateway passphrase--rpc-url URLCustom RPC endpoint for --network--network IDsolana-mainnet-betaNetwork to configure RPC for--port PORT15888Gateway port"
      },
      {
        "title": "Advanced: manage_gateway.py",
        "body": "For finer control (stop, restart, logs, per-network config), use manage_gateway.py:\n\npython scripts/manage_gateway.py status                    # Check status\npython scripts/manage_gateway.py start                     # Start Gateway\npython scripts/manage_gateway.py stop                      # Stop Gateway\npython scripts/manage_gateway.py restart                   # Restart Gateway\npython scripts/manage_gateway.py logs                      # View logs\npython scripts/manage_gateway.py networks                  # List all networks\npython scripts/manage_gateway.py network solana-mainnet-beta                          # Get network config\npython scripts/manage_gateway.py network solana-mainnet-beta --node-url https://...   # Set RPC node"
      },
      {
        "title": "Interpreting Output",
        "body": "OutputMeaningNext Step✓ Gateway is running or ✓ Gateway startedSuccessProceed to add-wallet✓ Gateway is already runningAlready set upProceed to add-wallet✗ Cannot connect to Hummingbot APIAPI not runningRun /lp-agent deploy-hummingbot-api first✗ Failed to start GatewayDocker issueCheck Docker is running, check logs✓ RPC configured + ✓ Gateway restartedCustom RPC setReady to use"
      },
      {
        "title": "Custom RPC Nodes",
        "body": "Gateway uses public RPC nodes by default, which can hit rate limits. Set a custom nodeUrl per network to avoid this.\n\nPopular Solana RPC providers:\n\nHelius — Free tier available\nQuickNode\nAlchemy\nTriton"
      },
      {
        "title": "Command: add-wallet",
        "body": "Add a Solana wallet for trading.\n\nRequires: deploy-hummingbot-api and setup-gateway completed first."
      },
      {
        "title": "Adding a Wallet",
        "body": "python scripts/add_wallet.py add\n\nYou'll be prompted to paste your private key (base58 format). The key is entered securely and won't appear in shell history.\n\nInterpreting Output:\n\nOutputMeaningNext Step✓ Wallet added successfully + Address: ABC...SuccessVerify with list commandError: HTTP 400 - Bad RequestInvalid private key formatCheck key is base58 encodedError: HTTP 503Gateway not availableRun bash scripts/check_gateway.shError: Cannot connect to APIAPI not runningRun /lp-agent deploy-hummingbot-api"
      },
      {
        "title": "Listing Wallets",
        "body": "python scripts/add_wallet.py list\n\nInterpreting Output:\n\nOutputMeaning[solana] ABC123...XYZWallet connected on SolanaNo wallets found.No wallets added yetEmpty list [] (with --json)No wallets added yet"
      },
      {
        "title": "Checking Balances",
        "body": "# Check all balances\npython scripts/add_wallet.py balances\n\n# Filter by account\npython scripts/add_wallet.py balances --account master_account\n\n# Show zero balances too\npython scripts/add_wallet.py balances --all"
      },
      {
        "title": "Requirements",
        "body": "SOL for fees: Wallet needs SOL for transaction fees (~0.06 SOL per LP position for rent)\nDefault chain: Solana mainnet-beta"
      },
      {
        "title": "Command: explore-pools",
        "body": "Find and explore Meteora DLMM pools before creating LP positions.\n\nNote: 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."
      },
      {
        "title": "List Pools",
        "body": "Search and list pools by name, token, or address:\n\n# Top pools by 24h volume\npython scripts/list_meteora_pools.py\n\n# Search by token symbol\npython scripts/list_meteora_pools.py --query SOL\npython scripts/list_meteora_pools.py --query USDC\n\n# Search by pool name\npython scripts/list_meteora_pools.py --query SOL-USDC\n\n# Sort by different metrics\npython scripts/list_meteora_pools.py --query SOL --sort tvl\npython scripts/list_meteora_pools.py --query SOL --sort apr\npython scripts/list_meteora_pools.py --query SOL --sort fees\n\n# Pagination\npython scripts/list_meteora_pools.py --query SOL --limit 50 --page 2\n\nOutput columns:\n\nPool: Trading pair name\nPool Address: Pool contract address (shortened, use get_meteora_pool.py for full address)\nBase (mint): Base token symbol with shortened mint address\nQuote (mint): Quote token symbol with shortened mint address\nTVL: Total value locked\nVol 24h: 24-hour trading volume\nFees 24h: Fees earned in last 24 hours\nAPR: Annual percentage rate\nFee: Base fee percentage\nBin: Bin step (affects max position width)\n\nNote: Token mints help identify the correct token when multiple tokens share the same name (e.g., multiple \"PERCOLATOR\" tokens)."
      },
      {
        "title": "Get Pool Details",
        "body": "Get detailed information about a specific pool. Fetches from both Meteora API (historical data) and Gateway (real-time data):\n\npython scripts/get_meteora_pool.py <pool_address>\n\n# Example\npython scripts/get_meteora_pool.py ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms\n\n# Output as JSON for programmatic use\npython scripts/get_meteora_pool.py ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms --json\n\n# Skip Gateway (faster, no bin distribution)\npython scripts/get_meteora_pool.py ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms --no-gateway\n\nData sources:\n\nMeteora API: Historical volume, fees, APR, token info, market caps\nGateway (requires running Gateway): Real-time price, liquidity distribution by bin\n\nDetails shown:\n\nToken info (symbols, mints, decimals, prices)\nPool configuration (bin step, fees, max range width)\nReal-time price from Gateway (SOL/token ratio)\nLiquidity distribution chart showing bins around current price\nLiquidity and reserves\nVolume across time windows (30m, 1h, 4h, 12h, 24h)\nFees earned across time windows\nYield (APR, APY, farm rewards)\nFee/TVL ratio (profitability indicator)"
      },
      {
        "title": "Choosing a Pool",
        "body": "When selecting a pool, consider:\n\nTVL: Higher TVL = more stable, but also more competition\nVolume: Higher volume = more fee opportunities\nFee/TVL Ratio: Higher = more profitable per $ of liquidity\nBin Step: Determines max position width\n\nbin_step=1 → max ~0.69% width (tight ranges)\nbin_step=10 → max ~6.9% width (medium ranges)\nbin_step=100 → max ~69% width (wide ranges)"
      },
      {
        "title": "Command: select-strategy",
        "body": "Help the user choose the right LP strategy. See references/ for detailed guides."
      },
      {
        "title": "LP Rebalancer Controller (Recommended)",
        "body": "Reference: references/lp_rebalancer_guide.md\n\nA controller that automatically manages LP positions with rebalancing logic.\n\nFeatureDescriptionAuto-rebalanceCloses and reopens positions when price exits rangePrice limitsConfigure BUY/SELL zones with anchor pointsKEEP logicAvoids unnecessary rebalancing when at optimal positionHands-offSet and forget - controller manages everything\n\nBest for: Longer-term LP strategies, range-bound markets, automated fee collection."
      },
      {
        "title": "LP Executor (Single Position)",
        "body": "Reference: references/lp_executor_guide.md\n\nCreates ONE liquidity position with fixed price bounds. No auto-rebalancing.\n\nFeatureDescriptionFixed boundsPosition stays at configured price rangeManual controlUser decides when to close/reopenLimit ordersCan auto-close when price exits range (like limit orders)SimpleDirect control over single position\n\nBest for: Short-term positions, limit-order-style LP, manual management, testing."
      },
      {
        "title": "Quick Comparison",
        "body": "AspectRebalancer ControllerLP ExecutorRebalancingAutomaticManualPosition countOne at a time, auto-managedOne, fixedPrice limitsYes (anchor points)No (but has auto-close)ComplexityHigher (more config)Lower (simpler)Use caseSet-and-forgetPrecise control"
      },
      {
        "title": "Command: run-strategy",
        "body": "Run, monitor, and manage LP strategies.\n\nRequires: deploy-hummingbot-api, setup-gateway, and add-wallet completed first."
      },
      {
        "title": "LP Rebalancer Controller (Recommended)",
        "body": "Reference: See references/lp_rebalancer_guide.md for full configuration details, rebalancing logic, and KEEP vs REBALANCE scenarios.\n\nAuto-rebalances positions when price moves out of range. Best for hands-off LP management.\n\nKey concepts:\n\n--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.\nAll *_pct params are already in percent. position_width_pct: 10 = 10% width. Do NOT pass decimals (not 0.10).\nPrice limits (--buy-min/max, --sell-min/max) default to 0 = no limit. Only set if you want a stop zone.\n\n# 1. Create LP Rebalancer config (pool and pair are required)\npython scripts/manage_controller.py create-config my_lp_config \\\n    --pool <pool_address> \\\n    --pair SOL-USDC \\\n    --amount 10 \\       # 10 USDC (quote asset for SOL-USDC)\n    --side 0 \\          # 0=BOTH, 1=BUY (quote only), 2=SELL (base only)\n    --width 10 \\        # 10% range around current price\n    --offset 1 \\        # center range 1% from current price\n    --rebalance-seconds 300 \\\n    --rebalance-threshold 1\n\n# Side=2 example: deploy base token only (e.g. 110k PRCLT ≈ 1.33 SOL)\npython scripts/manage_controller.py create-config percolator_sell \\\n    --pool ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms \\\n    --pair Percolator-SOL \\\n    --amount 1.33 \\     # 1.33 SOL worth (quote for Percolator-SOL pair)\n    --side 2\n\n# 2. Deploy bot with the config\npython scripts/manage_controller.py deploy my_lp_bot --configs my_lp_config\n\n# 3. Monitor status\npython scripts/manage_controller.py status\n\nKey Parameters:\n\nParameterFieldDefaultDescription--amounttotal_amount_quoterequiredAmount in quote asset (2nd token). SOL for X-SOL pairs, USDC for X-USDC pairs.--sideside00=BOTH, 1=BUY (quote only), 2=SELL (base only)--widthposition_width_pct10Range width in % (e.g. 10 = ±10% around price). Already in pct — do not use decimals.--offsetposition_offset_pct1Center offset from current price in %. Already in pct.--rebalance-secondsrebalance_seconds300Seconds out-of-range before closing and reopening--rebalance-thresholdrebalance_threshold_pct1Min price move % to trigger rebalance. Already in pct.--sell-max/--sell-minsell_price_max/min0Price limits for SELL side (0 = no limit)--buy-max/--buy-minbuy_price_max/min0Price limits for BUY side (0 = no limit)--strategy-typestrategy_type0Meteora shape: 0=Spot (uniform), 1=Curve (center-heavy), 2=Bid-Ask (edge-heavy)"
      },
      {
        "title": "Single LP Executor (Alternative)",
        "body": "Reference: See references/lp_executor_guide.md for state machine, single/double-sided positions, and limit range orders.\n\nCreates ONE position with fixed bounds. Does NOT auto-rebalance.\n\npython scripts/manage_executor.py create \\\n    --pool <pool_address> \\\n    --pair SOL-USDC \\\n    --quote-amount 100 \\\n    --lower 180 \\\n    --upper 185 \\\n    --side 1\n\nKey Parameters:\n\nParameterDescription--connectorMust include /clmm suffix (default: meteora/clmm)--lower/--upperPosition price bounds--base-amount/--quote-amountToken amounts (set one to 0 for single-sided)--side0=BOTH, 1=BUY, 2=SELL--auto-close-aboveAuto-close when price above range (for limit orders)--auto-close-belowAuto-close when price below range (for limit orders)"
      },
      {
        "title": "Monitor & Manage",
        "body": "Check Status:\n\n# Bot status\npython scripts/manage_controller.py status\n\n# Executor list\npython scripts/manage_executor.py list --type lp_executor\n\n# Executor details\npython scripts/manage_executor.py get <executor_id>\n\n# Executor summary\npython scripts/manage_executor.py summary\n\nExecutor States:\n\nOPENING - Creating position on-chain\nIN_RANGE - Position active, earning fees\nOUT_OF_RANGE - Price outside position bounds\nCLOSING - Removing position\nFAILED - Transaction failed\n\nStop:\n\n# Stop bot (stops all its controllers)\npython scripts/manage_controller.py stop my_lp_bot\n\n# Stop individual executor (closes position)\npython scripts/manage_executor.py stop <executor_id>\n\n# Stop executor but keep position on-chain\npython scripts/manage_executor.py stop <executor_id> --keep-position"
      },
      {
        "title": "After Stopping — Analyze Results",
        "body": "If the user ran an LP Executor (via manage_executor.py create or direct API), immediately offer to analyze it:\n\nYour executor has been stopped. Want me to generate a performance dashboard?\n\nThen run:\n\npython scripts/visualize_lp_executor.py --id <executor_id>\n\nThe 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:\n\ncurl -s -u admin:admin -X POST http://localhost:8000/executors/search \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"type\":\"lp_executor\"}' | python3 -c \"\nimport json,sys\ndata=json.load(sys.stdin)\nitems=data.get('data',data) if isinstance(data,dict) else data\nfor ex in (items if isinstance(items,list) else [items]):\n    print(ex.get('executor_id') or ex.get('id'), ex.get('trading_pair'), ex.get('status'))\n\"\n\nTo also export the raw data to CSV:\n\npython scripts/export_lp_executor.py --id <executor_id>\n\nIf the user ran a Rebalancer Controller bot, the data lives in a SQLite file — use analyze-performance with the SQLite-based scripts instead."
      },
      {
        "title": "Command: analyze-performance",
        "body": "Export data and generate visual dashboards from LP position events. Scripts are in this skill's scripts/ directory."
      },
      {
        "title": "Which Script to Use?",
        "body": "Always ask yourself: was this position deployed as an LP Executor (via manage_executor.py or direct API) or via a Rebalancer Controller bot?\n\nHow it was deployedScript to useLP Executor — manage_executor.py create or direct POST /executors/ APIvisualize_lp_executor.py --id <executor_id> ✅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\n\nIf the user has been running an LP Executor in this session (executor ID is known from context), skip the question and go straight to:\n\npython scripts/visualize_lp_executor.py --id <executor_id>"
      },
      {
        "title": "Available Scripts",
        "body": "ScriptPurposescripts/export_lp_positions.pyExport LP position events to CSV (SQLite/bot-container based)scripts/visualize_lp_positions.pyGenerate HTML dashboard from position events (SQLite/bot-container based)scripts/export_lp_executor.pyExport a single LP executor to CSV by --id (REST API, no SQLite)scripts/visualize_lp_executor.pyGenerate HTML dashboard for a single LP executor by --id (REST API)"
      },
      {
        "title": "Visualize LP Positions",
        "body": "Shows position ADD/REMOVE events from the blockchain. Works for both running and stopped bots.\n\n# Basic usage (auto-detects database in data/)\npython scripts/visualize_lp_positions.py --pair SOL-USDC\n\n# Specify database explicitly\npython scripts/visualize_lp_positions.py --db data/my_bot.sqlite --pair SOL-USDC\n\n# Filter by connector\npython scripts/visualize_lp_positions.py --pair SOL-USDC --connector meteora/clmm\n\n# Last 24 hours only\npython scripts/visualize_lp_positions.py --pair SOL-USDC --hours 24\n\nDashboard Features:\n\nKPI cards (total PnL, fees, IL, win/loss counts)\nCumulative PnL & fees chart\nPrice at open/close with LP range bounds\nPer-position PnL bar chart\nDuration vs PnL scatter plot\nSortable positions table with Solscan links"
      },
      {
        "title": "Export to CSV",
        "body": "# Export all position events\npython scripts/export_lp_positions.py --db data/my_bot.sqlite\n\n# Filter by trading pair\npython scripts/export_lp_positions.py --pair SOL-USDC --output exports/positions.csv\n\n# Show summary without exporting\npython scripts/export_lp_positions.py --summary"
      },
      {
        "title": "Executor Performance (API-based)",
        "body": "These scripts work directly from the Hummingbot REST API — no SQLite database needed.\nUse them when executors were deployed via the API directly (e.g., via manage_executor.py),\nbecause those do not always produce SQLite records the way bot containers do.\n\nExport a single LP executor to CSV:\n\npython scripts/export_lp_executor.py --id <executor_id>\npython scripts/export_lp_executor.py --id <executor_id> --output exports/my_run.csv\npython scripts/export_lp_executor.py --id <executor_id> --print   # JSON to stdout\n\nCSV columns (LP executor schema):\n\nIdentity: id, account_name, controller_id, connector_name, trading_pair\nState: status, close_type, is_active, is_trading, error_count\nTiming: created_at, closed_at, close_timestamp, duration_seconds\nPnL: net_pnl_quote, net_pnl_pct, cum_fees_quote, filled_amount_quote\nConfig (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\ncustom_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\n\nVisualize a single LP executor (HTML dashboard):\n\npython scripts/visualize_lp_executor.py --id <executor_id>\npython scripts/visualize_lp_executor.py --id <executor_id> --output report.html\npython scripts/visualize_lp_executor.py --id <executor_id> --no-open\n\nDashboard panels:\n\nKPI cards: status, net PnL, fees earned, duration, LP range\nPrice chart with LP lower/upper bounds + open/close markers (5m KuCoin candles; auto-skipped for exotic pairs)\nToken balance bar: initial vs final base + quote amounts\nPnL breakdown: fees earned vs IL/price impact vs net PnL\nFull position summary table with Solscan links for pool and position addresses\nDark theme (#0d1117 / #161b27), responsive layout, Chart.js from CDN\nAuth auto-loaded from .env or ~/.hummingbot/.env or ~/.env (keys: HUMMINGBOT_API_URL, API_USER, API_PASS)"
      },
      {
        "title": "Common Workflows",
        "body": "Full Setup (first time):\n\n# 1. Deploy API\nbash scripts/deploy_hummingbot_api.sh install\n\n# 2. Start Gateway\nbash scripts/setup_gateway.sh --rpc-url https://your-rpc-endpoint.com\n\n# 3. Add wallet\npython scripts/add_wallet.py add\n\n# 4. Find pool\npython scripts/list_meteora_pools.py --query SOL-USDC\n\n# 5. Check bin_step\npython scripts/get_meteora_pool.py <pool_address>\n\n# 6. Create config and deploy\npython scripts/manage_controller.py create-config my_lp --pool <pool_address> --pair SOL-USDC --amount 100\npython scripts/manage_controller.py deploy my_bot --configs my_lp\n\n# 7. Verify\npython scripts/manage_controller.py status\n\nAnalyze LP Positions:\n\n# Visualize\npython scripts/visualize_lp_positions.py --pair SOL-USDC\n\n# Export CSV\npython scripts/export_lp_positions.py --pair SOL-USDC"
      },
      {
        "title": "Checking Prerequisites",
        "body": "Before running commands that need the API or Gateway, verify they're running:\n\nbash scripts/check_api.sh       # Is Hummingbot API running?\nbash scripts/check_gateway.sh   # Is Gateway running? (also checks API)\n\nBoth support --json output. These scripts are also used internally by setup_gateway.sh and can be sourced by other shell scripts."
      },
      {
        "title": "Scripts Reference",
        "body": "ScriptPurposecheck_api.shCheck if Hummingbot API is running (shared)check_gateway.shCheck if Gateway is running (shared)deploy_hummingbot_api.shInstall/upgrade/manage Hummingbot APIsetup_gateway.shStart Gateway and configure RPCadd_wallet.pyAdd wallets and check balancesmanage_gateway.pyAdvanced Gateway managementlist_meteora_pools.pySearch and list poolsget_meteora_pool.pyGet pool details with liquidity chartmanage_executor.pyCreate, list, stop LP executorsmanage_controller.pyCreate configs, deploy bots, get statusexport_lp_positions.pyExport position events to CSV (SQLite/bot-container)visualize_lp_positions.pyGenerate HTML dashboard (SQLite/bot-container)export_lp_executor.pyExport single LP executor to CSV by --id (REST API)visualize_lp_executor.pyHTML dashboard for single LP executor by --id (REST API)"
      },
      {
        "title": "Error Troubleshooting",
        "body": "ErrorCauseSolution\"InvalidRealloc\"Position range too wideReduce --width (check bin_step limits)State stuck \"OPENING\"Transaction failedStop executor, reduce range, retry\"Insufficient balance\"Not enough tokensCheck wallet has tokens + 0.06 SOL for rent"
      }
    ],
    "body": "lp-agent\n\nThis skill helps you run automated liquidity provision strategies on concentrated liquidity (CLMM) DEXs using Hummingbot API.\n\nCommands (run as /lp-agent <command>):\n\nCommand\tDescription\nstart\tOnboarding wizard — check setup status and get started\ndeploy-hummingbot-api\tDeploy Hummingbot API trading infrastructure\nsetup-gateway\tStart Gateway, configure network RPC endpoints\nadd-wallet\tAdd or import a Solana wallet\nexplore-pools\tFind and explore Meteora DLMM pools\nselect-strategy\tChoose LP Executor or Rebalancer Controller\nrun-strategy\tRun, monitor, and manage LP strategies\nanalyze-performance\tVisualize LP position performance\n\nNew here? Run /lp-agent start to check your setup and get a guided walkthrough.\n\nTypical workflow: start → deploy-hummingbot-api → setup-gateway → add-wallet → explore-pools → select-strategy → run-strategy → analyze-performance\n\nCommand: start\n\nWelcome the user and guide them through setup. This is a conversational onboarding wizard — check infrastructure state, interpret results, and walk them through each step.\n\nStep 1: Welcome & Explain\n\nIntroduce yourself and explain what lp-agent does:\n\nI'm your LP agent — I help you run automated liquidity provision strategies on Meteora DLMM pools (Solana). I can:\n\nDeploy infrastructure — Hummingbot API + Gateway for DEX trading\nManage wallets — Add Solana wallets, check balances\nExplore pools — Search Meteora DLMM pools, compare APR/volume/TVL\nRun strategies — Auto-rebalancing LP controller or single-position executor\nAnalyze performance — Dashboards with PnL, fees, and position history\nStep 2: Check Infrastructure Status\n\nRun these scripts and interpret the JSON output:\n\nbash scripts/check_api.sh --json      # Is Hummingbot API running?\nbash scripts/check_gateway.sh --json  # Is Gateway running?\npython scripts/add_wallet.py list     # Any wallets connected?\n\n\nInterpreting Results:\n\nScript\tSuccess Output\tFailure Output\ncheck_api.sh --json\t{\"running\": true, \"url\": \"http://localhost:8000\", ...}\t{\"running\": false, ...} or connection error\ncheck_gateway.sh --json\t{\"running\": true, ...}\t{\"running\": false, ...}\nadd_wallet.py list\tShows wallet addresses like [solana] ABC123...\tNo wallets found. or empty list []\nStep 3: Show Progress\n\nPresent a checklist showing what's done and what's remaining based on the script outputs:\n\nSetup Progress:\n  [x] Hummingbot API    — Running at http://localhost:8000\n  [x] Gateway           — Running\n  [ ] Wallet            — No wallet connected\n\nNext step: Add a Solana wallet so you can start trading.\n\n\nAdapt the checklist to the actual state. If everything is unchecked, start from the top. If everything is checked, skip to the LP lifecycle overview.\n\nStep 4: Guide Next Action\n\nBased on the first unchecked item, offer to help:\n\nMissing\tWhat to say\nHummingbot API\t\"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\nGateway\t\"API is running! Now we need Gateway for DEX connectivity. Want me to start it?\" → /lp-agent setup-gateway\nWallet\tSee Adding a Wallet below\nAll ready\tMove to Step 5\n\nAdding a Wallet:\n\nWhen wallet is the next step, tell the user:\n\nInfrastructure is ready. You need a Solana wallet with SOL for transaction fees (~0.06 SOL per LP position).\n\nTo add a wallet, run:\n\npython scripts/add_wallet.py add\n\n\nYou'll be prompted to paste your private key (secure, not saved in shell history).\n\nInterpreting add_wallet.py output:\n\nOutput\tMeaning\n✓ Wallet added successfully + address\tSuccess — wallet is connected\nEnter private key (base58): then ✓ Wallet added\tSuccess after prompt\nError: HTTP 400 or validation error\tInvalid private key format\nError: Cannot connect to API\tAPI not running — run check_api.sh first\n\nAfter wallet is added, verify with python scripts/add_wallet.py list — should show the new address.\n\nStep 5: LP Lifecycle Overview\n\nOnce infrastructure is ready (or if user wants to understand the flow first), explain the LP lifecycle:\n\nHow LP strategies work:\n\nExplore pools (/lp-agent explore-pools) — Find a Meteora DLMM pool. Look at volume, APR, and fee/TVL ratio to pick a good one.\n\nSelect strategy (/lp-agent select-strategy) — Choose between:\n\nRebalancer Controller (recommended) — Automatically repositions when price moves out of range. Set-and-forget.\nLP Executor — Single fixed position. You control when to close/reopen. Good for testing or limit-order-style LP.\n\nRun strategy (/lp-agent run-strategy) — Configure parameters (amount, width, price limits) and deploy. Monitor status and stop when done.\n\nAnalyze (/lp-agent analyze-performance) — View PnL dashboard, fees earned, position history. Works for both running and stopped strategies.\n\nWant to explore some pools to get started?\n\nCommand: deploy-hummingbot-api\n\nDeploy the Hummingbot API trading infrastructure. This is the first step before using any LP features.\n\nWhat Gets Installed\n\nHummingbot API — A personal trading server that exposes a REST API for trading, market data, and deploying bot strategies across CEXs and DEXs.\n\nRepository: hummingbot/hummingbot-api\nUsage\n# Check if already installed\nbash scripts/deploy_hummingbot_api.sh status\n\n# Install (interactive, prompts for credentials)\nbash scripts/deploy_hummingbot_api.sh install\n\n# Install with defaults (non-interactive: admin/admin)\nbash scripts/deploy_hummingbot_api.sh install --defaults\n\n# Upgrade existing installation\nbash scripts/deploy_hummingbot_api.sh upgrade\n\n# View container logs\nbash scripts/deploy_hummingbot_api.sh logs\n\n# Reset (stop and remove everything)\nbash scripts/deploy_hummingbot_api.sh reset\n\nPrerequisites\nDocker and Docker Compose\nGit\nInterpreting Output\nOutput\tMeaning\tNext Step\n✓ Hummingbot API deployed successfully\tSuccess\tProceed to setup-gateway\n✓ Already installed and running\tAlready set up\tProceed to setup-gateway\nError: Docker not found\tDocker not installed\tInstall Docker first\nError: Port 8000 already in use\tAnother service on port\tStop conflicting service or use different port\nAfter Installation\n\nOnce the API is running:\n\nSwagger UI is at http://localhost:8000/docs\nDefault credentials: admin/admin\nProceed to setup-gateway to enable DEX trading\nCommand: setup-gateway\n\nStart the Gateway service, check its status, and configure key network parameters like RPC node URLs. Gateway is required for all LP operations on DEXs.\n\nPrerequisite: Hummingbot API must be running (deploy-hummingbot-api). The script checks this automatically.\n\nUsage\n# Check Gateway status\nbash scripts/setup_gateway.sh --status\n\n# Start Gateway with defaults\nbash scripts/setup_gateway.sh\n\n# Start Gateway with custom image (e.g., development build)\nbash scripts/setup_gateway.sh --image hummingbot/gateway:development\n\n# Start with custom Solana RPC (recommended to avoid rate limits)\nbash scripts/setup_gateway.sh --rpc-url https://your-rpc-endpoint.com\n\n# Configure RPC for a different network\nbash scripts/setup_gateway.sh --network ethereum-mainnet --rpc-url https://your-eth-rpc.com\n\n# Start with custom passphrase and port\nbash scripts/setup_gateway.sh --passphrase mypassword --port 15888\n\nOptions\nOption\tDefault\tDescription\n--status\t\tCheck Gateway status only (don't start)\n--image IMAGE\thummingbot/gateway:development\tDocker image to use\n--passphrase TEXT\thummingbot\tGateway passphrase\n--rpc-url URL\t\tCustom RPC endpoint for --network\n--network ID\tsolana-mainnet-beta\tNetwork to configure RPC for\n--port PORT\t15888\tGateway port\nAdvanced: manage_gateway.py\n\nFor finer control (stop, restart, logs, per-network config), use manage_gateway.py:\n\npython scripts/manage_gateway.py status                    # Check status\npython scripts/manage_gateway.py start                     # Start Gateway\npython scripts/manage_gateway.py stop                      # Stop Gateway\npython scripts/manage_gateway.py restart                   # Restart Gateway\npython scripts/manage_gateway.py logs                      # View logs\npython scripts/manage_gateway.py networks                  # List all networks\npython scripts/manage_gateway.py network solana-mainnet-beta                          # Get network config\npython scripts/manage_gateway.py network solana-mainnet-beta --node-url https://...   # Set RPC node\n\nInterpreting Output\nOutput\tMeaning\tNext Step\n✓ Gateway is running or ✓ Gateway started\tSuccess\tProceed to add-wallet\n✓ Gateway is already running\tAlready set up\tProceed to add-wallet\n✗ Cannot connect to Hummingbot API\tAPI not running\tRun /lp-agent deploy-hummingbot-api first\n✗ Failed to start Gateway\tDocker issue\tCheck Docker is running, check logs\n✓ RPC configured + ✓ Gateway restarted\tCustom RPC set\tReady to use\nCustom RPC Nodes\n\nGateway uses public RPC nodes by default, which can hit rate limits. Set a custom nodeUrl per network to avoid this.\n\nPopular Solana RPC providers:\n\nHelius — Free tier available\nQuickNode\nAlchemy\nTriton\nCommand: add-wallet\n\nAdd a Solana wallet for trading.\n\nRequires: deploy-hummingbot-api and setup-gateway completed first.\n\nAdding a Wallet\npython scripts/add_wallet.py add\n\n\nYou'll be prompted to paste your private key (base58 format). The key is entered securely and won't appear in shell history.\n\nInterpreting Output:\n\nOutput\tMeaning\tNext Step\n✓ Wallet added successfully + Address: ABC...\tSuccess\tVerify with list command\nError: HTTP 400 - Bad Request\tInvalid private key format\tCheck key is base58 encoded\nError: HTTP 503\tGateway not available\tRun bash scripts/check_gateway.sh\nError: Cannot connect to API\tAPI not running\tRun /lp-agent deploy-hummingbot-api\nListing Wallets\npython scripts/add_wallet.py list\n\n\nInterpreting Output:\n\nOutput\tMeaning\n[solana] ABC123...XYZ\tWallet connected on Solana\nNo wallets found.\tNo wallets added yet\nEmpty list [] (with --json)\tNo wallets added yet\nChecking Balances\n# Check all balances\npython scripts/add_wallet.py balances\n\n# Filter by account\npython scripts/add_wallet.py balances --account master_account\n\n# Show zero balances too\npython scripts/add_wallet.py balances --all\n\nRequirements\nSOL for fees: Wallet needs SOL for transaction fees (~0.06 SOL per LP position for rent)\nDefault chain: Solana mainnet-beta\nCommand: explore-pools\n\nFind and explore Meteora DLMM pools before creating LP positions.\n\nNote: 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.\n\nList Pools\n\nSearch and list pools by name, token, or address:\n\n# Top pools by 24h volume\npython scripts/list_meteora_pools.py\n\n# Search by token symbol\npython scripts/list_meteora_pools.py --query SOL\npython scripts/list_meteora_pools.py --query USDC\n\n# Search by pool name\npython scripts/list_meteora_pools.py --query SOL-USDC\n\n# Sort by different metrics\npython scripts/list_meteora_pools.py --query SOL --sort tvl\npython scripts/list_meteora_pools.py --query SOL --sort apr\npython scripts/list_meteora_pools.py --query SOL --sort fees\n\n# Pagination\npython scripts/list_meteora_pools.py --query SOL --limit 50 --page 2\n\n\nOutput columns:\n\nPool: Trading pair name\nPool Address: Pool contract address (shortened, use get_meteora_pool.py for full address)\nBase (mint): Base token symbol with shortened mint address\nQuote (mint): Quote token symbol with shortened mint address\nTVL: Total value locked\nVol 24h: 24-hour trading volume\nFees 24h: Fees earned in last 24 hours\nAPR: Annual percentage rate\nFee: Base fee percentage\nBin: Bin step (affects max position width)\n\nNote: Token mints help identify the correct token when multiple tokens share the same name (e.g., multiple \"PERCOLATOR\" tokens).\n\nGet Pool Details\n\nGet detailed information about a specific pool. Fetches from both Meteora API (historical data) and Gateway (real-time data):\n\npython scripts/get_meteora_pool.py <pool_address>\n\n# Example\npython scripts/get_meteora_pool.py ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms\n\n# Output as JSON for programmatic use\npython scripts/get_meteora_pool.py ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms --json\n\n# Skip Gateway (faster, no bin distribution)\npython scripts/get_meteora_pool.py ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms --no-gateway\n\n\nData sources:\n\nMeteora API: Historical volume, fees, APR, token info, market caps\nGateway (requires running Gateway): Real-time price, liquidity distribution by bin\n\nDetails shown:\n\nToken info (symbols, mints, decimals, prices)\nPool configuration (bin step, fees, max range width)\nReal-time price from Gateway (SOL/token ratio)\nLiquidity distribution chart showing bins around current price\nLiquidity and reserves\nVolume across time windows (30m, 1h, 4h, 12h, 24h)\nFees earned across time windows\nYield (APR, APY, farm rewards)\nFee/TVL ratio (profitability indicator)\nChoosing a Pool\n\nWhen selecting a pool, consider:\n\nTVL: Higher TVL = more stable, but also more competition\nVolume: Higher volume = more fee opportunities\nFee/TVL Ratio: Higher = more profitable per $ of liquidity\nBin Step: Determines max position width\nbin_step=1 → max ~0.69% width (tight ranges)\nbin_step=10 → max ~6.9% width (medium ranges)\nbin_step=100 → max ~69% width (wide ranges)\nCommand: select-strategy\n\nHelp the user choose the right LP strategy. See references/ for detailed guides.\n\nLP Rebalancer Controller (Recommended)\n\nReference: references/lp_rebalancer_guide.md\n\nA controller that automatically manages LP positions with rebalancing logic.\n\nFeature\tDescription\nAuto-rebalance\tCloses and reopens positions when price exits range\nPrice limits\tConfigure BUY/SELL zones with anchor points\nKEEP logic\tAvoids unnecessary rebalancing when at optimal position\nHands-off\tSet and forget - controller manages everything\n\nBest for: Longer-term LP strategies, range-bound markets, automated fee collection.\n\nLP Executor (Single Position)\n\nReference: references/lp_executor_guide.md\n\nCreates ONE liquidity position with fixed price bounds. No auto-rebalancing.\n\nFeature\tDescription\nFixed bounds\tPosition stays at configured price range\nManual control\tUser decides when to close/reopen\nLimit orders\tCan auto-close when price exits range (like limit orders)\nSimple\tDirect control over single position\n\nBest for: Short-term positions, limit-order-style LP, manual management, testing.\n\nQuick Comparison\nAspect\tRebalancer Controller\tLP Executor\nRebalancing\tAutomatic\tManual\nPosition count\tOne at a time, auto-managed\tOne, fixed\nPrice limits\tYes (anchor points)\tNo (but has auto-close)\nComplexity\tHigher (more config)\tLower (simpler)\nUse case\tSet-and-forget\tPrecise control\nCommand: run-strategy\n\nRun, monitor, and manage LP strategies.\n\nRequires: deploy-hummingbot-api, setup-gateway, and add-wallet completed first.\n\nLP Rebalancer Controller (Recommended)\n\nReference: See references/lp_rebalancer_guide.md for full configuration details, rebalancing logic, and KEEP vs REBALANCE scenarios.\n\nAuto-rebalances positions when price moves out of range. Best for hands-off LP management.\n\nKey concepts:\n\n--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.\nAll *_pct params are already in percent. position_width_pct: 10 = 10% width. Do NOT pass decimals (not 0.10).\nPrice limits (--buy-min/max, --sell-min/max) default to 0 = no limit. Only set if you want a stop zone.\n# 1. Create LP Rebalancer config (pool and pair are required)\npython scripts/manage_controller.py create-config my_lp_config \\\n    --pool <pool_address> \\\n    --pair SOL-USDC \\\n    --amount 10 \\       # 10 USDC (quote asset for SOL-USDC)\n    --side 0 \\          # 0=BOTH, 1=BUY (quote only), 2=SELL (base only)\n    --width 10 \\        # 10% range around current price\n    --offset 1 \\        # center range 1% from current price\n    --rebalance-seconds 300 \\\n    --rebalance-threshold 1\n\n# Side=2 example: deploy base token only (e.g. 110k PRCLT ≈ 1.33 SOL)\npython scripts/manage_controller.py create-config percolator_sell \\\n    --pool ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms \\\n    --pair Percolator-SOL \\\n    --amount 1.33 \\     # 1.33 SOL worth (quote for Percolator-SOL pair)\n    --side 2\n\n# 2. Deploy bot with the config\npython scripts/manage_controller.py deploy my_lp_bot --configs my_lp_config\n\n# 3. Monitor status\npython scripts/manage_controller.py status\n\n\nKey Parameters:\n\nParameter\tField\tDefault\tDescription\n--amount\ttotal_amount_quote\trequired\tAmount in quote asset (2nd token). SOL for X-SOL pairs, USDC for X-USDC pairs.\n--side\tside\t0\t0=BOTH, 1=BUY (quote only), 2=SELL (base only)\n--width\tposition_width_pct\t10\tRange width in % (e.g. 10 = ±10% around price). Already in pct — do not use decimals.\n--offset\tposition_offset_pct\t1\tCenter offset from current price in %. Already in pct.\n--rebalance-seconds\trebalance_seconds\t300\tSeconds out-of-range before closing and reopening\n--rebalance-threshold\trebalance_threshold_pct\t1\tMin price move % to trigger rebalance. Already in pct.\n--sell-max/--sell-min\tsell_price_max/min\t0\tPrice limits for SELL side (0 = no limit)\n--buy-max/--buy-min\tbuy_price_max/min\t0\tPrice limits for BUY side (0 = no limit)\n--strategy-type\tstrategy_type\t0\tMeteora shape: 0=Spot (uniform), 1=Curve (center-heavy), 2=Bid-Ask (edge-heavy)\nSingle LP Executor (Alternative)\n\nReference: See references/lp_executor_guide.md for state machine, single/double-sided positions, and limit range orders.\n\nCreates ONE position with fixed bounds. Does NOT auto-rebalance.\n\npython scripts/manage_executor.py create \\\n    --pool <pool_address> \\\n    --pair SOL-USDC \\\n    --quote-amount 100 \\\n    --lower 180 \\\n    --upper 185 \\\n    --side 1\n\n\nKey Parameters:\n\nParameter\tDescription\n--connector\tMust include /clmm suffix (default: meteora/clmm)\n--lower/--upper\tPosition price bounds\n--base-amount/--quote-amount\tToken amounts (set one to 0 for single-sided)\n--side\t0=BOTH, 1=BUY, 2=SELL\n--auto-close-above\tAuto-close when price above range (for limit orders)\n--auto-close-below\tAuto-close when price below range (for limit orders)\nMonitor & Manage\n\nCheck Status:\n\n# Bot status\npython scripts/manage_controller.py status\n\n# Executor list\npython scripts/manage_executor.py list --type lp_executor\n\n# Executor details\npython scripts/manage_executor.py get <executor_id>\n\n# Executor summary\npython scripts/manage_executor.py summary\n\n\nExecutor States:\n\nOPENING - Creating position on-chain\nIN_RANGE - Position active, earning fees\nOUT_OF_RANGE - Price outside position bounds\nCLOSING - Removing position\nFAILED - Transaction failed\n\nStop:\n\n# Stop bot (stops all its controllers)\npython scripts/manage_controller.py stop my_lp_bot\n\n# Stop individual executor (closes position)\npython scripts/manage_executor.py stop <executor_id>\n\n# Stop executor but keep position on-chain\npython scripts/manage_executor.py stop <executor_id> --keep-position\n\nAfter Stopping — Analyze Results\n\nIf the user ran an LP Executor (via manage_executor.py create or direct API), immediately offer to analyze it:\n\nYour executor has been stopped. Want me to generate a performance dashboard?\n\nThen run:\n\npython scripts/visualize_lp_executor.py --id <executor_id>\n\n\nThe 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:\n\ncurl -s -u admin:admin -X POST http://localhost:8000/executors/search \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"type\":\"lp_executor\"}' | python3 -c \"\nimport json,sys\ndata=json.load(sys.stdin)\nitems=data.get('data',data) if isinstance(data,dict) else data\nfor ex in (items if isinstance(items,list) else [items]):\n    print(ex.get('executor_id') or ex.get('id'), ex.get('trading_pair'), ex.get('status'))\n\"\n\n\nTo also export the raw data to CSV:\n\npython scripts/export_lp_executor.py --id <executor_id>\n\n\nIf the user ran a Rebalancer Controller bot, the data lives in a SQLite file — use analyze-performance with the SQLite-based scripts instead.\n\nCommand: analyze-performance\n\nExport data and generate visual dashboards from LP position events. Scripts are in this skill's scripts/ directory.\n\nWhich Script to Use?\n\nAlways ask yourself: was this position deployed as an LP Executor (via manage_executor.py or direct API) or via a Rebalancer Controller bot?\n\nHow it was deployed\tScript to use\nLP Executor — manage_executor.py create or direct POST /executors/ API\tvisualize_lp_executor.py --id <executor_id> ✅\nRebalancer Controller — manage_controller.py deploy (bot container, SQLite)\tvisualize_lp_positions.py --pair <pair>\nNot sure?\tRun 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\n\nIf the user has been running an LP Executor in this session (executor ID is known from context), skip the question and go straight to:\n\npython scripts/visualize_lp_executor.py --id <executor_id>\n\nAvailable Scripts\nScript\tPurpose\nscripts/export_lp_positions.py\tExport LP position events to CSV (SQLite/bot-container based)\nscripts/visualize_lp_positions.py\tGenerate HTML dashboard from position events (SQLite/bot-container based)\nscripts/export_lp_executor.py\tExport a single LP executor to CSV by --id (REST API, no SQLite)\nscripts/visualize_lp_executor.py\tGenerate HTML dashboard for a single LP executor by --id (REST API)\nVisualize LP Positions\n\nShows position ADD/REMOVE events from the blockchain. Works for both running and stopped bots.\n\n# Basic usage (auto-detects database in data/)\npython scripts/visualize_lp_positions.py --pair SOL-USDC\n\n# Specify database explicitly\npython scripts/visualize_lp_positions.py --db data/my_bot.sqlite --pair SOL-USDC\n\n# Filter by connector\npython scripts/visualize_lp_positions.py --pair SOL-USDC --connector meteora/clmm\n\n# Last 24 hours only\npython scripts/visualize_lp_positions.py --pair SOL-USDC --hours 24\n\n\nDashboard Features:\n\nKPI cards (total PnL, fees, IL, win/loss counts)\nCumulative PnL & fees chart\nPrice at open/close with LP range bounds\nPer-position PnL bar chart\nDuration vs PnL scatter plot\nSortable positions table with Solscan links\nExport to CSV\n# Export all position events\npython scripts/export_lp_positions.py --db data/my_bot.sqlite\n\n# Filter by trading pair\npython scripts/export_lp_positions.py --pair SOL-USDC --output exports/positions.csv\n\n# Show summary without exporting\npython scripts/export_lp_positions.py --summary\n\nExecutor Performance (API-based)\n\nThese 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.\n\nExport a single LP executor to CSV:\n\npython scripts/export_lp_executor.py --id <executor_id>\npython scripts/export_lp_executor.py --id <executor_id> --output exports/my_run.csv\npython scripts/export_lp_executor.py --id <executor_id> --print   # JSON to stdout\n\n\nCSV columns (LP executor schema):\n\nIdentity: id, account_name, controller_id, connector_name, trading_pair\nState: status, close_type, is_active, is_trading, error_count\nTiming: created_at, closed_at, close_timestamp, duration_seconds\nPnL: net_pnl_quote, net_pnl_pct, cum_fees_quote, filled_amount_quote\nConfig (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\ncustom_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\n\nVisualize a single LP executor (HTML dashboard):\n\npython scripts/visualize_lp_executor.py --id <executor_id>\npython scripts/visualize_lp_executor.py --id <executor_id> --output report.html\npython scripts/visualize_lp_executor.py --id <executor_id> --no-open\n\n\nDashboard panels:\n\nKPI cards: status, net PnL, fees earned, duration, LP range\nPrice chart with LP lower/upper bounds + open/close markers (5m KuCoin candles; auto-skipped for exotic pairs)\nToken balance bar: initial vs final base + quote amounts\nPnL breakdown: fees earned vs IL/price impact vs net PnL\nFull position summary table with Solscan links for pool and position addresses\nDark theme (#0d1117 / #161b27), responsive layout, Chart.js from CDN\nAuth auto-loaded from .env or ~/.hummingbot/.env or ~/.env (keys: HUMMINGBOT_API_URL, API_USER, API_PASS)\nQuick Reference\nCommon Workflows\n\nFull Setup (first time):\n\n# 1. Deploy API\nbash scripts/deploy_hummingbot_api.sh install\n\n# 2. Start Gateway\nbash scripts/setup_gateway.sh --rpc-url https://your-rpc-endpoint.com\n\n# 3. Add wallet\npython scripts/add_wallet.py add\n\n# 4. Find pool\npython scripts/list_meteora_pools.py --query SOL-USDC\n\n# 5. Check bin_step\npython scripts/get_meteora_pool.py <pool_address>\n\n# 6. Create config and deploy\npython scripts/manage_controller.py create-config my_lp --pool <pool_address> --pair SOL-USDC --amount 100\npython scripts/manage_controller.py deploy my_bot --configs my_lp\n\n# 7. Verify\npython scripts/manage_controller.py status\n\n\nAnalyze LP Positions:\n\n# Visualize\npython scripts/visualize_lp_positions.py --pair SOL-USDC\n\n# Export CSV\npython scripts/export_lp_positions.py --pair SOL-USDC\n\nChecking Prerequisites\n\nBefore running commands that need the API or Gateway, verify they're running:\n\nbash scripts/check_api.sh       # Is Hummingbot API running?\nbash scripts/check_gateway.sh   # Is Gateway running? (also checks API)\n\n\nBoth support --json output. These scripts are also used internally by setup_gateway.sh and can be sourced by other shell scripts.\n\nScripts Reference\nScript\tPurpose\ncheck_api.sh\tCheck if Hummingbot API is running (shared)\ncheck_gateway.sh\tCheck if Gateway is running (shared)\ndeploy_hummingbot_api.sh\tInstall/upgrade/manage Hummingbot API\nsetup_gateway.sh\tStart Gateway and configure RPC\nadd_wallet.py\tAdd wallets and check balances\nmanage_gateway.py\tAdvanced Gateway management\nlist_meteora_pools.py\tSearch and list pools\nget_meteora_pool.py\tGet pool details with liquidity chart\nmanage_executor.py\tCreate, list, stop LP executors\nmanage_controller.py\tCreate configs, deploy bots, get status\nexport_lp_positions.py\tExport position events to CSV (SQLite/bot-container)\nvisualize_lp_positions.py\tGenerate HTML dashboard (SQLite/bot-container)\nexport_lp_executor.py\tExport single LP executor to CSV by --id (REST API)\nvisualize_lp_executor.py\tHTML dashboard for single LP executor by --id (REST API)\nError Troubleshooting\nError\tCause\tSolution\n\"InvalidRealloc\"\tPosition range too wide\tReduce --width (check bin_step limits)\nState stuck \"OPENING\"\tTransaction failed\tStop executor, reduce range, retry\n\"Insufficient balance\"\tNot enough tokens\tCheck wallet has tokens + 0.06 SOL for rent"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/fengtality/lp-agent",
    "publisherUrl": "https://clawhub.ai/fengtality/lp-agent",
    "owner": "fengtality",
    "version": "1.0.1",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/lp-agent",
    "downloadUrl": "https://openagent3.xyz/downloads/lp-agent",
    "agentUrl": "https://openagent3.xyz/skills/lp-agent/agent",
    "manifestUrl": "https://openagent3.xyz/skills/lp-agent/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/lp-agent/agent.md"
  }
}