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 challenge probing, shared by the payment executor and the dry-run simulator.
//
// Both need the identical network behaviour: an SSRF-guarded request that never
// follows a redirect, pins the resolved address against DNS rebinding, and reads
// the 402 challenge from either the JSON body or the `payment-required` header.
// They differ only in what they do with the answer. The executor selects one
// Solana USDC accept and signs it; the simulator reports every rail and signs
// nothing. Keeping the transport in one place means a hardening fix to one path
// cannot leave the other exposed.
import { validatePublicUrl, resolvePublicHost, pinnedAgent, disposeAgent, SsrfError } from '../ssrf.js';
/** Canonical USDC mint on Solana mainnet. */
export const USDC_SOLANA_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
/** Canonical USDC contract on Base mainnet, for the secondary EVM rail. */
export const USDC_BASE_ADDRESS = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913';
/**
* How a session's network name maps onto the network ids a 402 challenge uses.
*
* A session stores the short name ("solana", "base"), but the wire format is
* CAIP-2: every live Base endpoint advertises `eip155:8453`, never `base`.
* Matching the short name against the challenge by prefix alone therefore found
* nothing for a Base session, so the simulator reported "no base payment option"
* for endpoints that were charging on Base right in front of it.
*/
const NETWORK_ALIASES = Object.freeze({
solana: ['solana'],
base: ['base', 'eip155:8453'],
});
export const DEFAULT_TIMEOUT_MS = 20_000;
export function safeJson(text) {
try { return JSON.parse(text); } catch { return null; }
}
export function b64decodeJson(s) {
if (!s) return null;
try { return JSON.parse(Buffer.from(String(s), 'base64').toString('utf8')); } catch { return null; }
}
/**
* Fetch a third-party URL with the full SSRF guard chain.
*
* `redirect: 'manual'` matters as much as the address pin: a 302 to
* 169.254.169.254 would otherwise bypass the check that just passed.
*/
export async function guardedFetch(rawUrl, {
method = 'GET',
headers = {},
body,
timeoutMs = DEFAULT_TIMEOUT_MS,
userAgent = 'three.ws-payment-session/1.0 (+https://three.ws/)',
} = {}) {
const url = validatePublicUrl(rawUrl);
const addrs = await resolvePublicHost(url.hostname);
const agent = pinnedAgent(url.hostname, addrs);
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await fetch(url, {
method,
redirect: 'manual',
signal: controller.signal,
dispatcher: agent,
headers: {
'user-agent': userAgent,
accept: 'application/json, text/plain;q=0.8, */*;q=0.5',
...(body != null ? { 'content-type': 'application/json' } : {}),
...headers,
},
...(body != null ? { body: typeof body === 'string' ? body : JSON.stringify(body) } : {}),
});
const text = await res.text();
return { status: res.status, ok: res.ok, headers: res.headers, text };
} finally {
clearTimeout(timer);
await disposeAgent(agent);
}
}
/** Read the challenge out of a 402 response, wherever the service put it. */
export function readChallenge(res) {
return safeJson(res.text) || b64decodeJson(res.headers.get('payment-required'));
}
/**
* Summarize one `accepts` entry into the shape both the simulator UI and the
* MCP tool render. `amount` is a decimal string of atomic units in the x402
* spec, so it is parsed as BigInt and never as a float.
*/
export function describeRail(accept) {
let atomics = null;
try { atomics = BigInt(accept?.amount); } catch { atomics = null; }
return {
network: typeof accept?.network === 'string' ? accept.network : null,
asset: accept?.asset ?? null,
pay_to: accept?.payTo ?? null,
amount_atomics: atomics === null ? null : atomics.toString(),
// Every asset we transact in uses 6 decimals; a rail that does not is
// reported with a null price rather than a wrong one.
amount_usd: atomics === null ? null : Number(atomics) / 1_000_000,
usdc:
accept?.asset === USDC_SOLANA_MINT ||
String(accept?.asset ?? '').toLowerCase() === USDC_BASE_ADDRESS ||
/usdc/i.test(String(accept?.extra?.name ?? '')),
};
}
/**
* Probe an endpoint and report what it charges, without paying anything.
*
* Never throws for an ordinary remote failure: an unreachable host, a blocked
* URL, or an unreadable challenge are all legitimate outcomes of a dry run and
* each is returned as a typed result so the caller can show the row instead of
* failing the whole batch.
*
* @returns {Promise<{kind: 'priced'|'free'|'error', ...}>}
*/
export async function probePrice(rawUrl, { method = 'GET', body = null, timeoutMs } = {}) {
let res;
try {
res = await guardedFetch(rawUrl, { method, body, timeoutMs });
} catch (err) {
if (err instanceof SsrfError) {
return {
kind: 'error',
code: 'blocked_url',
message: 'Target URL is not a reachable public endpoint',
};
}
return {
kind: 'error',
code: 'endpoint_unreachable',
message: `Could not reach endpoint: ${err?.message ?? 'network error'}`,
};
}
if (res.status !== 402) {
// Only a SUCCESS without a challenge is free. An endpoint that answers 404,
// 400, or 500 is broken, not free, and calling it free was the wrong answer
// to the one question the simulator exists to answer: a workload whose every
// call errored came back `feasible: true` at a cost of $0, because each dead
// endpoint scored as a free call and free calls never enter the replay.
if (res.ok) return { kind: 'free', status: res.status };
return {
kind: 'error',
code: 'endpoint_error',
message: `Endpoint answered HTTP ${res.status} with no payment challenge`,
status: res.status,
};
}
const challenge = readChallenge(res);
if (!challenge || !Array.isArray(challenge.accepts) || challenge.accepts.length === 0) {
return {
kind: 'error',
code: 'invalid_challenge',
message: 'Service returned an unreadable payment challenge',
};
}
const rails = challenge.accepts.map(describeRail);
return { kind: 'priced', status: 402, rails, description: challenge.description ?? null };
}
/**
* Pick the rail a payment session would actually settle on.
*
* Sessions settle Solana-first (the platform's home chain), so a Solana USDC
* accept always wins. `base` sessions select the EVM rail. When the requested
* network is absent the caller is told which networks the service does offer,
* because "no Solana option" is a useful dry-run finding, not an error to hide.
*/
export function selectRail(rails, network = 'solana') {
const want = String(network || 'solana').toLowerCase();
const ids = NETWORK_ALIASES[want] ?? [want];
const onNetwork = rails.filter(
(r) =>
typeof r.network === 'string' &&
ids.some((id) => r.network.toLowerCase().startsWith(id)),
);
if (onNetwork.length === 0) return null;
// A rail whose amount could not be parsed is worse than no rail: settling on
// it would mean signing for a price nobody read. Prefer a readable one.
const readable = onNetwork.filter((r) => r.amount_atomics !== null);
const pool = readable.length ? readable : onNetwork;
return pool.find((r) => r.usdc) ?? pool[0];
}