x402 Refund

An autonomous refund mechanism for x402 payments using EIP-712 signed refund authorizations and bonded escrow.

Problem

In the traditional x402 flow, clients must pay upfront for API requests. If the server fails to deliver the service after payment, clients need an autonomous way to instantly recover their funds without relying on manual dispute resolution.

Approach

This approach requires all the servers to lock-up some USDC in an escrow contract. When requests fail, servers sign refund authorizations that clients can submit on-chain to claim refunds directly from the bond. This creates accountability without any human intervention or intermediaries

Note: This is a basic approach that relies on sellers honestly signing refund authorizations for failed requests. A production system would need a better trust model.

Flow

Initial Handshake

Before making paid requests:

1. Client calls server's /escrow endpoint to get escrow contract address
2. Every seller/server should expose this endpoint.
3. Client checks isHealthy() on escrow to verify sufficient funds for refunds
4. If healthy, client proceeds with normal x402 flow.
5. If not, client can choose to proceed with a different server.

Refund Flow

When a paid request fails:

1. Server signs refund authorization using EIP-712
2. Server returns refund bundle: {requestCommitment, amount, signature}
3. Client submits refund claim to escrow contract
4. Contract verifies EIP-712 signature from seller
5. Contract transfers refund from bond pool to client

Refund Mechanism

Smart Contract

BondedEscrow.sol manages the bonded escrow:

• Seller deposits USDC bond via deposit()
• Enforces minimum bond requirement
• Verifies EIP-712 signatures for refund claims
• Prevents double-spending with settlement tracking
• Only seller can withdraw remaining bond

The requestCommitment is computed as:

keccak256(method, url, xpayment_header, window)

Server Requirements

Servers must expose /escrow endpoint:

app.get("/escrow", (_, res) => {
  res.json({ success: true, address: BOND_ESCROW_ADDRESS });
});

This allows clients to:

1. Discover the escrow contract address
2. Check isHealthy() to verify sufficient bonded funds
3. Abort if escrow is unhealthy (balance < minimum bond)

Servers should always sign the failed requests by implementing better error handling.

However, this approach cannot handle if server crashes or internal server errors

Usage

• Install dependencies and deploy the contracts to a forked local anvil instance
• Fill up the env variables

Terminal 1 - Facilitator:

pnpm facilitator

Terminal 2 - Resource Server:

pnpm server

Terminal 3 - Client:

pnpm client

The client will:

1. Fetch escrow address from server
2. Check escrow health
3. Make paid request to /fail endpoint
4. Receive refund authorization
5. Claim refund from escrow contract

---

_{Disclaimer: This project is for educational purposes only. The smart contracts are not audited and may contain vulnerabilities. Use at your own risk. Do not use with real funds on mainnet.}