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
// GET /api/x402/runway-lab
//
// The live seed for /economy-lab: everything the settle path's admission
// control depends on, read from the systems that actually enforce it.
//
// Nothing here is modelled or estimated where a real reading exists:
//
// • fee wallet + hard floor → ring-allowlist.js ringRoleWallets() and
// self-facilitator.js SPONSOR_SOL_FLOOR_LAMPORTS,
// the same constants the settle path enforces.
// • live SOL balance → Solana RPC through the platform's lane-failover
// connection, not a cached number.
// • governor config → wallet-fee-governor.js walletFeeGovernorConfig()
// over the running process env, so the lab shows
// what THIS deploy is configured with.
// • spent today → x402_self_facilitator_log, the exact SUM the
// meter itself runs (wallet-fee-meter.js).
// • fee per settle + demand → observed from the same log over 24h, so the
// projection starts from measured behaviour
// rather than a guessed arrival rate.
// • refusal mix → reject_reason histogram, bucketed by cause, so
// the page can show what the rail is ACTUALLY
// refusing next to what the model predicts.
//
// Read-only and unauthenticated by design: every field is already public
// through /api/x402-ring and /api/x402-status (balances of platform wallets,
// config thresholds, aggregate settle counts). No secret, no key material, and
// no per-user data is reachable from here.
import { cors, json, method, wrap } from '../_lib/http.js';
import { sql, isDbUnavailableError } from '../_lib/db.js';
import { PublicKey } from '@solana/web3.js';
import { solanaConnection } from '../_lib/solana/connection.js';
import { ringRoleWallets } from '../_lib/x402/ring-allowlist.js';
import { SPONSOR_SOL_FLOOR_LAMPORTS, SELF_FACILITATOR_ENABLED } from '../_lib/x402/self-facilitator.js';
import { walletFeeGovernorConfig } from '../_lib/x402/wallet-fee-governor.js';
import {
MIN_FEE_LAMPORTS,
LAMPORTS_PER_SOL,
equilibriumSettlesPerDay,
} from '../_lib/x402/runway-sim.js';
const WINDOW_HOURS = 24;
// Map a raw reject_reason to the cause an operator can act on. The reasons are
// prefixed strings with lamport detail appended (`fee_runway_exhausted:12+5>10`),
// so bucket on the prefix and keep one verbatim example per bucket.
function bucketReason(reason) {
const r = String(reason || '');
if (r.startsWith('fee_runway_exhausted')) return 'governor';
if (r.startsWith('fee_wallet_below_floor')) return 'floor';
if (r.startsWith('insufficient_lamports_for_fee')) return 'floor';
if (r.startsWith('amount_below_min_settle')) return 'dust_guard';
// Idempotency, not scarcity: the payment already landed and a retry hit the
// unique-signature guard (migration 20260729000000). Counted separately
// because folding it into the refusal total makes a healthy rail read as a
// starved one — on 2026-07-31 it was 3,470 of 9,504 "refusals".
if (r.startsWith('signature_already_settled')) return 'duplicate';
if (!r) return 'unspecified';
return 'other';
}
// Which buckets mean "the rail could not afford this settle". Duplicates and the
// dust guard are working-as-intended rejections, so the capacity view must not
// count them against admission.
const CAPACITY_CAUSES = new Set(['governor', 'floor']);
// Live SOL for one pubkey. A null result means "not read", never "zero" — the
// page must not draw a starvation conclusion from an RPC failure.
async function solLamportsOf(address) {
if (!address) return null;
try {
const connection = solanaConnection('mainnet');
return await connection.getBalance(new PublicKey(address), 'confirmed');
} catch {
return null;
}
}
// The meter's own query, verbatim in intent: today's summed fee burn for the
// fee wallet over successful settles.
async function spentTodayLamports(feeWallet) {
if (!feeWallet) return null;
const rows = await sql`
SELECT COALESCE(SUM(fee_lamports), 0)::bigint AS spent
FROM x402_self_facilitator_log
WHERE action = 'settle' AND ok = true
AND fee_payer = ${feeWallet}
AND ts >= date_trunc('day', now() at time zone 'utc')
`;
return Number(rows?.[0]?.spent ?? 0);
}
// Observed behaviour over the window: how often settles are attempted, how many
// land, what a landed settle costs, and why the rest were refused.
async function observeWindow() {
const since = new Date(Date.now() - WINDOW_HOURS * 3600_000).toISOString();
const [totals] = await sql`
SELECT
COUNT(*)::int AS attempts,
COUNT(*) FILTER (WHERE ok)::int AS settled,
COALESCE(SUM(fee_lamports) FILTER (WHERE ok), 0)::bigint AS fee_total,
COALESCE(
PERCENTILE_DISC(0.5) WITHIN GROUP (ORDER BY fee_lamports)
FILTER (WHERE ok AND fee_lamports > 0), 0)::bigint AS fee_median
FROM x402_self_facilitator_log
WHERE action = 'settle' AND ts >= ${since}
`;
// Group on the reason CLASS (the text before the first colon), not the whole
// string. Governor refusals carry their lamport arithmetic
// (`fee_runway_exhausted:8600843+10000>7509606`), so nearly every one is a
// distinct string; grouping on the full text under a row limit counted 391 of
// the 40,987 governor refusals on 2026-09-24 and reported a 92% capacity
// admission rate for a rail that was admitting 10%.
const reasons = await sql`
SELECT split_part(COALESCE(reject_reason, ''), ':', 1) AS reason_class,
COUNT(*)::int AS n,
(ARRAY_AGG(reject_reason ORDER BY ts DESC))[1] AS example
FROM x402_self_facilitator_log
WHERE action = 'settle' AND ok = false AND ts >= ${since}
GROUP BY 1
ORDER BY n DESC
`;
const buckets = new Map();
for (const row of reasons) {
const key = bucketReason(row.reason_class);
const hit = buckets.get(key) || { cause: key, count: 0, example: null };
hit.count += Number(row.n) || 0;
if (!hit.example) hit.example = row.example || null;
buckets.set(key, hit);
}
const attempts = Number(totals?.attempts ?? 0);
const settled = Number(totals?.settled ?? 0);
const feeMedian = Number(totals?.fee_median ?? 0);
const refusalList = [...buckets.values()].sort((a, b) => b.count - a.count);
// Capacity refusals only: what the rail could not AFFORD, as opposed to what
// it correctly declined. This is the number the projection is comparable to.
const capacityRefused = refusalList
.filter((b) => CAPACITY_CAUSES.has(b.cause))
.reduce((n, b) => n + b.count, 0);
const capacityAttempts = settled + capacityRefused;
return {
window_hours: WINDOW_HOURS,
attempts,
settled,
refused: attempts - settled,
capacity_refused: capacityRefused,
// Share of settles the rail could afford, excluding duplicates and the
// dust guard. Compare THIS against the simulated admission rate.
capacity_admission_rate: capacityAttempts > 0 ? settled / capacityAttempts : null,
admission_rate: attempts > 0 ? settled / attempts : null,
fee_total_lamports: Number(totals?.fee_total ?? 0),
// Median over landed settles is the honest per-settle cost: the mean is
// dragged by the occasional multi-signature transaction.
fee_lamports_observed: feeMedian > 0 ? feeMedian : MIN_FEE_LAMPORTS,
fee_source: feeMedian > 0 ? 'observed_median_24h' : 'base_fee_default',
// Real arrival rate, so the projection starts from measured demand rather
// than a guess. Duplicates are excluded: they are retries of a settle that
// already landed, not new demand on the rail.
//
// A rail that took fewer than 12 settles in 24 hours still took traffic, so
// the rate is clamped to 1 rather than rounded to 0. Reporting zero demand
// for a live-but-quiet rail is not a rounding artefact the caller can
// recover from: it reads as "nobody is paying", which is a different
// diagnosis entirely.
demand_per_hour: capacityAttempts > 0
? Math.max(1, Math.round(capacityAttempts / WINDOW_HOURS))
: 0,
refusals: refusalList,
};
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS' })) return;
if (!method(req, res, ['GET'])) return;
const roles = await ringRoleWallets();
// The wallet the governor actually meters is whichever one pays the fee. In
// sponsor mode that is the sponsor; the payer only pays its own fee when
// X402_RING_SELF_PAY is on, and the sponsor is still the shared-tenant wallet
// the starvation math is about.
const feeWallet = roles.sponsor || roles.payer || null;
const cfg = walletFeeGovernorConfig();
const [sponsorLamports, payerLamports] = await Promise.all([
solLamportsOf(feeWallet),
roles.payer && roles.payer !== feeWallet ? solLamportsOf(roles.payer) : Promise.resolve(null),
]);
let spent_today_lamports = null;
let observed = null;
let db_error = null;
try {
[spent_today_lamports, observed] = await Promise.all([
spentTodayLamports(feeWallet),
observeWindow(),
]);
} catch (err) {
// A DB outage must not blank the page: the config and the live balance are
// still enough to seed a projection, and the page says what is missing.
db_error = isDbUnavailableError(err) ? 'database_unavailable' : 'ledger_read_failed';
}
const spendable =
sponsorLamports != null ? Math.max(0, sponsorLamports - SPONSOR_SOL_FLOOR_LAMPORTS) : null;
json(res, 200, {
ok: true,
generated_at: new Date().toISOString(),
self_facilitator_enabled: SELF_FACILITATOR_ENABLED,
fee_wallet: {
role: roles.sponsor ? 'sponsor' : roles.payer ? 'payer' : null,
address: feeWallet,
sol_lamports: sponsorLamports,
sol: sponsorLamports != null ? sponsorLamports / LAMPORTS_PER_SOL : null,
spendable_lamports: spendable,
balance_read: sponsorLamports != null,
},
payer_wallet: roles.payer && roles.payer !== feeWallet
? { address: roles.payer, sol_lamports: payerLamports }
: null,
treasury: roles.treasury || null,
config: {
// The exact env names the lab emits a change command for.
floor_lamports: SPONSOR_SOL_FLOOR_LAMPORTS, // X402_SPONSOR_SOL_FLOOR_LAMPORTS
runway_days: cfg.runwayDays, // X402_WALLET_FEE_RUNWAY_DAYS
min_budget_lamports: cfg.minBudgetLamports, // X402_WALLET_FEE_MIN_BUDGET_LAMPORTS
governor_enabled: cfg.enabled, // X402_WALLET_FEE_GOVERNOR_ENABLED
spent_cache_ms: cfg.spentCacheMs,
},
meter: {
spent_today_lamports,
utc_hour: new Date().getUTCHours(),
},
// The closed-form throughput this configuration delivers at the live
// balance, so the headline number is available even before the browser
// runs a projection.
projected_settles_per_day:
spendable != null
? equilibriumSettlesPerDay({
spendableLamports: spendable,
feeLamports: observed?.fee_lamports_observed ?? MIN_FEE_LAMPORTS,
runwayDays: cfg.runwayDays,
minBudgetLamports: cfg.enabled ? cfg.minBudgetLamports : Number.MAX_SAFE_INTEGER,
})
: null,
observed,
db_error,
}, { 'Cache-Control': 'public, max-age=20, s-maxage=20' });
});