A2A x402 Extension

The x402 extension tracks payment progress using the metadata field on Message objects. Developers must use specific keys depending on whether they are implementing a Standalone Flow or an Embedded Flow.

Required Keys

• x402.payment.status: (Required) The current stage of the payment flow. This MUST be present in all x402-related messages.
• x402.payment.receipts: (Required) A persistent array containing the complete history of all x402SettleResponse objects for the task. This MUST be present in the final task message.

Flow-Specific Keys

• Standalone Flow Only:
  • x402.payment.required: The default metadata key for the x402PaymentRequiredResponse object.
  • x402.payment.payload: The default metadata key for the PaymentPayload object.
  • Note: These MUST NOT be used if an Embedded Flow is active.

Status Values for x402.payment.status

• payment-required: Payment requirements have been sent.
• payment-submitted: Payment payload has been received.
• payment-rejected: Payment requirements have been rejected.
• payment-verified: Payment payload has been verified.
• payment-completed: Payment transaction has been settled.
• payment-failed: Payment failed.

The exact scheme is a specific implementation of the x402 protocol designed for UMA. It allows for payments of a specific amount over Bitcoin using UMA, either by sending payments directly to a UMA address or by using a provided UMA invoice.

Protocol Flow:

1. Request: Client requests a resource from a Resource Server.
2. Challenge: Resource Server returns 402 Payment Required with paymentRequirements (using the exact scheme).
3. Payment: Client either sends an LNURLp request to the payTo address OR decodes the umaInvoice found in the extra field to send a pay request to the specified URL.
4. Settlement: Client completes the UMA handshake and makes the payment.
5. Verification: Client retries the original request, including an X-PAYMENT header containing the payment proof.
6. Access: Resource Server verifies the proof and returns the resource with a 200 OK and an X-PAYMENT-RESPONSE header.

The x402 extension manages the lifecycle of a payment through three main steps involving a Client Agent and a Merchant Agent:

1. Payment Request (Merchant → Client): The Merchant Agent identifies a service requires payment. It responds with a Task in the input-required state. The task's message metadata contains x402.payment.status: "payment-required" and an x402.payment.required object listing accepted payment terms.
2. Payment Authorization (Client → Wallet → Client): The Client Agent evaluates the requirements. If accepting, it selects a requirement and uses a signing service/wallet to create a signed PaymentPayload. If rejecting, it responds with x402.payment.status: "payment-rejected".
3. Fulfill and Settle (Client → Merchant → Client): The Client Agent sends a new message to the Merchant containing the PaymentPayload and the original taskId. The Merchant verifies and settles the payment on-chain, then updates the task status (e.g., to payment-verified or payment-completed) and includes x402.payment.receipts in the metadata.

sequenceDiagram
    participant Client Agent
    participant Merchant Agent
    Client Agent->>Merchant Agent: 1. Request service (Message)
    Merchant Agent-->>Client Agent: 2. Respond with Task (state: 'input-required', message: { metadata: x402PaymentRequiredResponse })
    Client Agent->>Client Agent: 3. Create signed PaymentPayload (Typically signed by a wallet or separate service)
    Client Agent->>Merchant Agent: 4. Fulfill request (Message with metadata containing PaymentPayload & taskId)
    Merchant Agent->>Merchant Agent: 5. Verifies and settles the PaymentPayload (Typically verified by an x402 Facilitator) and begins processing the task*.
    Merchant Agent-->>Client Agent: 6. Respond with updated Task (state: e.g., 'working', message: { metadata: { x402.payment.receipts: [...] }, payment-status: payment-verified | payment-complete })

The exact scheme is a specialized x402 protocol implementation for Bitcoin's Lightning Network. It uses the BOLT11 invoice standard to facilitate instant, low-fee micropayments.

Key characteristics:

• Instant Settlement: Sub-second confirmation.
• Micropayment Friendly: Supports sub-cent transactions.
• Security: Uses preimage verification and protects against invoice reuse and routing attacks.

Protocol Flow:

1. Client requests a resource from the Resource Server.
2. Resource Server requests a BOLT11 invoice from a Lightning Facilitator.
3. Resource Server returns a 402 Payment Required response containing PaymentRequirements (including the invoice in the extra field).
4. Client signs an authorization for that specific invoice.
5. Client submits a PaymentPayload containing the signed authorization.
6. Resource Server asks the Facilitator to verify the signature.
7. Resource Server asks the Facilitator to settle the payment (the facilitator pays the invoice on the Lightning Network).
8. Resource Server grants access upon successful settlement.

The Signing Service is a recommended architectural pattern for security and domain separation. While the x402 spec does not mandate a specific implementation, separating signing logic from the Client Agent allows for the use of secure environments like HSMs, MPC, or hardware wallets.

Implementation Options:

1. Separate Signing Service (Recommended): The Client Agent communicates with an independent service. This creates a clear security boundary.
2. Integrated Signing: The Client Agent handles signing directly. This is spec-compliant but offers less domain separation.

Core Responsibility: Receive an x402PaymentRequiredResponse, select an appropriate PaymentRequirements option from the accepts list, sign it using a private key/account, and return a PaymentPayload.

# Example pattern for a Signing Service
class SigningServiceOperations:
    def __init__(self, account: Account):
        self._account = account
        
    async def process_payment_required(
        self, 
        payment_required: x402PaymentRequiredResponse, 
        max_value: Optional[int] = None
    ) -> PaymentPayload:
        # 1. Select requirement
        selected_requirement = self._select_payment_requirement(payment_required.accepts)
        # 2. Sign requirement
        payment_payload = await process_payment(selected_requirement, self._account, max_value)
        return payment_payload

    def _select_payment_requirement(
        self, 
        accepts: list[PaymentRequirements]
    ) -> PaymentRequirements:
        return accepts[0]  # Implementation specific selection logic

In an Embedded Flow, an order authorization (e.g., AP2 PaymentMandate) envelops the x402PaymentPayload. Because x402 is a "push" payment method, the payload itself is the cryptographic authorization. The specification supports three patterns to handle this without excessive user friction:

1. Atomic Signing (Human-Present Flow)

Recommended for direct, human-present transactions.

• The Client Agent assembles both the unsigned order authorization and the unsigned x402PaymentPayload.
• A compatible wallet presents a single, unified confirmation to the user.
• The wallet performs two signatures: first the x402PaymentPayload, then the complete order authorization containing the signed payload.

2. Delegated Signing (Human-Not-Present Flow)

Ideal for asynchronous agentic commerce.

• The user provides a pre-authorization signature at an earlier time, granting the Client Agent authority within specific constraints.
• The Client Agent uses its own or a delegated key to sign both the x402PaymentPayload and the order authorization at the time of execution.

3. Smart Contract Escrow (Decoupled Flow)

Ideal for pre-funded users.

• Setup: User moves funds into a smart contract (one-time on-chain "push").
• Checkout: The Client Agent constructs only the order authorization. The user signs this single off-chain message.
• Settlement: The Merchant Agent presents the signed order to the smart contract, which verifies the signature and rules, then releases the pre-deposited funds to the merchant.