A2A Protocol: x402 Payments Extension v0.1

1. Abstract

The x402 Payments Extension is an Extension for the Agent-to-Agent (A2A) protocol. It enables agents to monetize services through on-chain cryptocurrency payments, reviving the spirit of the HTTP 402 "Payment Required" status code for the world of decentralized agents.

This specification defines the required data structures, message flows, and state machine for requesting, authorizing, and settling payments within the A2A framework. It allows a server agent to require payment for a service, a client agent to authorize that payment using a secure wallet, and the server to verify and settle the transaction on a blockchain network.

2. Extension URI

The canonical URI for this version of the extension is: https://github.com/google-a2a/a2a-x402/v0.1

Implementations of this extension MUST use this URI for declaration and activation.

3. Extension Declaration

Agents that support this extension MUST declare it in the extensions array of their AgentCard.

{
  "capabilities": {
    "extensions": [
      {
        "uri": "https://github.com/google-a2a/a2a-x402/v0.1",
        "description": "Supports payments using the x402 protocol for on-chain settlement.",
        "required": true,
      }
    ]
  }
}

3.1. Required Extension

Setting required: true is recommended. This signals to clients that they MUST understand and implement the x402 protocol to interact with the agent's monetized skills. If a required extension is not activated by the client, the agent should reject the request.

4. Payment Protocol Flow

This x402 extension represents the payment lifecycle using two layers of state: the high-level A2A Task state (e.g., input-required, completed) and a more granular x402.payment.status metadata field in the A2A Message object that offers a detailed view of the payment process. The flow involves a Client Agent (acting on behalf of a user/client) that orchestrates interactions between a Merchant Agent (selling a service).

4.1. Roles & Responsibilities

The x402 payment protocol defines the interactions between four distinct architectural roles. While a single application might combine some of these functions (e.g., a Client Agent with an integrated Signing Service), understanding their logical separation is key to a secure and correct implementation.

Client Agent

The Client Agent acts on behalf of a user, orchestrating the payment flow.

Initiates service requests to the Merchant Agent.
Receives a Task that requires payment and processes the x402PaymentRequiredResponse.
- The agent first extracts the list of accepted PaymentRequirements from the response.
- It then determines whether to proceed with payment based on the terms (e.g., cost, asset, network).
  - If accepting, the agent selects a preferred PaymentRequirements option and has it signed by a designated signing service or wallet. This service securely signs the object to create the PaymentPayload.
  - If rejecting, the agent responds to the Merchant Agent with a x402.payment.status of payment-rejected.
Submits the signed payment authorization, packaged as an PaymentPayload, back to the Merchant Agent, ensuring the taskId is included to correlate the payment with the original request.
Waits for and processes the final Task from the Merchant Agent, which contains either the completed service result or a payment failure notice.

Merchant Agent

The Merchant Agent is a specialist agent that provides a monetized skill or service.

Determines when a service request requires payment and responds with an input-required Task containing a list of accepted payment requirements.
Receives the correlated payment submission from the Client Agent.
Communicates with a type of facilitator to first verify the payment's signature and validity, and then to settle the transaction on-chain.
Concludes the flow by returning a final Task to the Client Agent, containing the service result as an Artifact and the settlement details in a payment receipt.

Note: The Merchant Agent is responsible for state management, using the taskId to track the payment lifecycle. When it receives a payment submission, it uses the taskId to retrieve the original PaymentRequirements offered for that task. This allows the agent to validate that the signed PaymentPayload corresponds to a valid payment option it previously sent.

4.2. Architecture

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 Merchant Agent SHOULD ensure that the requested work is completed before settling the payment

4.3. Step 1: Payment Request (Merchant → Client)

When a Client Agent requests a service, the Merchant Agent determines that payment is required. It creates a Task, sets its status to input-required, and includes the x402PaymentRequiredResponse object in the metadata of the Task's message. This Task is sent back to the Client Agent.

Task State: input-required

Task Message Metadata: x402.payment.status: "payment-required", x402.payment.required: { ... }

