Feature Request: Enable EIP-4337 Smart Wallet / UserOperation Support in x402 Protocol

[takasaki404]

Enable EIP-4337 Smart Wallet / UserOperation Support in x402 Protocol

1. Summary

We propose an extension to the x402 protocol that adds first-class support for smart contract wallets (account abstraction) and EIP-4337 style UserOperations. This enhancement enables clients using smart wallets (rather than simple EOAs) to generate and submit payment payloads conforming to x402 flows, including verification and settlement of UserOperations, thus making x402 compatible with next-gen wallet models and on-chain UX patterns.

2. Motivation

Currently, x402 supports payments via “wallet signing” of a payment payload, typically by an externally-owned account (EOA) transferring tokens via a facilitator. While effective, this model does not fully support smart contract wallets, meta-transactions, account abstraction flows, or bundler/Paymaster models.

With the rise of smart wallets (e.g., those created via SDKs like Alchemy Account Kit and Coinbase Smart Accounts) and the broader adoption of EIP-4337, extending x402 to include these will:

• Enable gas-less, sponsored, or token-paid gas flows for x402 clients.
• Permit users/agents to pay using smart wallets that batch operations, include permit/approval logic, or execute via Paymasters.
• Support payment delegation scenarios — for example, session keys or delegated smart-wallet flows where an agent or service can submit on behalf of a user under constrained authority — thereby broadening x402’s applicability to more agentic, delegated, and automation-centric use cases.
• Keep x402 up to date with the evolving Web3 wallet landscape, improving adoption among AI agents, SDKs, and decentralized services.
• Maintain the same developer-friendly HTTP flow (402 + X-PAYMENT header) while unlocking more flexible wallet semantics.

3. Architecture

Below is the proposed architecture and how the protocol flow would evolve:

3.1 Terminology additions

• Smart Wallet: A contract-based wallet (account abstraction) that supports EIP-4337 UserOperations.
• UserOperation: The standardized payload defined in EIP-4337 (sender, nonce, callData, initCode, paymasterAndData, etc).
• Facilitator / Bundler: The entity (or service) that receives the UserOperation, verifies it (via EntryPoint simulation), and submits it on-chain.
• Paymaster Flow: Optional gas sponsorship via a Paymaster contract; can be triggered by the UserOperation’s paymasterAndData field.

3.2 Payment Instruction (HTTP 402) phase

When a client requests a pay-gated resource and receives HTTP 402 with payment instructions, the server returns a PaymentRequirements object. To support ERC-4337 UserOperations, we extend the extra field within each payment option:

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "10000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "resource": "https://api.example.com/data",
      "description": "Access to premium market data",
      "mimeType": "application/json",
      "outputSchema": null,
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USDC",
        "version": "2",
        "userOperation": {
          "supported": true,
          "bundlerUrl": "https://bundler.example.com",
          "paymaster": "0xPaymasterAddress"
        }
      }
    }
  ]
}

Extension to the extra field:

• userOperation.supported (boolean): When true, indicates the facilitator supports ERC-4337 UserOperation payments for this payment option
• userOperation.bundlerUrl (string, optional): The bundler endpoint URL that the facilitator uses
• userOperation.paymaster (string, optional): Paymaster contract address if gas sponsorship is available

When extra.userOperation.supported is true, the client knows it can build a UserOperation instead of the conventional EOA authorization.

Important: The facilitator does NOT specify the EntryPoint contract address here. The client will specify which EntryPoint contract it uses when submitting the UserOperation payload, and the facilitator must support the canonical EntryPoint contracts for the specified network (e.g., v0.6, v0.7, v0.8 as defined by ERC-4337).

If extra.userOperation.supported is false or the field is absent, the client falls back to legacy "authorization" flow (e.g., ERC-3009).

3.3 Client builds and signs a UserOperation

