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): add the paid-retry columns migration and return outcome and settlement from the replay lookup

nirholas2a545b58f139
diff --git a/api/_lib/migrations/20260930180000_x402_spent_payments_paid_retry.sql b/api/_lib/migrations/20260930180000_x402_spent_payments_paid_retry.sql
new file mode 100644
index 000000000..97489d5a3
--- /dev/null
+++ b/api/_lib/migrations/20260930180000_x402_spent_payments_paid_retry.sql
@@ -0,0 +1,41 @@
+-- Migration: let a buyer charged for a failed call retry it with the same payment.
+-- Apply: node scripts/apply-migrations.mjs --apply --file 20260930180000_x402_spent_payments_paid_retry.sql
+-- Idempotent.
+--
+-- x402_spent_payments is the durable replay guard: one row per honoured
+-- X-PAYMENT proof, and a second use answers 409 payment_replayed. That was
+-- wrong for a streaming route whose handler failed after settlement (and for a
+-- SIWX grant write that failed after settlement): the buyer was charged, got
+-- nothing, and was told to pay again. These columns record how a proof ended
+-- so the paid-endpoint wrapper can tell the two apart:
+--
+-- outcome delivered the work shipped; a replay is a 409.
+-- failed_after_settle charged, work failed; the same header may
+-- retry (no second verify, no second settle).
+-- retrying a retry is running right now (atomic claim).
+-- retry_count retries taken so far, capped by X402_PAID_RETRY_MAX (default 3).
+-- retry_until the retry window, X402_PAID_RETRY_WINDOW_SECONDS after the first
+-- failure (default 24 h).
+-- settlement { transaction, network, payer, asset, amount, header }: what the
+-- retry re-emits as x-payment-response and feeds to post-settle hooks.
+-- last_error the failure, for support.
+--
+-- Every existing row is a delivered proof, which is what the default says.
+
+alter table x402_spent_payments
+ add column if not exists outcome text not null default 'delivered',
+ add column if not exists retry_count integer not null default 0,
+ add column if not exists retry_until timestamptz,
+ add column if not exists settlement jsonb,
+ add column if not exists last_error text,
+ add column if not exists updated_at timestamptz not null default now();
+
+do $$ begin
+ alter table x402_spent_payments
+ add constraint x402_spent_payments_outcome_check
+ check (outcome in ('delivered', 'failed_after_settle', 'retrying'));
+exception when duplicate_object then null; end $$;
+
+create index if not exists x402_spent_payments_retryable_idx
+ on x402_spent_payments (retry_until)
+ where outcome = 'failed_after_settle';
diff --git a/api/_lib/x402/spent-payments.js b/api/_lib/x402/spent-payments.js
index 63e04c4f6..72ad8be7d 100644
--- a/api/_lib/x402/spent-payments.js
+++ b/api/_lib/x402/spent-payments.js
@@ -69,29 +69,38 @@ export const PAID_RETRY_WINDOW_SECONDS = Math.max(
* 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, retryable: boolean, endpoint: string|null }>}
+ * @returns {Promise<{ spent: boolean, unavailable: boolean, retryable: boolean, outcome: string|null, endpoint: string|null, settlement: object|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, retryable: false, endpoint: null };
+ const none = { spent: false, retryable: false, outcome: null, endpoint: null, settlement: null };
+ if (!paymentHash) return { ...none, unavailable: false };
try {
const rows = await sql`
- SELECT endpoint, outcome, retry_count, retry_until
+ SELECT endpoint, outcome, retry_count, retry_until, settlement
FROM x402_spent_payments WHERE payment_hash = ${paymentHash} LIMIT 1
`;
const row = rows?.[0];
- if (!row) return { spent: false, unavailable: false, retryable: false, endpoint: null };
+ if (!row) return { ...none, unavailable: false };
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 };
+ const settlement = typeof row.settlement === 'string' ? JSON.parse(row.settlement) : row.settlement;
+ return {
+ spent: true,
+ unavailable: false,
+ retryable,
+ outcome: row.outcome || 'delivered',
+ endpoint: row.endpoint ?? null,
+ settlement: settlement || null,
+ };
} catch (err) {
logDegraded('lookup', err);
- return { spent: false, unavailable: true, retryable: false, endpoint: null };
+ return { ...none, unavailable: true };
}
}