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
feat(x402): report what an x402scan registration would do before signing
nirholas39a61d32cec6
diff --git a/docs/ops/x402-discovery-listings.md b/docs/ops/x402-discovery-listings.mdindex 8a3f8ba81..a85a6ba1a 100644--- a/docs/ops/x402-discovery-listings.md+++ b/docs/ops/x402-discovery-listings.md@@ -21,6 +21,7 @@ sells ranking.| Facilitator endpoints we query/settle through | `api/_lib/x402/bazaar-client.js` — PayAI (Base default), CDP (`api.cdp.coinbase.com/platform/v2/x402`), self-facilitator for Solana (`api/_lib/x402/self-facilitator.js`) || Per-agent A2A agent cards | `/a/sol/:id/.well-known/agent-card.json` || Env-overridable prices | `api/_lib/x402-prices.js` (`X402_PRICE_<SLUG>`) |+| Preview of what an x402scan registration run would add or deprecate | `scripts/x402scan-registration-gap.mjs` (`npm run preview:x402scan-registration`) |## 1. x402scan (x402scan.com) — Merit Systems@@ -61,7 +62,13 @@ metadata (og-tags, favicon) on the resource page, so those must be clean.its live 402 is. Since 2026-09-02 every paid service in`api/_lib/service-catalog/` is projected into it automatically(`catalogPaidPaths()` in `api/openapi-json.js`), guarded by- `tests/openapi-aggregator.test.js`.+ `tests/openapi-aggregator.test.js`, and live in production since the+ 2026-09-08 deploy.+- Preview the run before spending the signature: `npm run+ preview:x402scan-registration` reproduces their classify/probe/deprecate+ pipeline against live production and prints what would be added, what would+ fail its probe, and (the one result that should stop a run) what would be+ deprecated.- Solana volume needs no third party: since PR #1032 merged, x402scanattributes our own facilitator's settlements to us directly (section 7).Routing through the CDP facilitator is the separate, additive Base leg that@@ -311,6 +318,75 @@ The path to being counted, all Solana, no Base required:## Registration log+**2026-09-09: the deploy landed; registration is the only step left.** The+`catalogPaidPaths()` fix shipped (production commit `880bdcef8`, revision+`three-ws-api-00418-j26`), so `/openapi.json` now declares 82 paid+`/api/x402/*` paths where it declared 24. Re-measured the same day against live+production, no credentials used.++Ran x402scan's own discovery library (`@agentcash/discovery`+`discoverOriginSchema`) against `https://three.ws`: source `openapi`, 123+endpoints, of which 83 are `/api/x402/*`. It classifies 82 of those as `paid`+with the correct price and `pricingMode: fixed`. The one exception is correct+rather than a defect: `GET /api/x402/forge` is genuinely free price discovery+(`security: []`, no `x-payment-info`) and reads as `unprotected`, exactly+matching the free row already listed beside the paid `POST /api/x402/forge`.++This settles a question worth settling before a signature is spent: every paid+operation declares `security: []`, and `x-payment-info` overrides it, so our+paid endpoints register as paid rows and not as free "Public" catalog rows.++**What a registration run would do now** (`npm run preview:x402scan-registration`,+which reproduces their classify/probe/deprecate pipeline and agrees with their+library endpoint for endpoint):++| Outcome | Count |+|---|---|+| Registrable endpoints declared in `/openapi.json` | 123 |+| Already listed on the origin page | 63 |+| Rows the run would add | 60 |+| Rows the run would deprecate | **0** |+| Of the 60 new, answer a spec-valid 402 to a bare probe | 59 |++The zero is the safety property: the run is purely additive and cannot drop or+deprecate any of the 63 rows already listed. Run the preview again immediately+before registering, because a `/openapi.json` change is what would turn that+zero into a real deprecation.++The single endpoint that will not probe-register is `GET+/api/x402/vanity-premium`, and that is by design. A bare GET browses the+premium inventory for free; only `?address=<base58>` triggers the 402. Their+probe fills required query params only, and `address` is genuinely optional, so+the probe sees the free mode. Marking it required in the spec to force a+registration would be a lie about the route. It stays unlisted until the+inventory is worth a dedicated listing.++Also deliberately unlisted: `ring-settle` and `three-buy`. Both answer a valid+402 in production but carry `discoverable: false` and are absent from the+service catalog on purpose, so `catalogPaidPaths()` never projects them. They+are internal ring machinery, and listing them would let dogfooded volume+masquerade as organic third-party demand. Leave them out.++**Correction to the 2026-09-02 entry below.** It recorded five endpoints as+answering 503 `settlement_unavailable` instead of a 402 while the sponsor+wallet sits under its SOL settle floor, and therefore unregisterable. That is+no longer true. Re-probed 2026-09-09: `dance-tip`, `feed-health` and+`spend-session` all answer a spec-valid 402 advertising both USDC and $THREE on+Solana mainnet, so they are probe-registerable today; `ring-settle` and+`three-buy` also answer 402 but stay unlisted for the reason above. The floor+still bites at settle time rather than at challenge time+(`/api/healthz` reports `x402.self_facilitator.settle` at 84 ok / 366 failed,+every failure `fee_wallet_below_floor`), which is work order 01's capital+problem and not a listing problem.++**Remaining step, owner-gated:** one SIWX wallet signature at+<https://www.x402scan.com/resources/register>, "Add API" for origin+`https://three.ws`. It binds an identity and moves no funds. The alternative+their repo exposes, the paid `registry-register` x402 endpoint, registers one+URL per settled payment and would need 60 payments, so the bulk SIWX flow is+strictly better.++**2026-09-02: re-verification after the facilitator merge (measured, nocredentials used).** PR #1032 merged 2026-08-11 with zero reviews, so thereviewer-verification comment that blocked this for six weeks was never needed.diff --git a/scripts/x402scan-registration-gap.mjs b/scripts/x402scan-registration-gap.mjsnew file mode 100644index 000000000..de483c4af--- /dev/null+++ b/scripts/x402scan-registration-gap.mjs@@ -0,0 +1,223 @@+#!/usr/bin/env node+// scripts/x402scan-registration-gap.mjs+//+// Answers one question before anyone spends an owner wallet signature on+// https://www.x402scan.com/resources/register: what would that registration+// actually do to our origin listing?+//+// x402scan's "Add API" flow reads our /openapi.json, classifies every operation+// into an auth mode, probes the ones it treats as payable, and writes the+// survivors as resource rows keyed by (url, method). Anything already listed+// that the document no longer declares gets DEPRECATED in the same pass, so a+// registration run is not automatically additive and is worth previewing.+//+// This script reproduces that pipeline against live production:+//+// 1. Classify /openapi.json operations exactly the way @agentcash/discovery+// does: an operation carrying `x-payment-info` is `paid`; an+// explicit `security: []` without it is `unprotected`; a declared+// apiKey scheme is `apiKey`. Verified against that library's own+// output on 2026-09-09 (123 endpoints, identical classification).+// 2. Read the resource rows already on our x402scan origin page.+// 3. Probe every declared-but-unlisted endpoint the way their registrar+// does (bare request, minimal required query params) and report+// whether it answers a spec-valid 402.+// 4. Report new / already-listed / would-deprecate / would-fail.+//+// Exit code is 0 whenever the preview succeeds, 1 only when the document or the+// origin page could not be read. A non-empty "would deprecate" list is the one+// result that should stop a registration run.+//+// Usage:+// node scripts/x402scan-registration-gap.mjs+// node scripts/x402scan-registration-gap.mjs --base=http://localhost:3000+// node scripts/x402scan-registration-gap.mjs --json+// node scripts/x402scan-registration-gap.mjs --no-probe # classify only, no traffic++const args = process.argv.slice(2);+const argValue = (name) => args.find((a) => a.startsWith(`${name}=`))?.slice(name.length + 1) || null;++const base = (argValue('--base') || 'https://three.ws').replace(/\/$/, '');+const originId = argValue('--origin-id') || '17cbd874-52ac-4920-a020-b22ff2489a07';+const asJson = args.includes('--json');+const skipProbe = args.includes('--no-probe');++const PROBE_TIMEOUT_MS = 30_000;+const PROBE_CONCURRENCY = 6;+const METHODS = ['get', 'post', 'put', 'patch', 'delete'];++async function fetchJson(url) {+ const res = await fetch(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });+ if (!res.ok) throw new Error(`${url} answered ${res.status}`);+ return res.json();+}++// Mirrors @agentcash/discovery's OpenAPI auth-mode assignment. `x-payment-info`+// wins over the security list, which is why our paid operations register as paid+// rows despite declaring `security: []` (payment, not a credential, gates them).+function authModeFor(operation, securitySchemes) {+ if (operation['x-payment-info']) {+ return declaresApiKey(operation.security, securitySchemes) ? 'apiKey+paid' : 'paid';+ }+ if (Array.isArray(operation.security)) {+ if (operation.security.length === 0) return 'unprotected';+ if (declaresApiKey(operation.security, securitySchemes)) return 'apiKey';+ }+ return undefined;+}++function declaresApiKey(security, securitySchemes) {+ if (!Array.isArray(security)) return false;+ return security.some((requirement) =>+ Object.keys(requirement || {}).some((name) => securitySchemes[name]?.type === 'apiKey')+ );+}++// Their registrar only writes rows for these modes; anything else is skipped.+const REGISTRABLE = new Set(['paid', 'apiKey+paid', 'siwx', 'unprotected', 'apiKey']);++function declaredEndpoints(spec) {+ const securitySchemes = spec.components?.securitySchemes || {};+ const out = [];+ for (const [path, item] of Object.entries(spec.paths || {})) {+ for (const method of METHODS) {+ const operation = item?.[method];+ if (!operation) continue;+ const authMode = authModeFor(operation, securitySchemes);+ if (!REGISTRABLE.has(authMode)) continue;+ out.push({+ path,+ method: method.toUpperCase(),+ authMode,+ price: operation['x-payment-info']?.price?.amount || null,+ // Their probe only fills query params the spec marks required, so an+ // endpoint whose paid mode hides behind an optional param cannot be+ // reached by a bare probe. Carry them to explain such a failure.+ requiredQuery: (operation.parameters || [])+ .filter((p) => p?.in === 'query' && p.required)+ .map((p) => p.name),+ });+ }+ }+ return out;+}++// The origin page streams its resource rows inside the RSC payload. Read the+// (resource, method) pairs out of it rather than guessing from our own document.+async function listedRows() {+ const url = `https://www.x402scan.com/server/${originId}`;+ const res = await fetch(url, {+ headers: { 'user-agent': 'three-ws-registration-gap/1.0' },+ signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),+ });+ if (!res.ok) throw new Error(`${url} answered ${res.status}`);+ const html = await res.text();+ const rows = new Map();+ const pattern = /\\"resource\\":\\"([^\\"]+)\\",\\"method\\":\\"(\w+)\\"(.{0,600}?)\\"deprecatedAt\\":(null|\\"[^\\"]*\\")/g;+ for (const match of html.matchAll(pattern)) {+ const [, resource, method, , deprecatedAt] = match;+ if (!resource.startsWith(base)) continue;+ rows.set(`${resource.slice(base.length)} ${method}`, { deprecated: deprecatedAt !== 'null' });+ }+ if (rows.size === 0) throw new Error(`no resource rows parsed from ${url} (their page format may have changed)`);+ return rows;+}++async function probe(endpoint) {+ const url = new URL(base + endpoint.path);+ for (const name of endpoint.requiredQuery) url.searchParams.set(name, 'probe');+ const init = {+ method: endpoint.method,+ headers: { 'user-agent': 'three-ws-registration-gap/1.0' },+ signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),+ };+ if (endpoint.method !== 'GET' && endpoint.method !== 'HEAD') {+ init.headers['content-type'] = 'application/json';+ init.body = '{}';+ }+ try {+ const res = await fetch(url, init);+ if (res.status !== 402) return { status: res.status, valid: false, reason: `answered ${res.status}, not 402` };+ const body = await res.json().catch(() => null);+ const accepts = Array.isArray(body?.accepts) ? body.accepts : [];+ if (accepts.length === 0) return { status: 402, valid: false, reason: '402 carried no accepts[]' };+ const networks = [...new Set(accepts.map((a) => a?.network).filter(Boolean))];+ return { status: 402, valid: true, networks };+ } catch (err) {+ return { status: null, valid: false, reason: err instanceof Error ? err.message : String(err) };+ }+}++async function mapWithConcurrency(items, worker, limit) {+ const results = new Array(items.length);+ let next = 0;+ const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {+ while (true) {+ const index = next++;+ if (index >= items.length) return;+ results[index] = await worker(items[index]);+ }+ });+ await Promise.all(runners);+ return results;+}++async function main() {+ const spec = await fetchJson(`${base}/openapi.json`);+ const declared = declaredEndpoints(spec);+ const listed = await listedRows();++ const key = (e) => `${e.path} ${e.method}`;+ const declaredKeys = new Set(declared.map(key));++ const unlisted = declared.filter((e) => !listed.has(key(e)));+ const already = declared.filter((e) => listed.has(key(e)));+ const wouldDeprecate = [...listed.keys()].filter((k) => !declaredKeys.has(k) && !listed.get(k).deprecated);++ // Only payable modes get probed; free catalog rows register without one.+ const toProbe = skipProbe ? [] : unlisted.filter((e) => e.authMode === 'paid' || e.authMode === 'apiKey+paid');+ const probes = await mapWithConcurrency(toProbe, async (e) => ({ endpoint: e, result: await probe(e) }), PROBE_CONCURRENCY);+ const failing = probes.filter((p) => !p.result.valid);++ const report = {+ base,+ originId,+ declaredRegistrable: declared.length,+ alreadyListed: already.length,+ newRows: unlisted.length,+ wouldDeprecate,+ probed: probes.length,+ probeFailures: failing.map((p) => ({ path: p.endpoint.path, method: p.endpoint.method, reason: p.result.reason })),+ newEndpoints: unlisted.map((e) => ({ path: e.path, method: e.method, authMode: e.authMode, price: e.price })),+ };++ if (asJson) {+ console.log(JSON.stringify(report, null, 2));+ return;+ }++ console.log(`x402scan registration preview for ${base}`);+ console.log(` declared registrable in /openapi.json : ${report.declaredRegistrable}`);+ console.log(` already listed on the origin page : ${report.alreadyListed}`);+ console.log(` would be added : ${report.newRows}`);+ console.log(` would be deprecated : ${wouldDeprecate.length}`);+ if (wouldDeprecate.length > 0) {+ console.log('\n STOP: registering now would deprecate these listed rows:');+ for (const k of wouldDeprecate.sort()) console.log(` ${k}`);+ }+ if (!skipProbe) {+ console.log(`\n probed ${report.probed} payable endpoints: ${report.probed - failing.length} answer a valid 402, ${failing.length} do not`);+ for (const p of failing) console.log(` ${p.endpoint.method} ${p.endpoint.path}: ${p.result.reason}`);+ }+ if (report.newRows > 0) {+ console.log('\n new rows this run would add:');+ for (const e of report.newEndpoints) {+ console.log(` ${e.method.padEnd(4)} ${e.path}${e.price ? ` $${e.price}` : ''} [${e.authMode}]`);+ }+ }+}++main().catch((err) => {+ console.error(`x402scan-registration-gap: ${err instanceof Error ? err.message : String(err)}`);+ process.exitCode = 1;+});