A2A Registry Extension (v1)
Extension for A2A agent cards providing identity hints and payment capability declarations
Using A2A v0.3 or older agent cards?
You can still use payment discovery with legacy metadata fields. See the v0.3 Legacy Payment Metadata Guide for details.
https://a2a-registry.org/extensions/registry/v1Declare this URI in your agent card's capabilities.extensions array to use these features.
Overview
The A2A Registry extension provides two capabilities for agent cards:
- Identity hints — help the registry deduplicate agents from unofficial domains (Workers, GitHub Pages)
- 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 personal or free hosting platforms (such as *.workers.dev, *.vercel.app, or *.github.io), identity hints enable the registry to verify developer ownership and allow claiming under an authorized namespace.
Providers
- GitHub (
provider: "github"):identity.username— your GitHub username (case-insensitive matching)identity.packageName(required) — package name of the agent to match for claiming (e.g.,"dev.workers.youruser.my_agent"or"github.youruser.my_agent")
- Verified Domain (
provider: "domain"):identity.domain— apex or subdomain verified by your organization (e.g.,"acme.ai")identity.packageName(required) — package name of the agent to match for claiming (e.g.,"dev.workers.youruser.my_agent"or"ai.acme.my_agent")
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.
Examples
1. GitHub User Hint:
{
"params": {
"identity": {
"provider": "github",
"username": "youruser",
"packageName": "github.youruser.my_agent"
}
}
}2. Domain-Verified Organization Hint:
{
"params": {
"identity": {
"provider": "domain",
"domain": "acme.ai",
"packageName": "ai.acme.my_agent"
}
}
}Domain Verification & Claiming Workflow
If your agent is hosted on your own custom domain, you can claim it under your organization's verified namespace. This links the listing to your organization account and unlocks owner features (refresh, analytics, reviews management).
Step-by-step
- Verify your domain — Go to Organization Settings → Domains and add your apex domain (e.g.,
acme.ai). Follow the DNS TXT record instructions to complete verification. - Add the identity hint to your agent card — In your agent's
agent.json, declare the registry extension withprovider: "domain"and setdomainto your verified domain:{ "capabilities": { "extensions": [{ "uri": "https://a2a-registry.org/extensions/registry/v1", "required": false, "params": { "identity": { "provider": "domain", "domain": "acme.ai", "packageName": "ai.acme.my_agent" } } }] } } - Claim the agent — Either:
- Use Submit & Claim on the Card Builder page while signed in — the registry auto-detects your domain hint and claims it in one step.
- Or, if the agent was already submitted anonymously, open its listing in the Console → Agents panel and click Claim. The registry verifies your organization owns the declared domain and transfers ownership.
Package name matching: packageName is required and used to match the agent listing you want to claim, ensuring you claim the intended agent and preventing abuse. The claim transfers ownership to your organization without changing the agent's package name.
Moving from a free-hosting domain to your own? After claiming both the legacy and new agent, you can supersede the old listing to consolidate its review history into the new one. See the Superseding Agents guide for the full workflow.
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 objectspayment.refs— array of extension URIs already declared in this card that describe runtime payment (e.g.["https://x402.org/extension/v1"]); the registry reads protocols/rails from them when not set explicitlypayment.skills— array of per-skill payment terms, each withskillId(required),price,currency, andunitpayment.meta— free-form object for anything buyers might search on: refund policy, SLA, settlement notes, etc.
Protocol IDs
x402— HTTP 402-based (Coinbase open standard)ap2— Agent Payment Protocolstripe— Stripe payment intentslightning-invoice— Bitcoin Lightning BOLT11 invoicesmanual— 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 protocolfeeModel(optional) —"feeless","low","variable"settlementTime(optional) —"instant","fast","standard"caip2(optional) — chain ID (e.g.,"eip155:8453"for Base)contractAddress(optional) — token contract addressverification(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"
}
]
}
}
}Example — Freemium agent with per-skill pricing, refs and meta
{
"params": {
"payment": {
"model": "freemium",
"direction": "inbound",
"refs": ["https://x402.org/extension/v1"],
"skills": [
{
"skillId": "weather-aware-plan",
"price": "0.03",
"unit": "call",
"currency": "USDC"
}
],
"meta": {
"settlement": "onchain",
"refund_policy": "not charged on failure",
"sla": "p95 < 2s"
}
}
}
}refs points to the x402 extension already declared in capabilities.extensions. The registry reads the network and asset from it automatically, so you don't need to repeat rails here. skills binds a price to a specific skill ID. meta is free-form and fully searchable.
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
Card Builder
Use the "Add Registry Extension" button to declare payment capabilities visually
Validator
Validate your agent card with the registry extension
Browse Payment-Enabled Agents
See examples of agents with payment capabilities
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.
Before (v0.3 metadata)
{
"metadata": {
"registryIdentityProvider": "github",
"registryIdentity": "youruser",
"registryPackageName": "github.youruser.agent"
}
}After (v1.0 extension)
{
"capabilities": {
"extensions": [{
"uri": "https://a2a-registry.org/extensions/registry/v1",
"required": false,
"params": {
"identity": {
"provider": "github",
"username": "youruser",
"packageName": "github.youruser.agent"
}
}
}]
}
}