ap2

The AP2 (Agent Payments Protocol) extension declares payment roles for agents, enabling payment-aware agent discovery.

Installation

bun add @regent/ap2

Basic Usage

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { payments } from '@regent/x402';
import { ap2 } from '@regent/ap2';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .use(payments({ config: paymentsConfig }))
  .use(ap2({ roles: ['merchant'] }))
  .build();

API Reference

ap2(options?)

Creates the AP2 extension.

function ap2(options?: AP2Config): Extension<{ ap2?: AP2Runtime }>

AP2Config

type AP2Config = {
  roles: AP2Role[];
  description?: string;
  required?: boolean;
};

AP2Runtime

When the extension is used, agent.ap2 provides:

interface AP2Runtime {
  config: AP2Config;  // readonly
}

AP2 Roles

Agents can declare one or more payment roles:

Role	Purpose	Use Case
merchant	Accepts payments	Service provider, vendor
shopper	Makes payments	Buyer, consumer
credentials-provider	Provides credentials	KYC/AML provider
payment-processor	Processes payments	Payment gateway

type AP2Role = 'merchant' | 'shopper' | 'credentials-provider' | 'payment-processor';

Single Role

.use(ap2({ roles: ['merchant'] }))

Multiple Roles

.use(ap2({
  roles: ['merchant', 'shopper'],
  description: 'Trading agent that buys and sells'
}))

Manifest Integration

AP2 adds an extension descriptor to the Agent Card:

{
  "capabilities": {
    "extensions": [
      {
        "uri": "https://github.com/google-agentic-commerce/ap2/tree/v0.1",
        "description": "Agent Payments Protocol (AP2)",
        "required": true,
        "params": {
          "roles": ["merchant"]
        }
      }
    ]
  }
}

Default required Behavior

• required: true when 'merchant' role is included

• required: false otherwise

• Can be explicitly overridden

// Merchant defaults to required: true
.use(ap2({ roles: ['merchant'] }))

// Shopper defaults to required: false
.use(ap2({ roles: ['shopper'] }))

// Override default
.use(ap2({ roles: ['merchant'], required: false }))

Manual Card Enhancement

import { createAgentCardWithAP2 } from '@regent/ap2';

let card = buildAgentCard({ meta, registry, origin });
card = createAgentCardWithAP2(card, {
  roles: ['merchant'],
  description: 'Payment-enabled agent',
});

Detecting AP2 Support

Check if another agent supports AP2:

import { AP2_EXTENSION_URI } from '@regent/ap2';

const card = await fetchAgentCard('https://other-agent.example.com');

const ap2Extension = card.capabilities?.extensions?.find(
  ext => 'uri' in ext && ext.uri === AP2_EXTENSION_URI
);

if (ap2Extension) {
  console.log('Roles:', ap2Extension.params.roles);
}

Integration Examples

Payment Receiver (Merchant)

const merchantAgent = await createAgent({
  name: 'subscription-service',
  version: '1.0.0',
})
  .use(http())
  .use(payments({
    config: {
      payTo: '0x1234...',
      network: 'base-sepolia',
      facilitatorUrl: 'https://facilitator.example.com',
    },
  }))
  .use(ap2({
    roles: ['merchant'],
    description: 'Subscription payment service',
  }))
  .build();

Payment Sender (Shopper)

const shopperAgent = await createAgent({
  name: 'data-buyer',
  version: '1.0.0',
})
  .use(http())
  .use(ap2({
    roles: ['shopper'],
    required: false,
  }))
  .build();

Bidirectional Trading Agent

const tradingAgent = await createAgent({
  name: 'market-maker',
  version: '1.0.0',
})
  .use(http())
  .use(payments({ config: paymentsConfig }))
  .use(ap2({
    roles: ['merchant', 'shopper'],
    description: 'Buys and sells trading signals',
  }))
  .build();

AP2 and A2A Relationship

Aspect	A2A	AP2
Purpose	Agent discovery & communication	Payment capability declaration
Scope	Protocol-agnostic interface	Payment-specific roles
Required	Always present with a2a()	Optional, explicit config
Agent Card	Base structure	Extension metadata

AP2 extends A2A by adding payment information to Agent Cards.

Exports

// Extension
export { ap2 } from '@regent/ap2';

// Runtime
export { createAP2Runtime } from '@regent/ap2';

// Manifest
export { createAgentCardWithAP2 } from '@regent/ap2';

// Constants
export { AP2_EXTENSION_URI } from '@regent/ap2';

// Types
export type {
  AP2Config,
  AP2Runtime,
  AP2Role,
  AP2ExtensionDescriptor,
  AP2ExtensionParams,
} from '@regent/ap2';