A2A Registry Extension (v1)

Overview

The A2A Registry extension provides two capabilities for agent cards:

1. Identity hints — help the registry deduplicate agents from unofficial domains (Workers, GitHub Pages)
2. Payment capabilities — declare which payment protocols and settlement rails your agent supports

This extension is declared in the capabilities.extensions[] array of your agent card.

Extension Structure

{
  "capabilities": {
    "extensions": [
      {
        "uri": "https://a2a-registry.org/extensions/registry/v1",
        "description": "Registry metadata and payment capabilities",
        "required": false,
        "params": {
          "identity": { ... },
          "payment": { ... }
        }
      }
    ]
  }
}

Note: The required field must be false. The registry extension is advisory — it helps the registry organize and filter agents, but does not affect protocol-level compatibility.

Identity Hints

For agents hosted on *.workers.dev or *.github.io, identity hints help the registry treat multiple URLs as the same agent.

Fields

• identity.provider — always "github" for now
• identity.username — your GitHub username (case-insensitive matching)
• identity.packageName — must start with github.<username>.

v0.3 migration note: The v0.3 registryIdentity field maps to username in v1.0. All three v0.3 fields have direct equivalents: registryIdentityProvider → provider, registryIdentity → username, registryPackageName → packageName.

Example

{
  "params": {
    "identity": {
      "provider": "github",
      "username": "youruser",
      "packageName": "github.youruser.my_agent"
    }
  }
}

Payment Capabilities

Declare which payment protocols and settlement rails your agent supports so users can discover you by payment method.

Top-level fields

• payment.model — "free" | "paid" | "freemium" (recommended to declare explicitly)
• payment.protocols — array of protocol IDs (e.g., ["x402", "stripe"])
• payment.direction — "inbound" | "outbound" | "both"
• payment.rails — array of settlement rail objects

Protocol IDs

• 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

Rail Fields

• network (required) — e.g., "nano", "base", "stripe"
• token (optional) — e.g., "XNO", "USDC"
• type (optional) — "crypto" | "fiat" | "stablecoin"
• protocol (optional) — binds this rail to a specific protocol
• feeModel (optional) — "feeless", "low", "variable"
• settlementTime (optional) — "instant", "fast", "standard"
• caip2 (optional) — chain ID (e.g., "eip155:8453" for Base)
• contractAddress (optional) — token contract address
• verification (optional) — proof of address ownership

Example — Nano x402 Agent

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

Example — Multi-protocol Agent

{
  "params": {
    "payment": {
      "model": "paid",
      "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"
        }
      ]
    }
  }
}

Discovery Filters

Once declared, users can filter agents by:

• ?payment_model=free — free agents (no payment required)
• ?payment_model=paid — paid agents only
• ?payment_model=freemium — freemium agents (free + paid tiers)
• ?payment_protocol=x402 — agents supporting x402
• ?payment_rail=nano:XNO — agents accepting Nano XNO
• ?payment_direction=inbound — agents that can receive payment

Tools & Resources

Migration from v0.3 metadata

If your agent card uses the informal v0.3 metadata fields, you should migrate to the v1.0 extension pattern. The registry still reads v0.3 metadata as a fallback, but the extension takes priority.

{
  "metadata": {
    "registryIdentityProvider": "github",
    "registryIdentity": "youruser",
    "registryPackageName": "github.youruser.agent"
  }
}

{
  "capabilities": {
    "extensions": [{
      "uri": "https://a2a-registry.org/extensions/registry/v1",
      "required": false,
      "params": {
        "identity": {
          "provider": "github",
          "username": "youruser",
          "packageName": "github.youruser.agent"
        }
      }
    }]
  }
}