Discovery

Let agents find your services

The discovery directory is a public, searchable index of x402-payable services: paid APIs, bookings, and reusable payment links. Agents query it first (“book me a flight”), pick a match, and pay its resourceUrl — no marketplace account, no scraping.

List a service

Create listings from the dashboard's Discovery section: either promote an existing reusable payment link (kind: link) or register an external x402 endpoint URL you gate yourself (kind: api, see gating your own API). Give it a title, description, price, and category; unlist it any time.

Search the directory

GET /api/v1/discovery is free and needs no authentication (rate-limited per IP). Parameters: q (substring match over title, description, and category), category, and limit (default 20, max 50).

Terminal

curl "$PEERPAY_BASE_URL/api/v1/discovery?q=flight&limit=5"

200 OK

{
  "listings": [
    {
      "title": "Vector Air flight booking",
      "description": "Book Vienna -> Lisbon, fare settled in USDC",
      "priceUsdc": "89.00",
      "kind": "api",
      "resourceUrl": "https://your-peerpay-host/api/demo/flights",
      "category": "flights"
    }
  ]
}

priceUsdc is a decimal string. kind is api or link; both are payable the same way — request resourceUrl, get a 402, pay it.

Discover from agents

The agent SDK and the MCP server both expose discovery. agent.discover(query) returns typed listings; the peerpay_discover MCP tool tells the model to search first, then pay the best match with peerpay_pay.

agent.ts

import { PeerPayAgent } from "@genesis-tech/peerpay-agent";

const agent = new PeerPayAgent({
  apiKey: process.env.PEERPAY_AGENT_KEY!,
  baseUrl: process.env.PEERPAY_BASE_URL!,
});

const services = await agent.discover("flight", { limit: 5 });
const best = services[0];

if (best) {
  // Pay the discovered service directly:
  const result = await agent.pay(best.resourceUrl, { maxAmountUsdc: "100.00" });
}