T402 v2.8.0—Stellar support + 39 packages across 45 networks→
AdvancedA2A Transport

A2A Transport (Agent-to-Agent)

T402 payment flows over the Agent-to-Agent (A2A) protocol, enabling AI agents to pay each other for services.

Overview

The A2A transport adapts the T402 payment protocol for Google’s Agent-to-Agent protocol, enabling autonomous AI agents to monetize their services through on-chain payments.

Instead of HTTP status codes and headers, A2A uses task state and message metadata to signal payment requirements and submit payments.

Key Differences from HTTP

AspectHTTP TransportA2A Transport
Payment signal402 status codeTask state input-required
Requirements locationResponse bodyTask metadata
Payment submissionPayment-Signature headerMessage metadata
Settlement receiptPayment-Response headerTask metadata
State managementStatelessTask lifecycle
Error signalingHTTP status codesTask state failed

Payment Flow

Client sends task

The client agent sends a message/send request to the server agent.

Server signals payment required

Instead of HTTP 402, the server returns a task with state: "input-required" and payment requirements in metadata.

Client submits payment

The client signs the payment authorization and sends it back as a message with t402.payment.payload metadata.

Server verifies and settles

The server verifies the payment, settles on-chain, and completes the task with the response and settlement receipt.

Payment Required Signal

When a server agent requires payment, it returns a task in input-required state:

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "result": {
    "kind": "task",
    "id": "task-123",
    "status": {
      "state": "input-required",
      "message": {
        "role": "agent",
        "parts": [{ "text": "Payment required to access this service." }],
        "metadata": {
          "t402.payment.status": "payment-required",
          "t402.payment.required": {
            "t402Version": 2,
            "error": "Payment required",
            "resource": {
              "url": "a2a://agent/weather-tool",
              "description": "Weather data lookup",
              "mimeType": "application/json"
            },
            "accepts": [{
              "scheme": "exact",
              "network": "eip155:8453",
              "amount": "1000",
              "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              "payTo": "0xAgentAddress...",
              "maxTimeoutSeconds": 300
            }]
          }
        }
      }
    }
  }
}

Payment Submission

The client signs the payment and sends it back with the task ID for correlation:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": "req-002",
  "params": {
    "message": {
      "taskId": "task-123",
      "role": "user",
      "parts": [],
      "metadata": {
        "t402.payment.status": "payment-submitted",
        "t402.payment.payload": {
          "t402Version": 2,
          "scheme": "exact",
          "network": "eip155:8453",
          "payload": {
            "authorization": {
              "from": "0xClientAddress...",
              "to": "0xAgentAddress...",
              "value": "1000",
              "validAfter": 1700000000,
              "validBefore": 1700000300,
              "nonce": "0xabc..."
            },
            "signature": "0xdef..."
          }
        }
      }
    }
  }
}

Settlement Response

After successful verification and settlement, the task completes with the receipt:

{
  "kind": "task",
  "id": "task-123",
  "status": {
    "state": "completed",
    "message": {
      "role": "agent",
      "parts": [{ "text": "Weather in Tokyo: 22°C, sunny." }],
      "metadata": {
        "t402.payment.status": "payment-completed",
        "t402.payment.receipts": [{
          "success": true,
          "transaction": "0x1234abcd...",
          "network": "eip155:8453",
          "payer": "0xClientAddress..."
        }]
      }
    }
  }
}

AP2 Embedded Flow

The Agent Payments Protocol (AP2) extends A2A with a structured, mandate-based payment flow. Instead of carrying x402 requirements in message metadata, AP2 wraps them inside CartMandate artifacts using the W3C Payment Request format.

Embedded vs Standalone

AspectStandalone (A2A)Embedded (AP2)
Requirements locationt402.payment.required metadataCartMandate artifact DataPart
Payment submissiont402.payment.payload metadataPaymentMandate message DataPart
Payment method formatt402 PaymentRequirementsW3C PaymentMethodData wrapping t402
Cart supportNoYes (PaymentDetailsInit)
Mandate trackingNoYes (mandate IDs, receipts)
DetectionisStandaloneFlow(task)isEmbeddedFlow(task)

How It Works

In the embedded flow, the server creates a CartMandate with x402 requirements embedded in the PaymentMethodData:

{
  "artifacts": [{
    "kind": "ap2.cart",
    "name": "Cart Mandate",
    "parts": [{
      "kind": "data",
      "data": {
        "ap2.mandates.CartMandate": {
          "contents": {
            "payment_request": {
              "method_data": [{
                "supported_methods": "https://www.x402.org/",
                "data": { "requirements": [{ "scheme": "exact", "network": "eip155:8453", "..." }] }
              }]
            }
          }
        }
      }
    }]
  }]
}