/* Response from Merchant Agent to Client Agent */
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "result": {
    "kind": "task",
    "id": "task-123",
    "status": {
      "state": "input-required",
      "message": {
        "kind": "message",
        "role": "agent",
        "parts": [
          { "kind": "text", "text": "Payment is required to generate the image." }
        ],
        "metadata": {
          "x402.payment.status": "payment-required",
          "x402.payment.required": {
            "x402Version": 1,
            "accepts": [{
              "scheme": "exact",
              "network": "base",
              "resource": "https://api.example.com/generate-image",
              "description": "Generate an image",
              "mimeType": "application/json",
              "outputSchema": {},
              "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bda02913",
              "payTo": "0xServerWalletAddressHere",
              "maxAmountRequired": "48240000",
              "maxTimeoutSeconds": 600,
              "extra": {
                "name": "USD Coin",
                "version": 2
              }
            }]
          }
        }
      }
    }
  }
}

4.4. Step 2: Payment Authorization (Client → Wallet → Client)

The Client Agent receives the Task and must determine how to proceed:

Client selects the preferred Payment Requirements: The Client Agent extracts the x402PaymentRequiredResponse object from the task's message metadata, finds the preferred payment requirement object to sign and creates a PaymentPayload by signing the payment requirements via its wallet or preffered signing service.
Client Rejects PaymentRequirements: The client rejects all PaymentRequirements options and responds to the server agent with a message setting the message metadata field x402.payment.status to payment-rejected.

4.5. Step 3: Fulfill and Settle (Client → Merchant → Client)

Client relays signed payload to Merchant: The Client Agent prepares the signed payload and sends it back to the Merchant Agent in the metadata of a new Message. This message MUST include the taskId from the original payment request so the Merchant can correlate the payment to the correct service.

/* Request from Client Agent to Merchant Agent */
{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": "req-003",
  "params": {
    "message": {
      "taskId": "task-123", /* <-- CRITICAL: Links to the original request */
      "role": "user",
      "parts": [
        { "kind": "text", "text": "Here is the payment authorization." }
      ],
      "metadata": {
        "x402.payment.status": "payment-submitted",
        "x402.payment.payload": { /* ... The signed objects from the Client as a PaymentPayload  ... */ }
      }
    }
  }
}

Merchant verifies, settles, and completes: The Merchant receives the signed payload, verifies it, and settles the payment on-chain. It updates the original Task's x402.payment.status and includes the x402PaymentReceipt in the task's message metadata.

Task State: input-required → completed | working ... The management of intermediate Task states during the payment flow, such as transitioning to working during settlement, is at the discretion of the Merchant Agent's implementation.

Task Metadata: x402.payment.status: "payment-verified" → "payment-completed"

The Agent MUST include ALL payment receipts created in the lifetime of a Task in the final TaskStatus.message.

/* Payment Completed response from Merchant Agent to Client Agent */
{
  "jsonrpc": "2.0",
  "id": "req-003",
  "result": {
    "kind": "task",
    "id": "task-123",
    "status": {
      "state": "working",
      "message": { 
        "kind": "message",
        "role": "agent",
        "parts": [{ "kind": "text", "text": "Payment successful. Your image is ready." }],
        "metadata": {
          "x402.payment.status": "payment-completed",
          "x402.payment.receipts": [{
            "success": true,
            "transaction": "0xabc123...",
            "network": "base",
            "payer": "0xpayerAddress"
          }]
        }
      }
    },
    "artifacts": [ /* ... service result ... */ ],
  }
}

Note: The Task state may be working if the payment is complete but the primary Artifact is still being generated. The Task will transition to completed in a subsequent update.

5. Data Structures

5.1. `x402PaymentRequiredResponse`

Sent by the Merchant Agent in the metadata of a Task to request payment.

Field	Type	Required	Description
`x402Version`	number	Yes	The version of the x402 protocol being used (e.g., 1).
`accepts`	`PaymentRequirements[]`	Yes	An array of accepted payment options. The client can choose any one.

