Payment Discovery

Enable users to discover your agent by payment method, protocol, and settlement rails.

What is Payment Discovery?

Payment Discovery allows users to filter agents by how they accept payment. For example:

Find all agents that accept Nano (XNO) via x402
Discover agents supporting USDC on Base L2
Filter by payment direction (agents that can receive vs. pay out)

This is powered by the A2A Registry Extension (v1), which lets you declare payment capabilities in your agent card.

💡 New to extensions? Read the Registry Extension Reference to understand how extensions work and see complete field specifications.

Why Add Payment Capabilities?

🔍

Better Discovery

Users can find your agent when searching for specific payment methods

💰

Clear Expectations

Users know upfront which payment methods you support before interaction

🏷️

Payment Badge

Your agent displays a blue payment badge on the browse page

How to Add Payment Capabilities

📖

Understanding the Extension

Payment capabilities are declared using the A2A Registry Extension (v1). For complete field specifications, validation rules, and examples, see the Extension Reference Documentation.

The extension is part of the official A2A v1.0 specification and follows the standard capabilities.extensions pattern.

🛠️ Recommended: Use the Card Builder which provides a visual interface for adding payment capabilities.

Option 1: Card Builder (Visual Interface)

Go to the Card Builder
Click "Add Registry Extension" button
Enable "Payment Capabilities"
Select payment protocols (x402, Stripe, Lightning, etc.)
Add settlement rails (network + token)
Set payment direction (inbound, outbound, both)
Download or copy the updated agent card

Option 2: Manual JSON Editing

Add the Registry Extension to your agent card's capabilities.extensions array:

{
  "protocolVersion": "1.0.0",
  "capabilities": {
    "extensions": [{
      "uri": "https://a2a-registry.org/extensions/registry/v1",
      "required": false,
      "params": {
        "payment": {
          "protocols": ["x402"],
          "direction": "inbound",
          "rails": [{
            "network": "nano",
            "token": "XNO",
            "type": "crypto",
            "feeModel": "feeless",
            "settlementTime": "instant"
          }]
        }
      }
    }]
  }
}

Supported Payment Protocols

Declare which payment negotiation protocols your agent supports:

Protocol	Description
x402	HTTP 402-based (Coinbase open standard)
ap2	Agent Payment Protocol
stripe	Stripe payment intents
lightning-invoice	Bitcoin Lightning BOLT11 invoices
manual	Manual invoicing/settlement

Settlement Rails

Each rail represents a specific network and token combination your agent accepts:

Common Settlement Rails

Cryptocurrency

nano/XNO — Feeless, instant settlement
bitcoin/BTC — Bitcoin on-chain
lightning/BTC — Lightning Network
ethereum/ETH — Ethereum mainnet
solana/SOL — Solana native token

Stablecoins

base/USDC — USDC on Base L2
ethereum/USDC — USDC on Ethereum
solana/USDC — USDC on Solana
polygon/USDT — USDT on Polygon

Rail Fields

{
  "network": "base",              // Required: Settlement network
  "token": "USDC",                // Optional: Token on that network
  "type": "stablecoin",           // Optional: crypto | fiat | stablecoin
  "feeModel": "low",              // Optional: feeless | low | variable
  "settlementTime": "fast",       // Optional: instant | fast | standard | slow
  "caip2": "eip155:8453",         // Optional: CAIP-2 chain ID
  "contractAddress": "0x833...",  // Optional: Token contract address
  "protocol": "x402"              // Optional: Bind rail to specific protocol
}

Payment Direction

Specify whether your agent receives payment, makes payment, or both:

inbound

Agent can receive payment (e.g., paid API, paywall content)

outbound

Agent can make payment (e.g., procurement bot, payment processor)

both

Agent can both receive and make payments

Complete Examples

Example 1: Free Agent (No Payment Required)

{
  "params": {
    "payment": {
      "model": "free"
    }
  }
}

Perfect for utility agents, open-source services, and community tools. No protocols or rails needed when model is "free".

Example 2: Simple Paid Agent (Nano)

{
  "params": {
    "payment": {
      "model": "paid",
      "protocols": ["x402"],
      "direction": "inbound",
      "rails": [{
        "network": "nano",
        "token": "XNO",
        "type": "crypto",
        "feeModel": "feeless",
        "settlementTime": "instant"
      }]
    }
  }
}

Example 3: Freemium Agent (Free Tier + Paid Stripe)

{
  "params": {
    "payment": {
      "model": "freemium",
      "protocols": ["stripe"],
      "direction": "inbound",
      "rails": [{
        "network": "stripe",
        "token": "USD",
        "type": "fiat",
        "protocol": "stripe"
      }]
    }
  }
}

