Superior Trade Lighter

Create a Lighter CCTP deposit via POST /v3/portfolio/lighter/deposit. The endpoint mints an intent for the authenticated Superior-managed wallet and moves the exact amount FROM THAT SAME WALLET — the Superior wallet must already hold the USDC on source_chain; external funds enter the Superior wallet first. The intent address in the response is internal plumbing, never an external payment target. The body carries "confirmed": true as a platform constant (vendor-required on money calls); the Steward confirmation gate lives in the playbook. owner_address is the Superior-managed Privy wallet CREDITED on Lighter and also the funding source. source_chain: arbitrum, base, or avalanche. amount: native USDC decimal string, minimum 5, up to 6 decimals. idempotency_key (min 8 chars) is sent as the Idempotency-Key REQUEST HEADER by the platform wrapper — generate it once per deposit attempt and REUSE the SAME key when retrying that same attempt; a new key means a new deposit. Only ONE active deposit per Lighter account (409 if one is pending). 201 = intent created and transfer submitted; 202 = ambiguous, poll SuperiorTrade_GetLighterDeposit about every 30 seconds (30-minute budget) without resubmitting. Errors: 400 (validation/precision), 404 (feature disabled), 409 (active deposit / key reuse with different input), 502.

READ. Returns available balance and collateral. Pre-deposit accounts return zero with a needs_deposit indication — that is a state, not an error. Always check before orders, deployment starts, or withdrawals. Tool-specific errors: 404 (feature disabled / not owned). Input: owner_address (Superior-managed Privy owner wallet). Output: {available:"0", collateral:"0", needs_deposit:true, ...}. Zero balances plus needs_deposit on a pre-deposit account is a PASS state — present it as "not funded yet", never as a failure.

READ-only — reconciles the persisted record against chain state but NEVER submits funds. The polling surface after CreateLighterDeposit: poll about every 30 seconds with a 30-minute budget (CCTP is cross-chain). Report persisted state changes honestly; when the first deposit credits, readiness reaches 'account_created' and onboarding can proceed. Tool-specific errors: 404. Input: depositId from CreateLighterDeposit + owner_address (Owned Superior-managed wallet used to authorize access). Output: {deposit_id, status, amount, source_chain, ...}. The persisted status is the truth — report it verbatim, never chain hope.

READ-only — never resubmits. The polling surface after WithdrawFromLighter, and the ONLY correct response to an 'unknown' submit outcome: poll about every 15 seconds with a 15-minute budget and report the persisted state. Never promise arrival before the record confirms it. Tool-specific errors: 404. Input: withdrawalId from WithdrawFromLighter + owner_address (Owned Superior-managed wallet used to authorize access). Output: {withdrawal_id, status, amount, to_address, ...}. The persisted state here is the only truth about an ambiguous withdrawal — report it verbatim.

WRITE (real funds: places one immediate REAL Lighter market order — requires explicit confirmation showing market, side, quote amount, slippage, and wallet, and exactly ONE request per confirmed action). The server loads the stored Lighter API key, signs, and submits. market_id is an integer (0 = ETH perp on mainnet — verify OTHER market ids against live market metadata before use; never guess). side 'buy' or 'sell'. quote_amount is the USDC notional as a decimal string. max_slippage is a string fraction 0-0.5 (default '0.005' = 0.5%). reduce_only default false; price_protection default true. The spec's other action variant, sendTx (pre-signed tx_type/tx_info from a Lighter SDK signer), is deliberately NOT exposed — the Mind has no signer and must never fabricate signed payloads. Pre-checks before any order: readiness 'ready', balance sufficient (SuperiorTrade_GetLighterBalance), amount above venue minimums. On min-size or slippage rejections: re-check market metadata and balance, reconfirm with the Steward, never blind-retry. Tool-specific errors: 400 (validation/min size/slippage shape), 404 (feature disabled / not owned), 502 (venue rejected — report the exact message).

Secure withdrawal to the Superior wallet via POST /v3/portfolio/lighter/withdraw. Funds return ONLY to the Steward's Superior-managed L1 owner wallet — direct external withdrawal is not available on this route and external destinations are rejected; an onward move to an external wallet is a SEPARATE step after arrival. There is NO destination parameter on this tool. The body carries "confirmed": true as a platform constant (vendor-required on money calls). Signed server-side with the stored Lighter key. amount: USDC decimal string, minimum 1, up to 6 decimals. idempotency_key (min 8 chars) maps to the Idempotency-Key request header — same reuse rules as deposits. A 202 response means submitted, replayed, or recorded-with-unknown-outcome: on 'unknown', NEVER resubmit with a new key — poll SuperiorTrade_GetLighterWithdrawal about every 15 seconds (15-minute budget) until the persisted state resolves. Errors: 400 (validation/minimum/precision), 404 (feature disabled / not owned), 409 (key reuse with different input), 502.