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
// fund, provider, usage, ask: an agent's wallet pays for the model calls.
//
// three-ws fund --amount 5 --agent <id> top up credits from the agent wallet;
// the first fund also mints an inference
// key bound to that agent
// three-ws provider use three-ws point this machine's clients at three.ws
// three-ws provider show the active provider
// three-ws usage [--agent <id>] credits, burn rate, days left, top-ups
// three-ws ask "<prompt>" one completion through the active provider
//
// Moving money is two calls on the server: a preview, then an execute that
// needs confirm_deposit and that preview's id. `fund` prints the preview as a
// table (recipient, amount, token, chain, credits) and waits for an explicit
// yes. --yes answers yes for scripts after the table is printed; without a TTY
// and without --yes it refuses, so nothing ever moves unseen.
import { existsSync } from 'node:fs';
import * as p from '@clack/prompts';
import { answer, canPrompt } from './common.js';
import { c, line, rows, sym, printJson, tildify } from '../ui.js';
import { requestJson, ApiError } from '../http.js';
import { bearerFor } from '../oauth.js';
import { readStore, updateStore } from '../store.js';
import {
readProvider,
writeProvider,
threeWsProvider,
writeHermesModel,
hermesConfigPath,
providerPath,
complete,
THREE_WS_PROVIDER,
} from '../provider.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;
const PENDING_POLL_MS = 5_000;
const PENDING_POLL_MAX = 12;
async function authed(ctx) {
const bearer = await bearerFor(ctx.env, { origin: ctx.origin });
if (!bearer) throw new ApiError('sign in first: `npx three-ws login --financial` (funding needs the wallet:write scope)');
return bearer;
}
function api(ctx, bearer, pathname, opts = {}) {
return requestJson(`${ctx.origin}${pathname}`, {
timeoutMs: 90_000,
...opts,
headers: { authorization: `Bearer ${bearer}`, ...(opts.headers || {}) },
});
}
function sleep(ms) {
return new Promise((r) => setTimeout(r, ms));
}
/** The confirmation table every fund-moving path shows before the yes. */
export function previewRows(preview) {
return [
['Agent', `${preview.agent?.name || ''} ${c.dim(preview.agent?.id || '')}`.trim()],
['From', `${preview.from} ${c.dim('(agent wallet)')}`],
['To', `${preview.to} ${c.dim(`(${preview.to_label})`)}`],
['Amount', `${preview.amount_usdc} ${preview.token}`],
['Chain', `Solana ${preview.network}`],
['Credits', `+$${Number(preview.credits_usd).toFixed(2)} at ${preview.rate} credit per USDC, no fee`],
['Network fee', preview.network_fee],
['After', `$${Number(preview.balance_after_usd).toFixed(2)} credits, ${preview.wallet_usdc_after} USDC left in the wallet`],
['Expires', new Date(preview.expires_at).toLocaleTimeString()],
];
}
async function confirmMove(ctx, preview) {
if (!ctx.flags.json) {
line(c.bold('Review this on-chain transfer:'));
rows(previewRows(preview), ' ');
line();
}
if (ctx.flags.yes) return true;
if (!canPrompt(ctx)) {
throw new ApiError('refusing to move funds without a confirmation. Review the preview above and rerun with --yes to approve it.');
}
return answer(await p.confirm({ message: `Move ${preview.amount_usdc} USDC from the agent wallet now?`, initialValue: false }));
}
/** Execute a preview, then follow a pending settlement until it resolves. */
async function executeAndSettle(ctx, bearer, pathname, body) {
let result = await api(ctx, bearer, pathname, { method: 'POST', json: body });
for (let i = 0; result?.status === 'pending' && i < PENDING_POLL_MAX; i++) {
if (!ctx.flags.json) line(c.dim(` Broadcast ${result.signature || ''}; waiting for Solana to confirm…`));
await sleep(PENDING_POLL_MS);
result = await api(ctx, bearer, pathname, { method: 'POST', json: body });
}
return result;
}
export async function fund(ctx) {
const amount = Number(ctx.flags.amount);
const agentId = String(ctx.flags.agent || '');
if (!(amount > 0)) throw new ApiError('usage: three-ws fund --amount <usdc> --agent <agent-id>');
if (!UUID_RE.test(agentId)) throw new ApiError('--agent must be one of your agent ids (see https://three.ws/my-agents)');
const bearer = await authed(ctx);
const store = readStore(ctx.env);
const existing = store.inference?.key && store.inference.agent_id === agentId ? store.inference : null;
// A key for this agent already exists: a plain credit top-up. Otherwise the
// provision flow tops up AND mints the key in one confirmed move.
const previewPath = existing ? `/api/agents/${agentId}/credits/topup/preview` : '/api/me/inference/provision/preview';
const executePath = existing ? `/api/agents/${agentId}/credits/topup` : '/api/me/inference/provision';
const preview = await api(ctx, bearer, previewPath, {
method: 'POST',
json: existing ? { amount_usdc: amount } : { agent_id: agentId, amount_usdc: amount },
});
const yes = await confirmMove(ctx, preview);
if (!yes) {
if (ctx.flags.json) printJson({ confirmed: false, preview });
else line('Nothing moved.');
return 1;
}
const result = await executeAndSettle(ctx, bearer, executePath, {
preview_id: preview.preview_id,
confirm_deposit: true,
...(existing ? {} : { name: typeof ctx.flags.name === 'string' ? ctx.flags.name : undefined }),
});
if (result.status === 'pending') {
if (ctx.flags.json) printJson(result);
else line(`${c.yellow(sym.warn)} Still confirming (${result.signature}). Run \`three-ws usage\` in a minute; the credits land as soon as Solana confirms.`);
return 3;
}
if (result.key?.token) {
updateStore((s) => {
s.inference = {
key: result.key.token,
prefix: result.key.prefix,
key_id: result.key.id,
agent_id: agentId,
base_url: result.key.base_url,
created_at: new Date().toISOString(),
};
return s;
}, ctx.env);
}
if (ctx.flags.json) {
printJson({ ...result, key: result.key ? { ...result.key, token: result.key.token ? `${result.key.prefix}…` : null } : undefined });
return 0;
}
line(`${c.green(sym.ok)} Added $${Number(result.credits_usd).toFixed(2)} of credits from ${result.amount_usdc} USDC.`);
if (result.signature) line(c.dim(` ${result.explorer_url}`));
if (result.key?.token) {
line(`${c.green(sym.ok)} Minted inference key ${result.key.prefix}… bound to this agent, stored in your credentials.`);
line(c.dim(' Next: `three-ws provider use three-ws` to point your clients at it.'));
} else if (result.key && !result.key.token) {
line(c.yellow(result.note || 'This top-up already minted its key earlier.'));
}
return 0;
}
export async function provider(ctx) {
const [sub, name] = ctx.positionals;
if (sub === 'show' || !sub) return showProvider(ctx);
if (sub !== 'use') throw new ApiError('usage: three-ws provider use three-ws | three-ws provider show');
if (name !== THREE_WS_PROVIDER.id) {
throw new ApiError(`unknown provider "${name || ''}". Supported: ${THREE_WS_PROVIDER.id}.`);
}
const store = readStore(ctx.env);
const key = typeof ctx.flags.key === 'string' && ctx.flags.key ? ctx.flags.key : store.inference?.key;
if (!key) {
throw new ApiError('no inference key yet. Fund one from an agent wallet: `three-ws fund --amount 5 --agent <id>` (or pass --key sk_live_... with the inference scope).');
}
const record = threeWsProvider({ origin: ctx.origin, key, agentId: store.inference?.agent_id || null });
const written = [writeProvider(record, ctx.env)];
const wanted = String(ctx.flags.clients || '').split(',').map((s) => s.trim()).filter(Boolean);
// A Hermes-style agent on this machine gets its model block pointed at
// three.ws too; --clients hermes forces it, --clients with anything else skips it.
const hermesPresent = existsSync(hermesConfigPath(ctx.env));
if (wanted.includes('hermes') || (hermesPresent && !wanted.length)) written.push(writeHermesModel(record, ctx.env));
if (ctx.flags.json) {
printJson({ provider: record.provider, base_url: record.base_url, model: record.model, key: `${key.slice(0, 12)}…`, written });
return 0;
}
line(`${c.green(sym.ok)} Model provider is now ${c.bold('three.ws')} (${record.model}), billed to your credits.`);
for (const f of written) line(c.dim(` wrote ${tildify(f)}`));
line(c.dim(' `three-ws ask` and anything reading provider.json switch on the next call. For any other OpenAI client:'));
line(` export OPENAI_BASE_URL=${record.base_url}`);
line(` export OPENAI_API_KEY=${key.slice(0, 12)}… ${c.dim('(the full key is in the file above)')}`);
return 0;
}
function showProvider(ctx) {
const prov = readProvider(ctx.env);
if (ctx.flags.json) {
printJson(prov ? { ...prov, api_key: `${prov.api_key.slice(0, 12)}…`, file: providerPath(ctx.env) } : { provider: null });
return prov ? 0 : 1;
}
if (!prov) {
line('No model provider configured. Run `three-ws provider use three-ws`.');
return 1;
}
rows([
['Provider', prov.provider],
['Base URL', prov.base_url],
['Model', prov.model],
['Key', `${prov.api_key.slice(0, 12)}…`],
['Agent', prov.agent_id || c.dim('none (account budget only)')],
['File', tildify(providerPath(ctx.env))],
]);
return 0;
}
export async function usage(ctx) {
const store = readStore(ctx.env);
const bearer = (await bearerFor(ctx.env, { origin: ctx.origin })) || store.inference?.key;
if (!bearer) throw new ApiError('sign in first: `npx three-ws login`');
const agent = ctx.flags.agent ? `?agent_id=${encodeURIComponent(ctx.flags.agent)}` : '';
const u = await api(ctx, bearer, `/api/me/usage${agent}`);
if (ctx.flags.json) {
printJson(u);
return 0;
}
const pairs = [
['Credits', `$${u.balance_usd.toFixed(4)}`],
['Burn rate', `$${u.burn_rate_usd_per_day.toFixed(4)} a day (7-day average)`],
['Days left', u.days_remaining != null ? String(u.days_remaining) : c.dim('no recent usage')],
['This month', `${u.inference_month.calls} calls, ${u.inference_month.input_tokens + u.inference_month.output_tokens} tokens, $${u.inference_month.spent_usd.toFixed(4)}`],
];
if (u.agent) {
const b = u.agent.budget;
pairs.push(['Agent', `${u.agent.name || u.agent.id}`]);
pairs.push(['Budget', b ? `${b.daily_usd != null ? `$${b.daily_usd}/day` : 'no daily cap'}, ${b.monthly_usd != null ? `$${b.monthly_usd}/month` : 'no monthly cap'}` : c.dim('none')]);
pairs.push(['Spent', `$${u.agent.spend.today_usd.toFixed(4)} today, $${u.agent.spend.month_usd.toFixed(4)} this month`]);
if (u.agent.exhausted) pairs.push(['Status', c.red(`${u.agent.exhausted.window} budget used, resets ${new Date(u.agent.exhausted.resets_at).toLocaleString()}`)]);
}
rows(pairs);
if (u.topups.length) {
line();
line(c.bold('Recent top-ups'));
for (const t of u.topups.slice(0, 5)) {
line(` ${t.status.padEnd(8)} ${String(t.amount_usdc).padStart(8)} USDC ${t.signature ? c.dim(t.explorer_url) : ''}`);
}
}
return 0;
}
export async function ask(ctx) {
const prompt = ctx.positionals.join(' ').trim();
if (!prompt) throw new ApiError('usage: three-ws ask "<prompt>"');
const out = await complete({
messages: [{ role: 'user', content: prompt }],
env: ctx.env,
onDelta: ctx.flags.json ? undefined : (d) => process.stdout.write(d),
});
if (ctx.flags.json) {
printJson(out);
return 0;
}
if (!out.content) line(c.yellow('(the model finished without any text; nothing to show)'));
else process.stdout.write('\n');
if (out.billing) {
line(c.dim(` ${out.usage?.total_tokens ?? '?'} tokens, charged $${Number(out.billing.charged_usd).toFixed(6)}, $${Number(out.billing.balance_usd).toFixed(4)} credits left`));
}
return 0;
}