feat(lp-agent): add Solana DEX LP Expert — autonomous CLMM liquidity provisioning

[fengtality]

Adds the Solana DEX LP Expert, an autonomous agent that provides concentrated liquidity to memecoin pools on Solana — plus a Solana-specific note in the order_executor guide that came out of running it live against a real wallet.

The /stop orphaned-positions guard (condor/agents/shutdown.py, condor/web/routes/agents.py) that used to be in this PR is unrelated to the LP agent and now lives in #184.

---

The agent

Each tick it monitors open LP slots, exits any that hit take-profit / stop-loss or idle out of range, and fills one free slot with the best-yielding pool it doesn't already hold.

• Scan — lp_scanner routine pulls GeckoTerminal pools across Meteora / Orca / Raydium and ranks by fee yield (fees ÷ TVL) over a configurable window. The quote asset is matched by mint on either pool side, so a SOL-quoted scan also finds pools GeckoTerminal lists as SOL/USDC (SOL as base) — orientation is normalized before ranking. Telegram-form inputs are tolerated: list fields accept comma/space-separated text, and blank coerces to empty.
• Size — capital split into slots, each opened at a base_pct base/quote ratio (default 20/80).
• Place — LP Executors (side=3 RANGE, keep_position=false), range placed asymmetrically so an even Spot distribution lands the target ratio.
• Manage — per-slot TP/SL, plus an out-of-range idle exit (out_of_range_max_sec) that recycles capital sitting out of range earning nothing.
• Wind down — shutdown.md declares on_kill_switch: flatten_all: positions are risk to close, never spot to keep.

Files: AGENT.md, shutdown.md, strategies/lp_slot_operator/strategy.md, 4 skills (pool_ranking, lp_range_config, slot_exit, lp_bot_report), and the lp_scanner routine. Runtime session data (journals, snapshots) is deliberately untracked, matching the existing market_making_expert layout.

Two correctness rules that took live runs to find

Range bounds flip by venue. Meteora quotes SOL-per-memecoin (memecoin above P); Orca and Raydium invert it (memecoin below P). Apply one convention to the other and the bounds don't bracket the live price — the open fails on-chain with no funds moved and the slot silently stays empty.

Width clamps must be in granularity units, not percent. Percent width isn't comparable across pools:

Meteora:       bins     = ln(Pu/Pl) / ln(1 + bin_step/10000)      < 69
Orca/Raydium:  spacings = ln(Pu/Pl) / (ln(1.0001) × tick_spacing) ≤ 120

Two Orca opens at an identical 20.8% width landed on opposite sides purely on tick_spacing: 16 → 118 spacings opened fine, 8 → 237 failed. Successes observed at 75 / 76 / 98 / 118 spacings; the only failure was 237. Any percent-based rule of thumb is wrong in both directions — it rejects good ranges and admits failing ones.

The winddown's swap-back leg is not guaranteed

keep_position=false should remove liquidity and swap the base tokens back to quote. Observed twice that only the first leg ran: liquidity came out, the swap silently failed, and the full base position sat as spot while every lp_executor reported a clean EARLY_STOP.

A clean executor status is not evidence the tokens were converted. shutdown.md says so and requires re-reading the on-chain balance and retrying until it's ~0.

order_executor guide: Solana sizing note

executed_amount_base is the amount REQUESTED, not received. The agent swaps quote→base, then immediately opens the LP with what it just bought. But order_executor reports the requested amount (62), while slippage and fees mean the wallet actually receives less (61.962753, −0.06%; another case −0.44%). Passing the reported fill into base_amount asks the pool for tokens that aren't there — the open fails, position_address=null, no funds move.

Fix, now documented in the guide: base_amount = executed_amount_base × 0.995, or read the true post-swap balance. This was the cause of every "SIMULATION_FAILED" open. After the fix: 7 opens across two sessions, 0 failures (previously 3 and 2 failures per session).

---

Testing

Run live against a real Solana wallet across sessions 8–11: start/stop/shutdown, 3 concurrent LP slots, TP/SL and out-of-range idle exits, and full winddown. All positions verified closed on-chain — position accounts and NFTs checked directly via RPC, not just the API, after the API's total_value_quote was found to misreport a slot's value by ~2.7×. Final wallet reconciled to chain.

No secrets included — the staged diff was scanned for API keys, RPC credentials, wallet addresses, and tokens before commit.

🤖 Generated with Claude Code

https://claude.ai/code/session_0154EUNSY4ocqsWPKZWgwBJn

[rapcmia]

Commit 36fc10d

• Build local .whl from staging and deploy with HAPI
• Setup Condor + HAPI successfully
• Deployed gateway via HAPI using staging branch docker image
• Observed the behavior between keep_position false and true from previous tests ✅
• For most of the test, I consult/delegate solana_dex_lp_expert and switched agents from claude to codex (vice versa) ✅
• Open a small LP per venue and verify bounds bracket price, respect bin/tick caps, and create a position. ✅

