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
// POST /api/pay/simulate: dry-run a payment session policy against real prices.
//
// The problem this solves: authorizing an agent budget is a guess. You pick
// $10 and a $0.50 per-transaction cap because those are round numbers, hand the
// token to an agent, and find out which of your assumptions was wrong only when
// the agent is already running and something has already been spent. If the cap
// was too low the agent stalls on its third call. If the allowlist missed a
// host the agent stalls on its first. If the budget was too small it dies
// halfway through the job with money already gone.
//
// So: run the policy first, with no money and no session.
//
// This endpoint takes a proposed policy and the list of endpoints an agent
// intends to call, probes each endpoint for its real x402 price (a live 402
// challenge, not an estimate), and replays the whole sequence through the exact
// predicates the enforcer uses (api/_lib/pay/policy.js). It reports which calls
// would settle, which would be refused and by which rule, where the budget
// runs dry, and the smallest policy that would let every call through.
//
// Nothing is signed. No session is created. No credits are debited. No row is
// written. The only side effect is one unpaid HTTP request per unique endpoint,
// which is exactly what any x402 client does before it decides to pay.
import { cors, error, json, wrap, readJson, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { validatePublicUrl, isPrivateAddress } from '../_lib/ssrf.js';
import { isIP } from 'node:net';
import { probePrice, selectRail } from '../_lib/pay/probe.js';
import {
SESSION_LIMITS,
replay,
usdToAtomics,
atomicsToUsd,
canonicalizeAllowlist,
normalizeHost,
hostMatches,
canonicalizePerRailDaily,
resolveRailDailyCapAtomics,
} from '../_lib/pay/policy.js';
// A simulation fans out one request per unique endpoint. These bounds keep a
// single call from turning the platform into an amplifier.
const MAX_CALLS = 40;
const MAX_UNIQUE_URLS = 20;
const MAX_REPEAT = 500;
const PROBE_CONCURRENCY = 6;
const PROBE_TIMEOUT_MS = 10_000;
function bad(res, code, message, detail) {
return error(res, 400, code, message, detail);
}
/**
* Normalize the `calls` input.
*
* Accepts a bare string, `{url}`, or `{url, method, body, times, price_usd}`.
* `times` models the realistic case the naive version of this tool misses: an
* agent that polls one endpoint sixty times has a completely different budget
* profile from one that calls sixty endpoints once.
*/
export function parseCalls(raw) {
if (!Array.isArray(raw) || raw.length === 0) {
throw Object.assign(new Error('calls must be a non-empty array of endpoint URLs'), {
code: 'invalid_calls',
});
}
if (raw.length > MAX_CALLS) {
throw Object.assign(
new Error(`calls may contain at most ${MAX_CALLS} entries (received ${raw.length})`),
{ code: 'too_many_calls' },
);
}
const calls = raw.map((entry, i) => {
const spec = typeof entry === 'string' ? { url: entry } : (entry ?? {});
const url = String(spec.url ?? '').trim();
if (!url) {
throw Object.assign(new Error(`calls[${i}] has no url`), { code: 'invalid_calls' });
}
// `allowHttp: false` is passed explicitly rather than relying on the
// default, which relaxes to http outside production. This endpoint is
// unauthenticated and fetches caller-chosen URLs, so it holds the
// production rule everywhere instead of being laxer on a dev box.
let parsed;
try {
parsed = validatePublicUrl(url, { allowHttp: false });
} catch {
throw Object.assign(
new Error(`calls[${i}] must be a public https URL: ${url}`),
{ code: 'invalid_url' },
);
}
// A literal private address is refused here, before any DNS work. The
// probe path re-checks resolved addresses and pins them (api/_lib/ssrf.js),
// which is what catches a public hostname that resolves inward; this is the
// cheap first gate for the obvious `https://169.254.169.254/` case.
const literal = parsed.hostname.replace(/^\[|\]$/g, '');
const family = isIP(literal);
if (family && isPrivateAddress(literal, family)) {
throw Object.assign(
new Error(`calls[${i}] points at a private address: ${parsed.hostname}`),
{ code: 'invalid_url' },
);
}
const times = Math.max(1, Math.min(MAX_REPEAT, Math.round(Number(spec.times ?? 1)) || 1));
// price_usd lets a caller simulate an endpoint that is not live yet, or
// model a price change, without any network access at all.
const priceUsd =
spec.price_usd == null || spec.price_usd === ''
? null
: Number(spec.price_usd);
if (priceUsd !== null && (!Number.isFinite(priceUsd) || priceUsd < 0)) {
throw Object.assign(new Error(`calls[${i}].price_usd must be a non-negative number`), {
code: 'invalid_price',
});
}
return {
url,
method: String(spec.method ?? 'GET').toUpperCase() === 'POST' ? 'POST' : 'GET',
body: spec.body ?? null,
times,
label: spec.label ? String(spec.label).slice(0, 120) : null,
priceUsd,
};
});
const unique = new Set(calls.filter((c) => c.priceUsd === null).map((c) => `${c.method} ${c.url}`));
if (unique.size > MAX_UNIQUE_URLS) {
throw Object.assign(
new Error(`calls may reference at most ${MAX_UNIQUE_URLS} distinct endpoints to probe`),
{ code: 'too_many_endpoints' },
);
}
return calls;
}
/** Normalize the proposed policy, clamping to the real session-creation limits. */
export function parsePolicy(raw = {}) {
const notes = [];
const { MIN_BUDGET_USD, MAX_BUDGET_USD, MIN_TTL_SECONDS, MAX_TTL_SECONDS, MAX_ALLOWED_HOSTS } =
SESSION_LIMITS;
let budgetUsd = Number(raw.budget_usd);
if (!Number.isFinite(budgetUsd) || budgetUsd <= 0) {
// A blank or zero budget used to become $1 in silence, so the caller read a
// verdict computed against a budget they never proposed. Substituting is
// still the right move (there is nothing to simulate against $0), but the
// substitution has to be visible in the answer.
notes.push('budget_usd was missing or not a positive number, so the run was costed against $1');
budgetUsd = 1;
}
if (budgetUsd < MIN_BUDGET_USD) {
notes.push(`budget_usd raised to the $${MIN_BUDGET_USD} minimum a session accepts`);
budgetUsd = MIN_BUDGET_USD;
}
if (budgetUsd > MAX_BUDGET_USD) {
notes.push(`budget_usd lowered to the $${MAX_BUDGET_USD} maximum a session accepts`);
budgetUsd = MAX_BUDGET_USD;
}
let maxPerTxUsd =
raw.max_per_tx_usd == null || raw.max_per_tx_usd === '' ? null : Number(raw.max_per_tx_usd);
if (maxPerTxUsd !== null && (!Number.isFinite(maxPerTxUsd) || maxPerTxUsd <= 0)) {
maxPerTxUsd = null;
notes.push('max_per_tx_usd ignored: not a positive number');
}
if (maxPerTxUsd !== null && maxPerTxUsd > budgetUsd) {
notes.push('max_per_tx_usd exceeds the budget, so it can never bind');
}
const rawHosts = Array.isArray(raw.allowed_hosts)
? raw.allowed_hosts
: String(raw.allowed_hosts ?? '').split(/[\s,]+/);
let allowedHosts = [...new Set(canonicalizeAllowlist(rawHosts))];
if (allowedHosts.length > MAX_ALLOWED_HOSTS) {
notes.push(`allowed_hosts truncated to the ${MAX_ALLOWED_HOSTS}-entry maximum`);
allowedHosts = allowedHosts.slice(0, MAX_ALLOWED_HOSTS);
}
const rawBlocked = Array.isArray(raw.blocked_hosts)
? raw.blocked_hosts
: String(raw.blocked_hosts ?? '').split(/[\s,]+/);
let blockedHosts = [...new Set(canonicalizeAllowlist(rawBlocked))];
if (blockedHosts.length > MAX_ALLOWED_HOSTS) {
notes.push(`blocked_hosts truncated to the ${MAX_ALLOWED_HOSTS}-entry maximum`);
blockedHosts = blockedHosts.slice(0, MAX_ALLOWED_HOSTS);
}
let approvalThresholdUsd =
raw.approval_threshold_usd == null || raw.approval_threshold_usd === ''
? null
: Number(raw.approval_threshold_usd);
if (approvalThresholdUsd !== null && (!Number.isFinite(approvalThresholdUsd) || approvalThresholdUsd < 0.000001)) {
approvalThresholdUsd = null;
notes.push('approval_threshold_usd ignored: not a positive number');
}
// canonicalizePerRailDaily silently drops non-positive or unrecognized-network
// entries; this mirrors that leniency (matching what session creation itself
// does) but surfaces it as a note so a caller's typo is not silent here either.
const rawPerRailDaily = raw.per_rail_daily_usd && typeof raw.per_rail_daily_usd === 'object'
? raw.per_rail_daily_usd
: {};
const perRailDailyUsd = canonicalizePerRailDaily(rawPerRailDaily);
if (Object.keys(rawPerRailDaily).length > 0 && Object.keys(perRailDailyUsd).length === 0) {
notes.push('per_rail_daily_usd ignored: no valid network/amount entries');
}
let expirySeconds = Number(raw.expiry_seconds ?? 3600);
if (!Number.isFinite(expirySeconds)) expirySeconds = 3600;
expirySeconds = Math.min(MAX_TTL_SECONDS, Math.max(MIN_TTL_SECONDS, Math.round(expirySeconds)));
const network = String(raw.network ?? 'solana').toLowerCase() === 'base' ? 'base' : 'solana';
return {
budgetUsd,
maxPerTxUsd,
allowedHosts,
blockedHosts,
approvalThresholdUsd,
perRailDailyUsd,
expirySeconds,
network,
notes,
};
}
/** Probe the distinct endpoints, at bounded concurrency. */
async function priceEndpoints(calls, network) {
const keys = [...new Set(calls.filter((c) => c.priceUsd === null).map((c) => `${c.method} ${c.url}`))];
const byKey = new Map();
const queue = [...keys];
async function worker() {
for (;;) {
const key = queue.shift();
if (!key) return;
const call = calls.find((c) => `${c.method} ${c.url}` === key);
const probe = await probePrice(call.url, {
method: call.method,
body: call.body,
timeoutMs: PROBE_TIMEOUT_MS,
});
byKey.set(key, { probe, rail: probe.kind === 'priced' ? selectRail(probe.rails, network) : null });
}
}
await Promise.all(Array.from({ length: Math.min(PROBE_CONCURRENCY, keys.length) }, worker));
return byKey;
}
/**
* Expand each call spec into one priced step per repetition.
*
* A repeated call is expanded rather than multiplied because the budget check
* is per payment: 60 calls at $0.02 against a $1 budget is 50 settlements and
* 10 refusals, not one $1.20 refusal.
*/
export function buildSteps(calls, priced, network) {
const steps = [];
const problems = [];
for (const call of calls) {
const key = `${call.method} ${call.url}`;
let amountAtomics = null;
let pricing;
if (call.priceUsd !== null) {
amountAtomics = usdToAtomics(call.priceUsd);
pricing = { source: 'supplied', amount_usd: call.priceUsd, network: null };
} else {
const entry = priced.get(key);
const probe = entry?.probe;
if (!probe || probe.kind === 'error') {
problems.push({
url: call.url,
code: probe?.code ?? 'probe_failed',
message: probe?.message ?? 'Endpoint could not be priced',
});
pricing = {
source: 'unpriced',
amount_usd: null,
network: null,
error: probe?.code ?? 'probe_failed',
error_message: probe?.message ?? 'Endpoint could not be priced',
};
} else if (probe.kind === 'free') {
// api/pay/execute.js returns the response before touching the session
// when an endpoint answers without a 402. So a free call is never
// allowlist-checked, never capped, and never charged. Treating it as a
// $0 payment here would let the simulator report an allowlist refusal
// the real enforcer would never raise.
pricing = { source: 'free', amount_usd: 0, network: null, http_status: probe.status };
} else if (!entry.rail) {
const offered = [...new Set(probe.rails.map((r) => r.network).filter(Boolean))];
problems.push({
url: call.url,
code: 'no_rail_for_network',
message: `Endpoint charges on ${offered.join(', ') || 'an unknown network'} but this session settles on ${network}`,
});
pricing = {
source: 'unpriced',
amount_usd: null,
network: null,
error: 'no_rail_for_network',
error_message: `No ${network} payment option (offered: ${offered.join(', ') || 'none'})`,
networks_offered: offered,
};
} else if (entry.rail.amount_atomics === null) {
// describeRail reports a null price rather than guessing zero when a
// challenge quotes something that is not an integer of atomic units.
// Coercing that to 0n here would put a "settles for free" row in the
// timeline for a call the executor refuses outright.
problems.push({
url: call.url,
code: 'unreadable_price',
message: `Endpoint charges on ${entry.rail.network ?? network} but quoted a price that could not be read`,
});
pricing = {
source: 'unpriced',
amount_usd: null,
network: entry.rail.network,
error: 'unreadable_price',
error_message: 'Endpoint quoted a price that is not a whole number of atomic units',
};
} else {
amountAtomics = BigInt(entry.rail.amount_atomics);
pricing = {
source: 'probed',
amount_usd: entry.rail.amount_usd,
network: entry.rail.network,
pay_to: entry.rail.pay_to,
asset: entry.rail.asset,
rails_offered: probe.rails.length,
description: probe.description,
};
}
}
for (let i = 0; i < call.times; i++) {
steps.push({
url: call.url,
method: call.method,
label: call.label,
repetition: call.times > 1 ? i + 1 : null,
of: call.times > 1 ? call.times : null,
pricing,
// Only priced calls enter the replay. An unpriced call is excluded
// rather than treated as free, because charging it $0 would quietly
// inflate how far the budget goes; a free call is excluded because the
// enforcer never runs governance on it.
priceable: amountAtomics !== null,
free: pricing.source === 'free',
amountAtomics: amountAtomics ?? 0n,
});
}
}
return { steps, problems };
}
/**
* Work out the smallest policy that would have let every priceable call settle.
*
* This is the part a user cannot compute in their head: it needs the summed
* cost of the whole sequence, the largest single payment in it, and the exact
* set of hosts touched.
*/
export function recommend(steps, policy) {
const priceable = steps.filter((s) => s.priceable);
const totalAtomics = priceable.reduce((acc, s) => acc + s.amountAtomics, 0n);
const maxAtomics = priceable.reduce((acc, s) => (s.amountAtomics > acc ? s.amountAtomics : acc), 0n);
const hosts = [...new Set(priceable.map((s) => normalizeHost(s.url)).filter(Boolean))];
const covered = (host) =>
policy.allowedHosts.length === 0 || policy.allowedHosts.some((entry) => hostMatches(host, entry));
const missingHosts = hosts.filter((h) => !covered(h));
const { MIN_BUDGET_USD, MAX_BUDGET_USD } = SESSION_LIMITS;
// Round the recommended budget up to a whole cent: a budget of exactly the
// summed cost leaves no room for a price that moves between now and the run.
const exactUsd = atomicsToUsd(totalAtomics);
const roundedUsd = Math.min(MAX_BUDGET_USD, Math.max(MIN_BUDGET_USD, Math.ceil(exactUsd * 100) / 100));
return {
budget_usd: roundedUsd,
exact_cost_usd: exactUsd,
max_per_tx_usd: maxAtomics > 0n ? atomicsToUsd(maxAtomics) : null,
allowed_hosts: hosts,
missing_hosts: missingHosts,
network: policy.network,
expiry_seconds: policy.expirySeconds,
};
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', origins: '*' })) return;
if (req.method?.toUpperCase() !== 'POST') {
return error(res, 405, 'method_not_allowed', 'POST required');
}
// Unauthenticated on purpose: evaluating the governance model should not
// require an account, and the simulation cannot move money. It does make
// outbound requests, so it is rate limited like any other fan-out endpoint.
const rl = await limits.authIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
// The second argument is a byte limit, not the response object: passing `res`
// silently disabled the 1 MB cap, since every `length > [object]` compare is
// false. Returning without answering on a falsy body would hang the request.
const body = await readJson(req);
if (!body || typeof body !== 'object') {
return bad(res, 'invalid_body', 'a JSON object body is required');
}
let calls;
try {
calls = parseCalls(body.calls);
} catch (err) {
return bad(res, err.code ?? 'invalid_calls', err.message);
}
const policy = parsePolicy(body.policy ?? body);
const t0 = Date.now();
const priced = await priceEndpoints(calls, policy.network);
const { steps, problems } = buildSteps(calls, priced, policy.network);
// Replay only the calls that have a real price. The unpriced ones are
// reported separately so a probe failure never masquerades as a policy pass.
const replayInput = steps.filter((s) => s.priceable);
const expiresAt = new Date(Date.now() + policy.expirySeconds * 1000);
const { steps: verdicts, spentAtomics, remainingAtomics } = replay(
replayInput.map((s) => ({ url: s.url, amountAtomics: s.amountAtomics, ref: s })),
{
budgetAtomics: usdToAtomics(policy.budgetUsd),
maxPerTxAtomics: policy.maxPerTxUsd == null ? null : usdToAtomics(policy.maxPerTxUsd),
allowedHosts: policy.allowedHosts,
blockedHosts: policy.blockedHosts,
approvalThresholdAtomics: policy.approvalThresholdUsd == null ? null : usdToAtomics(policy.approvalThresholdUsd),
// A dry run has no live session, so the rolling rail window starts
// empty: railSpentAtomics defaults to 0 inside replay().
railDailyCapAtomics: resolveRailDailyCapAtomics(policy.network, policy.perRailDailyUsd),
status: 'active',
expiresAt,
},
);
const verdictByStep = new Map(verdicts.map((v) => [v.call.ref, v]));
let firstDenialIndex = null;
const timeline = steps.map((step, index) => {
const verdict = verdictByStep.get(step);
const outcome = step.free
? 'free'
: !step.priceable
? 'unpriced'
: verdict.allowed
? 'settles'
: 'refused';
if (outcome === 'refused' && firstDenialIndex === null) firstDenialIndex = index;
return {
index,
url: step.url,
host: normalizeHost(step.url),
method: step.method,
label: step.label,
repetition: step.repetition,
of: step.of,
outcome,
amount_usd: step.free ? 0 : step.priceable ? atomicsToUsd(step.amountAtomics) : null,
pricing: step.pricing,
rejected_by: verdict?.rejection?.code ?? null,
reason: verdict?.rejection?.message ?? null,
detail: verdict?.rejection?.detail ?? null,
remaining_after_usd: verdict ? atomicsToUsd(verdict.remainingAfterAtomics) : null,
};
});
const settled = timeline.filter((s) => s.outcome === 'settles');
const refused = timeline.filter((s) => s.outcome === 'refused');
const free = timeline.filter((s) => s.outcome === 'free');
const unpriced = timeline.filter((s) => s.outcome === 'unpriced');
// Group refusals by rule so the caller sees "the allowlist blocked 6 calls",
// not six near-identical rows they have to read one at a time.
const byRule = {};
for (const s of refused) byRule[s.rejected_by] = (byRule[s.rejected_by] ?? 0) + 1;
const suggestion = recommend(steps, policy);
const feasible = refused.length === 0 && problems.length === 0;
return json(res, 200, {
ok: true,
simulated: true,
note: 'Dry run only. Nothing was signed, no session was created, and no credits were spent.',
policy: {
budget_usd: policy.budgetUsd,
max_per_tx_usd: policy.maxPerTxUsd,
allowed_hosts: policy.allowedHosts,
blocked_hosts: policy.blockedHosts,
approval_threshold_usd: policy.approvalThresholdUsd,
per_rail_daily_usd: policy.perRailDailyUsd,
expiry_seconds: policy.expirySeconds,
network: policy.network,
notes: policy.notes,
},
verdict: {
feasible,
calls_total: timeline.length,
calls_settled: settled.length,
calls_refused: refused.length,
calls_free: free.length,
calls_unpriced: unpriced.length,
refusals_by_rule: byRule,
first_refusal_index: firstDenialIndex,
spend_usd: atomicsToUsd(spentAtomics),
remaining_usd: atomicsToUsd(remainingAtomics),
budget_used_pct:
policy.budgetUsd > 0
? Math.round((atomicsToUsd(spentAtomics) / policy.budgetUsd) * 1000) / 10
: 0,
},
timeline,
problems,
recommended_policy: suggestion,
// Ready to paste: the exact create call that would run this workload.
create_request: {
endpoint: 'POST /api/pay/session',
body: {
budget_usd: suggestion.budget_usd,
max_per_tx_usd: suggestion.max_per_tx_usd,
allowed_hosts: suggestion.allowed_hosts,
// recommend() only infers budget/cap/hosts from the priced call list.
// Blocked hosts, the approval threshold, and the rail cap are opt-in
// safety limits with no signal in the call list to infer them from,
// so the create call simply carries through whatever was simulated.
blocked_hosts: policy.blockedHosts,
approval_threshold_usd: policy.approvalThresholdUsd,
per_rail_daily_usd: policy.perRailDailyUsd,
expiry_seconds: suggestion.expiry_seconds,
network: suggestion.network,
},
},
duration_ms: Date.now() - t0,
});
});