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): tell buyers what paid, retry_safe and each post-payment status mean, with a retry loop
nirholasa4cd24a81b0a
diff --git a/docs/api-reference.md b/docs/api-reference.mdindex 0f4d44172..c81eade39 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -70,6 +70,33 @@ If the body also has `"reason": "rate_limiter_unavailable"`, you did not hit a qWrites on the versioned agents API accept an `Idempotency-Key` header (up to 200 characters). The first request with a key runs; a retry with the same key and the same body within 24 hours gets the stored response back with `Idempotent-Replayed: true`, and nothing runs twice. Reusing a key with a different body is rejected with `422 idempotency_key_reused`, and a retry that arrives while the first is still running gets `409 idempotency_in_progress`. Other write endpoints are not idempotent unless their section says so, so guard retries on your side. Paid x402 endpoints are idempotent per payment: see [x402](/docs/x402).+### Paid (x402) errors++Errors from a paid endpoint add two fields that tell a buyer's client whether it was charged. Full status table and a buyer loop: [x402: paid endpoint failures and retries](/docs/x402#paid-endpoint-failures-and-retries).++| Field | Values | What it means |+|---|---|---|+| `paid` | `true` / `false` | `true`: the payment settled on chain before the failure. `false`: nothing settled, you were not charged. |+| `retry_safe` | `true` / `false` | `true`: repeat this exact request (same method, URL, body) with the same `X-PAYMENT` header and the work re-runs with no second charge. Never sign a new payment when `paid` is `true`. |+| `settlement` | `{ transaction, network }` | Present when `paid` is `true`: the transaction you paid with. |+| `retries_left`, `retry_until` | number, ISO time | The remaining paid retries (default 3) and when the window closes (default 24 hours). |+| `message` | string | A plain sentence for a human, e.g. "You were charged; repeat this exact request with the same payment to get your result." |++```json+{+ "error": "upstream_unavailable",+ "error_description": "internal error, quote ref 3f9a… to support",+ "paid": true,+ "retry_safe": true,+ "settlement": { "transaction": "5Xk…", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" },+ "retries_left": 3,+ "retry_until": "2026-10-09T18:40:00.000Z",+ "message": "You were charged; repeat this exact request with the same payment to get your result."+}+```++A completed paid call replayed with the same payment still answers `409 payment_replayed`: the result was delivered, so buying it again needs a new payment. A paid payment whose retries are used up answers `409 payment_retries_exhausted` with `paid: true` and `retry_safe: false`; contact support with `settlement.transaction`.+---## Solana Transaction Inspection APIdiff --git a/docs/x402.md b/docs/x402.mdindex ad6a10a2d..7961cdbc2 100644--- a/docs/x402.md+++ b/docs/x402.md@@ -231,6 +231,86 @@ Owner API: `GET` / `PUT /api/agents/:id/api-service` with`{ "active": true, "price_usd": 0.05, "description": "..." }` (see the[API reference](api-reference.md#sell-an-agent-as-an-api)).+## Paid endpoint failures and retries++Every paid route under `/api/x402/*` (and the other routes built on the+shared `paidEndpoint()` helper) tells a buyer's client whether it was charged.+The rule a client needs is one field: **if an error body says `paid: true`,+never sign a new payment. Repeat the exact same request with the same+`X-PAYMENT` header.**++### When you are charged++Most routes run the work first and settle only when it succeeded, so a+failure there costs nothing. Routes that stream their body (downloads, SSE)+settle first, then run. Either way, once the payment has settled the call is+yours: if the work then fails, the error body carries++| Field | Meaning |+|---|---|+| `paid` | `true`: the payment settled on chain. `false`: nothing was settled, you were not charged. |+| `retry_safe` | `true`: repeating this exact request with the same `X-PAYMENT` header re-runs the work without a second charge. |+| `settlement` | `{ transaction, network }` of the payment you made. Quote it to support. |+| `retries_left` | How many paid retries this payment still has (default 3). |+| `retry_until` | When the retry window closes (default 24 hours after the first failure). |+| `message` | One sentence for a human, e.g. "You were charged; repeat this exact request with the same payment to get your result." |++The `x-payment-response` header is set on these errors too, so a client that+reads receipts from headers still gets one.++A paid retry skips verify and settle entirely: the server finds the spent+payment, re-runs the request and answers with the original+`x-payment-response`. It must be the same request: same method, URL and body.+A retry against a different request answers `409 payment_retry_mismatch`.++### What each status means for a buyer++| Status / `error` | `paid` | What the client should do |+|---|---|---|+| `402` | n/a | Pay. The body lists the accepted networks and amounts. |+| any 4xx/5xx with `paid: false` | `false` | You were not charged. Fix the input if it was a 4xx, then send the request again; the same payment may be reused or a fresh one signed. |+| any 4xx/5xx with `paid: true, retry_safe: true` | `true` | Repeat the exact request with the same `X-PAYMENT` header. Do not pay again. |+| `502 siwx_record_failed` | `true` | The wallet re-access grant could not be saved after you paid. Repeat with the same payment; the grant is written on the retry. |+| `502 settle_failed` | not set | Settlement did not happen. Retrying with the same payment is safe. |+| `409 payment_replayed` | not set | This payment already bought this request and the result was delivered. Pay again to buy it a second time. |+| `409 payment_retries_exhausted` | `true` | You paid, the work kept failing and the retries are used up. Contact support with `settlement.transaction`. |+| `409 payment_retry_mismatch` | `true` | You sent a paid retry for a different request. Repeat the original request instead. |+| `409` with `x-x402-idempotent: in-flight` | n/a | The same payment is being processed right now. Wait a moment and repeat; you will get the result. |+| `409 payment_identifier_conflict` | n/a | The same payment identifier was used for a different request. Use a new identifier for a new request. |++### Idempotency++A response is cached per payment for the idempotency window+(`X402_IDEMPOTENCY_TTL_SECONDS`). Repeating a successful paid request with the+same payment returns the cached body with `x-x402-idempotent: replay`, and+nothing runs or settles twice. Clients may also send the `payment-identifier`+extension to name the payment explicitly. The cache key covers the method, the+URL and, on every non-GET route, the request body, so two different POST+bodies under one identifier never share a response: the second is answered+`409 payment_identifier_conflict`.++### A buyer loop that handles all of it++```js+async function buy(url, init, pay) {+ let res = await fetch(url, init);+ if (res.status !== 402) return res;+ const payment = await pay(await res.json()); // sign once+ const headers = { ...init.headers, 'x-payment': payment };+ for (let attempt = 0; attempt < 4; attempt++) {+ res = await fetch(url, { ...init, headers });+ if (res.ok) return res;+ const body = await res.clone().json().catch(() => ({}));+ if (!(body.paid === true && body.retry_safe === true)) return res;+ }+ return res;+}+```++The spent-payment ledger behind this is `x402_spent_payments`+(`api/_lib/x402/spent-payments.js`); the wrapper is `paidEndpoint()` in+`api/_lib/x402-paid-endpoint.js`.+## Open-source packagesThe x402 toolkit is published to npm and maintained as standalone, provider-neutral