x402-recovery

Late settlement recovery for x402 facilitator timeouts.

When a facilitator times out but the chain later confirms success, clients see failure while the chain shows success. This package polls the chain and tracks the outcome through a state machine.

States

State	Meaning
created	Record exists, polling not started
polling	Actively checking chain truth
confirmed	Chain confirmed within facilitator timeout
confirmed_late	Chain confirmed after facilitator timeout
unresolved	Cannot safely classify the result
failed	Transaction reverted or recovery window ended
failed_orphaned	Recovery window ended after validBefore; authorization expired

Profiles

Profile	Facilitator timeout	Poll interval	Max poll window	Confirmations	Indexer lag
datacenter	5s	2s	30s	1	0ms
emerging_markets	15s	5s	90s	1	0ms
batch	30s	8s	48s	1	10s

Custom profiles:

import { defineProfile } from 'x402-recovery';

const profile = defineProfile({
  name: 'mobile_money',
  facilitatorTimeoutMs: 20_000,
  pollIntervalMs: 7_000,
  maxPollWindowMs: 120_000,
  requiredConfirmations: 1,
});

Installation

npm install x402-recovery

validBefore

validBefore is stored as Unix milliseconds. If your upstream value is EIP-3009 Unix seconds, convert it first:

import { normalizeValidBefore } from 'x402-recovery';
const validBeforeMs = normalizeValidBefore(contractValidBefore);

Settlement identity

canonicalKey(payer, payTo, value, nonce)

import { canonicalKey } from 'x402-recovery';
const key = canonicalKey({
  payer: '0xSender',
  payTo: '0xRecipient',
  value: '1000000000000000000',
  nonce: '42',
});
// => "0xSender:0xRecipient:1000000000000000000:42"

Use canonicalKey for persistence and idempotency. value and nonce are strings.

batchCanonicalKey(payer, payTo, nonce, claimTxHash)

For batch settlements (scheme: 'batch'):

import { batchCanonicalKey } from 'x402-recovery';
const key = batchCanonicalKey('0xSender', '0xRecipient', '0xa3f2...', '0x60a960bd...');

Usage

x402 v2 lifecycle hooks (recommended)

import { x402ResourceServer } from '@x402/core';
import { RecoveryPlugin } from 'x402-recovery';

const server = new x402ResourceServer(facilitatorClient);

const recovery = RecoveryPlugin({
  profile: 'datacenter',
  rpcUrl: process.env.BASE_RPC_URL,
});

server.onSettleFailure(recovery.onSettleFailure);
server.onUncertainSettlement(recovery.onUncertainSettlement);

Or with a shared StateMachine:

import { createSettlementStateMachine, createRecoveryHook } from 'x402-recovery';

const machine = createSettlementStateMachine({ onTransition: logToTelemetry });

server.onSettleFailure(
  createRecoveryHook({ profile: 'datacenter', rpcUrl: '...', stateMachine: machine }),
);

State machine

import { createSettlementStateMachine, SettlementState } from 'x402-recovery';

const machine = createSettlementStateMachine();

machine.create('tx-001', {
  profileName: 'emerging_markets',
  txHash: '0xabc...',
  validBefore: Date.now() + 90_000,
});

machine.transition('tx-001', SettlementState.Confirmed);

Poller

import { createPublicClient, http } from 'viem';
import { baseSepolia } from 'viem/chains';
import {
  pollUntilResolved,
  createSettlementStateMachine,
  createViemReceiptProvider,
  PROFILES,
} from 'x402-recovery';

const client = createPublicClient({
  chain: baseSepolia,
  transport: http(process.env.BASE_RPC_URL),
});

const receiptProvider = createViemReceiptProvider(client);
const machine = createSettlementStateMachine();

machine.create('settlement-1', {
  profileName: 'datacenter',
  txHash: '0xdead...',
  validBefore: Date.now() + 30_000,
});

const result = await pollUntilResolved({
  machine,
  receiptProvider,
  id: 'settlement-1',
  txHash: '0xdead...',
  profile: PROFILES.datacenter,
});

console.log(result.state);

Custom ReceiptProvider

import type { ReceiptProvider } from 'x402-recovery';

function createWsReceiptProvider(wsUrl: string): ReceiptProvider {
  return {
    async getTransactionReceipt({ txHash }) {
      const resp = await fetch(`${wsUrl}/tx/${txHash}`);
      if (!resp.ok) return null;
      const data = await resp.json();
      return {
        status: data.status === 1 ? 'success' : data.status === 0 ? 'reverted' : 'unknown',
        blockNumber: BigInt(data.blockNumber),
        confirmations: data.confirmations,
      };
    },
  };
}

Custom StateMachine

import type { StateMachine, SettlementRecord } from 'x402-recovery';

class RedisStateMachine implements StateMachine {
  async create(id: string, opts?) { /* persist to Redis */ }
  async get(id: string) { /* read from Redis */ }
  async transition(id: string, newState: SettlementState) { /* persist in Redis */ }
  async update(id: string, fields: SettlementRecordUpdate) { /* patch in Redis */ }
  async list() { /* scan Redis */ }
}

update() for batch settlements

await machine.update('settlement-1', { settleTxHash: '0x7c6a7fe8...' });

Production

• The default state machine is in-memory and per-process. Provide a persistent StateMachine for production. Recoveries disappear on process restart.
• For horizontal scaling, all workers must share the same StateMachine.
• Terminal records remain in memory indefinitely. Long-running services should implement TTL or eviction in their custom StateMachine.
• If the facilitator response has no txHash, the settlement is recorded as unresolved and not polled.
• value and nonce are strings by design.
• Use canonicalKey as the durable identity for retries and persistence.
• Logging uses toSafeJSON() by default to avoid leaking tx hashes or payer addresses to external log services.

Related

• NDSS 2026 Two-Phase Gap poster
• x402 Foundation discussion

Contributing

See CONTRIBUTING.md.

License

Apache 2.0