Test base_pct 0, 20, and 100 to catch the conflicting range instructions. ✅

## `base_pct` → sizing (key lever; full presets in the `lp_range_config` skill)
- **`0`** → quote-only, `side=1`, range **below** P, no swap.
- **`100`** → base-only: swap quote→base first, `side=2`, range **above** P.
- **`0<base_pct<100`** → double-sided, `side=3`: `quote_amount = capital×(1−base_pct/100)`, acquire base worth `capital×base_pct/100` (swap the shortfall).

• While checking the solana_dex_lp_exert, i found this base_pct to test behavior
  • base_pct=0 opened a USDC-only BUY LP with no SOL. It was correctly out of range above its buy range.
  • base_pct=40 opened a mixed SOL/USDC RANGE LP. The live price was inside its range.
  • base_pct=100 opened a SOL-only SELL LP with no USDC. It was correctly out of range below its sell range.

---

Verify unavailable executor/position data blocks stop rather than allowing it. ✅

#### confirm the Solana LP expert blocks all actions for the terminated executor
curl -sS --max-time 180 -H "Authorization: Bearer XXX" -H "Content-Type: application/json" -X POST http://localhost:8088/api/v1/agents/solana_dex_lp_expert/consult -d '
{
  "task": "Planning-only negative QA check; block all LP actions for a terminated, failed executor with no position.",
  "context": "Reference executor FCLc3WAqbdpkByJfDZTQMHQYNqXcnv2veizGRgd32JAG is terminated, FAILED, and has position_address null.",
  "server_name": "local"
}' | jq
{
  "agent": "solana_dex_lp_expert",
  "answer": {
    "lookup_status": "terminated_failed_no_position",
    "recommended_action": "block_all_lp_actions",
    "blocked": true,
    "reason": "Reference executor is terminated with FAILED state and position_address=null"
  }
}

• Condor found an old LP executor that had already stopped and had no position attached to it.
• The Solana LP expert stopped the process and did not make any LP change, swap, or transaction.
• This confirms the safety check works when an executor has stopped or its position data is missing.

---

Confirm scanner results for SOL/USDC pools regardless of GeckoTerminal token orientation across Meteora, Orca, and Raydium. ❌

• I ran the default config and it only displayed pairs ending with XXX-SOL
  

• After i updated the Base token mints to exclude (already held) does not let use the routine anymore ❌
  

  condor.routine_store - ERROR - Routine lp_scanner[0b61e696] failed: ValidationError: 1 validation error for Config
  exclude_mints
    Input should be a valid list [type=list_type, input_value='', input_type=str]
    For further information visit https://errors.pydantic.dev/2.12/v/list_type
  Traceback (most recent call last):
    File "/home/eddga/hummingbot/condor/162/condor/routine_store.py", line 333, in _execute_and_record
      cfg = routine.config_class(**config)
    File "/home/eddga/hummingbot/condor/162/.venv/lib/python3.13/site-packages/pydantic/main.py", line 250, in __init__
      validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
  pydantic_core._pydantic_core.ValidationError: 1 validation error for Config
  exclude_mints
    Input should be a valid list [type=list_type, input_value='', input_type=str]
    For further information visit https://errors.pydantic.dev/2.12/v/list_type
  

  • Leaving Base token mints to exclude (already held) blank prevents the LP scanner from starting, so the SOL/USDC orientation check cannot run.
  • The routine receives exclude_mints as "", but its configuration requires a list; it stops with a Pydantic validation error before generating a report.
  • Entering 0, a space, {}, or [] gives the same error, which confirms the form is submitting text values instead of omitting the field or sending a list.

[fengtality]

Both ❌ items are addressed in f1160c3:

Blank exclude_mints no longer blocks the routine. The Telegram form submits list fields as text, so venues / exclude_pools / exclude_mints now accept comma- or space-separated text via a mode="before" validator — blank ("" or whitespace) coerces to [], and mintA, mintB parses to a list. The Pydantic list_type error is gone.

SOL/USDC pools now appear regardless of GeckoTerminal orientation. The scanner previously kept a pool only when Gecko's quote_token_symbol matched the configured quote, so a SOL-quoted scan dropped every pool Gecko lists as SOL/USDC (SOL as base) — hence only XXX-SOL rows. The quote asset is now matched by mint on either side of the pool, and inverted listings are flipped into base-quote orientation (price sourced from quote_token_price_usd when flipped). Verified against live GeckoTerminal data: 13 SOL/USDC pools across Meteora/Orca/Raydium that were previously dropped now enter the ranking as USDC-SOL.

Also, an unsupported quote_asset now returns a clear error up front instead of silently matching nothing.

🤖 Generated with Claude Code