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.

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.md
index 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 q
Writes 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 API
diff --git a/docs/x402.md b/docs/x402.md
index 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 packages
The x402 toolkit is published to npm and maintained as standalone, provider-neutral