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 Developer Tools
A free test bench for building and debugging x402 integrations against a live server. Six tools (three free diagnostics plus three paid probe endpoints) that let you inspect what the server sees, understand why a payment was rejected, and confirm a receipt.
The three diagnostic tools are free and keyless, rate-limited to 30 requests/minute per IP. The three probe endpoints are paid ($0.001 USDC each).
Base URL: https://three.ws
The three free diagnostics
1. Echo — POST /api/x402/echo
httpbin for x402. Returns exactly what your request looked like from the
server's perspective: method, the headers that matter for a paid call, and your
body. If an X-PAYMENT header is present (or you pass paymentHeader in the
body), it is base64-decoded and echoed back with every signature and secret
redacted to a short prefix, plus the rail's local verification verdict — the
same pre-facilitator checks a real paid endpoint runs — without settling or
charging anything.
Pass a requirement (one accepts[] entry) to have the verdict check your
signed amount and recipient against it:
curl -s https://three.ws/api/x402/echo \
-H 'content-type: application/json' \
-d '{
"paymentHeader": "<base64 X-PAYMENT value>",
"requirement": { "amount": "10000", "payTo": "0x…", "network": "eip155:8453" }
}'
Response (abridged):
{
"ok": true,
"method": "POST",
"headers": { "x-payment": "eyJ4NDAyVm…(redacted, 512 chars)" },
"payment": {
"x402Version": 2,
"scheme": "exact",
"network": "eip155:8453",
"signedAmount": "10000",
"signedRecipient": "0x75d0…cf69",
"envelope": { "payload": { "signature": "0xdededede…(redacted, 132 chars)" } },
"verdict": { "valid": true, "checks": [ … ] },
"note": "Local pre-facilitator verdict only — no facilitator round-trip, no settlement, no charge."
}
}
You can also send the payment as a real X-PAYMENT header instead of in the
body — the header wins when both are present. The full signature is never
returned; only a prefix, so the echo is safe to paste into a bug report.
2. Debug — POST /api/x402/debug
Paste any subset of a failed exchange and get a structured diagnosis keyed to
the failure modes this server's rail actually produces. Each finding is
{ severity, field, problem, fix }, ordered most-severe first.
curl -s https://three.ws/api/x402/debug \
-H 'content-type: application/json' \
-d '{
"challenge": { "x402Version": 2, "accepts": [{ "scheme": "exact", "network": "eip155:8453", "amount": "10000", "payTo": "0x…" }] },
"payment": { "x402Version": 1, "network": "base", "payload": { "authorization": { "value": "0.01", "to": "0x…" } } },
"response": { "error": "invalid_payment" }
}'
Response:
{
"ok": false,
"count": 5,
"findings": [
{ "severity": "error", "field": "payment.x402Version", "problem": "payment declares x402Version 1; server requires 2", "fix": "Set x402Version: 2." },
{ "severity": "error", "field": "payment.network", "problem": "network \"base\" is a shorthand, not the CAIP-2 id the rail matches on", "fix": "Use \"eip155:8453\"." },
{ "severity": "error", "field": "payment.network", "problem": "you signed for \"base\" but the challenge only offers [eip155:8453]", "fix": "Pick one of the offered networks and re-sign against that accepts[] entry." },
{ "severity": "error", "field": "payment.authorization.value", "problem": "value \"0.01\" contains a decimal point", "fix": "Authorization value is atomic units as an integer string (\"10000\"), not a decimal token amount." },
{ "severity": "info", "field": "response.error", "problem": "server returned \"invalid_payment\"", "fix": "The payload was structurally valid but failed a check — usually underpayment, wrong payTo, or a malformed authorization. Run /api/x402/echo on your header to see the decoded amount/recipient." }
]
}
Common footguns it catches: wrong x402Version, shorthand instead of CAIP-2
network ids, signing for a network the challenge doesn't offer, decimal amounts
where atomic-unit integer strings are required, underpayment, and a missing
accepts[] array.
3. Verify receipt — POST /api/x402/verify-receipt
Two independent checks; supply either or both. The response says exactly what was and wasn't verifiable.
Attestation integrity — pass a three.ws paid response carrying a
sha256:… attestation (e.g. from /api/x402/fact-check).
The digest is recomputed over the committed fields; if any was altered after
signing, the recomputed digest won't match.
curl -s https://three.ws/api/x402/verify-receipt \
-H 'content-type: application/json' \
-d '{ "result": { "verdict": "true", "confidence": 0.92, "claim": "…", "sources": ["https://…"], "attestation": "sha256:…" } }'
{ "ok": true, "attestation": { "verified": true, "scheme": "sha256", "recomputed": "sha256:…", "claimed": "sha256:…" } }
Settlement confirmation — pass { tx: { hash, network } } for a read-only
on-chain lookup confirming the settlement transaction exists and is confirmed.
network is CAIP-2 (solana:…, eip155:8453) or shorthand (solana, base).
An unreachable RPC is reported as status: "rpc_unavailable", never a false
confirmed.
curl -s https://three.ws/api/x402/verify-receipt \
-H 'content-type: application/json' \
-d '{ "tx": { "hash": "<signature or txhash>", "network": "solana" } }'
{ "ok": true, "settlement": { "verified": true, "status": "confirmed", "detail": "settlement confirmed on Solana", "slot": 301234567 } }
The settlement check also works over a plain GET, so you can confirm a
settlement from a browser address bar, a curl one-liner, or an uptime probe
with no request body:
curl -s 'https://three.ws/api/x402/verify-receipt?hash=<signature or txhash>&network=solana'
Attestation integrity stays POST-only, because it needs the whole attested
object. When a POST body supplies tx, the body wins over the query string.
The three probe endpoints
These already existed; the docs are consolidated here.
Schema check — POST /api/x402/schema-check (paid, $0.001 USDC)
Fetches a named three.ws public JSON API and validates its response against the
declared schema, so a breaking change surfaces before consumers notice. Current
target: changelog_json (the /changelog.json feed).
# Requires an x402 payment; see docs/x402-buyer.md for the buyer flow.
curl -s https://three.ws/api/x402/schema-check -d '{ "api": "changelog_json" }'
Rate-limit probe — POST /api/x402/rate-limit-probe (paid, $0.001 USDC)
Returns how many more calls the x402 autonomous loop can make to a target
endpoint today before hitting its daily USDC spend cap — remaining_calls,
reset_at, and cooldown_active — so an agent can throttle before it fails.
curl -s https://three.ws/api/x402/rate-limit-probe -d '{ "endpoint": "/api/x402/forge" }'
endpoint must be a metered route: a path under /api/x402, /api/mcp, or
/api/ibm-mcp. Those are the only routes that answer a 402 challenge, so they
are the only ones with a price to report; anything else is rejected 400 endpoint_not_metered before the probe runs.
Permit2 paid demo: GET /api/x402/permit2-paid-demo (paid, $0.001 USDC)
A target that advertises only the Permit2 + EIP-2612 gas-sponsoring accept (no EIP-3009 fallback), so you can prove a wallet with USDC but zero native gas can pay end-to-end through the gasless path. Use it to test a Permit2 client implementation against a live server.
Typical debugging loop
- Your paid call fails. Copy the base64
X-PAYMENTheader you sent. POST /api/x402/echowith it → see the decoded amount, recipient, and the local verdict. If the verdict is invalid, thereasontells you which check failed.- Still unclear?
POST /api/x402/debugwith{ challenge, payment, response }→ get an ordered fix list. - After a successful call,
POST /api/x402/verify-receiptto confirm the attestation and settlement.
Checking our own endpoints the way a marketplace does
The tools above debug a buyer's call. This one checks the seller side: whether the paid routes three.ws lists would pass the checklist a marketplace validator (Agentic Market's Seller Tools, the CDP Bazaar crawler) runs before it catalogs a resource. It sends the same unpaid request an indexer sends, so it costs nothing.
npm run x402:probe # every listed route on https://three.ws
npm run x402:probe -- --only=/api/x402/forge # routes whose path contains the text
npm run x402:probe -- --base=http://localhost:8080 # a local or preview server
npm run x402:probe -- --url=https://three.ws/api/x402/model-check
npm run x402:probe -- --json # machine-readable report
It reads /.well-known/x402.json, takes one sample per route (the datapoint
catalog lists thousands of parameterised URLs behind a few handlers), and fails
a route when any of these is false:
| Group | Checks |
|---|---|
| Transport | HTTPS, reachable, body at most 65,536 bytes, HTTP 402, valid JSON, resource object present |
| Payment | x402Version 2, a PAYMENT-REQUIRED header that decodes, accepts[] present and well formed, known scheme, CAIP-2 network, asset, USDC price at least $0.001, payTo, maxTimeoutSeconds |
| Bazaar | extension present, info block, input type and method, schema, and info validating against that schema |
Two readings to know:
- "No x402 setup detected" with a body over 65,536 bytes means the URL is not a paid route. A page or the discovery document answers 200 with a large body, the validator truncates it, and every later check is skipped. Validate a route from the catalog, with the method the catalog lists for it.
- HTTP 500 on every route is a handler that throws while loading, not a
payment problem.
npm run check:api-importsfinds it locally in under a minute, and it gatesdeploy:gcp:submit.
With --base, catalog URLs are rebased onto that host, so a local run never
quietly tests production. A local server without the production settlement
configuration advertises fewer payment options than production does; an empty
accepts[] there is a local artifact, so confirm it with --url against
production before treating it as a defect.
Every route's Bazaar block is normalized in one place,
normalizeBazaarEntry in api/_lib/x402/bazaar-helpers.js, which
paidEndpoint() applies to whatever a handler declares. A handler may still
declare the older flat { input: { type, example, schema }, output } block; the
live 402 carries the v2 { info, schema } entry either way.
Related
- x402 Protocol - the challenge / verify / settle mechanics.
- x402 Paid Endpoints - the full catalog and pricing.
- x402 Buyer Client - how to settle a challenge from code.
- Receipt Vault - every signed receipt issued to a wallet.