Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Spec — Agent trading capability (Feature B)
Status: proposed · Author: three.ws · Depends on: autopilot v0.2.0 (SOL spend cap + $THREE buy-only guard)
Why
Today an agent's autopilot can create alerts, author briefings, and send native SOL. It cannot trade. The realistic, high-value autonomous behavior users want is buying and selling pump.fun coins in SOL — sniping new launches and acting on alpha — while treating $THREE as buy-only (accumulate/burn, never sell). This spec adds that capability on top of the v0.2.0 foundation.
Principles (inherited from v0.2.0)
- SOL is the spend currency. Every buy is denominated in SOL and counts against the daily SOL cap (
daily_spend_sol). Sells return SOL. - $THREE is a one-way valve. The agent may buy $THREE (SOL → $THREE) and burn it, but a sell of $THREE (or any transfer out of $THREE) is hard-refused server-side — the same guard
validateWalletTransferalready enforces, extended to the swap path. - Runtime mints only. Coins to trade are supplied at runtime (mint address from discovery/intel). Never hardcode, market, or recommend a specific non-$THREE mint in source, copy, or proposals (CLAUDE.md). $THREE remains the only coin the platform promotes.
- Server-side enforcement. Scope, caps, slippage bounds, and the $THREE-sell ban live in
api/_lib/autopilot.js/ a new trade guard — the MCP client cannot bypass them.
New autopilot action kind: trade
Extend AUTOPILOT_ACTION_KINDS with trade and ACTION_TYPE.trade = 'autopilot.trade.executed'.
Params (validated by a new validateTrade):
{
side: "buy" | "sell",
mint: "<solana mint>", // the coin to trade; "three"/$THREE allowed for side:"buy" ONLY
amount_sol?: number, // required for buy — SOL to spend (counts against daily cap)
amount_tokens?: number | "all", // required for sell — token units (or all) to sell back to SOL
max_slippage_bps?: number, // default 100 (1%), hard ceiling e.g. 500
reason: string
}
Guards (all server-side, deny — never partial-execute):
side:"sell"withmint === $THREE(or the CA) → refused (code: 'three_sell_forbidden'). This is the buy-only valve.side:"buy":amount_sol > 0,spent_24h + amount_sol ≤ daily_spend_sol, scopetradegranted,confirm:true(reuse the irreversible-confirmation policy).side:"sell": agent must hold the position; slippage withinmax_slippage_bps.- Reuse
dailySolSpentfor buys; sells do not add to the spend tally (they return SOL).
Execution path
Reuse existing building blocks — do not add a new swap implementation if one is reusable:
- Quote:
@three-ws/pumpfun-mcpalready exposespumpfun_quote_swap/quote_swap; the backend equivalent should quote via the same Jupiter/pump.fun route. - Buy: pattern already proven in
avatar-agent-mcp(pump_buy) and the agent custodial wallet path (recoverSolanaAgentKeypair,submitProtected). - Settle: bundle/submit via the same protected-send path used by
transferNativeSol. - Record: write a signed
agent_actionsrow (autopilot.trade.executed) with provenance, mint, side, amounts, signature, realized SOL — same receipt discipline aswallet_transfer.
MCP surface
Two options — recommended: a dedicated @three-ws/trading-mcp rather than overloading autopilot, because trading has its own discovery + quote + position surface:
quote_trade(read) — price + expected out + slippage for a prospective buy/sell.list_positions(read) — open positions with cost basis + unrealized PnL (reuseportfolio-mcpdata).execute_trade(write · destructive) — buy/sell in SOL;confirm:true; $THREE-sell refused.- Autopilot integration:
generate_proposalsmay emittradeproposals (grounded inintel-mcpsmart-money / signal memories); they flow through the existing dryrun → confirm → execute → signed-receipt loop.
portfolio-mcp's send_transfer already lazy-loads @solana/spl-token; the trading server should follow the same lazy-import discipline to avoid the ESM load crash.
Discovery → decision (where alpha comes from)
Trading proposals should cite real signals, never guess:
intel-mcp— smart-money score, KOL trades, signal-feed accuracy.pumpfun-mcp— new/trending/graduating tokens, bonding-curve + holder analysis.- Alert fires (
alerts-mcp) → a candidatetradeproposal the owner reviews.
Risk & limits
- Per-trade cap + daily SOL cap (existing) + max open positions + slippage ceiling.
- Confirmation: buys/sells are irreversible →
require_confirmapplies, likewallet_transfer. - Trust gating: only agents at
trusted/autonomoustrust may auto-execute reversibly-scoped trades (sells of a held position); buys always confirm. - No $THREE sell, ever — enforced at validate + execute, covered by a test mirroring the v0.2.0
three_sell_forbiddencase.
Phased plan
- Quotes + positions (read-only):
quote_trade,list_positionsover live routes. No funds move. Ship + verify. - Buy (SOL → coin):
execute_trade side:"buy", confirm-gated, daily-cap-bounded, signed receipt. - Sell (coin → SOL):
execute_trade side:"sell"for held positions; $THREE-sell hard-refused. - Autopilot
tradeproposals: generation from intel/signal memories → dryrun → confirm → execute. - Changelog + docs at each phase; publish
@three-ws/trading-mcp(start 0.1.0) and bumpautopilot-mcpwhen thetradekind lands.
Definition of done (per phase)
Real routes (no mocks), server-side guards with tests (including the $THREE-sell refusal), confirm-gated irreversible actions, signed agent_actions receipts, MCP descriptions accurate, changelog entry, and npm run test:mcp green.