The client extracts the requirements, signs the payment, and wraps it in a PaymentMandate DataPart in a message.

See the AP2 Integration guide for the full embedded flow with code examples.

Payment Status Lifecycle

StatusTask StateDescription
payment-requiredinput-requiredServer needs payment
payment-submittedworkingClient sent payment payload
payment-verifiedworkingPayload verified
payment-completedcompletedSettled on-chain
payment-rejectedfailedClient declined to pay
payment-failedfailedVerification or settlement failed

Extension Declaration

Agent Card

Server agents advertise T402 support in their Agent Card:

{
  "name": "Weather Agent",
  "capabilities": {
    "extensions": [
      {
        "uri": "https://github.com/google-a2a/a2a-t402/v0.1",
        "description": "Accepts T402 USDT payments",
        "required": true
      },
      {
        "uri": "https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2",
        "description": "x402 v0.2 compatibility",
        "required": false
      }
    ]
  }
}

Client Activation

Clients signal T402 support via an HTTP header on the A2A connection:

X-A2A-Extensions: https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2

Error Handling

When payment fails, the task transitions to failed state with error details:

{
  "kind": "task",
  "id": "task-123",
  "status": {
    "state": "failed",
    "message": {
      "role": "agent",
      "parts": [{ "text": "Payment verification failed." }],
      "metadata": {
        "t402.payment.status": "payment-failed",
        "t402.payment.error": "EXPIRED_PAYMENT",
        "t402.payment.receipts": [{
          "success": false,
          "errorReason": "Payment authorization has expired",
          "network": "eip155:8453"
        }]
      }
    }
  }
}

Error Codes

Error CodeDescriptionRecovery
EXPIRED_PAYMENTAuthorization deadline passedRetry with new signature
INSUFFICIENT_AMOUNTAmount less than requiredRetry with correct amount
INVALID_SIGNATURESignature verification failedCheck signer address
NETWORK_MISMATCHWrong networkUse correct network from accepts
SETTLEMENT_FAILEDOn-chain settlement failedRetry or try different network

Metadata Fields Reference

FieldLocationDescription
t402.payment.statusMessage metadataCurrent payment lifecycle state
t402.payment.requiredMessage metadataPaymentRequired object (same as HTTP 402 body)
t402.payment.payloadMessage metadataSigned PaymentPayload
t402.payment.receiptsMessage metadataArray of settlement receipts
t402.payment.errorMessage metadataError code string
x402.payment.statusMessage metadatax402 compat alias for t402.payment.status
x402.payment.requiredMessage metadatax402 compat alias for t402.payment.required
x402.payment.payloadMessage metadatax402 compat alias for t402.payment.payload
x402.payment.receiptsMessage metadatax402 compat alias for t402.payment.receipts
x402.payment.errorMessage metadatax402 compat alias for t402.payment.error

Implementation Example

import { A2AServer } from '@google/a2a'
 
const server = new A2AServer({
  agentCard: {
    name: 'Premium Data Agent',
    capabilities: {
      extensions: [{
        uri: 'https://github.com/google-a2a/a2a-t402/v0.1',
        required: true
      }]
    }
  }
})
 
server.onMessage(async (message, task) => {
  // Check for payment
  const paymentPayload = message.metadata?.['t402.payment.payload']
 
  if (!paymentPayload) {
    // Return payment required
    return task.requireInput({
      metadata: {
        't402.payment.status': 'payment-required',
        't402.payment.required': {
          t402Version: 2,
          accepts: [{
            scheme: 'exact',
            network: 'eip155:8453',
            amount: '1000',
            asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
            payTo: agentAddress,
            maxTimeoutSeconds: 300
          }]
        }
      }
    })
  }
 
  // Verify and settle payment
  const receipt = await facilitator.settle(paymentPayload)
 
  // Return result with receipt
  return task.complete({
    parts: [{ text: 'Here is your data...' }],
    metadata: {
      't402.payment.status': 'payment-completed',
      't402.payment.receipts': [receipt]
    }
  })
})

Comparison with MCP Transport

FeatureA2A TransportMCP Transport
Use caseAgent-to-agent servicesTool access for AI models
ProtocolJSON-RPC + tasksJSON-RPC + tool calls
Payment signalTask input-requiredTool result with 402
StateTask lifecycleStateless per call
DiscoveryAgent CardMCP server manifest

For AI agents accessing tools (like weather APIs), use the MCP transport. For agents providing services to other agents, use A2A.

Related

MCP IntegrationAP2 Integration