Skip to content

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.

11.0 KB
Raw Blame

The Trading Copilot — talk to your wallet

The Trading Copilot is the conversational front door to an agent's self-custodied Solana wallet. You talk to it — by text or by voice — and it answers with real live data (your balance, holdings, open positions, coin safety, smart-money) and prepares guarded trades you confirm. It never signs on its own.

It lives in the Copilot tab of the Agent Wallet hub (/agents/<id>/wallet → Copilot) and is owner-only: only the wallet's owner can open it, because it reads that wallet's positions and can place trades from it.

Think of it as a ChatGPT-style chat that happens to hold a wallet: markdown replies, streamed tokens, tool-use disclosure, copy/regenerate — plus crypto-native data cards and confirm-before-execute trade cards.


What it can do

You say It does
"How's my portfolio?" Reads your live SOL balance, SPL holdings, and open sniper positions, and shows a portfolio card
"Is <mint> safe to buy?" Runs the rug/honeypot firewall and shows a verdict card (allow / warn / block) with reasons, including a warning when one of the coin's earliest buyers is linked to its creator
"Is smart money in <mint>?" Counts reputable wallets and scores smart-money conviction
"Buy 0.25 SOL of <mint>" Surfaces a buy card — fresh quote + firewall verdict — that you confirm
"Sell 50% of <mint>" Surfaces a sell card grounded on your actual held balance
"Cap my trades at 0.5 SOL" / "Pause trading" Surfaces a risk-limits card (per-trade cap, daily budget, max impact, kill switch)

Every read is instant and free — the copilot calls the tool immediately instead of asking permission. Every trade or limit change comes back as a card you explicitly confirm.

Slash commands

Type / in the composer to open the command palette:

Command Action
/portfolio Show live balance, holdings & positions
/limits Read your current risk guardrails
/safety <mint> Run the firewall on a mint
/buy 0.2 <mint> Start a buy proposal
/sell 50% <mint> Start a sell proposal
/clear Clear the conversation
/help List what the copilot can do

Arrow keys move through the menu, Enter/Tab selects, Esc closes.

Chat conveniences

  • Markdown replies — bold, lists, and links render inline (via src/md.js).
  • Live data cards — grounded numbers appear as cards under a "Looked at N sources" disclosure, so the narration stays short (and voice-friendly) while the figures are always visible and exact.
  • Copy / Regenerate — hover any reply to copy it or re-run the last turn.
  • Stop — the send button becomes a stop button while a reply streams.
  • Voice: 🎙 dictates your message (browser SpeechRecognition); 🔊 speaks replies in the agent's configured voice (ElevenLabs, with a browser-speech fallback). The request names the agent, so an owner-cloned voice on the owner's saved ElevenLabs key plays here too instead of silently degrading to browser speech.
  • Persistence — the conversation, its data cards, and the executed-action log are saved per wallet + network in localStorage and restored when you return. Live trade proposals are intentionally not persisted, so a reload never resurrects a confirmable card grounded on a stale quote.
  • One thread across chats: every finished web turn is also appended to the agent's cross-channel thread (channel web), the same thread the paired Telegram, Discord, and other chat gateways (api/_lib/gateway/) read and write. Each time the tab is opened or shown again it pulls what was said in those chats since it last looked and shows those messages tagged "via Telegram", "via Discord", and so on.

How safety is enforced

The model is read-and-propose only. It cannot sign, and it cannot bypass a guard:

  1. Read-only tools (get_portfolio, get_coin_intel, get_smart_money, assess_safety, get_quote, get_trade_limits) run server-side and feed grounded numbers back into the conversation. The model can never invent a balance, price, or safety verdict.
  2. Any state-changing intent (buy / sell / risk-limits) is returned to the browser as a structured proposal, never executed on the server.
  3. The browser re-quotes it live and, only on your confirmation, calls the existing guarded endpoints:
    • POST /api/agents/:id/solana/trade: enforces the spend guards (api/_lib/agent-trade-guards.js), the rug/honeypot firewall (api/_lib/trade-firewall.js), and the custody audit (agent_custody_events). The guards fail closed: a caller that passes neither pre-read limits nor the agent's meta gets the policy read from the agent's own row (a deleted agent has no policy and its spend is refused), and the ledger also meters a per_counterparty_daily_usd ceiling on what one agent can send to a single destination per day. The copilot's risk-limits card edits the per-trade cap, daily budget, max price impact, and kill switch; the counterparty cap is set from the wallet hub. The capped-burner tier (api/_lib/burner-tier.js) bounds what the agent may sign alone: above the owner's cap a spend becomes a pending approval (policy_step_up), not a failure. A trade you confirm in the copilot is your own action, so it is exempt from the burner cap (burnerExempt); the per-trade, daily, firewall and kill-switch guards still apply.
    • PUT /api/agents/:id/trade/limits — patches guardrails by key.

