Skip to content

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.

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.md
index 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, x402scan
attributes 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, no
credentials used).** PR #1032 merged 2026-08-11 with zero reviews, so the
reviewer-verification comment that blocked this for six weeks was never needed.
diff --git a/scripts/x402scan-registration-gap.mjs b/scripts/x402scan-registration-gap.mjs
new file mode 100644
index 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;
+});