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-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.js
new file mode 100644
index 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.md
new file mode 100644
index 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.