A conversation can therefore never bypass a spend cap, the kill switch, or the firewall. If the firewall verdict is block, the buy card cannot be confirmed at all.

The endpoint

POST /api/agents/:id/copilot          Owner-only. Body: { messages:[{role,content}], network, model?, paid_fallback? }
                                      → text/event-stream
GET  /api/agents/:id/copilot?after=<message id>&limit=<1-100>
                                      Owner-only. → { messages:[{id,role,content,channel,signatures,createdAt}], latest_id }

POST keeps the last 24 user and assistant turns, each cut to 4000 characters, and refuses a request whose final message is not from the user (422 no_message). GET returns the agent's cross-channel thread oldest first (30 messages by default), so a client can merge what the owner said in a paired chat; pass the returned latest_id as after next time to fetch only newer messages.

model overrides the agent's default model for this one message. The brain is resolved in one place, api/_lib/agent-brain.js (on top of api/_lib/agent-model.js), so the copilot, the chat gateways and the agent message API all honor an agent's chosen model, including a Grok brain that runs on the owner's saved xAI key when they have one. Because the copilot is a tool loop, an override without tool calling is refused (400 model_lacks_tools), as is an unknown id (400 unknown_model); an agent default without tool calling is skipped and the turn runs on the platform chain instead. A free open model draws on the owner's daily free-tier allowance and answers 429 free_tier_exhausted with a Retry-After header once it is spent; the error body carries a paid route, and resending with paid_fallback: true skips the free tier, gates on the owner's credits, and bills each model round to them. Every model round is metered to the owner's usage ledger at the price of the lane that served it (free lanes cost nothing).

SSE events:

Event Payload Meaning
model { model, source, served?, lane?, chosen?, keySource?, failover? } the model chosen for the turn; re-sent each round with the model and provider lane that actually answered, the key source behind it, and whether a failover rung served instead of the chosen brain
status { phase } thinking / continuing / finalizing
tool { name, summary, data } a read-only tool ran; data is the card payload
proposal trade/limits proposal a confirm-before-execute card
chunk { text } streamed narration tokens
done { reply, proposals, citations } final reply
error { code, message } turn failed

With no model override, the provider chain is free-first and OpenAI-compatible, shared with the built-in chat agent loop in api/_lib/llm-tool-chain.js: Groq → Cerebras → OpenRouter (including any OPENROUTER_FALLBACK_KEYS) → NVIDIA → SambaNova → Mistral → Z.ai → Gemini (API key), with paid OpenAI as the backstop, each rung present only when its key is set, so the copilot works without any paid key. Whenever the GCP project is configured, a keyless, credits-billed Vertex Gemini rung is appended unconditionally as the final anchor, so the chain always ends on a provider that cannot be evicted by a dead key. A named model's own lanes are tried first and the platform chain follows behind them. With no rung configured at all, the request is 503 llm_unavailable before the stream opens. Each round has a 45s deadline and fails over to the next rung on any transport or non-2xx error. A 15s heartbeat keeps the stream alive across slow tool rounds; the client aborts a genuinely dead stream and offers Retry rather than hanging.

$THREE

$THREE (FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump) is the only coin three.ws promotes. The copilot trades whatever mint the owner names at runtime — coin-agnostic plumbing — and never suggests, shills, or names another token on its own initiative.


Code map

Piece Location
Client mount (chat UI, cards, slash, persistence, voice) src/agent-copilot.js
Wallet-hub tab wrapper src/agent-wallet-hub/tabs/copilot.js
Server route (auth, model choice, SSE, thread read) api/agents/copilot.js
Copilot engine (tools, prompt, loop; shared with the chat gateways) api/_lib/copilot-engine.js
Cross-channel thread store api/_lib/agent-thread.js
Brain resolution and served-lane badge api/_lib/agent-brain.js
Provider chain + streamed tool-call reader (shared with the chat agent loop) api/_lib/llm-tool-chain.js
Markdown renderer src/md.js
UI contract tests tests/agent-copilot-ui.test.js

Related