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
/**
* BrowserWalletClient — browser-side half of the wallet bridge.
*
* Listens for pending transactions via SSE (instant push, no polling), then
* either auto-signs or calls the optional `onApproval` handler first so your
* UI can show a confirmation card before the wallet prompt appears.
*
* Works in any browser — no Node.js APIs, no React dependency.
*
* Quick start (auto-sign everything):
* const client = new BrowserWalletClient("/api/wallet", wallet.signTransaction.bind(wallet));
* client.connect();
*
* With confirmation UI:
* const client = new BrowserWalletClient("/api/wallet", signer, {
* onApproval: (pending, approve, reject) => {
* showConfirmModal(pending.meta, approve, reject);
* },
* });
* client.connect();
*/
import { Transaction, VersionedTransaction } from "@solana/web3.js";
import type { PendingTx } from "./browser-server.js";
export type SignerFn = (
tx: Transaction | VersionedTransaction,
) => Promise<Transaction | VersionedTransaction>;
export type ApprovalHandler = (
pending: PendingTx,
approve: () => void,
reject: () => void,
) => void;
export interface BrowserWalletClientOptions {
/**
* Session id issued by the server-side BrowserWalletProvider. Required to
* authorize /stream, /sign and /reject — the server rejects requests without
* it. Pass the provider's `sessionId` through to the browser at page load.
*/
sessionId?: string;
/**
* Called with each pending tx before the wallet prompt.
* Must call approve() or reject() — whichever the user chooses.
* If omitted, all transactions are auto-approved (no confirmation UI).
*/
onApproval?: ApprovalHandler;
/**
* Called after a transaction is confirmed on-chain.
* Useful for showing a success toast or updating chat state.
*/
onConfirmed?: (pending: PendingTx, signature: string) => void;
/**
* Called when a transaction is rejected by the user or the wallet.
*/
onRejected?: (pending: PendingTx, reason: string) => void;
/**
* Reconnect delay in ms after SSE drops (default 2000).
*/
reconnectMs?: number;
}
export class BrowserWalletClient {
private readonly baseUrl: string;
private readonly signer: SignerFn;
private readonly opts: BrowserWalletClientOptions;
private eventSource: EventSource | null = null;
private processing = new Set<string>();
private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
constructor(
baseUrl: string,
signer: SignerFn,
opts: BrowserWalletClientOptions = {},
) {
this.baseUrl = baseUrl.replace(/\/$/, "");
this.signer = signer;
this.opts = opts;
}
/** Open the SSE connection and start handling pending transactions. */
connect(): void {
if (this.eventSource) return;
this.openStream();
}
/** Close the SSE connection and stop processing. */
disconnect(): void {
if (this.reconnectTimer) {
clearTimeout(this.reconnectTimer);
this.reconnectTimer = null;
}
if (this.eventSource) {
this.eventSource.close();
this.eventSource = null;
}
}
private sessionQuery(): string {
const sid = this.opts.sessionId;
return sid ? `?session=${encodeURIComponent(sid)}` : "";
}
private authHeaders(extra: Record<string, string> = {}): Record<string, string> {
const sid = this.opts.sessionId;
return sid ? { ...extra, "x-wallet-session": sid } : extra;
}
private openStream(): void {
const es = new EventSource(`${this.baseUrl}/stream${this.sessionQuery()}`);
this.eventSource = es;
es.onmessage = (event: MessageEvent<string>) => {
const pending = JSON.parse(event.data) as PendingTx;
if (!this.processing.has(pending.id)) {
this.processing.add(pending.id);
void this.handle(pending).finally(() => this.processing.delete(pending.id));
}
};
es.onerror = () => {
es.close();
this.eventSource = null;
const delay = this.opts.reconnectMs ?? 2_000;
this.reconnectTimer = setTimeout(() => this.openStream(), delay);
};
}
private handle(pending: PendingTx): Promise<void> {
return new Promise<void>((resolve) => {
const proceed = () => void this.sign(pending).then(resolve, resolve);
const decline = () => {
void this.reject(pending, "User rejected");
resolve();
};
if (this.opts.onApproval) {
this.opts.onApproval(pending, proceed, decline);
} else {
proceed();
}
});
}
private async sign(pending: PendingTx): Promise<void> {
const buf = base64ToUint8Array(pending.transaction);
const tx = pending.versioned
? VersionedTransaction.deserialize(buf)
: Transaction.from(buf);
let signed: Transaction | VersionedTransaction;
try {
signed = await this.signer(tx);
} catch (err) {
const reason = err instanceof Error ? err.message : "Wallet rejected";
await this.reject(pending, reason);
return;
}
const serialized = uint8ArrayToBase64(signed.serialize());
const res = await fetch(`${this.baseUrl}/sign/${pending.id}`, {
method: "POST",
headers: this.authHeaders({ "Content-Type": "application/json" }),
body: JSON.stringify({ signedTransaction: serialized }),
});
if (res.ok) {
const { signature } = (await res.json()) as { signature?: string };
if (signature) this.opts.onConfirmed?.(pending, signature);
}
}
private async reject(pending: PendingTx, reason: string): Promise<void> {
await fetch(`${this.baseUrl}/reject/${pending.id}`, {
method: "POST",
headers: this.authHeaders(),
}).catch(() => undefined);
this.opts.onRejected?.(pending, reason);
}
}
// ─── Base64 helpers (no Buffer — browser safe) ────────────────────────────────
function base64ToUint8Array(b64: string): Uint8Array {
const binary = atob(b64);
const bytes = new Uint8Array(binary.length);
for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
return bytes;
}
function uint8ArrayToBase64(bytes: Uint8Array): string {
let binary = "";
for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i] as number);
return btoa(binary);
}