@t402/a2a

A2A (Agent-to-Agent) transport implementation for the t402 payment protocol. Enables AI agents to monetize their services through on-chain cryptocurrency payments using the A2A protocol.

Installation

npm install @t402/a2a
# or
pnpm add @t402/a2a

Overview

This package provides tools for implementing t402 payments over the A2A (Agent-to-Agent) protocol:

• A2APaymentClient: Client-side payment handling for AI agents requesting services
• A2APaymentServer: Server-side payment processing for AI agents providing services
• Type definitions: Complete TypeScript types for A2A payment flows
• Helper functions: Utilities for creating and parsing payment messages

Usage

Client-Side (Requesting Services)

import { A2APaymentClient } from "@t402/a2a";
import { ExactEVMClient } from "@t402/evm/exact/client";

// Create a payment client
const paymentClient = new A2APaymentClient({
  onPaymentRequired: (requirements) =>
    console.log("Payment required:", requirements),
  onPaymentSubmitted: (payload) =>
    console.log("Payment submitted:", payload),
});

// Create your mechanism client (e.g., EVM)
const mechanism = new ExactEVMClient({ signer: yourSigner });

// Handle payment flow
async function handleTask(task: A2ATask) {
  // Check if payment is required
  if (paymentClient.requiresPayment(task)) {
    // Get requirements and create payment
    const requirements = paymentClient.getRequirements(task);
    const payload = await paymentClient.createPayload(mechanism, requirements!);

    // Create message with payment
    const message = paymentClient.createPaymentMessage(payload);

    // Send message via A2A protocol
    return message;
  }
}

// Or use the convenience method
const paymentMessage = await paymentClient.handlePayment(task, mechanism);

Server-Side (Providing Services)

import { A2APaymentServer } from "@t402/a2a";
import { HTTPFacilitatorClient } from "@t402/core/server";

// Create a payment server
const paymentServer = new A2APaymentServer({
  facilitator: new HTTPFacilitatorClient(),
  defaultRequirements: {
    resource: { url: "agent://my-agent/skill" },
  },
  onPaymentReceived: (payload) => console.log("Payment received:", payload),
  onPaymentSettled: (receipts) => console.log("Payment settled:", receipts),
});

// Create payment-required task for a new request
function createPaymentTask(taskId: string): A2ATask {
  const requirements = paymentServer.createRequirements({
    accepts: [
      {
        scheme: "exact",
        network: "eip155:8453",
        amount: "1000000", // 1 USDC
        asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        payTo: "0xYourAddress",
        maxTimeoutSeconds: 3600,
        extra: {},
      },
    ],
  });

  return paymentServer.createPaymentRequiredTask(taskId, requirements);
}

// Process payment when received
async function processPayment(
  task: A2ATask,
  message: A2AMessage,
  requirements: PaymentRequired,
): Promise<A2ATask> {
  const result = await paymentServer.processPayment(message, requirements);

  if (result.success) {
    // Payment successful, continue with task execution
    return {
      ...task,
      status: {
        state: "working",
        message: { kind: "message", role: "agent", parts: [{ kind: "text", text: "Processing..." }] },
      },
    };
  }

  // Payment failed
  return paymentServer.updateTaskWithPaymentResult(task, result);
}

API Reference

A2APaymentClient

Client for handling payments in A2A client agents.

| Method | Description | |--------|-------------| | requiresPayment(task) | Check if a task requires payment | | getRequirements(task) | Extract payment requirements from a task | | selectPaymentOption(requirements, network?, scheme?) | Select the best payment option | | createPayload(mechanism, requirements) | Create a signed payment payload | | createPaymentMessage(payload, text?) | Create an A2A message with payment | | handlePayment(task, mechanism, network?, scheme?) | Handle complete payment flow |

A2APaymentServer

Server for processing payments in A2A server agents.

| Method | Description | |--------|-------------| | createRequirements(requirements) | Create requirements with defaults | | createPaymentRequiredTask(taskId, requirements, text?) | Create a payment-required task | | extractPaymentPayload(message) | Extract payment from a message | | hasPaymentPayload(message) | Check if message contains payment | | processPayment(message, requirements) | Process a payment submission | | handlePayment(task, message, requirements) | Handle payment and update task | | updateTaskWithPaymentResult(task, result) | Update task with payment result |

Re-exported Types

All A2A types from @t402/core/types are re-exported:

• A2ATask, A2AMessage, A2ATaskStatus
• A2APaymentStatus, A2APaymentMetadata
• A2AAgentCard, A2ASkill, A2ACapabilities
• isPaymentRequired(), isPaymentCompleted(), isPaymentFailed()
• createPaymentRequiredMessage(), createPaymentSubmissionMessage()
• createPaymentCompletedMessage(), createPaymentFailedMessage()
• T402_A2A_EXTENSION_URI, A2A_EXTENSIONS_HEADER

A2A Extension

When advertising t402 payment support in your agent card:

import { createT402Extension } from "@t402/a2a";

const agentCard: A2AAgentCard = {
  name: "My AI Agent",
  url: "https://my-agent.example.com",
  capabilities: {
    extensions: [
      createT402Extension(true), // required = true
    ],
  },
  // ...
};

License

Apache-2.0