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)

CapabilityDescription
extract_content(url)Returns cleaned Markdown from any URL

Wikipedia

registry.utility.wiki

Provide grounded truth from Wikipedia

CapabilityDescription
search_page(query)Search Wikipedia pages
get_summary(page_id)Get article summary

Finance

registry.utility.finance

Real-time financial data

CapabilityDescription
get_current_price(symbol)Get crypto/stock price

REST API Endpoints

Public Endpoints

MethodPathDescription
GET/.well-known/agent-card.jsonRegistry's own Agent Card
GET/public/agentsList agents (supports category, target, tags and payment filters). Search with ?q= needs an API token.
GET/public/agents/:idGet agent by ID or package name
GET/public/agents/resolve/:packageNameA2A protocol discovery (returns agent card)
POST/public/agents/searchSemantic search (supports payment filters). API token required.

Search Access and API Tokens

Listing agents and looking one up are open to everyone. Searching (any request with a query) needs a free API token from Console → API Tokens. Send it as Authorization: Bearer zv_... or X-API-Key: zv_.... Search on this website works without a token.

RequestWithout a tokenWith a token
GET /public/agents (no q)ListingListing
GET /public/agents/:id, /public/agents/resolve/:packageNameLookupLookup
GET /public/agents?q=..., POST /public/agents/search, /a2a/*401 with an error descriptionSemantic search, counted against the daily quota

A missing, invalid, revoked or expired token returns 401 with a JSON body such as {"success": false, "code": "token_required", "error": "...", "docs": "..."}. Codes: token_required, invalid_token, token_revoked, token_expired. A token sent with a listing request is validated too, so an invalid one fails instead of being ignored.

Daily Search Quota

Each account can run 720 searches per UTC day (about one every two minutes), shared by all of its tokens and all search endpoints. Tokens created in an organization share the organization's quota. Listing and lookups never count. The quota resets at 00:00 UTC.

Every metered response carries:

  • X-RateLimit-Limit: searches allowed per day
  • X-RateLimit-Remaining: searches left today
  • X-RateLimit-Reset: when the quota resets (Unix seconds, next UTC midnight)

Over the quota, search endpoints return 429 with a Retry-After header and {"success": false, "code": "quota_exceeded", "error": "...", "limit": 720, "used": 720, "resetAt": "...", "docs": "..."}. The A2A JSON-RPC endpoint (/a2a/v1) returns HTTP 429 with JSON-RPC error code -32029 and the same details in error.data. Agents rarely change, so caching results on your side for a few hours keeps you well inside the quota.

Payment Filters

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

ParameterDescriptionExamples
payment_modelPayment model (comma-separated OR)free, paid, freemium, free,freemium
payment_protocolPayment negotiation protocolx402, stripe, lightning-invoice
payment_railSettlement network and asset (flexible syntax)nano:xno, base:usdc, usdc
payment_directionPayment flow directioninbound, outbound, both

Payment Rail Syntax

The payment_rail parameter supports multiple flexible formats:

FormatExampleBehavior
network:assetbase:usdcExact network, prefix-match asset (e.g., usdc, usdc.e, usdt)
network:nano:Network only (all assets on that network)
bare termusdcPrefix-matches network OR asset (union)
multi-termusdc, nanoEach term evaluated independently, results OR-ed
mixedbase:usdc nanoBase 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

MethodPathDescription
POST/api/agents/publishCreate new agent
PUT/api/agents/:idUpdate agent
POST/api/agents/:id/go-livePublish (STAGE → ACTIVE)
POST/api/agents/:id/unpublishUnpublish (ACTIVE → STAGE)
DELETE/api/agents/:idDelete agent

Playground Endpoints

MethodPathDescription
POST/api/playground/sessionCreate session
POST/api/playground/session/:id/discoverDiscover agents
POST/api/playground/session/:id/executeExecute capability