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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* Wallet Intents API — owner-only control surface for the programmable,
* conversational money layer. Routed from api/agents/[id].js as
* /api/agents/:id/intents.
*
* GET /api/agents/:id/intents → the owner's intents + live summary
* POST /api/agents/:id/intents/compile → plain-language rule → validated structured intent (preview; never arms)
* POST /api/agents/:id/intents → arm a validated intent (real)
* POST /api/agents/:id/intents/run → owner "test this rule now" (dry-run or real) { intent_id, dry_run }
* POST /api/agents/:id/intents/copilot → conversational "how am I doing?" over real holdings + custody P&L
* PUT /api/agents/:id/intents/:intentId → enable / disable / edit / publish
* DELETE /api/agents/:id/intents/:intentId → remove
*
* Every write is owner-only (server-side) and CSRF-protected. Executing paths act
* ONLY on the agent's own wallet, are clamped to the agent's spend policy at
* execution time, and write an audited custody event stamped with the intent_id.
* A visitor (or logged-out caller) can never read, create, arm, or fire an intent.
*/
import { cors, json, method, error, readJson, rateLimited, serverError } from '../_lib/http.js';
import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.js';
import { assertBearerMaySpend } from '../_lib/spend-scope.js';
import { limits } from '../_lib/rate-limit.js';
import { requireCsrf } from '../_lib/csrf.js';
import { requireRealFundsAgreement } from '../_lib/real-funds-agreement.js';
import { OPENROUTER_ATTRIBUTION_HEADERS } from '../_lib/openrouter-attribution.js';
import { sql } from '../_lib/db.js';
import { loadUserProviderKeys } from '../_lib/provider-keys.js';
import { getSpendLimits, getTradeLimits } from '../_lib/agent-trade-guards.js';
import { getSolanaAddressBalances } from '../_lib/agent-wallet.js';
import { getBalances } from '../_lib/balances.js';
import { solUsdPrice } from '../_lib/avatar-wallet.js';
import {
listIntents,
getIntent,
createIntent,
updateIntent,
deleteIntent,
runIntentNow,
compileIntentFromText,
normalizeIntent,
describeIntent,
} from '../_lib/wallet-intents.js';
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
async function resolveAuth(req) {
const session = await getSessionUser(req);
if (session) return { userId: session.id };
const bearer = assertBearerMaySpend(await authenticateBearer(extractBearer(req)), req, { kind: 'trade' });
if (bearer) return { userId: bearer.userId };
return null;
}
async function loadOwned(req, res, id) {
const auth = await resolveAuth(req);
if (!auth) {
error(res, 401, 'unauthorized', 'sign in to manage this agent’s wallet intents');
return { error: true };
}
const [row] = await sql`SELECT id, user_id, name, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) { error(res, 404, 'not_found', 'agent not found'); return { error: true }; }
if (row.user_id !== auth.userId) { error(res, 403, 'forbidden', 'only the owner can manage wallet intents'); return { error: true }; }
return { auth, row, meta: { ...(row.meta || {}) } };
}
function netOf(req) {
const url = new URL(req.url, 'http://x');
return url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
}
// readJson resolves whatever valid JSON the caller sent, which includes `null`,
// a bare string, and a number. Every handler below then reads a property off it
// (`body.text`, `body.intent`, `'enabled' in body`), which throws a TypeError on
// a non-object and surfaces as a 500 for what is really malformed input. Funnel
// the body through here so a scalar degrades to an empty object and the
// handler's own validation returns its normal 400.
async function readJsonObject(req, res) {
let body;
try {
body = await readJson(req);
} catch (e) {
error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
return null;
}
return body && typeof body === 'object' && !Array.isArray(body) ? body : {};
}
export default async function handler(req, res, id, action) {
if (cors(req, res, { methods: 'GET,POST,PUT,DELETE,OPTIONS', credentials: true })) return;
if (action === 'compile') return handleCompile(req, res, id);
if (action === 'run') return handleRun(req, res, id);
if (action === 'copilot') return handleCopilot(req, res, id);
if (action && UUID_RE.test(action)) {
if (req.method === 'PUT') return handleUpdate(req, res, id, action);
if (req.method === 'DELETE') return handleDelete(req, res, id, action);
if (req.method === 'GET') return handleGetOne(req, res, id, action);
return error(res, 405, 'method_not_allowed', 'use PUT, DELETE, or GET on an intent');
}
if (action) return error(res, 404, 'not_found', 'unknown intents sub-resource');
if (req.method === 'GET') return handleList(req, res, id);
if (req.method === 'POST') return handleCreate(req, res, id);
return method(req, res, ['GET', 'POST']) ? error(res, 405, 'method_not_allowed', 'use GET or POST') : undefined;
}
// GET — the owner's intents + a live summary (balance, today's & lifetime impact).
async function handleList(req, res, id) {
const owned = await loadOwned(req, res, id);
if (owned.error) return;
const rl = await limits.walletRead(owned.auth.userId);
if (!rl.success) return rateLimited(res, rl);
const network = netOf(req);
const intents = await listIntents(id);
const spendLimits = getSpendLimits(owned.meta);
let balanceSol = null;
try { balanceSol = Number((await getSolanaAddressBalances(owned.meta.solana_address, network))?.sol ?? null); }
catch { balanceSol = null; }
const lifetimeUsd = intents.reduce((a, i) => a + (i.stats?.spent_usd || 0), 0);
const fires = intents.reduce((a, i) => a + (i.stats?.fire_count || 0), 0);
return json(res, 200, {
data: {
intents,
summary: {
count: intents.length,
enabled: intents.filter((i) => i.enabled).length,
lifetime_usd: lifetimeUsd,
lifetime_fires: fires,
balance_sol: balanceSol,
frozen: !!spendLimits.frozen,
spend_limits: { per_tx_usd: spendLimits.per_tx_usd, daily_usd: spendLimits.daily_usd },
},
},
});
}
async function handleGetOne(req, res, id, intentId) {
const owned = await loadOwned(req, res, id);
if (owned.error) return;
// Same meter as the collection read: this is the one owner-scoped read that
// was unmetered, so a loop over intent ids could out-run the list endpoint.
const rl = await limits.walletRead(owned.auth.userId);
if (!rl.success) return rateLimited(res, rl);
const intent = await getIntent(id, intentId);
if (!intent) return error(res, 404, 'not_found', 'intent not found');
return json(res, 200, { data: { intent } });
}
// Shared: the live context the compiler/dry-run needs (balance, holdings, caps).
async function compileContext(req, owned, network) {
let balanceSol = null;
let holdings = [];
try {
const bal = await getSolanaAddressBalances(owned.meta.solana_address, network);
balanceSol = Number(bal?.sol ?? null);
} catch { /* unknown */ }
// The compiler prompt lists the wallet's real tokens so a rule like "sell half
// my $THREE" grounds against something the agent actually holds. This used to
// be declared and never filled, so every compile claimed "Tokens held: none
// detected." even for a funded wallet. Mainnet only: the shared cached
// getBalances path (Helius DAS, then public RPC) indexes mainnet mints.
if (network === 'mainnet' && owned.meta.solana_address) {
try {
const balances = await getBalances({ chain: 'solana', address: owned.meta.solana_address });
holdings = (balances?.tokens || [])
.filter((t) => t.mint && Number(t.amount) > 0)
.map((t) => ({ mint: t.mint, symbol: t.symbol || null, ui_amount: t.amount }));
} catch { /* holdings unavailable, the prompt falls back to "none detected" */ }
}
let userKeys = {};
try {
const [u] = await sql`SELECT provider_keys FROM users WHERE id = ${owned.auth.userId}`;
userKeys = await loadUserProviderKeys(u?.provider_keys);
} catch { userKeys = {}; }
return {
agentName: owned.row.name,
network,
balanceSol,
holdings,
limits: getSpendLimits(owned.meta),
tradeLimits: getTradeLimits(owned.meta),
anthropicKey: userKeys.anthropic,
grokKey: userKeys.grok,
openrouterKey: userKeys.openrouter,
};
}
// POST /compile — plain-language → structured intent. Preview only; never arms.
async function handleCompile(req, res, id) {
if (!method(req, res, ['POST'])) return;
const owned = await loadOwned(req, res, id);
if (owned.error) return;
if (!(await requireCsrf(req, res, owned.auth.userId))) return;
const rl = await limits.chatUser(owned.auth.userId);
if (!rl.success) return rateLimited(res, rl, 'slow down — too many compile requests');
const body = await readJsonObject(req, res);
if (!body) return;
const text = typeof body.text === 'string' ? body.text : '';
if (!text.trim()) return error(res, 400, 'validation_error', 'describe a rule to compile');
const network = netOf(req);
const ctx = await compileContext(req, owned, network);
ctx.history = Array.isArray(body.history) ? body.history : [];
let compiled;
try { compiled = await compileIntentFromText(text, ctx); }
catch (e) { return serverError(res, 500, 'compile_failed', e); }
if (!compiled.ok) {
const status = compiled.error === 'unavailable' ? 503 : compiled.error === 'clarify' ? 200 : 422;
return json(res, status, { data: { ok: false, error: compiled.error, message: compiled.message, clarify: compiled.clarify || null, provider: compiled.provider || null } });
}
// Concrete dry-run preview alongside the compiled intent.
const sim = await simulate(compiled.intent, owned, network).catch(() => null);
return json(res, 200, { data: { ok: true, intent: compiled.intent, readback: describeIntent(compiled.intent), simulation: sim, provider: compiled.provider } });
}
// Build a concrete "on a sample event, this does X; remaining budget Y" preview.
async function simulate(intent, owned, network) {
const a = intent.action;
let balanceSol = null;
try { balanceSol = Number((await getSolanaAddressBalances(owned.meta.solana_address, network))?.sol ?? null); } catch { /* */ }
let price = null;
try { price = await solUsdPrice(); } catch { /* */ }
const lines = [];
if (intent.trigger.type === 'on_tip_received' && a.pct != null) {
const sampleSol = Math.max(intent.trigger.min_sol || 0.2, 0.2);
const back = sampleSol * (a.pct / 100);
lines.push(`On a ${sampleSol} SOL tip, this sends back ${back.toFixed(3)} SOL${a.to_tipper ? ' to the tipper' : ''}.`);
} else if (a.amount_sol != null) {
lines.push(`Each fire moves ${a.amount_sol} SOL${a.destination_label ? ` to ${a.destination_label}` : ''}${price ? ` (~$${(a.amount_sol * price).toFixed(2)})` : ''}.`);
} else if (a.above_sol != null && balanceSol != null) {
const over = Math.max(0, balanceSol - a.above_sol);
lines.push(`At your current ${balanceSol.toFixed(3)} SOL, this would withdraw ${over.toFixed(3)} SOL above the ${a.above_sol} SOL floor.`);
} else if (a.pct != null) {
lines.push(`Each fire moves ${a.pct}% of ${a.of || 'income'}${a.destination_label ? ` to ${a.destination_label}` : ''}.`);
} else if (a.type === 'freeze') {
lines.push(`When balance drops below ${intent.trigger.threshold_sol} SOL, all spending freezes and you're notified.`);
} else if (a.type === 'notify') {
lines.push('This sends you a notification — it never moves funds.');
}
const lim = intent.limits || {};
if (lim.daily_usd != null) lines.push(`Daily budget: $${lim.daily_usd}.`);
if (lim.per_action_usd != null) lines.push(`Per-action cap: $${lim.per_action_usd}.`);
return { balance_sol: balanceSol, lines };
}
// POST / — arm a validated intent. Re-validates server-side; ownership + CSRF gated.
async function handleCreate(req, res, id) {
const owned = await loadOwned(req, res, id);
if (owned.error) return;
const body = await readJsonObject(req, res);
if (!body) return;
if (!body.intent || typeof body.intent !== 'object') return error(res, 400, 'validation_error', 'an intent object is required');
const norm = normalizeIntent(body.intent);
if (!norm.ok) return error(res, 422, norm.error || 'invalid_intent', norm.message || 'the intent could not be validated');
// Arming a rule that can move funds needs the signed real-funds agreements;
// freeze and notify rules never spend. Checked before CSRF so a refusal does
// not burn the owner's single-use token.
const spends = !['freeze', 'notify'].includes(norm.intent.action?.type);
if (spends && !(await requireRealFundsAgreement(req, res, { userId: owned.auth.userId, network: netOf(req), context: 'wallet-intent' }))) return;
if (!(await requireCsrf(req, res, owned.auth.userId))) return;
// Preserve a resolved destination + tip-back flag the compiler already grounded.
if (body.intent.action) {
const src = body.intent.action;
if (src.destination && !norm.intent.action.destination) norm.intent.action.destination = src.destination;
if (src.destination_label) norm.intent.action.destination_label = src.destination_label;
if (src.to_tipper) norm.intent.action.to_tipper = true;
if (src.mint && !norm.intent.action.mint) norm.intent.action.mint = src.mint;
}
const network = netOf(req);
try {
const intent = await createIntent(id, owned.auth.userId, norm.intent, {
network,
sourceText: typeof body.source_text === 'string' ? body.source_text.slice(0, 1000) : null,
publicTrait: body.public_trait === true,
});
return json(res, 201, { data: { intent } });
} catch (e) {
return serverError(res, 500, 'create_failed', e);
}
}
// PUT /:intentId — enable/disable/edit/publish.
async function handleUpdate(req, res, id, intentId) {
const owned = await loadOwned(req, res, id);
if (owned.error) return;
const body = await readJsonObject(req, res);
if (!body) return;
const patch = {};
if ('enabled' in body) patch.enabled = body.enabled === true;
if ('public_trait' in body) patch.public_trait = body.public_trait === true;
if ('title' in body) patch.title = body.title;
if ('intent' in body) patch.intent = body.intent;
// Enabling a rule or rewriting what it does re-arms autonomous spending.
// Disabling, renaming, and publishing never need the agreement.
const rearms = patch.enabled === true || 'intent' in patch;
if (rearms && !(await requireRealFundsAgreement(req, res, { userId: owned.auth.userId, network: netOf(req), context: 'wallet-intent' }))) return;
if (!(await requireCsrf(req, res, owned.auth.userId))) return;
try {
const result = await updateIntent(id, owned.auth.userId, intentId, patch);
if (!result) return error(res, 404, 'not_found', 'intent not found');
if (result.error) return error(res, 422, result.error, result.message);
return json(res, 200, { data: { intent: result } });
} catch (e) {
return serverError(res, 500, 'update_failed', e);
}
}
async function handleDelete(req, res, id, intentId) {
const owned = await loadOwned(req, res, id);
if (owned.error) return;
if (!(await requireCsrf(req, res, owned.auth.userId))) return;
try {
const ok = await deleteIntent(id, owned.auth.userId, intentId);
if (!ok) return error(res, 404, 'not_found', 'intent not found');
return json(res, 200, { data: { deleted: true } });
} catch (e) {
return serverError(res, 500, 'delete_failed', e);
}
}
// POST /run — owner "test this rule now" (honors freeze, spend policy, caps).
async function handleRun(req, res, id) {
if (!method(req, res, ['POST'])) return;
const owned = await loadOwned(req, res, id);
if (owned.error) return;
const rl = await limits.walletRead(owned.auth.userId);
if (!rl.success) return rateLimited(res, rl);
let body = {};
try {
const raw = await readJson(req);
if (raw && typeof raw === 'object' && !Array.isArray(raw)) body = raw;
} catch { body = {}; }
const intentId = String(body.intent_id || '');
if (!UUID_RE.test(intentId)) return error(res, 400, 'validation_error', 'intent_id is required');
const dryRun = body.dry_run !== false; // default to a safe simulation
if (!dryRun && !(await requireRealFundsAgreement(req, res, { userId: owned.auth.userId, network: netOf(req), context: 'wallet-intent' }))) return;
if (!(await requireCsrf(req, res, owned.auth.userId))) return;
try {
const result = await runIntentNow({ agentId: id, userId: owned.auth.userId, intentId, network: netOf(req), dryRun });
return json(res, 200, { data: result });
} catch (e) {
return serverError(res, 500, 'run_failed', e);
}
}
// POST /copilot — conversational "how am I doing?" over REAL holdings + custody P&L.
// Funds never move here; the copilot only reads + explains. Owner-only.
async function handleCopilot(req, res, id) {
if (!method(req, res, ['POST'])) return;
const owned = await loadOwned(req, res, id);
if (owned.error) return;
if (!(await requireCsrf(req, res, owned.auth.userId))) return;
const rl = await limits.chatUser(owned.auth.userId);
if (!rl.success) return rateLimited(res, rl, 'slow down');
const body = await readJsonObject(req, res);
if (!body) return;
const message = typeof body.message === 'string' ? body.message.trim().slice(0, 500) : '';
if (!message) return error(res, 400, 'validation_error', 'ask a question');
const network = netOf(req);
// Real numbers first — the copilot never guesses a balance or a P&L.
let balanceSol = null;
try { balanceSol = Number((await getSolanaAddressBalances(owned.meta.solana_address, network))?.sol ?? null); } catch { /* */ }
const [agg] = await sql`
SELECT
COALESCE(SUM(usd) FILTER (WHERE event_type = 'tip'), 0)::float8 AS tip_usd,
COALESCE(SUM(usd) FILTER (WHERE event_type = 'spend'), 0)::float8 AS spend_usd,
COUNT(*) FILTER (WHERE meta->>'intent_id' IS NOT NULL) AS intent_events
FROM agent_custody_events
WHERE agent_id = ${id} AND network = ${network} AND created_at > now() - interval '30 days'
`;
const intents = await listIntents(id);
const facts = {
balance_sol: balanceSol,
tips_30d_usd: Number(agg?.tip_usd || 0),
spend_30d_usd: Number(agg?.spend_usd || 0),
net_30d_usd: Number(agg?.tip_usd || 0) - Number(agg?.spend_usd || 0),
active_intents: intents.filter((i) => i.enabled).length,
intent_fires: intents.reduce((a, i) => a + (i.stats?.fire_count || 0), 0),
intent_moved_usd: intents.reduce((a, i) => a + (i.stats?.spent_usd || 0), 0),
};
const factual = `Balance: ${facts.balance_sol == null ? 'unknown' : facts.balance_sol.toFixed(3) + ' SOL'}. ` +
`Last 30 days — tips in: $${facts.tips_30d_usd.toFixed(2)}, spend out: $${facts.spend_30d_usd.toFixed(2)}, net: ${facts.net_30d_usd >= 0 ? '+' : ''}$${facts.net_30d_usd.toFixed(2)}. ` +
`${facts.active_intents} active rule${facts.active_intents === 1 ? '' : 's'} have fired ${facts.intent_fires} time${facts.intent_fires === 1 ? '' : 's'}, moving $${facts.intent_moved_usd.toFixed(2)}.`;
// Phrase it in-character if an LLM is available; otherwise return the real facts.
let reply = factual;
let provider = 'facts';
try {
let userKeys = {};
try { const [u] = await sql`SELECT provider_keys FROM users WHERE id = ${owned.auth.userId}`; userKeys = await loadUserProviderKeys(u?.provider_keys); } catch { /* */ }
const key = userKeys.anthropic || process.env.ANTHROPIC_API_KEY;
const orKey = userKeys.openrouter || process.env.OPENROUTER_API_KEY;
const persona = (owned.row.meta?.persona_prompt || owned.meta.system_prompt || '').toString().slice(0, 600);
const sys = `You are the wallet copilot for "${owned.row.name}", a 3D AI agent on three.ws. Answer the owner's question about their money in 1–3 short sentences, in character${persona ? ` (persona: ${persona})` : ''}. Use ONLY these real facts — never invent numbers: ${factual}`;
if (key) {
const r = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST', headers: { 'x-api-key': key, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
body: JSON.stringify({ model: 'claude-opus-4-8', max_tokens: 300, system: sys, messages: [{ role: 'user', content: message }] }),
signal: AbortSignal.timeout(15_000),
});
if (r.ok) { const j = await r.json(); const t = (j.content || []).find((b) => b.type === 'text')?.text; if (t) { reply = t.trim(); provider = 'anthropic'; } }
} else if (orKey) {
const r = await fetch('https://openrouter.ai/api/v1/chat/completions', {
method: 'POST', headers: { Authorization: `Bearer ${orKey}`, 'content-type': 'application/json', ...OPENROUTER_ATTRIBUTION_HEADERS },
body: JSON.stringify({ model: 'openai/gpt-oss-120b', max_tokens: 300, messages: [{ role: 'system', content: sys }, { role: 'user', content: message }] }),
signal: AbortSignal.timeout(15_000),
});
if (r.ok) { const j = await r.json(); const t = j.choices?.[0]?.message?.content; if (t) { reply = t.trim(); provider = 'openrouter'; } }
}
} catch { /* fall back to facts */ }
return json(res, 200, { data: { reply, facts, provider } });
}