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
docs(x402): document the preflight surface a buyer checks before it signs
nirholasb87fd5207791
diff --git a/docs/x402-preflight.md b/docs/x402-preflight.mdnew file mode 100644index 000000000..6f0a23bb2--- /dev/null+++ b/docs/x402-preflight.md@@ -0,0 +1,198 @@+# x402 Preflight++**Ask an x402 seller whether it can actually settle, before you sign anything.**++- Try it: [three.ws/preflight](https://three.ws/preflight)+- Live attestation: [three.ws/.well-known/x402-preflight](https://three.ws/.well-known/x402-preflight)+- Client: [`@three-ws/x402-preflight`](../packages/x402-preflight)+- Wire contract: [specs/x402-preflight.md](../specs/x402-preflight.md)++---++## The gap this closes++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 committed:++1. Your agent `GET`s a paid route and gets `402` with a price.+2. Your agent signs a USDC transfer and retries with `X-PAYMENT`.+3. The seller cannot settle. Your agent gets `502`, having burned a signature, a+ blockhash and two round trips.++In the sponsored-fee model **your funds were never the problem**. The broken+thing belongs to the seller: an empty fee wallet, an unreachable facilitator, an+over-quota RPC. You had no way to see any of it before paying.++We know because we were the broken seller. On 2026-08-28 the three.ws fee sponsor+held 0.000899107 SOL against a 0.02 SOL floor, which is 0.0000082 SOL of+spendable headroom, less than two transaction fees. Every transaction it fee-paid+died at simulation with `InsufficientFundsForRent`. **95 payment attempts, 0+settled, three hours.** Every one of those was predictable from state our server+already had and was not publishing.++So we published it, signed it, and wrote the client that reads it.++## Using it++### From an agent++```bash+npm i @three-ws/x402-preflight+```++```js+import { guardedFetch } from '@three-ws/x402-preflight';++// A drop-in fetch that will not spend your money on a seller who cannot deliver.+const fetch402 = guardedFetch({ prefer: ['solana:mainnet'] });++await fetch402('https://three.ws/api/x402/echo');+```++Before the request that could trigger payment, the seller's attestation is+fetched once (cached for its own lifetime), verified offline, and either the+request goes through on a rail that works, or it throws before your agent signs+anything.++Want the verdict rather than the guard:++```js+import { assertPayable, PreflightError } from '@three-ws/x402-preflight';++try {+ await assertPayable('https://three.ws', 'solana:mainnet');+} catch (err) {+ if (err instanceof PreflightError) {+ err.reason; // 'sponsor_below_floor'+ err.alternates; // ['eip155:8453'] <- pay here instead+ err.retryAfter; // 300 <- or come back in 5 minutes+ }+}+```++### From a terminal++```bash+npx @three-ws/x402-preflight https://three.ws+```++```+https://three.ws signed by 87ZCUMTEaXopUJtQoaFcrk7TrxJBtfd4F9RvkqgrQ4Bc+ attestation verified, valid for another 60s++ NOT PAYABLE solana:mainnet+ reason sponsor_below_floor+ settle 0.0% of 76 attempts over 3h (confidence 0.88)+ retry after 300s+```++The exit code is the answer, so it composes: `0` payable, `1` verified and not+payable, `2` unverifiable.++```bash+npx @three-ws/x402-preflight https://three.ws --network solana:mainnet && ./pay.sh+```++### From a conversation++The MCP tool `x402_preflight` is free, read-only, and needs no wallet or account.+Any agent connected to the three.ws MCP server can ask about **any** origin:++> Before you pay that endpoint, check whether it can settle.++It returns the verdict per network with the reason in plain language, the+suggested retry delay, and any other rail on the same seller that does work.++### From a browser++[three.ws/preflight](https://three.ws/preflight) checks any origin you paste and+verifies the signature **in your browser**, not on our server. A status page you+have to trust is worth nothing; this one you can check with devtools open.++## What you get back++```json+{+ "solana:mainnet": {+ "payable": false,+ "reason": "sponsor_below_floor",+ "retry_after": 300,+ "settle": { "rate": 0.0, "attempts": 76, "window_hours": 3, "confidence": 0.88 },+ "alternates": ["eip155:8453"]+ }+}+```++**`payable` is three-valued**: `true`, `false`, or `"unknown"`. A seller that+cannot determine its own state must answer `"unknown"` and must never answer+`true`. That asymmetry is the safety property of the format: acting on `true`+means an irreversible transfer, so a false `true` is expensive and a false+`"unknown"` costs a retry. Clients treat `"unknown"` as not payable by default.++**Every rate carries its window and sample.** A seller that settled 3 of 3+payments overnight reports 100%, which is indistinguishable from a proven rail+unless `attempts` travels with it. `confidence` is derived from the sample alone+and is capped below `1`.++**`alternates`** names the other networks on the same seller that are payable, so+your agent re-routes in the same round trip instead of discovering the outage one+failed payment at a time.++## Why it is signed++An unsigned health endpoint is a courtesy. A signed, time-bounded one is+evidence, and three properties follow that a status page cannot give you:++- **Attributable.** A client that paid after reading `payable: true` holds a+ statement signed by the seller's own key saying the seller believed it could+ settle, at a stated instant. Between autonomous agents transacting with+ strangers, that is the difference between "it broke" and "you said it would+ work".+- **Unreplayable.** Every attestation carries `expires_at`, and verification+ *rejects* an expired one. A seller cannot serve a cached healthy attestation+ through an outage.+- **Relayable.** Because it verifies offline against a public key, a registry or+ an index can cache and forward attestations without becoming trusted.+ Discovery can rank sellers by measured settleability rather than by+ self-description.++Verification checks the signature, re-derives the digest from the report bytes,+enforces expiry and rejects a future timestamp, and pins the subject to the+origin you asked about. All of it happens before any field is readable, because+a check a caller can forget is one that will be forgotten.++## Serving one from your own endpoint++The format is open and unencumbered. Nothing routes through three.ws, and a+client needs no coordination with you.++1. Generate an ed25519 keypair; publish the public key wherever you already+ publish identity.+2. Answer `GET /.well-known/x402-preflight` with a signed envelope built from+ whatever settlement health you already measure.+3. Keep the TTL short. A long TTL is a weaker assurance, not a stronger one.++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.++The full normative contract, including the canonicalization rules and the+verification steps a conforming client must perform, is in+[specs/x402-preflight.md](../specs/x402-preflight.md). The reference server is+[api/x402/preflight.js](../api/x402/preflight.js) and the pure format core is+[api/_lib/x402/preflight.js](../api/_lib/x402/preflight.js), both under 300+lines.++## What it does not promise++- **Not a guarantee.** It is the seller's signed, timestamped best assessment. A+ rail can fail in the seconds after it signs.+- **Not a reputation system.** It reports current settleability, not honesty or+ history. It is an input a reputation system could use.+- **It does not stop a seller lying.** It makes lying attributable.++## Related++- [docs/x402.md](x402.md) walks the payment flow itself.+- [docs/mcp.md](mcp.md) covers connecting an agent to the three.ws MCP server.+- [specs/x402-preflight.md](../specs/x402-preflight.md) is the wire contract.