x402 Global

Problem Statement

At its core, x402 Global upgrades the x402 standard into a rich, machine-readable payment language that unlocks global reach. Extending the simple “payment required” banner, the server returns a structured payment requirements object: which token to pay, on which chain, how much, to which vault address, and before what deadline. The client (buyer) can use this payload to decide how much they’re willing to spend, sign the necessary approvals, and then retry the request with a fully-formed, on-chain-ready payment. In our demo, we showcase OTC-style asset sales over plain HTTP. A server exposes endpoints like GET /buy-asset; a client with a EUR wallet asks to buy a given amount of an on-chain asset (e.g., yield-bearing pool shares, tokenized deposits, ERC-4626 vault shares) that the seller prices in USD. Payments are settled in EUR and USD stablecoins on Polygon Amoy: the seller thinks in USD, while the buyer manges her affairs in EUR. Instead of manually juggling approve transactions, both buyer and seller sign EIP-712 permits. The buyer authorizes a facilitator contract to pull tokens from her wallet, and the seller authorizes the same contract to move the asset tokens from his wallet into a vault. The server then submits a single transaction that consumes both permits and pulls funds and assets into a secure settlement vault. The vault briefly holds the client’s EUR while the system uses a Uniswap v4 pool plus a custom hook to convert EUR →USD. The hook is designed to preserve vault integrity: if the swap doesn’t produce enough USD, the entire transaction reverts and the vault stays consistent and safe. x402 Global is aimed squarely at high-frequency, high-stakes transactions—the kind where a $10M payment really matters. That’s why we put a strong emphasis on finality awareness: assets remain locked in the vault until the underlying transactions reach the configured finality threshold. Only then are the assets and proceeds released, combining fast, modern infrastructure with a safety posture that serious capital can confidently rely on.

Solution

We built x402 Global as an end-to-end technical demo that connects HTTP 402, EIP-2612, Uniswap V4, and finality-aware settlement on Polygon Amoy.On-chain:Settlement vault in Solidity that escrows:Buyer funds (MockEURC) andSeller inventory (on-chain asset tokens, e.g. ERC-4626 shares).Facilitator/puller contract that consumes two EIP-2612/EIP-712 permits in a single transaction:Buyer permit → pull MockEURC into the vault.Seller permit → pull asset tokens into the vault. This collapses a multi-step OTC flow (two approvals + two transfers) into one atomic vault-funding call.Uniswap V4 hook integrated with our own PoolManager, swap router, and liquidity router on Amoy:Pre-swap: moves MockEURC from the vault into the pool as input.Post-swap: enforces a minimum MockUSDC output taken directly from the x402 payment requirements; if the threshold isn’t met, the entire tx reverts.On success: pushes MockUSDC and any residual MockEURC back to the vault, so vault accounting is always consistent.Off-chain x402 HTTP server (Python) that:On first request returns HTTP 402 with a structured “payment requirements” JSON (token, chain, vault, amount, deadline).On second request accepts an X-PAYMENT payload containing signed EIP-712 permits and triggers the on-chain facilitator call.Client script that:Parses the x402 object,Queries an off-chain EUR/USD price feed (mocked),Computes max MockEURC spend, builds and signs the buyer/seller permits, and resubmits the HTTP call.Finality-aware watcher that:Subscribes to events like VaultFunded / FulfillmentEvent,Waits until the corresponding block reaches a configured Amoy finality threshold (confirmation depth),Only then calls the vault’s settle function to deliver MockUSDC to the seller, the asset to the buyer, and refund any excess MockEURC.ObservabilityEvent-driven tracker (CLI / simple web UI) that renders each step as a state transition: PaymentRequested → PermitsConsumed → SwapCompleted → VaultFunded → Settled.Notable technical innovationsTurning HTTP 402 into a machine-readable payment spec (x402), bridging Web2 and on-chain settlement cleanly.Using dual EIP-2612 permits to atomically fund a vault from both buyer and seller in one transaction.A vault-safe Uniswap V4 hook that enforces min-out guarantees and keeps vault balances coherent without relying on off-chain checks.Finality-gated settlement, where vault release is explicitly tied to chain finality rather than just inclusion.