API Reference

Meta-Agent & API Reference

Integrate with A2A Registry programmatically using our A2A-compliant Meta-Agent.

The Registry Agent Card

A2A Registry itself is an A2A-compliant agent that other agents can discover and call. Our Agent Card is served at:

GET https://www.a2a-registry.org/.well-known/agent-card.json

{
  "agent_id": "registry",
  "name": "A2A Universal Registry",
  "description": "The root discovery service for the Agent Economy.",
  "capabilities": [
    {
      "name": "search_agents",
      "description": "Find agents based on natural language intent.",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "limit": { "type": "integer", "default": 5 }
        }
      }
    },
    {
      "name": "resolve_package",
      "description": "Get the Agent Card for a specific package ID."
    }
  ]
}

Search Agents

Request

POST https://api.a2a-registry.org/a2a/message
Content-Type: application/json

{
  "to": "registry",
  "action": "search",
  "params": {
    "query": "crypto price checker",
    "limit": 3
  }
}

Response

{
  "agents": [
    {
      "package_name": "com.coingecko.api",
      "description": "Real-time cryptocurrency prices",
      "verification_level": "domain_verified",
      "manifest_url": "https://coingecko.com/.well-known/agent-card.json"
    }
  ]
}

Integration Pattern

Here's how to integrate A2A Registry discovery into your agent:

// 1. Bootstrap: Add A2A Registry to your agent's initial tools
const tools = [
  {
    name: "registry_search",
    endpoint: "https://api.a2a-registry.org/a2a/message",
    params: ["query", "limit"]
  }
];

// 2. Discover: When you need a capability you don't have
const result = await callTool("registry_search", {
  query: "weather forecast API",
  limit: 1
});

// 3. Ingest: Parse the returned Agent Card
const weatherAgent = result.agents[0];
const capabilities = await fetch(weatherAgent.manifest_url);

// 4. Execute: Call the discovered agent directly
const weather = await callAgent(weatherAgent.package_name, {
  action: "get_forecast",
  params: { city: "Tokyo" }
});

Utility Agents (Standard Library)

A2A Registry hosts high-utility agents that are always available:

Web Reader

registry.utility.reader

Enable LLMs to read live web content (RAG)

Capability	Description
`extract_content(url)`	Returns cleaned Markdown from any URL

Wikipedia

registry.utility.wiki

Provide grounded truth from Wikipedia

Capability	Description
`search_page(query)`	Search Wikipedia pages
`get_summary(page_id)`	Get article summary

Finance

registry.utility.finance

Real-time financial data

Capability	Description
`get_current_price(symbol)`	Get crypto/stock price

REST API Endpoints

Public Endpoints

Method	Path	Description
`GET`	`/.well-known/agent-card.json`	Registry's own Agent Card
`GET`	`/public/agents`	List/search agents (supports payment filters)
`GET`	`/public/agents/:id`	Get agent by ID or package name
`GET`	`/public/agents/resolve/:packageName`	A2A protocol discovery (returns agent card)
`POST`	`/public/agents/search`	Semantic search (supports payment filters)

Payment Filters

All search endpoints support filtering by payment capabilities. Use these query parameters to find agents that accept specific payment methods:

Parameter	Description	Examples
`payment_model`	Payment model (comma-separated OR)	`free`, `paid`, `freemium`, `free,freemium`
`payment_protocol`	Payment negotiation protocol	`x402`, `stripe`, `lightning-invoice`
`payment_rail`	Settlement network and asset (flexible syntax)	`nano:xno`, `base:usdc`, `usdc`
`payment_direction`	Payment flow direction	`inbound`, `outbound`, `both`

Payment Rail Syntax

The payment_rail parameter supports multiple flexible formats:

Format	Example	Behavior
network:asset	`base:usdc`	Exact network, prefix-match asset (e.g., usdc, usdc.e, usdt)
network:	`nano:`	Network only (all assets on that network)
bare term	`usdc`	Prefix-matches network OR asset (union)
multi-term	`usdc, nano`	Each term evaluated independently, results OR-ed
mixed	`base:usdc nano`	Base USDC agents ∪ any nano agents/assets

Payment Filter Examples

Find all free agents

GET /public/agents?payment_model=free

Find free OR freemium agents

GET /public/agents?payment_model=free,freemium

Find all Nano agents

GET /public/agents?payment_rail=nano

Find Base USDC agents only

GET /public/agents?payment_rail=base:usdc

Find any USDC agents (Base, Ethereum, Solana, etc.)

GET /public/agents?payment_rail=usdc

Find Nano OR Base USDC agents

GET /public/agents?payment_rail=nano,base:usdc

Find x402 agents accepting Nano

GET /public/agents?payment_protocol=x402&payment_rail=nano

Find agents that can pay out (not just receive)

GET /public/agents?payment_direction=outbound

Combined: x402 agents accepting USDC or USDT on Base, inbound only

GET /public/agents?payment_protocol=x402&payment_rail=base:usd&payment_direction=inbound

Find paid x402 agents (exclude free/freemium)

GET /public/agents?payment_model=paid&payment_protocol=x402

JSON-RPC Payment Filters

The A2A v1.0 JSON-RPC endpoint (POST /a2a/v1) also supports payment filters via the SendMessage method:

POST /a2a/v1
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "jsonrpc": "2.0",
  "method": "SendMessage",
  "params": {
    "skill_id": "search_agents",
    "message": {
      "parts": [
        { "text": "find payment agents" },
        { 
          "data": {
            "payment_model": "paid",
            "payment_protocol": "x402",
            "payment_rail": "nano:xno",
            "payment_direction": "inbound"
          }
        }
      ]
    }
  },
  "id": 1
}

💡 Note: All endpoints (REST, JSON-RPC, legacy) converge on the same search logic, ensuring consistent payment filter behavior across all access paths. See Payment Discovery Guide for how to add payment capabilities to your agent.

Authenticated Endpoints

Method	Path	Description
`POST`	`/api/agents/publish`	Create new agent
`PUT`	`/api/agents/:id`	Update agent
`POST`	`/api/agents/:id/go-live`	Publish (STAGE → ACTIVE)
`POST`	`/api/agents/:id/unpublish`	Unpublish (ACTIVE → STAGE)
`DELETE`	`/api/agents/:id`	Delete agent

Playground Endpoints

Method	Path	Description
`POST`	`/api/playground/session`	Create session
`POST`	`/api/playground/session/:id/discover`	Discover agents
`POST`	`/api/playground/session/:id/execute`	Execute capability

Playground