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-preflight): let a buyer ask a seller whether it can settle before signing, with spec, SDK, MCP tool and page
nirholas76ce37101c78
diff --git a/api/_mcp3d/tools/preflight.js b/api/_mcp3d/tools/preflight.jsnew file mode 100644index 000000000..38e113753--- /dev/null+++ b/api/_mcp3d/tools/preflight.js@@ -0,0 +1,219 @@+// x402 Preflight — MCP tool.+//+// • x402_preflight(origin, network?) — FREE, read-only, public. Fetches any+// x402 seller's signed payability attestation, verifies the ed25519+// signature, the expiry and the subject, and answers the only question that+// matters before an agent spends: can this seller actually settle?+//+// This is the conversational surface of the same format the SDK and the CLI+// consume. An agent about to pay for a service can ask first, in one free call,+// and get a verdict it can act on: pay, pay on a different rail, or come back+// later. No wallet, no payment, no account, so it ships on the free track.+//+// The verification runs HERE, on the fetched bytes, using the same verifier the+// browser SDK uses. The tool never relays a seller's claim unchecked: an+// attestation that does not verify is reported as unverified, not as an outage+// and not as health.+//+// Spec: specs/x402-preflight.md. Client: packages/x402-preflight.++import { fetchSafePublicUrl } from '../../_lib/ssrf-guard.js';+import { verifyPreflight, networkVerdict, normalizeOrigin } from '../../_lib/x402/preflight.js';++const PREFLIGHT_PATH = '/.well-known/x402-preflight';+// An attestation is a small JSON document. Anything larger is not one, and+// reading it would just be an amplification vector.+const MAX_BYTES = 256 * 1024;+const TIMEOUT_MS = 6000;++function toolError(message, code) {+ return {+ content: [{ type: 'text', text: message }],+ structuredContent: { error: true, code: code || 'error', message },+ isError: true,+ };+}++// Plain sentences for a model to relay to a person. The enum is for code; this+// is what an agent should actually say out loud.+const REASON_COPY = {+ ok: 'settling normally',+ sponsor_below_floor:+ "the seller's own fee wallet cannot cover network fees, so nothing you sign can settle. Only the seller can fix this",+ settlement_degraded: 'recent settlements are failing, so a payment may not complete',+ facilitator_unreachable: 'the seller cannot reach its settlement facilitator, so it will not vouch for this rail',+ network_not_configured: 'the seller does not accept payment on this network',+ rail_unavailable: 'the payment rail itself is unavailable',+ unknown: 'the seller could not measure this rail, so it will not claim it works',+};++function describeSettle(s) {+ if (!s || s.rate == null) return 'no settled payments measured in the window';+ return `${(s.rate * 100).toFixed(1)}% of ${s.attempts} attempt(s) over ${s.window_hours}h (confidence ${s.confidence})`;+}++async function handlePreflight(args) {+ const origin = normalizeOrigin(args?.origin || '');+ if (!origin.startsWith('http')) {+ return toolError('Pass an origin such as https://three.ws', 'bad_origin');+ }+ const network = args?.network ? String(args.network) : null;++ let res;+ try {+ // SSRF-guarded: `origin` is caller-supplied and would otherwise be a+ // straightforward way to make the server fetch its own metadata service.+ res = await fetchSafePublicUrl(`${origin}${PREFLIGHT_PATH}`, {+ headers: { accept: 'application/json' },+ // A hung seller must not hold an agent's turn open.+ signal: AbortSignal.timeout(TIMEOUT_MS),+ });+ } catch (err) {+ return toolError(+ `Could not reach ${origin} to check whether it can settle: ${err?.message || err}. ` ++ 'Treat this seller as unverified rather than healthy.',+ 'unreachable',+ );+ }++ if (!res.ok) {+ const notSupported = res.status === 404;+ return {+ content: [+ {+ type: 'text',+ text: notSupported+ ? `${origin} does not publish an x402 preflight attestation. That is not a fault (preflight is ` ++ 'opt-in and most x402 sellers have not adopted it), but it does mean there is no way to know ' ++ 'whether it can settle before paying it.'+ : `${origin} answered HTTP ${res.status} for its preflight attestation. A seller that cannot sign ` ++ 'one is a seller you should not assume is healthy.',+ },+ ],+ structuredContent: {+ origin,+ supported: !notSupported,+ verified: false,+ status: res.status,+ code: notSupported ? 'not_supported' : 'unavailable',+ },+ };+ }++ let envelope;+ try {+ const buf = Buffer.from(await res.arrayBuffer());+ // An attestation is a small JSON document. Anything larger is not one, and+ // parsing it would only be an amplification vector.+ if (buf.length > MAX_BYTES) {+ return toolError(`${origin} returned ${buf.length} bytes, which is not a preflight attestation.`, 'too_large');+ }+ envelope = JSON.parse(buf.toString('utf8'));+ } catch {+ return toolError(`${origin} returned something that is not a preflight attestation.`, 'malformed');+ }++ const verification = verifyPreflight(envelope, { subject: origin });+ if (!verification.valid) {+ const expired = verification.reason === 'expired';+ return {+ content: [+ {+ type: 'text',+ text:+ `${origin} served an attestation that did not verify (${verification.reason}). ` ++ (expired+ ? 'It has already expired. Expiry is what stops a healthy report being replayed through an ' ++ 'outage, so an expired one carries no assurance at all.'+ : 'The document is signed but the signature does not match its contents. Treat this seller as ' ++ 'unverified.'),+ },+ ],+ structuredContent: { origin, supported: true, verified: false, reason: verification.reason },+ };+ }++ const report = envelope.report;+ const entries = Object.entries(report.networks || {});++ if (network) {+ const v = networkVerdict(envelope, network);+ const payable = v.payable === true;+ const lines = [+ `${origin} on ${network}: ${payable ? 'PAYABLE' : v.payable === false ? 'NOT PAYABLE' : 'UNKNOWN'}.`,+ `Why: ${REASON_COPY[v.reason] || v.reason}.`,+ ];+ if (!payable && v.alternates.length) lines.push(`It can settle on ${v.alternates.join(', ')} instead.`);+ if (!payable && v.retry_after) lines.push(`The seller suggests retrying in ${v.retry_after}s.`);+ return {+ content: [{ type: 'text', text: lines.join(' ') }],+ structuredContent: {+ origin,+ supported: true,+ verified: true,+ issuer: envelope.issuer,+ expires_at: report.expires_at,+ network,+ ...v,+ },+ };+ }++ const lines = [`${origin} published a verified attestation, signed by ${envelope.issuer}.`];+ for (const [id, n] of entries) {+ const state = n.payable === true ? 'PAYABLE' : n.payable === false ? 'NOT PAYABLE' : 'UNKNOWN';+ lines.push(` ${id}: ${state} — ${REASON_COPY[n.reason] || n.reason}; ${describeSettle(n.settle)}.`);+ }+ if (!report.payable_any) {+ lines.push('No network on this origin can settle right now. Do not sign a payment for it.');+ }++ return {+ content: [{ type: 'text', text: lines.join('\n') }],+ structuredContent: {+ origin,+ supported: true,+ verified: true,+ issuer: envelope.issuer,+ issued_at: report.issued_at,+ expires_at: report.expires_at,+ payable_any: report.payable_any,+ networks: report.networks,+ },+ };+}++export const toolDefs = [+ {+ name: 'x402_preflight',+ title: 'Check whether an x402 seller can actually settle before paying it',+ annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },+ description:+ 'Before paying any x402 endpoint, check whether that seller can currently SETTLE what it charges. ' ++ 'x402 tells you the price; it does not tell you whether the seller’s own fee wallet, facilitator and ' ++ 'payment rail can complete the transaction, and when they cannot you lose a signature and get a 502. ' ++ 'This fetches the seller’s signed payability attestation from /.well-known/x402-preflight, verifies the ' ++ 'ed25519 signature and its expiry, and returns payable / not payable / unknown per network, with the ' ++ 'reason, a suggested retry delay, and any other rail on the same seller that DOES work. Free, read-only, ' ++ 'no wallet or account. Works against any origin implementing the open x402-preflight/1 format.',+ inputSchema: {+ type: 'object',+ additionalProperties: false,+ required: ['origin'],+ properties: {+ origin: {+ type: 'string',+ format: 'uri',+ description: 'The seller origin to check, e.g. https://three.ws',+ },+ network: {+ type: 'string',+ description:+ 'Optional CAIP-2 network id to check specifically, e.g. solana:mainnet or eip155:8453. ' ++ 'Omit to get every network the seller offers.',+ },+ },+ },+ handler: (args) => handlePreflight(args),+ },+];diff --git a/specs/x402-preflight.md b/specs/x402-preflight.mdnew file mode 100644index 000000000..1e9a87173--- /dev/null+++ b/specs/x402-preflight.md@@ -0,0 +1,259 @@+# x402 Preflight, version 1++A signed, time-bounded statement that an x402 seller can currently **settle**+what it charges for.++This is a wire contract, not a tutorial. It is written so that an implementation+that has never seen three.ws code can serve and verify a conforming attestation.+The format is unencumbered: implement it, ship it, no permission required.++- Report profile: `x402-preflight/1`+- Envelope version: `threews.x402.preflight.v1`+- Well-known path: `/.well-known/x402-preflight`+- Reference implementation: [api/_lib/x402/preflight.js](../api/_lib/x402/preflight.js)+ (server), [packages/x402-preflight](../packages/x402-preflight) (client)+- Human page: [/preflight](https://three.ws/preflight) · guide: [docs/x402-preflight.md](../docs/x402-preflight.md)++---++## 1. The problem++x402 answers *what does this resource cost*. It has no way to answer *can this+seller complete the transaction it is charging for*. The two questions share a+happy path and diverge only after the buyer has already committed:++1. Client `GET`s a paid route and receives `402` with a price and accepts.+2. Client signs a transfer and retries with `X-PAYMENT`.+3. Server cannot settle. The client gets `502`, having burned a signature, a+ blockhash and two round trips.++In the sponsored-fee model the buyer's own funds are fine. The broken thing+belongs to the **seller** (an empty fee wallet, an unreachable facilitator, an+over-quota RPC), and the buyer has no way to see it before paying.++three.ws was that seller on 2026-08-28: the fee sponsor held 0.000899107 SOL+against a 0.02 SOL floor, and every transaction it fee-paid failed simulation+with `InsufficientFundsForRent`. 95 payment attempts, 0 settled, three hours.+Every one of those was predictable from state the server already had.++Preflight closes the gap the way CORS preflight closes its own: one cheap,+cacheable request before the expensive one, answered from state the server+already computes.++## 2. Serving an attestation++A conforming seller answers `GET /.well-known/x402-preflight` with+`application/json`.++Query parameters, all optional:++| Parameter | Meaning |+|---|---|+| `network` | CAIP-2 id. `404` with an `offered` array if this origin does not offer it. |+| `endpoint` | Path of a specific route, echoed into `report.endpoint`. |+| `ttl` | Requested validity in seconds. Clamped to the server's maximum. |++Responses:++| Status | Meaning |+|---|---|+| `200` | A signed envelope (§3). |+| `404` | This origin does not implement preflight, or does not offer the requested network. |+| `503` | The seller cannot sign right now. **It MUST NOT return an unsigned report.** An unsigned report is not an assurance, and a client that accepted one would be worse off than one that got nothing. |++The response SHOULD be cacheable for exactly the attestation's remaining+lifetime and no longer (`cache-control: public, max-age=<remaining>,+must-revalidate`). A shared cache serving it one second past expiry hands+clients a document that fails verification.++The endpoint MUST be free, unauthenticated, and cheap. An assurance check that+costs money or requires a key is one nobody calls, and one nobody calls prevents+nothing.++## 3. The envelope++```json+{+ "spec": "threews.x402.preflight.v1",+ "report": { "...": "see §4" },+ "issuer": "<base58 ed25519 public key>",+ "signedAt": "2026-08-28T03:14:15.926Z",+ "digest": "<sha256 hex>",+ "algorithm": "ed25519",+ "signature": "<base58 ed25519 signature>"+}+```++### 3.1 Canonicalization++The digest is taken over a canonical JSON encoding of+`{ report, issuer, signedAt }`:++- object keys sorted lexicographically, recursively+- properties whose value is `undefined` omitted+- no insignificant whitespace+- arrays keep their order++Signer and verifier MUST produce byte-identical input. This is the one+representation that may be hashed.++### 3.2 Digest and signature++```+digest = sha256_hex(canonical({ report, issuer, signedAt }))+message = utf8("threews.x402.preflight.v1:" + digest)+signature = base58(ed25519_sign(message, secret_key))+```++The envelope version is mixed into the signed message as a **domain separator**.+Without it, a signature produced for a preflight report could be replayed as+some other statement signed by the same identity.++`ed25519` is the only defined algorithm. A verifier MUST reject any other value+rather than ignoring the field.++## 4. The report++```json+{+ "$schema": "https://three.ws/schemas/x402-preflight/1.json",+ "spec": "x402-preflight/1",+ "subject": "https://three.ws",+ "issued_at": "2026-08-28T03:14:15.926Z",+ "expires_at": "2026-08-28T03:15:15.926Z",+ "payable_any": true,+ "networks": {+ "solana:mainnet": {+ "payable": false,+ "reason": "sponsor_below_floor",+ "retry_after": 300,+ "settle": { "rate": 0.0, "attempts": 95, "window_hours": 3, "confidence": 0.9 },+ "alternates": ["eip155:8453"],+ "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",+ "pay_to": "<recipient>"+ }+ }+}+```++| Field | Rule |+|---|---|+| `subject` | The origin this report speaks for. A verifier that knows which origin it asked MUST check it. |+| `issued_at` / `expires_at` | RFC 3339. Validity SHOULD be short (this implementation defaults to 60s, caps at 300s). |+| `networks` | Keyed by CAIP-2 id, the same identifier the `402` challenge uses, so a verdict maps to an accept without a translation table. |+| `payable_any` | True when at least one network is payable. Convenience only; it is inside the signature. |++### 4.1 `payable` is three-valued++`true`, `false`, or `"unknown"`. **A seller that cannot determine its own state+MUST answer `"unknown"` and MUST NOT answer `true`.**++This asymmetry is the safety property of the whole format. A client acting on+`true` makes an irreversible transfer, so a false `true` is expensive and a+false `"unknown"` costs a retry. Every failure path in a conforming+implementation degrades to `"unknown"`.++Clients SHOULD treat `"unknown"` as not payable by default.++### 4.2 `reason`++Machine-readable. Clients switch on it, so values may be added but never+repurposed.++| Reason | Meaning |+|---|---|+| `ok` | Settling normally. |+| `sponsor_below_floor` | The seller's fee wallet cannot pay network fees. **No buyer action can fix this.** |+| `settlement_degraded` | Recent settlements are failing. |+| `facilitator_unreachable` | The seller cannot reach its settlement facilitator. |+| `network_not_configured` | This origin does not accept payment on this network. |+| `rail_unavailable` | The payment rail itself is unavailable. |+| `unknown` | Not measurable right now. |++### 4.3 `settle`: a rate is never reported without its window++`{ rate, attempts, window_hours, confidence }`.++A rate without the sample behind it is a rumour. A seller that settled 3 of 3+payments overnight reports `rate: 1.0`, which is indistinguishable from a proven+rail unless `attempts` travels with it. `confidence` is derived from the sample+alone and is capped below `1`, because no finite sample proves the next payment+settles.++### 4.4 `alternates` and `retry_after`++`alternates` lists the other networks on **this same origin** that are payable,+so a client whose preferred rail is down re-routes within the same round trip+instead of discovering the outage one failed payment at a time. It is computed+by the server and covered by the signature so every consumer agrees on the same+fallback set.++`retry_after` is advisory back-off in seconds, so a fleet of agents meeting an+unpayable seller backs off instead of synchronising into a retry storm.++## 5. Verification (normative)++A verifier MUST perform all of these, and MUST NOT expose the report body to+application code unless every one passes:++1. `spec` equals `threews.x402.preflight.v1`.+2. `algorithm`, if present, equals `ed25519`.+3. `issuer`, `signature` and `signedAt` are present.+4. `report.spec` equals `x402-preflight/1`.+5. Recompute the digest from the report bytes; if `digest` is present it MUST+ match. This catches a body edited after signing before any curve arithmetic+ runs.+6. The signature verifies against `issuer` over the domain-separated message.+7. `report.expires_at` parses, and **now is not past it**, allowing a bounded+ clock skew (this implementation: 30s).+8. `report.issued_at`, if present, is not in the future beyond that same skew.+9. If the caller named an origin, `report.subject` matches it after+ normalization (scheme + host, case-insensitive, trailing slash ignored).++### 5.1 Expiry is part of verification, not a caller's responsibility++An expired attestation is **not** a valid one that happens to be old. Treating+it as valid is precisely the replay the format exists to prevent: a seller could+serve a cached healthy attestation straight through an outage. Verification that+returns "valid, but check the date yourself" will eventually be used by someone+who does not.++### 5.2 Verification never throws++A conforming verifier returns a verdict for every input, including `null`,+non-objects and hostile bodies. A paying agent's loop must not be crashable by a+malformed response from a seller.++## 6. What this format does NOT promise++Stated plainly, because an assurance format that oversells itself is worse than+none:++- **It is not a guarantee.** It is the seller's signed, timestamped best+ assessment. A seller can be wrong, and a rail can fail in the seconds after it+ signs.+- **It is not a reputation system.** It reports current settleability, not+ honesty, quality or history. It is an input a reputation system could use.+- **It does not protect against a malicious seller lying.** It makes lying+ *attributable*: a signed statement, bound to an instant, that the seller+ believed it could settle. In a marketplace of autonomous agents transacting+ with strangers, that is the difference between "it broke" and "you said it+ would work".++## 7. Adopting it++The wire format is deliberately small enough to implement in an afternoon+against any x402 server:++1. Generate an ed25519 keypair. Publish the public key wherever you already+ publish identity (a DID document, an agent card, a `.well-known` file).+2. Answer `GET /.well-known/x402-preflight` with a signed envelope built from+ whatever settlement health you already measure. If you measure nothing yet,+ report `"unknown"`. That is honest and still useful: a client learns you are+ not claiming health you cannot back up.+3. Keep the TTL short. A long TTL is not a stronger assurance, it is a weaker+ one.++Clients need no coordination with you: `@three-ws/x402-preflight` verifies any+conforming attestation from any origin, and passes through sellers that do not+publish one, so adoption is incremental in both directions.