• The client’s smart wallet (EOA + contract, or full contract wallet) constructs a UserOperation whose callData executes the transfer of the token (e.g., USDC) from the smart wallet to the payTo address for the specified amount.
• If extra.paymaster is present, the UserOperation’s paymasterAndData field is set accordingly, enabling gas sponsorship.
• The client specifies which canonical EntryPoint contract it is using by including the entryPoint address in the payload. This should be one of the canonical EntryPoint contracts deployed for that network (e.g., v0.6, v0.7, or v0.8).
• The client then serializes the UserOperation (as JSON) and includes it in the HTTP X-PAYMENT header.
• Example payload:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base-sepolia",
  "payload": {
    "entryPoint": "0x0000000071727De22E5E9d8BAf0edAc6f37da032",
    "userOperation": {
      "sender": "0xSmartWalletAddress0123456789abcdef",
      "nonce": "0x0000000000000000000000000000000000000000000000000000000000000042",
      "initCode": "0x",
      "callData": "0x095ea7b300000000000000000000000000209693Bc6afc0C5328bA36FaF03C514EF312287C0000000000000000000000000000000000000000000000000000000000002710",
      "callGasLimit": "0x0000000000000000000000000000000000000000000000000000000000098968",
      "verificationGasLimit": "0x0000000000000000000000000000000000000000000000000000000000027100",
      "preVerificationGas": "0x0000000000000000000000000000000000000000000000000000000000001f40",
      "maxFeePerGas": "0x000000000000000000000000000000000000000000000000000000000000012c",
      "maxPriorityFeePerGas": "0x00000000000000000000000000000000000000000000000000000000000000a",
      "paymasterAndData": "0xPaymasterAddress000000000000000000000000000000000000000000000000000000000000",
      "signature": "0xabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
    }
  }
}

Note: The entryPoint field specifies the canonical EntryPoint contract address (in this example, v0.7's address). The facilitator validates this is a supported EntryPoint for the network.

3.4 Server/Resource verification & settlement

• The resource server receives the request with the X-PAYMENT header. The scheme is always "exact". The server checks whether the payload contains a userOperation object (indicating ERC-4337 payment) or legacy authorization data (e.g., ERC-3009).
• For UserOperation payments: the server forwards the payload to its facilitator's /verify endpoint. The facilitator validates that the entryPoint specified by the client is a canonical EntryPoint contract it supports (e.g., v0.6, v0.7, or v0.8 for that network). If unsupported, the facilitator rejects the request.
• The facilitator then simulates the UserOperation using the specified EntryPoint's simulateValidation function, verifying valid sender, correct callData, sufficient allowance/balance, valid nonce, paymaster constraints (if any).
• If the simulation passes, the facilitator returns isValid: true. Then the facilitator issues /settle or directly calls the bundler/RPC to submit the UserOperation to the specified EntryPoint on-chain. Once mined, the facilitator returns the txHash, networkId, etc.
• The server then responds with 200 OK and may include an X-PAYMENT-RESPONSE header with settlement proof.
• For legacy authorization flows (scheme "exact" without userOperation.supported), the existing x402 settlement path is unchanged.

3.5 Optional gas sponsorship / Paymaster flow

• If the extra.userOperation.paymaster field is provided, the UserOperation leverages a Paymaster contract so that the user’s smart wallet doesn’t pay gas. The seller/facilitator would fund or operate the Paymaster.
• This enables “gasless” client payments: the user only transfers tokens (USDC) and the aggregator/facilitator handles gas.
• If no Paymaster is configured, the client’s smart wallet must hold native ETH/chain token, but the rest of the flow remains unchanged.
• The x402 server API may advertise in payment requirements whether gas sponsorship is available (via a boolean gasSponsored: true).

3.6 Backwards compatibility

• Existing clients and servers that do not support smart wallets continue to use scheme: "exact" with legacy authorization (e.g., ERC-3009 TransferWithAuthorization).
• New clients, when they see extra.userOperation.supported: true, can opt-in to using UserOperations while still maintaining scheme: "exact".
• Facilitators must update to support verification and settlement for UserOperations; until then, they may advertise userOperation.supported: false.
• The extension does not alter the core x402 HTTP semantics (402 response, X-PAYMENT header). It only augments the payload schema.

4. Who we are

AiMo Network (https://aimo.network/) is building the Intelligence Capital Market On-Chain: a permissionless API infrastructure where agents, humans, and service providers interact and transact without censorship, borders or gatekeepers. Via pay-per-inference using x402, and an agent-native interface, AiMo connects humans, AI agents and service providers in a seamless Web3 ecosystem. We propose this extension to x402 so that “smart wallets + agent payments” become a first-class design pattern.