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
/**
* AgentClient — programmatic x402 payment support for invoking priced agent skills.
*
* The three.ws x402 flow is intent-based and matches the live API
* (`api/agents/x402/[action].js` + `api/_lib/x402.js`):
*
* 1. `POST /api/agents/x402/invoke` with `{ agent_id, skill, args }`. When the
* skill is priced and the request is unpaid, the server answers **402**
* with a payment manifest body (recipient, amount, currency, `intent_url`,
* `verify_url`, `retry_with_header`).
* 2. The caller settles that manifest's payment intent on-chain — preparing it
* at the manifest's `intent_url` and confirming at `verify_url` — and
* obtains a paid intent id.
* 3. Retry the same POST with header `x-payment-intent: <intentId>`; the server
* verifies the intent and answers **200** with the skill result.
*
* Free / unpriced skills are intentionally NOT served by the x402 endpoint (it
* answers 409 `no_payments`); call those through the regular agent skill API.
*/
/**
* @typedef {object} X402Manifest
* @property {string|number} version
* @property {'agent-skill'} kind
* @property {string} agent_id
* @property {string} skill
* @property {string} amount
* @property {string} currency
* @property {string} recipient
* @property {string} [recipient_name]
* @property {number} valid_until
* @property {string} intent_url
* @property {string} verify_url
* @property {string} retry_with_header
*/
export class PaymentRequiredError extends Error {
/** @param {X402Manifest} manifest */
constructor(manifest) {
super(
`Skill "${manifest?.skill}" requires payment: ${manifest?.amount} ${manifest?.currency}`,
);
this.name = 'PaymentRequiredError';
/** @type {X402Manifest} */
this.manifest = manifest;
}
}
export class AgentClient {
/**
* @param {object} [opts]
* @param {string} [opts.baseUrl] Base URL of the three.ws API (e.g. `https://three.ws`). Defaults to same-origin.
* @param {string} [opts.apiKey] Bearer token with `avatars:read` (or a session) — required to invoke (the endpoint is auth-gated).
* @param {typeof fetch} [opts.fetch] Custom fetch (for SSR / tests). Defaults to the global `fetch`.
*/
constructor({ baseUrl = '', apiKey = '', fetch: fetchImpl } = {}) {
this.baseUrl = baseUrl.replace(/\/$/, '');
this.apiKey = apiKey;
this._fetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch.bind(globalThis) : null);
if (!this._fetch) {
throw new Error(
'AgentClient: no fetch implementation available — pass { fetch } in non-browser runtimes',
);
}
}
/** @param {Record<string,string>} [extra] */
_headers(extra) {
const h = { 'content-type': 'application/json', ...extra };
if (this.apiKey) h.authorization = `Bearer ${this.apiKey}`;
return h;
}
/**
* List prices for every priced skill on an agent.
* `GET /api/agents/:id/pricing` → `{ prices: SkillPrice[] }`.
*
* @param {string} agentId
* @returns {Promise<Array<{skill:string, amount:string, currency_mint?:string, chain?:string}>>}
*/
async getSkillPrices(agentId) {
const res = await this._fetch(
`${this.baseUrl}/api/agents/${encodeURIComponent(agentId)}/pricing`,
);
if (!res.ok) throw new Error(`getSkillPrices failed: ${res.status} ${res.statusText}`);
const body = await res.json();
// The endpoint wraps the list as `{ prices }`; tolerate a bare array too.
return Array.isArray(body) ? body : body?.prices || [];
}
/**
* Fetch the x402 payment manifest for a single skill (discovery / prefetch).
* `GET /api/agents/x402/manifest?agent_id=&skill=`.
*
* @param {string} agentId
* @param {string} skill
* @returns {Promise<X402Manifest | null>} `null` when the skill is free/unpriced (409).
*/
async getManifest(agentId, skill) {
const url =
`${this.baseUrl}/api/agents/x402/manifest` +
`?agent_id=${encodeURIComponent(agentId)}&skill=${encodeURIComponent(skill)}`;
const res = await this._fetch(url);
if (res.status === 409) return null; // not priced → free skill
if (!res.ok) throw new Error(`getManifest failed: ${res.status} ${res.statusText}`);
return res.json();
}
/**
* Bring an agent live in one call: claim its one-time on-chain activation grant.
* `POST /api/agents/:id/activate`. The platform funds the agent's wallet and the
* agent immediately appears on the Money Pulse as an active, funded wallet.
*
* Requires a bearer token with `avatars:write` for the agent's owner. Idempotent
* — if the agent is already live it resolves to the existing receipt
* (`already: true`) rather than granting twice.
*
* @param {string} agentId
* @returns {Promise<{ ok:boolean, already?:boolean, pending?:boolean, signature?:string,
* explorer?:string|null, sol?:number, usd?:number|null, network?:string }>}
*/
async activate(agentId) {
const res = await this._fetch(
`${this.baseUrl}/api/agents/${encodeURIComponent(agentId)}/activate`,
{ method: 'POST', headers: this._headers() },
);
const body = await this._json(res, 'activate');
return body?.data ?? body;
}
/**
* Read an agent's activation status (which "Go Live" state it's in). Owner view.
* `GET /api/agents/:id/activate`.
*
* @param {string} agentId
* @returns {Promise<{ enabled:boolean, eligible:boolean, activated:boolean,
* pending:boolean, reason:string|null, grant_sol:number, network:string,
* receipt:object|null }>}
*/
async getActivationStatus(agentId) {
const res = await this._fetch(
`${this.baseUrl}/api/agents/${encodeURIComponent(agentId)}/activate`,
{ headers: this._headers() },
);
const body = await this._json(res, 'getActivationStatus');
return body?.data ?? body;
}
/**
* Invoke a priced skill, settling x402 payment automatically when required.
*
* Pass a `payIntent` callback (or `signer.payIntent`) that, given the 402
* manifest, settles the payment on-chain and resolves to the paid intent id
* (either `{ intentId }` or the id string). Omit it to surface a
* {@link PaymentRequiredError} carrying the manifest so the caller can pay.
*
* @param {string} agentId
* @param {string} skill
* @param {Record<string, unknown>} [args]
* @param {{ signer?: { payIntent: (m: X402Manifest) => Promise<{intentId:string}|string> },
* payIntent?: (m: X402Manifest) => Promise<{intentId:string}|string> }} [options]
* @returns {Promise<unknown>} The skill result payload.
*/
async invokeSkill(agentId, skill, args = {}, options = {}) {
const first = await this._invoke(agentId, skill, args, null);
if (first.status === 402) {
const manifest = await first.json();
const payFn =
options.payIntent ||
(options.signer && typeof options.signer.payIntent === 'function'
? (m) => options.signer.payIntent(m)
: null);
if (!payFn) throw new PaymentRequiredError(manifest);
const settled = await payFn(manifest);
const intentId = typeof settled === 'string' ? settled : settled?.intentId;
if (!intentId)
throw new Error(
'payIntent must resolve to a paid intent id (string or { intentId })',
);
const paid = await this._invoke(agentId, skill, args, intentId);
return this._json(paid, 'invokeSkill');
}
if (first.status === 409) {
throw new Error(
`Skill "${skill}" is not a paid skill on agent ${agentId} — call it through the standard skill API instead.`,
);
}
return this._json(first, 'invokeSkill');
}
/**
* @param {string} agentId
* @param {string} skill
* @param {Record<string, unknown>} args
* @param {string | null} intentId
*/
_invoke(agentId, skill, args, intentId) {
const headers = this._headers(intentId ? { 'x-payment-intent': intentId } : undefined);
return this._fetch(`${this.baseUrl}/api/agents/x402/invoke`, {
method: 'POST',
headers,
body: JSON.stringify({ agent_id: agentId, skill, args }),
});
}
/**
* @param {{ ok: boolean, status: number, statusText: string, json: () => Promise<any> }} res
* @param {string} label
*/
async _json(res, label) {
if (!res.ok) {
let detail = '';
try {
detail = (await res.json())?.error || '';
} catch {
/* non-JSON error body */
}
throw new Error(
`${label} failed: ${res.status} ${res.statusText}${detail ? ` (${detail})` : ''}`,
);
}
return res.json();
}
}