5.2. `PaymentRequirements`

Describes a single way a client can pay.

Field	Type	Required	Description
`scheme`	string	Yes	The payment scheme (e.g., "exact").
`network`	string	Yes	The blockchain network identifier (e.g., "base").
`asset`	string	Yes	The contract address of the token to be paid.
`payTo`	string	Yes	The recipient's wallet address.
`maxAmountRequired`	string	Yes	The required payment amount in the token's smallest unit (e.g., wei).
`resource`	string	No	A unique identifier for the resource being purchased.
`description`	string	No	A human-readable description of the payment.
`maxTimeoutSeconds`	number	No	The number of seconds the payment requirements are valid for.
`extra`	object	No	A container for additional scheme-specific data (e.g., EIP-712 domain info).

5.3. `PaymentPayload`

Created by the Signing Service, containing the signed payment authorization.

Field	Type	Required	Description
`x402Version`	number	Yes	The version of the x402 protocol being used.
`network`	string	Yes	The blockchain network for the payment.
`scheme`	string	Yes	The payment scheme being used.
`payload`	object	Yes	The signed payment details, specific to the scheme.

5.4. `x402SettleResponse`

Returned by the Merchant Agent in Task's Message metadata after a successful payment.

Field	Type	Required	Description
`success`	bool	Yes	Status of the transaction settlement
`errorReason`	string	No	Error reason for unsuccessful settlement
`transaction`	string	No	The on-chain transaction hash of the settled payment. Present only if `success` is true.
`network`	string	Yes	The network where the payment was settled.
`payer`	string	No	The payer of the settled transaction

6. Metadata and State Management

This extension uses the metadata field on the Message objects to track the payment state and transport data.

x402.payment.status: The current stage of the payment flow. Values:
- "payment-required": Payment requirements have been sent to client agent
- "payment-submitted": Payment payload has been received by the server agent
- "payment-rejected": Payment requirements have been rejected by the client
- "payment-verified": Payment payload has been sent to verified by the server agent
- "payment-completed": Payment transaction has been settled by the server agent
- "payment-failed": Payment payload failed to be verified, settled, or posted on-chain successfully.
x402.payment.required: Contains the x402PaymentRequiredResponse object sent from the Merchant.
x402.payment.payload: Contains the PaymentPayload object with the signed authorization from the signing service.
x402.payment.receipts: A persistent array containing the complete history of all x402SettleResponse objects for the task. Each new settlement attempt (successful or failed) MUST be appended to this array, never replacing it.
x402.payment.error: In case of failure, a short error code (e.g., "insufficient_funds").

6.1. State Transitions

stateDiagram-v2
    [*] --> PAYMENT_REQUIRED: Server Requires Payment
    PAYMENT_REQUIRED --> PAYMENT_REJECTED: Client Rejects Payment Requirements
    PAYMENT_REQUIRED --> PAYMENT_SUBMITTED: Client creates PaymentPayload
    PAYMENT_SUBMITTED --> PAYMENT_VERIFIED: Server agent verified submitted PaymentPayload
    PAYMENT_VERIFIED --> PAYMENT_COMPLETED: Payment settles and is now on chain.
    PAYMENT_VERIFIED --> PAYMENT_FAILED: Payment failed to be verified or settled
    PAYMENT_FAILED --> [*]
    PAYMENT_COMPLETED --> [*]

7. Extension Activation

Clients MUST request activation of this extension by including its URI in the X-A2A-Extensions HTTP header.

X-A2A-Extensions: https://github.com/google-a2a/a2a-x402/v0.1

The server agent MUST echo the URI in the response header to confirm activation.

8. Error Handling

If a payment fails, the server MUST set the x402.payment.status to payment-failed and provide a reason in the TaskStatus message and metadata. The management of Task states at payment failure is at the discretion of the Merchant Agent's implementation. For example the agent could leave the Task state as working or request a payment requirement with input-required again.

8.1. Common Error Codes

