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.

fix(x402): let a buyer charged for a failed call retry with the same payment instead of a 409

nirholasc2e980f09f8f
diff --git a/api/_lib/x402/spent-payments.js b/api/_lib/x402/spent-payments.js
index f74292dfa..63e04c4f6 100644
--- a/api/_lib/x402/spent-payments.js
+++ b/api/_lib/x402/spent-payments.js
@@ -20,10 +20,14 @@
// another request already honoured this proof, i.e.
// a replay that raced past the lookup.
//
-// The claim runs LAST in the settle path on purpose. A payment that settled
-// but then failed a downstream step (SIWX grant write, receipt sign) leaves no
-// spent row, so the payer's retry with the same header still works. The row is
-// written only for a payment that was actually honoured end to end.
+// The claim runs LAST in the settle path on purpose, and a payment that
+// settled but then failed a downstream step is NOT a replay: the buyer was
+// charged and got nothing. Such a proof is recorded with outcome
+// `failed_after_settle` plus the settlement it produced, and the same X-PAYMENT
+// header may then re-run the work a bounded number of times within a window
+// (claimPaidRetry) with no second verify or settle. Re-verifying would not
+// work anyway: the payment already landed on chain, so the facilitator rejects
+// it. Only a proof whose work was delivered (`delivered`) answers 409.
//
// Failure policy: FAIL OPEN, deliberately. The in-cache guard, the payment
// identifier reservation and the on-chain settle-credit gate all remain in
@@ -52,48 +56,83 @@ function logDegraded(op, err) {
);
}
+/** Retries a buyer gets after a failure that happened once they were charged. */
+export const PAID_RETRY_MAX = Math.max(1, Number(process.env.X402_PAID_RETRY_MAX) || 3);
+/** How long those retries stay open, from the first failure. */
+export const PAID_RETRY_WINDOW_SECONDS = Math.max(
+ 60,
+ Number(process.env.X402_PAID_RETRY_WINDOW_SECONDS) || 24 * 3600,
+);
+
/**
- * Has this payment proof already been honoured?
+ * Has this payment proof already been honoured, and if it failed after the
+ * buyer was charged, may it still be retried?
*
* @param {string|null|undefined} paymentHash Hash of the signed X-PAYMENT proof.
- * @returns {Promise<{ spent: boolean, unavailable: boolean }>}
- * `spent` is true only on a positive, durable answer. `unavailable` marks the
- * fail-open path so the caller can log it rather than silently trusting a
- * "not spent" that was never actually checked.
+ * @returns {Promise<{ spent: boolean, unavailable: boolean, retryable: boolean, endpoint: string|null }>}
+ * `spent` is true only on a positive, durable answer. `retryable` is true when
+ * the proof settled but its work failed, retries remain and the window is
+ * open. `unavailable` marks the fail-open path so the caller can log it rather
+ * than silently trusting a "not spent" that was never actually checked.
*/
export async function isPaymentSpent(paymentHash) {
- if (!paymentHash) return { spent: false, unavailable: false };
+ if (!paymentHash) return { spent: false, unavailable: false, retryable: false, endpoint: null };
try {
const rows = await sql`
- SELECT 1 FROM x402_spent_payments WHERE payment_hash = ${paymentHash} LIMIT 1
+ SELECT endpoint, outcome, retry_count, retry_until
+ FROM x402_spent_payments WHERE payment_hash = ${paymentHash} LIMIT 1
`;
- return { spent: Boolean(rows?.length), unavailable: false };
+ const row = rows?.[0];
+ if (!row) return { spent: false, unavailable: false, retryable: false, endpoint: null };
+ const retryable =
+ row.outcome === 'failed_after_settle' &&
+ Number(row.retry_count || 0) < PAID_RETRY_MAX &&
+ (!row.retry_until || new Date(row.retry_until).getTime() > Date.now());
+ return { spent: true, unavailable: false, retryable, endpoint: row.endpoint ?? null };
} catch (err) {
logDegraded('lookup', err);
- return { spent: false, unavailable: true };
+ return { spent: false, unavailable: true, retryable: false, endpoint: null };
}
}
/**
* Claim the proof as spent. Atomic: the primary key is the arbiter, so of any
* set of concurrent requests carrying one X-PAYMENT header exactly one claim
- * returns a row.
+ * returns a row. Pass `outcome: 'failed_after_settle'` (with the settlement)
+ * when the buyer was charged but the work did not complete, so the same header
+ * can retry through claimPaidRetry.
*
* @param {object} args
* @param {string|null|undefined} args.paymentHash
* @param {string} args.endpoint Route the proof was spent on (audit context).
* @param {string|number|null} [args.amountAtomics] Price paid, in asset atomics.
+ * @param {'delivered'|'failed_after_settle'} [args.outcome]
+ * @param {object|null} [args.settlement] { transaction, network, payer, asset, amount, header }
+ * @param {string|null} [args.lastError]
* @returns {Promise<{ granted: boolean, replay: boolean, unavailable: boolean }>}
*/
-export async function claimSpentPayment({ paymentHash, endpoint, amountAtomics = null }) {
+export async function claimSpentPayment({
+ paymentHash,
+ endpoint,
+ amountAtomics = null,
+ outcome = 'delivered',
+ settlement = null,
+ lastError = null,
+}) {
// No hash means no signed proof to key on (never produced by the paid-endpoint
// path, which derives the hash before it gets here). Nothing to claim, and
// nothing that could double-deliver under this key either.
if (!paymentHash) return { granted: true, replay: false, unavailable: false };
+ const failed = outcome === 'failed_after_settle';
try {
const rows = await sql`
- INSERT INTO x402_spent_payments (payment_hash, endpoint, amount_atomics)
- VALUES (${paymentHash}, ${endpoint}, ${amountAtomics == null ? null : String(amountAtomics)})
+ INSERT INTO x402_spent_payments
+ (payment_hash, endpoint, amount_atomics, outcome, settlement, last_error, retry_until)
+ VALUES (${paymentHash}, ${endpoint}, ${amountAtomics == null ? null : String(amountAtomics)},
+ ${failed ? 'failed_after_settle' : 'delivered'},
+ ${settlement ? JSON.stringify(settlement) : null}::jsonb,
+ ${lastError ? String(lastError).slice(0, 500) : null},
+ ${failed ? new Date(Date.now() + PAID_RETRY_WINDOW_SECONDS * 1000) : null})
ON CONFLICT (payment_hash) DO NOTHING
RETURNING payment_hash
`;
@@ -105,6 +144,108 @@ export async function claimSpentPayment({ paymentHash, endpoint, amountAtomics =
}
}
+/**
+ * Record that a claimed proof's work failed after settlement. Opens (or keeps)
+ * the retry window and stores the settlement the retry will re-emit.
+ *
+ * @returns {Promise<{ retriesLeft: number, retryUntil: string|null }>}
+ */
+export async function markFailedAfterSettle({ paymentHash, settlement = null, lastError = null }) {
+ if (!paymentHash) return { retriesLeft: 0, retryUntil: null };
+ try {
+ const rows = await sql`
+ UPDATE x402_spent_payments
+ SET outcome = 'failed_after_settle',
+ settlement = coalesce(settlement, ${settlement ? JSON.stringify(settlement) : null}::jsonb),
+ last_error = ${lastError ? String(lastError).slice(0, 500) : null},
+ retry_until = coalesce(retry_until, ${new Date(Date.now() + PAID_RETRY_WINDOW_SECONDS * 1000)}),
+ updated_at = now()
+ WHERE payment_hash = ${paymentHash}
+ RETURNING retry_count, retry_until
+ `;
+ const row = rows?.[0];
+ if (!row) return { retriesLeft: 0, retryUntil: null };
+ const open = !row.retry_until || new Date(row.retry_until).getTime() > Date.now();
+ return {
+ retriesLeft: open ? Math.max(0, PAID_RETRY_MAX - Number(row.retry_count || 0)) : 0,
+ retryUntil: row.retry_until ? new Date(row.retry_until).toISOString() : null,
+ };
+ } catch (err) {
+ logDegraded('mark_failed', err);
+ return { retriesLeft: 0, retryUntil: null };
+ }
+}
+
+/**
+ * Take one retry for a proof that failed after settlement. Atomic: two
+ * concurrent retries of one header cannot both run. Returns the stored
+ * settlement so the retry can answer with the original x-payment-response.
+ *
+ * @returns {Promise<{ granted: boolean, settlement: object|null, attempt: number }>}
+ */
+export async function claimPaidRetry({ paymentHash, endpoint }) {
+ if (!paymentHash) return { granted: false, settlement: null, attempt: 0 };
+ try {
+ const rows = await sql`
+ UPDATE x402_spent_payments
+ SET outcome = 'retrying', retry_count = retry_count + 1, updated_at = now()
+ WHERE payment_hash = ${paymentHash}
+ AND endpoint = ${endpoint}
+ AND outcome = 'failed_after_settle'
+ AND retry_count < ${PAID_RETRY_MAX}
+ AND (retry_until IS NULL OR retry_until > now())
+ RETURNING settlement, retry_count
+ `;
+ const row = rows?.[0];
+ if (!row) return { granted: false, settlement: null, attempt: 0 };
+ const settlement = typeof row.settlement === 'string' ? JSON.parse(row.settlement) : row.settlement;
+ return { granted: true, settlement: settlement || null, attempt: Number(row.retry_count) };
+ } catch (err) {
+ logDegraded('claim_retry', err);
+ return { granted: false, settlement: null, attempt: 0 };
+ }
+}
+
+/** A retried call delivered: from here on the proof answers 409 like any other. */
+export async function markDelivered(paymentHash) {
+ if (!paymentHash) return;
+ try {
+ await sql`
+ UPDATE x402_spent_payments
+ SET outcome = 'delivered', last_error = NULL, updated_at = now()
+ WHERE payment_hash = ${paymentHash}
+ `;
+ } catch (err) {
+ logDegraded('mark_delivered', err);
+ }
+}
+
+export const PAID_RETRY_SENTENCE =
+ 'You were charged; repeat this exact request with the same payment to get your result.';
+export const PAID_EXHAUSTED_SENTENCE =
+ 'You were charged, and this payment has used up its retries. Contact support with the settlement transaction and it will be made right.';
+
+/**
+ * The fields every failure after settlement carries, so a buyer's client can
+ * tell "you paid, retry safely" from "you were not charged".
+ *
+ * @param {{ settlement: object|null, retriesLeft: number, retryUntil?: string|null }} ctx
+ */
+export function paidFailureFields({ settlement, retriesLeft, retryUntil = null }) {
+ const retrySafe = retriesLeft > 0;
+ return {
+ paid: true,
+ retry_safe: retrySafe,
+ settlement: {
+ transaction: settlement?.transaction ?? null,
+ network: settlement?.network ?? null,
+ },
+ retries_left: Math.max(0, retriesLeft),
+ ...(retryUntil ? { retry_until: retryUntil } : {}),
+ message: retrySafe ? PAID_RETRY_SENTENCE : PAID_EXHAUSTED_SENTENCE,
+ };
+}
+
/**
* 409 for a proof that was already honoured. Distinct from the idempotency
* conflict/in-flight 409s (`x-x402-idempotent: conflict` / `in-flight`) so a