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
// api/_lib/x402/ring-config.js
//
// Routing + configuration truth for the closed-loop x402 ring.
//
// The ring's whole point is that NO third party ever touches a ring settlement
// — yet the stock Solana facilitator default is an external one (PayAI). This
// module is the single place that decides where Solana settlement routes and
// that says, loudly and structurally, when a deploy is mis-enveloped:
//
// 1. resolveSolanaFacilitator() — the resolution rule facilitatorFor() uses.
// An EXPLICIT X402_FACILITATOR_URL_SOLANA (or legacy X402_FACILITATOR_URL)
// always wins; with no explicit URL, X402_SELF_FACILITATOR_ENABLED=true
// defaults to our own /api/x402-facilitator, and only a disabled
// self-facilitator falls back to the external default. No surprise
// re-routing for existing deploys: explicit env beats computed defaults.
//
// 2. validateRingConfig() — structured findings for every known ring
// misconfiguration, surfaced by /api/x402-ring (config_warnings) and
// /api/x402-status (ring.config_warnings).
//
// 3. warnIfRingRoutesExternal() — one structured console warning per boot
// (not per call) when ring intent exists but settlement would route to an
// external facilitator.
//
// Deliberately light: imports only env.js and x402-prices.js so the pure-logic
// tests (tests/api/x402-ring-config.test.js) never touch @solana/web3.js, the
// DB, or the network.
import { env } from '../env.js';
import { priceFor } from '../x402-prices.js';
import { RING_SETTLE_DEFAULT_PRICE_ATOMICS, volumePerRunCapAtomic } from './ring-constants.js';
// External default when the self-facilitator is off and no URL is set.
// Mirrors the default baked into env.js X402_FACILITATOR_URL_SOLANA.
export const EXTERNAL_FACILITATOR_URL_DEFAULT = 'https://facilitator.payai.network';
export function selfFacilitatorEnabled() {
return String(process.env.X402_SELF_FACILITATOR_ENABLED || '').toLowerCase() === 'true';
}
export function ringSelfPayEnabled() {
return String(process.env.X402_RING_SELF_PAY || '').toLowerCase() === 'true';
}
// The self-hosted facilitator's own URL. Anchored on APP_ORIGIN (canonical
// fallback https://three.ws) so preview deploys resolve to THEIR facilitator.
export function selfFacilitatorUrl() {
return `${env.APP_ORIGIN}/api/x402-facilitator`;
}
// Does a facilitator URL point at (any deploy of) our self-hosted facilitator?
// Matched on the route path, not the host, so an explicit env var pinning the
// production origin still counts as self on a preview deploy.
export function isSelfFacilitatorUrl(url) {
if (!url) return false;
try {
return new URL(url).pathname.replace(/\/$/, '').endsWith('/api/x402-facilitator');
} catch {
return false;
}
}
// The explicitly-configured Solana facilitator URL, or null when unset/blank.
// Blank values (X402_FACILITATOR_URL_SOLANA= in a .env) count as unset —
// otherwise the resolver would emit '' and every facilitator call would fetch
// a relative path.
function explicitSolanaFacilitatorUrl() {
const raw = process.env.X402_FACILITATOR_URL_SOLANA ?? process.env.X402_FACILITATOR_URL;
const trimmed = String(raw ?? '').trim();
if (!trimmed) return null;
return trimmed.replace(/\/$/, '');
}
// Resolution rule for Solana settlement — the seam facilitatorFor() calls.
// Returns { url, self } where `self` is true when the resolved URL is our own
// facilitator. Order:
// 1. explicit env URL (always wins — existing deploys never re-route)
// 2. self-hosted facilitator, when X402_SELF_FACILITATOR_ENABLED=true
// 3. the external default (PayAI)
export function resolveSolanaFacilitator() {
const explicit = explicitSolanaFacilitatorUrl();
if (explicit) return { url: explicit, self: isSelfFacilitatorUrl(explicit) };
if (selfFacilitatorEnabled()) return { url: selfFacilitatorUrl(), self: true };
return { url: EXTERNAL_FACILITATOR_URL_DEFAULT, self: false };
}
// Boot-time ring configuration validation. Returns structured findings — empty
// when the ring envelope is complete. Each finding: { code, severity, message,
// fix }. severity 'error' = ring settlement will not work as intended;
// 'warn' = it works but costs more or a component is degraded.
export function validateRingConfig() {
const findings = [];
const enabled = selfFacilitatorEnabled();
const route = resolveSolanaFacilitator();
if (!enabled) {
findings.push({
code: 'self_facilitator_disabled',
severity: 'error',
message:
'X402_SELF_FACILITATOR_ENABLED is not "true" — /api/x402-facilitator answers 503 and nothing settles in-house',
fix: 'set X402_SELF_FACILITATOR_ENABLED=true',
});
}
if (!route.self) {
findings.push({
code: 'facilitator_url_external',
severity: 'error',
message: `Solana settlement resolves to ${route.url} — an external facilitator would touch ring settlements`,
fix: `set X402_SELF_FACILITATOR_ENABLED=true and either unset X402_FACILITATOR_URL_SOLANA or point it at ${selfFacilitatorUrl()}`,
});
}
if (!String(process.env.X402_TREASURY_SECRET_BASE58 || '').trim()) {
findings.push({
code: 'treasury_secret_missing',
severity: 'warn',
message:
'X402_TREASURY_SECRET_BASE58 is not set — the rebalancer cannot sweep treasury→payer, so the float drains one-way into the treasury',
fix: 'set X402_TREASURY_SECRET_BASE58 from scripts/x402-ring-setup.mjs output',
});
}
if (!env.X402_FEE_PAYER_SOLANA) {
findings.push({
code: 'fee_payer_pubkey_missing',
severity: 'error',
message:
'X402_FEE_PAYER_SOLANA is not set — 402 challenges cannot advertise extra.feePayer, so no Solana accept entry is buildable',
fix: 'set X402_FEE_PAYER_SOLANA to the sponsor pubkey from scripts/x402-ring-setup.mjs',
});
}
// When settlement routes in-house, the sponsor SECRET must be present or every
// sponsor-mode settle throws `sponsor_key_unconfigured` and the buyer gets a 502
// AFTER paying. The advertising layer (solanaSettleable() in x402-spec.js) now
// drops the Solana accept when this secret is missing, turning that 502 into a
// clean unpayable state — but the deploy still can't earn on Solana until it is
// set, so surface it here as an error the health board and /api/x402-status show.
// Only meaningful when we route to our own facilitator; an external facilitator
// co-signs with its own key.
if (route.self && !ringSelfPayEnabled() && !String(process.env.X402_FEE_PAYER_SECRET_BASE58 || '').trim()) {
findings.push({
code: 'fee_payer_secret_missing',
severity: 'error',
message:
'X402_FEE_PAYER_SECRET_BASE58 is not set and self-pay is off — the self-facilitator cannot co-sign sponsor-mode settlements, so the Solana accept is withheld and no Solana payment can settle in-house',
fix: 'set X402_RING_SELF_PAY=true (buyer pays its own fee, no sponsor key needed) OR set X402_FEE_PAYER_SECRET_BASE58 to the sponsor secret (must match X402_FEE_PAYER_SOLANA)',
});
}
const priceAtomic = Number(priceFor('ring-settle', RING_SETTLE_DEFAULT_PRICE_ATOMICS));
const capAtomic = volumePerRunCapAtomic();
if (capAtomic > 0 && priceAtomic > capAtomic) {
findings.push({
code: 'ring_price_exceeds_run_cap',
severity: 'error',
message: `priceFor('ring-settle')=${priceAtomic} atomics exceeds X402_VOLUME_PER_RUN_CAP_ATOMIC=${capAtomic} — the volume loop skips ring-settle on every tick`,
fix: 'raise X402_VOLUME_PER_RUN_CAP_ATOMIC above X402_PRICE_RING_SETTLE (or lower the price)',
});
}
if (!ringSelfPayEnabled()) {
findings.push({
code: 'ring_self_pay_off',
severity: 'warn',
message:
'X402_RING_SELF_PAY is not "true" — sponsor mode needs 2 signatures (~2× the base fee) plus the sponsor secret on every settle',
fix: 'set X402_RING_SELF_PAY=true and fund the payer with a little SOL',
});
}
return findings;
}
// One structured warning per boot (not per call) when ring settlement would
// route to an external facilitator. Returns the warning object (for surfacing
// in API responses) or null when routing is already self-hosted. Callers are
// the ring surfaces (/api/x402-ring) plus the module-load hook below for
// deploys that declare ring intent via X402_RING_SELF_PAY=true.
let externalRouteWarned = false;
export function warnIfRingRoutesExternal(context = 'ring') {
const route = resolveSolanaFacilitator();
if (route.self) return null;
const warning = {
code: 'ring_external_facilitator',
context,
facilitator_url: route.url,
self_facilitator_enabled: selfFacilitatorEnabled(),
ring_self_pay: ringSelfPayEnabled(),
message: `ring settlement routes to EXTERNAL facilitator ${route.url}; set X402_SELF_FACILITATOR_ENABLED=true and unset X402_FACILITATOR_URL_SOLANA (or point it at ${selfFacilitatorUrl()})`,
};
if (!externalRouteWarned) {
externalRouteWarned = true;
console.warn(`[x402-ring-config] ${JSON.stringify(warning)}`);
}
return warning;
}
// Test hook — the once-per-boot latch above is process state.
export function _resetRingConfigWarningsForTest() {
externalRouteWarned = false;
}
// Boot hook: a deploy that turned on self-pay declared ring intent — if its
// settlement still routes externally, say so once, immediately, instead of
// waiting for the first pipeline tick.
if (ringSelfPayEnabled()) {
warnIfRingRoutesExternal('boot');
}