Code	Description
`INSUFFICIENT_FUNDS`	The client's wallet has insufficient funds to cover the payment.
`INVALID_SIGNATURE`	The payment authorization signature could not be verified.
`EXPIRED_PAYMENT`	The payment authorization was submitted after its expiry time.
`DUPLICATE_NONCE`	The nonce for this payment has already been used.
`NETWORK_MISMATCH`	The payment was signed for a different blockchain network.
`INVALID_AMOUNT`	The payment amount does not match the required amount.
`SETTLEMENT_FAILED`	The transaction failed on-chain for a reason other than the above.

8.2. Example Error Response

{
  "kind": "task",
  "id": "task-123",
  "status": {
    "state": "failed",
    "message": {
      "kind": "message",
      "role": "agent",
      "parts": [{ "kind": "text", "text": "Payment verification failed: The signature has expired." }],
      "metadata": {
        "x402.payment.status": "payment-failed",
        "x402.payment.error": "EXPIRED_PAYMENT",
        "x402.payment.receipts": [{
            "success": false,
            "errorReason": "Payment authorization was submitted after its 'validBefore' timestamp.",
            "network": "base",
        "transaction": ""
        }]
      }
    }
  }
}

9. Security Considerations

Private Key Security: Private keys MUST only be handled by trusted entities and never be handled directly by any LLM operating an agent.
Signature Verification: Server agents MUST cryptographically verify every payment signature before attempting settlement.
Input Validation: Servers MUST rigorously validate the contents of all payment-related data structures.
Replay Protection: Servers MUST track used nonces to prevent replay attacks.
Transport Security: All A2A communication MUST use a secure transport layer like HTTPS/TLS

10. References

A2A Protocol Specification: The core Agent-to-Agent protocol specification, defining the base data structures and methods that this extension builds upon.
A2A Extensions Documentation: The official documentation on how to create and use extensions within the A2A protocol.
x402 Protocol Specification: The underlying x402 payments protocol specification that provides the conceptual framework for this A2A extension.

Navigation Menu

Repository navigation

spec.md

spec.md

A2A Protocol: x402 Payments Extension v0.1

1. Abstract

2. Extension URI

3. Extension Declaration

3.1. Required Extension

4. Payment Protocol Flow

4.1. Roles & Responsibilities

Client Agent

Merchant Agent

4.2. Architecture

4.3. Step 1: Payment Request (Merchant → Client)

4.4. Step 2: Payment Authorization (Client → Wallet → Client)

4.5. Step 3: Fulfill and Settle (Client → Merchant → Client)

5. Data Structures

5.1. `x402PaymentRequiredResponse`

5.2. `PaymentRequirements`

5.3. `PaymentPayload`

5.4. `x402SettleResponse`

6. Metadata and State Management

6.1. State Transitions

7. Extension Activation

8. Error Handling

8.1. Common Error Codes

8.2. Example Error Response

9. Security Considerations

10. References

FilesExpand file tree

spec.md

Latest commit

History

spec.md

File metadata and controls

A2A Protocol: x402 Payments Extension v0.1

1. Abstract

2. Extension URI

3. Extension Declaration

3.1. Required Extension

4. Payment Protocol Flow

4.1. Roles & Responsibilities

Client Agent

Merchant Agent

4.2. Architecture

4.3. Step 1: Payment Request (Merchant → Client)

4.4. Step 2: Payment Authorization (Client → Wallet → Client)

4.5. Step 3: Fulfill and Settle (Client → Merchant → Client)

5. Data Structures

5.1. x402PaymentRequiredResponse

5.2. PaymentRequirements

5.3. PaymentPayload

5.4. x402SettleResponse

6. Metadata and State Management

6.1. State Transitions

7. Extension Activation

8. Error Handling

8.1. Common Error Codes

8.2. Example Error Response

9. Security Considerations

10. References

5.1. `x402PaymentRequiredResponse`

5.2. `PaymentRequirements`

5.3. `PaymentPayload`

5.4. `x402SettleResponse`