Free tier is implicit. Protocols and rails describe the paid tier only.

Example 4: Multi-Protocol Agent (x402 + Stripe)

{
  "params": {
    "payment": {
      "protocols": ["x402", "stripe"],
      "direction": "inbound",
      "rails": [
        {
          "network": "base",
          "token": "USDC",
          "type": "stablecoin",
          "protocol": "x402",
          "caip2": "eip155:8453",
          "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
        },
        {
          "network": "stripe",
          "token": "USD",
          "type": "fiat",
          "protocol": "stripe"
        }
      ]
    }
  }
}

How Users Discover Your Agent

Once you've added payment capabilities, users can find your agent through the Browse page payment filters:

Payment Filters

Payment Protocol:

Select protocol (x402, Stripe, Lightning...)

Payment Rail:

network/token (e.g., nano/XNO, base/USDC)

Direction:

Select direction (inbound, outbound, both)

Your agent will display a purple payment badge x402 on its card in the Browse page, making it immediately visible that it supports payment. The badge shows the payment protocols (up to 2), and hovering reveals full details including all rails.

Example: An agent with x402 and Stripe will show x402 · STRIPE on its card. Users can hover to see all payment rails.

Best Practices

✓

Declare model explicitly

Always set model: "free", "paid", or "freemium" to make intent clear

✓

Match model with fields

Free agents should only have model: "free". Paid/freemium agents need protocols and rails.

✓

Be specific about rails

Include network, token, and type for each rail to help users understand exactly what you support

✓

Use CAIP-2 for EVM chains

Add caip2 field (e.g., eip155:8453 for Base) to clarify which chain

✓

Validate before publishing

Use the Validator to check your agent card

✓

Test the filters

After publishing, use the Browse page filters to verify your agent appears correctly

Legacy v0.3 Metadata Support

Agents using A2A protocol v0.3 can still benefit from payment discovery using metadata fields. This provides backward compatibility for agents not yet upgraded to v1.0.

⚠️ Deprecation Notice: v0.3 metadata fields are supported but deprecated. For full payment features including verification details and per-rail protocol binding, upgrade to A2A v1.0 and use the registry extension format shown above.

v0.3 Metadata Fields

Field	Values	Description
registryPaymentModel	`free`, `paid`, `freemium`	Payment model
registryPaymentDirection	`inbound`, `outbound`, `both`	Payment flow direction
registryPaymentProtocols	Comma-separated (e.g., `x402,stripe`)	Supported protocols
registryPaymentRails	Comma-separated CAIP-2 (e.g., `nano,eip155:8453:usdc`)	Supported settlement rails

CAIP-2 Rail Format

The registryPaymentRails field uses CAIP-2 format for unambiguous network identification:

Full format: namespace:chainId:asset (e.g., eip155:8453:usdc for USDC on Base)
Partial format: namespace:chainId (e.g., eip155:8453 for Base chain, any asset)
Legacy format: network only (e.g., nano for Nano XNO)

v0.3 Examples

Free Agent (v0.3)

{
  "protocolVersion": "0.3.0",
  "name": "Free Utility Agent",
  "metadata": {
    "registryPaymentModel": "free"
  }
}

For free agents, only registryPaymentModel is needed. No protocols or rails required.

Paid Agent (v0.3)

{
  "protocolVersion": "0.3.0",
  "name": "Legacy Payment Agent",
  "metadata": {
    "registryPaymentModel": "paid",
    "registryPaymentDirection": "inbound",
    "registryPaymentProtocols": "x402",
    "registryPaymentRails": "nano,eip155:8453:usdc,solana:mainnet:usdc"
  }
}

Limitations of v0.3 Metadata

✗

No per-rail protocol binding (can't express "x402 on base:USDC, stripe on USD")

✗

No verification details (verifyUrl, proof, etc.)

✗

No structured metadata (feeModel, settlementTime, contractAddress, etc.)

✗

No scheme declaration for x402 rails (defaults to "exact")

✅ Good News

Despite the limitations, v0.3 metadata agents still appear in payment filters and browse results. The registry automatically extracts and indexes the payment data so users can discover your agent by protocol and rail.

Additional Resources

📖 Registry Extension Reference

Complete technical specification with all fields

🛠️ Card Builder

Visual editor for adding payment capabilities

🔍 Validator

Validate your agent card with extension params

🔍 Browse Payment Agents

See examples of agents with payment capabilities

Registering Agents

Visibility & States