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
// x402 v2 `upto` on Solana: the buyer authorizes a CAP, the seller measures the
// work and settles only what was used.
//
// Wire protocol, all from the official `@x402/svm/upto/*` packages (no
// hand-rolled signing):
// 402 accepts[] carries {scheme:'upto', amount:<cap>, extra:{feePayer,
// receiverAuthorizer, withdrawDelay, tokenProgram, ...}}.
// client signs a payment-channel `open` transaction depositing the cap and
// carries it in payload.openTransaction.
// deposit settle (before the handler): the facilitator broadcasts the open
// tx, escrowing the cap on chain.
// claim settle (after the handler): requirement.amount = the MEASURED
// charge, plus a voucher signed by the receiverAuthorizer over that
// cumulative amount. The program pays the seller the charge and
// refunds the rest of the deposit to the buyer.
// cancel a claim of "0": a handler that failed settles nothing and the whole
// deposit goes back to the buyer.
//
// three.ws is its own facilitator for this scheme: the UptoSvmScheme
// facilitator runs in-process, co-signing with the sponsor key that already
// backs the exact self-facilitator (X402_FEE_PAYER_SECRET_BASE58). The same key
// is the channel's receiverAuthorizer, so vouchers are signed locally and no
// third-party facilitator has to support `upto`.
import { env } from '../env.js';
import { loadFeePayerKeypair } from './self-facilitator.js';
export const UPTO_SCHEME = 'upto';
// Seconds a channel may stay open. The facilitator refuses longer lifetimes, so
// the 402 never advertises a maxTimeoutSeconds above this.
export const UPTO_MAX_TIMEOUT_SECONDS = 600;
export class UptoError extends Error {
constructor(code, message, extra = {}) {
super(message);
this.name = 'UptoError';
this.code = code;
Object.assign(this, extra);
}
}
let _bundle = null;
let _override = null;
// True when this deployment can run `upto`: opt-in flag plus the sponsor key.
export function uptoEnabled() {
if (_override) return true;
if (String(process.env.X402_UPTO_ENABLED || '').toLowerCase() !== 'true') return false;
return !!process.env.X402_FEE_PAYER_SECRET_BASE58;
}
// Test seam: install a prebuilt { facilitator, server, signer } bundle (a real
// UptoSvmScheme facilitator wired to a test-controlled signer). Pass null to
// clear.
export function setUptoBundleForTests(bundle) {
_override = bundle || null;
_bundle = null;
}
async function bundle() {
if (_override) return _override;
if (_bundle) return _bundle;
const [{ createKeyPairSignerFromBytes }, svmFac, svmSrv, svmRoot] = await Promise.all([
import('@solana/kit'),
import('@x402/svm/upto/facilitator'),
import('@x402/svm/upto/server'),
import('@x402/svm'),
]);
const kp = loadFeePayerKeypair();
const signer = await createKeyPairSignerFromBytes(kp.secretKey);
const rpc = env.SOLANA_RPC_URL;
const facilitatorSigner = svmRoot.toFacilitatorSvmSigner(signer, { defaultRpcUrl: rpc });
const facilitator = new svmFac.UptoSvmScheme(facilitatorSigner, {
maxChannelLifetimeSecs: 3600,
});
const server = new svmSrv.UptoSvmScheme({
receiverAuthorizerSigner: signer,
rpcUrl: rpc,
});
_bundle = { facilitator, server, signer };
return _bundle;
}
// Build the `accepts[]` entry for an upto offer. `capAtomics` is the maximum
// the buyer can be charged; the seller settles <= this.
export async function buildUptoRequirement({ capAtomics, network, asset, payTo, resourceUrl, description, mimeType }) {
const b = await bundle();
const base = {
scheme: UPTO_SCHEME,
network,
asset,
amount: String(capAtomics),
payTo,
maxTimeoutSeconds: UPTO_MAX_TIMEOUT_SECONDS,
extra: {},
};
const supportedKind = {
x402Version: 2,
scheme: UPTO_SCHEME,
network,
extra: b.facilitator.getExtra(network) || {},
};
const req = await b.server.enhancePaymentRequirements(base, supportedKind, []);
void resourceUrl;
void description;
void mimeType;
return req;
}
// Verify a client's upto authorization against the requirement it chose.
// Resolves {isValid, invalidReason, payer}. The facilitator checks the signed
// open transaction (program, deposit == cap, payee, fee payer, simulation) and
// rejects a client-supplied voucher.
export async function verifyUpto({ paymentPayload, requirement }) {
const b = await bundle();
return b.facilitator.verify(paymentPayload, requirement);
}
// Phase 1: broadcast the open transaction so the cap is escrowed. Must succeed
// before the handler runs, otherwise the seller would do work it cannot collect.
export async function settleUptoDeposit({ paymentPayload, requirement }) {
const b = await bundle();
const stamped = await b.server.enrichSettlementPayload({
phase: 'before-handler',
paymentPayload,
requirements: requirement,
});
return b.facilitator.settle(withStamp(paymentPayload, stamped), requirement);
}
// Phase 2: claim the measured amount. `amountAtomics` of 0 cancels: the whole
// deposit returns to the buyer. Resolves the facilitator SettleResponse.
export async function settleUptoClaim({ paymentPayload, requirement, amountAtomics }) {
const b = await bundle();
const amount = BigInt(amountAtomics);
const cap = BigInt(requirement.amount);
if (amount < 0n || amount > cap) {
throw new UptoError(
'charge_exceeds_cap',
`upto: measured charge ${amount} is outside 0..${cap}`,
{ status: 500 },
);
}
const claimReq = { ...requirement, amount: amount.toString() };
const stamped = await b.server.enrichSettlementPayload({
phase: 'after-handler',
paymentPayload,
requirements: claimReq,
});
return b.facilitator.settle(withStamp(paymentPayload, stamped), claimReq);
}
function withStamp(paymentPayload, stamped) {
return {
...paymentPayload,
payload: { ...paymentPayload.payload, ...(stamped || {}) },
};
}
// A requirement is an upto offer when its scheme says so.
export function isUptoRequirement(r) {
return r?.scheme === UPTO_SCHEME;
}
// Normalise a handler's measured charge to bigint, clamped by the cap. A
// handler may return atomic units as a bigint/number/string; anything
// unparseable is an error (we never guess a charge).
export function normaliseCharge(charge, capAtomics) {
let n;
try {
n = BigInt(charge);
} catch {
throw new UptoError('invalid_charge', 'upto: handler charge must be a base-10 integer of atomic units', { status: 500 });
}
if (n < 0n) throw new UptoError('invalid_charge', 'upto: handler charge cannot be negative', { status: 500 });
const cap = BigInt(capAtomics);
return n > cap ? cap : n;
}