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.
x402 Preflight
Ask an x402 seller whether it can actually settle, before you sign anything.
- Try it: three.ws/preflight
- Live attestation: three.ws/.well-known/x402-preflight
- Client:
@three-ws/x402-preflight - Wire contract: 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:
- Your agent
GETs a paid route and gets402with a price. - Your agent signs a USDC transfer and retries with
X-PAYMENT. - 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
npm i @three-ws/x402-preflight
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:
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
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.
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 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
{
"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: trueholds 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.
- Generate an ed25519 keypair; publish the public key wherever you already publish identity.
- Answer
GET /.well-known/x402-preflightwith a signed envelope built from whatever settlement health you already measure. - 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. The reference server is api/x402/preflight.js and the pure format core is 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 walks the payment flow itself.
- docs/mcp.md covers connecting an agent to the three.ws MCP server.
- specs/x402-preflight.md is the wire contract.