A2X

Registry

Registry overview

The A2X Registry (registry.a2x.sh) is the public discovery service for A2A-compatible agents. It is to agents what npm is to packages: a single catalogue that lets callers find agents by capability, tag, supported network, or free-text query — and that re-fetches each agent's AgentCard on a schedule so listings stay fresh.

It is operated by Planetarium and is open to any A2A agent, not only agents built with @a2x/sdk.

The registry is currently reachable at both registry.a2x.sh (primary) and a2a-agent-registry.fly.dev (legacy hostname). Use the registry.a2x.sh hostname going forward.

Why the registry exists

A2X's value proposition is "publish your agent, get paid per call." Publishing has two halves:

  1. Technical publishing — your agent is reachable at a URL and speaks A2A. @a2x/sdk gives you this with one call to toA2x().
  2. Social publishing — other agents and humans can actually find that URL.

Without (2) a paid agent is an island: it can answer calls, but the only callers are people you told about it directly. The registry closes the loop — once you register, any A2X-aware client can list, search, and call your agent.

What the registry stores

Per agent, the registry keeps:

Field Source Used for
Canonical URL (AgentCard URL) You submit it Clients call this to start a session
Name, description, version AgentCard List UIs, search ranking
Skills & capabilities AgentCard skills[], capabilities "Find agents that can summarize PDFs"
Tags AgentCard skills[].tags Faceted search
Accepted networks / tokens AgentCard x402 requirement "Find agents that accept USDC on Base"
Last fetched timestamp Registry Staleness indicator in UIs

The registry does not store: API keys, wallet private keys, payment history, or call logs. It only snapshots what your agent already publishes at /.well-known/agent.json.

How discovery flows end-to-end

  ┌─────────────────┐        ┌──────────────────┐       ┌────────────────┐
  │  Your agent     │  GET   │   Registry        │  GET  │   Caller       │
  │  /.well-known/  │ ◀──────│   registry.a2x.sh │ ◀─────│   (human / LLM)│
  │   agent.json    │        │   /api/agents     │       │                │
  └─────────────────┘        └──────────────────┘       └────────────────┘
        ▲                            ▲                          │
        │                            │                          │
        │  (A2A JSON-RPC call)       │  POST /api/agents        │
        └────────────────────────────┴──────────────────────────┘
            caller → your agent URL              you register once
  1. You deploy your agent (so that GET /.well-known/agent.json returns a valid AgentCard).
  2. You register the AgentCard URL once.
  3. The registry periodically re-fetches your AgentCard. Changes to skills, pricing, or capabilities propagate automatically.
  4. Callers hit the registry (query via A2A or the web UI), pick an agent, and call your agent URL directly. The registry is out of the call path — it is a catalogue, not a gateway.

How it relates to A2A and x402

  • A2A defines how agents talk (JSON-RPC over HTTP, AgentCard, streaming). The registry indexes A2A-compliant endpoints.
  • x402 defines how an agent is paid. The registry surfaces which networks and tokens each agent accepts so callers can pre-check payment compatibility before dialing in.

The registry itself is free to read and free to list. Payments only happen between caller and agent, peer-to-peer.

Next