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
#!/usr/bin/env node
// scripts/x402-facilitator-smoke-test.mjs
//
// Smoke test for the self-hosted x402 facilitator (api/x402-facilitator).
//
// TWO MODES, and the safe one is the default:
//
// verify-only (DEFAULT, no --settle)
// Drives the whole paying path except the broadcast: reads the facilitator's
// capability documents, asserts the ring reports no config warnings, pulls a
// real 402 challenge off /api/x402/ring-settle, signs a real USDC transfer
// for that challenge, and POSTs it to the facilitator's /verify action.
// /verify runs the same structural + on-chain settleability checks the money
// path runs (validateRingTransaction then assertSettleable) and never
// broadcasts, so a green run proves the rail end to end while moving zero
// USDC and burning zero SOL. This is what the x402 sweep runs.
//
// --settle
// Drives ONE real, cents-capped USDC settlement through
// /api/x402/ring-settle: the exact code path the production autonomous ring
// loop uses (api/_lib/x402/pay.js:payX402 -> 402 challenge -> self-facilitator
// verify+settle). Real money moves, so it requires an explicit --url and is
// never pointed at a default target.
//
// Config is read from the shell first and .env / .env.local second (same
// secrets the ring pipelines use, never committed):
// X402_SEED_SOLANA_SECRET_BASE58 ring payer keypair (signs the transfer)
// X402_ASSET_MINT_SOLANA USDC mint (defaults to mainnet USDC)
// SOLANA_RPC_URL any working mainnet RPC
//
// Usage:
// node scripts/x402-facilitator-smoke-test.mjs # verify-only vs https://three.ws
// node scripts/x402-facilitator-smoke-test.mjs --url=https://<preview> # verify-only vs a preview
// node scripts/x402-facilitator-smoke-test.mjs --url=https://<preview> --settle --cap=0.05
//
// Exit code: 0 = every check passed, 1 = anything else (never silently
// "probably fine": a skipped, free, or failed result is a failed test).
import { config as dotenv } from 'dotenv';
// Shell env wins: dotenv never overrides a var that is already set, so an
// operator pointing this at a preview with different secrets stays in control.
dotenv({ path: new URL('../.env', import.meta.url), quiet: true });
dotenv({ path: new URL('../.env.local', import.meta.url), quiet: true });
const { PublicKey } = await import('@solana/web3.js');
const { getAssociatedTokenAddressSync, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID } =
await import('@solana/spl-token');
const {
payX402, bootstrapSolanaContext, buildPaymentTx, parseSolanaAccept,
fetchWithTimeout, ringSelfPayDefault, nextAutoNonce, USDC_MINT,
} = await import('../api/_lib/x402/pay.js');
const args = process.argv.slice(2);
const opt = (name, def) => {
const p = args.find((a) => a.startsWith(`--${name}=`));
return p ? p.slice(name.length + 3) : def;
};
const DEFAULT_TARGET = 'https://three.ws';
const settleMode = args.includes('--settle');
const explicitUrl = opt('url', null);
const baseUrl = (explicitUrl || DEFAULT_TARGET).replace(/\/$/, '');
const capUsd = Number(opt('cap', '0.05'));
// A real settlement never runs against an implied target. Naming the deployment
// is the operator's acknowledgement that this call spends mainnet USDC.
if (settleMode && !explicitUrl) {
console.error('--settle spends real USDC and refuses an implied target. Pass --url=https://<deployment> explicitly.');
process.exit(1);
}
if (!USDC_MINT) {
console.error('X402_ASSET_MINT_SOLANA resolved empty. Export the same value used on the target deploy.');
process.exit(1);
}
if (settleMode && (!Number.isFinite(capUsd) || capUsd <= 0 || capUsd > 1)) {
console.error('--cap must be a small positive USD number (<=1). Refusing to run a smoke test with a large cap.');
process.exit(1);
}
const capAtomic = Math.round(capUsd * 1_000_000); // USDC = 6dp
const RING_SETTLE_URL = `${baseUrl}/api/x402/ring-settle`;
const SOLANA_NETWORK_PREFIX = 'solana:';
const checks = [];
function record(name, ok, detail) {
checks.push({ name, ok, detail });
console.log(`${ok ? 'PASS' : 'FAIL'} ${name}${detail ? `\n ${detail}` : ''}`);
return ok;
}
// ── Stage 1: capability documents ───────────────────────────────────────────
// The facilitator index and /supported are public probes. If either stops
// advertising exact/solana, every paying client silently routes elsewhere.
async function checkCapabilityDocs() {
const index = await fetchWithTimeout(`${baseUrl}/api/x402-facilitator`, { method: 'GET' });
const doc = index.body && typeof index.body === 'object' ? index.body : null;
if (!index.ok || !doc) {
return record('facilitator index reachable', false, `HTTP ${index.status} from ${baseUrl}/api/x402-facilitator`);
}
const kinds = Array.isArray(doc.kinds) ? doc.kinds : [];
const solanaExact = kinds.find(
(k) => k?.scheme === 'exact' && String(k?.network || '').startsWith(SOLANA_NETWORK_PREFIX),
);
record(
'facilitator index reachable',
true,
`enabled=${doc.enabled} payTo=${doc.payTo || 'unset'} feePayer=${doc.feePayer || 'unset'} asset=${doc.asset || 'unset'}`,
);
record('facilitator advertises exact/solana', Boolean(solanaExact), solanaExact ? `network=${solanaExact.network}` : `kinds=${JSON.stringify(kinds)}`);
record('self facilitator enabled', doc.enabled === true, doc.enabled === true ? null : 'X402_SELF_FACILITATOR_ENABLED is not true on the target: settlement falls through to an external facilitator');
record('facilitator receiver configured', Boolean(doc.payTo && doc.asset), doc.payTo && doc.asset ? null : 'payTo or asset missing: 402 challenges cannot advertise a Solana accept');
const supported = await fetchWithTimeout(`${baseUrl}/api/x402-facilitator/supported`, { method: 'GET' });
const supportedKinds = Array.isArray(supported.body?.kinds) ? supported.body.kinds : [];
const supportedSolana = supportedKinds.some(
(k) => k?.scheme === 'exact' && String(k?.network || '').startsWith(SOLANA_NETWORK_PREFIX),
);
record(
'/supported capability probe',
supported.ok && supportedSolana,
supported.ok && supportedSolana ? `kinds=${supportedKinds.length}` : `HTTP ${supported.status} body=${JSON.stringify(supported.body).slice(0, 200)}`,
);
}
// ── Stage 2: ring configuration ─────────────────────────────────────────────
// config_warnings is the ring's own self-diagnosis (missing payer, price above
// cap, unfunded fee wallet). A non-empty list means the loop is degraded even
// when every individual endpoint answers.
async function checkRingConfig() {
const status = await fetchWithTimeout(`${baseUrl}/api/x402-status`, { method: 'GET' });
const accepts = Array.isArray(status.body?.accepts) ? status.body.accepts : [];
const solanaAccepts = accepts.filter((a) => String(a?.network || '').startsWith(SOLANA_NETWORK_PREFIX));
record(
'x402-status advertises a Solana accept',
status.ok && solanaAccepts.length > 0,
status.ok ? `accepts=${accepts.length} solana=${solanaAccepts.length}` : `HTTP ${status.status}`,
);
const ring = await fetchWithTimeout(`${baseUrl}/api/x402-ring`, { method: 'GET' });
if (!ring.ok || !ring.body || typeof ring.body !== 'object') {
return record('ring reports no config warnings', false, `HTTP ${ring.status} from ${baseUrl}/api/x402-ring`);
}
const warnings = Array.isArray(ring.body.config_warnings) ? ring.body.config_warnings : [];
record('ring reports no config warnings', warnings.length === 0, warnings.length ? JSON.stringify(warnings) : null);
const settlements = ring.body.settlements || {};
console.log(` settlements so far: count=${settlements.count ?? '?'} gross_usdc=${settlements.gross_usdc ?? '?'}`);
}
// ── Stage 3: the 402 challenge ──────────────────────────────────────────────
// An unpaid POST is a read: the paywall answers 402 with the requirements and
// changes no state. Returns the parsed Solana accept for stage 4.
async function fetchChallenge() {
const probe = await fetchWithTimeout(RING_SETTLE_URL, {
method: 'POST',
headers: { 'content-type': 'application/json', 'user-agent': 'threews-x402-facilitator-smoke/1.0' },
body: JSON.stringify({ note: 'facilitator-smoke-test', seq: 1 }),
});
if (probe.status !== 402) {
record('ring-settle issues a 402 challenge', false, `expected HTTP 402, got ${probe.status}: ${JSON.stringify(probe.body).slice(0, 200)}`);
return null;
}
const accept = parseSolanaAccept(probe.body);
if (!accept) {
record('402 challenge carries a Solana accept', false, `accepts=${JSON.stringify(probe.body?.accepts || []).slice(0, 300)}`);
return null;
}
record('ring-settle issues a 402 challenge', true, `price=${(Number(accept.amount) / 1e6).toFixed(6)} USDC payTo=${accept.payTo}`);
record('402 challenge carries a Solana accept', accept.asset === USDC_MINT, accept.asset === USDC_MINT ? `asset=${accept.asset}` : `advertised asset ${accept.asset} is not the configured mint ${USDC_MINT}`);
return accept;
}
// ── Stage 4: signed-payment verification (no broadcast) ─────────────────────
// Builds the same signed transfer payX402 would send and hands it to the
// facilitator's /verify action. /verify decodes it, enforces the payTo
// allowlist, the settleable-mint pin, the fee ceiling and the instruction shape,
// then simulates settleability against the RPC. It never broadcasts, so this
// exercises the money path without moving money.
async function checkSignedVerify() {
const accept = await fetchChallenge();
if (!accept) return;
const ctx = await bootstrapSolanaContext();
console.log(` payer pubkey: ${ctx.buyer.publicKey.toBase58()}`);
const selfPay = ringSelfPayDefault();
const receiverAta = getAssociatedTokenAddressSync(
new PublicKey(accept.asset), new PublicKey(accept.payTo),
false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
);
const receiverAtaInfo = await ctx.conn.getAccountInfo(receiverAta).catch(() => null);
const txBase64 = buildPaymentTx({
accept, buyer: ctx.buyer, blockhash: ctx.blockhash, mintInfo: ctx.mintInfo,
receiverAtaExists: receiverAtaInfo !== null,
nonce: nextAutoNonce(), selfPay,
});
const verifyRes = await fetchWithTimeout(`${baseUrl}/api/x402-facilitator/verify`, {
method: 'POST',
headers: { 'content-type': 'application/json', 'user-agent': 'threews-x402-facilitator-smoke/1.0' },
body: JSON.stringify({
paymentPayload: {
x402Version: 2,
scheme: 'exact',
network: accept.network,
resource: { url: RING_SETTLE_URL, mimeType: 'application/json' },
payload: { transaction: txBase64 },
accepted: accept,
},
paymentRequirements: accept,
}),
});
const verdict = verifyRes.body && typeof verifyRes.body === 'object' ? verifyRes.body : null;
record(
'facilitator verifies a real signed payment',
Boolean(verifyRes.ok && verdict?.isValid),
verdict?.isValid
? `payer=${verdict.payer} asset=${verdict.asset} selfPay=${selfPay} (nothing broadcast)`
: `HTTP ${verifyRes.status} reason=${verdict?.invalidReason || JSON.stringify(verifyRes.body).slice(0, 200)}`,
);
}
// ── Stage 5 (--settle only): one real capped settlement ─────────────────────
async function checkRealSettlement() {
const ctx = await bootstrapSolanaContext();
console.log(`\nPaying ${RING_SETTLE_URL} (capped at $${capUsd.toFixed(2)}, payer ${ctx.buyer.publicKey.toBase58()})...`);
const result = await payX402({
url: RING_SETTLE_URL,
body: { note: 'facilitator-smoke-test', seq: 1 },
buyer: ctx.buyer,
conn: ctx.conn,
blockhash: ctx.blockhash,
mintInfo: ctx.mintInfo,
remainingCap: capAtomic,
});
console.log(JSON.stringify(result, null, 2));
record(
'real settlement landed on-chain',
Boolean(result.success && result.paid && result.txSig),
result.txSig ? `https://solscan.io/tx/${result.txSig}` : `status=${result.status} err=${result.errorMsg}`,
);
}
async function main() {
console.log('\n=== x402 self-facilitator smoke test ===');
console.log(`target: ${baseUrl}`);
console.log(`mode: ${settleMode ? `settle (real USDC, capped at $${capUsd.toFixed(2)} / ${capAtomic} atomic)` : 'verify-only (no money moves)'}\n`);
await checkCapabilityDocs();
await checkRingConfig();
await checkSignedVerify();
if (settleMode) await checkRealSettlement();
const failed = checks.filter((c) => !c.ok);
console.log(`\n--- summary ---`);
console.log(` passed: ${checks.length - failed.length}/${checks.length}`);
if (failed.length) {
console.log(` failed: ${failed.map((c) => c.name).join(', ')}`);
process.exit(1);
}
console.log(settleMode
? '\nPASS. Re-check the target /api/x402-ring so settlements.count moved and config_warnings is still empty.'
: '\nPASS. The rail verifies end to end with no settlement. Add --settle --url=<deployment> to move real USDC.');
}
main().catch((err) => {
console.error('\nFAIL, smoke test threw:', err);
process.exit(1);
});