SOL-BSC DESK AI — Live Executor Module: Developer

SOL-BSC DESK AI — Live Executor Module: Developer Specification Purpose: This document specifies ONE small Python module that connects an existing, working trading system to real on-chain execution on Solana. Almost everything already exists (signal source, paper engine, kill switch, gate, slippage measurement, accounting). The ONLY thing being built here is the live signing plus swap execution layer. A competent Solana developer should be able to build this in a few hours. Do NOT build a whole trading bot — only the module described below. --- 0. CONTEXT (what already exists — do NOT rebuild) The system runs on an Ubuntu VPS, Python, PostgreSQL (in Docker), and already: - Detects trade signals — an existing process (alphai_fire.py) receives a Solana token mint to trade, in real time, from a Telegram signal source. - Has a kill switch — live/kill_switch.py, function is_live_allowed() returns True only if live trading is permitted. MUST be checked before any trade. Fails safe (returns not-allowed on any error). - Has a liquidity gate — token liquidity (LP) and market cap (MC) are known at signal time. Trade only if LP is at least 10000 USD AND MC is at least 12000 USD. - Measures slippage — live/slippage_model.py already quotes Jupiter. - Has an accounting ledger — live/wallet_ledger.py, function record_event(...) writes deposits, trades, sweeps, gas to the DB. - PostgreSQL access pattern: psycopg2, config in strategy/config.py (POSTGRES_HOST, PORT, DB, USER, PASSWORD). The bot wallet keypair already exists at the path HOME/.config/solana/bot_wallet.json (standard Solana CLI keypair file, solana-keygen format, permissions 600). Solana RPC: a mainnet RPC URL (the owner will provide; e.g. a paid endpoint like Helius, QuickNode, or Alchemy — the public RPC is too rate-limited for live). --- 1. WHAT TO BUILD A single Python module: live/live_executor.py It exposes ONE main function named execute_live_trade that takes three inputs: - mint (string): the Solana token mint address to trade - lp_usd (number): the token liquidity in USD at signal time - mc_usd (number): the token market cap in USD at signal time and returns a result dictionary (success or failure plus details). It is called when the signal source fires. It must perform a buy then hold then sell round trip for ONE position, using Jupiter, signing with the bot wallet, and recording everything. Required sequence inside execute_live_trade: 1. Kill-switch check. Call kill_switch.is_live_allowed(). If it returns False, return a failure result with reason equal to kill_switch and do NOTHING else. 2. Gate check. If lp_usd is below 10000 or mc_usd is below 12000, return a failure result with reason equal to gate. No trade. 3. Single-position check. If a live position is already open (track this in a DB row or in-memory flag), return a failure result with reason equal to max_open. Max concurrent live positions equals 1. 4. Balance check. Read bot wallet SOL balance. Required position size equals 30 USD worth of SOL (configurable constant POSITION_USD equals 30). Ensure wallet has enough for the position PLUS a gas reserve (keep at least 0.01 SOL free for fees). If insufficient, return a failure result with reason equal to insufficient_balance. 5. BUY. Use the Jupiter Swap API (see station.jup.ag docs — quote plus swap endpoints) to swap POSITION_USD worth of SOL into the target token (mint). - Get a quote (input equals SOL or wrapped SOL, output equals the mint, amount equals 30 USD worth of SOL in lamports). - Use a sane slippage tolerance (suggest slippageBps from 1000 to 3000, i.e. 10 to 30 percent, because these are thin memecoins — make it a config constant). - Get the swap transaction from Jupiter, sign it with the bot wallet keypair, submit, and confirm the transaction landed (poll for confirmation). - Record the actual tokens received and the actual SOL spent. 6. HOLD. Wait HOLD_SECONDS equals 12 (config constant). This matches the strategy 12-second scalp window. 7. SELL. Jupiter swap the FULL received token amount back into SOL. - Same signing, submit, and confirm pattern. - Record actual SOL received. 8. RECORD P AND L. Compute realized profit and loss (SOL out of sell minus SOL into buy, in USD using a SOL price), write it via wallet_ledger.record_event with event type trade_pnl, including the on-chain transaction signatures for both buy and sell. 9. Clear the single-position flag. Return a success result containing the buy signature, the sell signature, and the realized profit and loss in USD. Hard requirements and safety: - The private key NEVER leaves the server, is NEVER logged, NEVER printed, NEVER sent anywhere. Load it only to sign, in memory. - Every step that can fail must fail SAFE. On any error during buy, the code must not proceed to a state where funds are stuck untracked. If the SELL fails, RETRY the sell (the position must not be left open silently — log loudly and keep attempting to exit, or alert). - Confirm every transaction on-chain before proceeding. Do not assume success. - Idempotency and no double-spend: never fire two buys for one signal. - Wrap the whole thing so an exception cannot crash the calling process. - Respect the kill switch at the top — it is the master off-switch. --- 2. LIBRARIES (developer choice, but suggested) - solders plus solana-py (official-ecosystem Solana Python libraries) for keypair loading, transaction signing, RPC submission. - requests or httpx for Jupiter API calls. - psycopg2 for DB (already used project-wide). Jupiter Swap API reference: station.jup.ag docs, apis swap-api section (quote endpoint plus swap endpoint that returns a serialized transaction to sign). --- 3. CONFIG CONSTANTS (top of module) POSITION_USD equals 30 (fixed position size in USD) MAX_CONCURRENT equals 1 (only one live position at a time) HOLD_SECONDS equals 12 (scalp hold window) GATE_LP_FLOOR_USD equals 10000 GATE_MC_FLOOR_USD equals 12000 SLIPPAGE_BPS equals 1500 (15 percent — tune for memecoin thinness) GAS_RESERVE_SOL equals 0.01 (always keep this free for fees) KEYPAIR_PATH equals the path HOME/.config/solana/bot_wallet.json RPC_URL equals owner provides a paid mainnet RPC --- 4. HOW TO TEST (REQUIRED before touching the real bot wallet) The developer must demonstrate the module working on a THROWAWAY test wallet funded with about 5 USD, NOT the owner real bot wallet. Steps: 1. Generate a separate throwaway keypair, fund with about 5 USD of SOL. 2. Point KEYPAIR_PATH at the throwaway. 3. Run a single real 1 to 2 USD round-trip on a known liquid token (e.g. a major Solana token, not a memecoin) and show: buy confirmed on-chain, hold, sell confirmed on-chain, profit and loss recorded, transaction signatures verifiable on solscan.io. 4. Demonstrate the kill switch blocks a trade when engaged. 5. Demonstrate the gate blocks a sub-threshold token. Only AFTER all five pass on the throwaway wallet does the owner switch KEYPAIR_PATH to the real bot wallet — a change the OWNER makes, not the dev. --- 5. WHAT THE DEVELOPER DOES NOT GET AND DOES NOT DO - Does NOT receive the owner real bot-wallet key file or seed phrase. - Does NOT receive server SSH access to the production wallet (develop on a throwaway environment; owner integrates the final reviewed file). - Does NOT build the signal source, strategy, dashboard, or anything else — ONLY live/live_executor.py per this spec. - Does NOT add any code that transmits keys, balances, or data off-server. The owner will review the final code (especially key handling), run it on the throwaway wallet first, and only then deploy with the real wallet behind the kill switch. --- 6. INTEGRATION POINT (for the owner, after the module is delivered and reviewed) The existing alphai_fire.py already computes the mint, and liquidity and MC are available at signal time. After review plus throwaway testing, the owner adds a single guarded call where live trading should occur: import live_executor from the live package and call execute_live_trade with the mint, lp_usd, and mc_usd. This stays behind the kill switch (default: KILLED). Paper trading continues in parallel for fill comparison. --- End of spec. This module is the ONLY missing piece. Everything else — signal, paper engine, kill switch, gate, slippage measurement, accounting, the funded bot wallet — already exists and works.