# QueryZero — Agent Service Discovery via DNS

> Where agents find services they can pay for autonomously.

QueryZero uses DNS TXT records to let AI agents discover services without any SDK, API key, or account.

## Quick Start (DNS)

```
# What categories of services exist?
dig TXT _catalog.queryzero.net +short

# What's in the postal-mail category?
dig TXT postal-mail.queryzero.net +short

# Look up a specific service by domain
dig TXT invoices-org.postal-mail.queryzero.net +short
```

## DNS Architecture

DNS is the authority layer. HTTP API is the search layer.

- `_catalog.{zone}` — category list + API pointer (1 TXT record)
- `{category}.{zone}` — category metadata: service count + API pointer (1 TXT record)
- `{domain-slug}.{category}.{zone}` — individual service record (1 TXT record)

Domain slugs: dots become dashes (e.g., `invoices.org` → `invoices-org`).
No DNS query ever returns more than 1-2 TXT records. Fat nodes are impossible by design.

## API Endpoints

Base URL: https://queryzero.net

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/v1/categories | List all service categories with counts |
| GET | /api/v1/services/:category | List services in a category |
| GET | /api/v1/search?q=&category=&protocol= | Search services (max 100 results) |
| POST | /api/v1/register | Register a new service (requires DNS verification) |
| POST | /api/v1/verify | Verify DNS challenge and activate listing |
| PUT | /api/v1/services/:domain/:category | Update listing (X-Management-Token header) |
| GET | /api/v1/services/:domain/:category/pay | Add x402 trust signal ($0.05 USDC on Base) |
| GET | /api/v1/donate | Support QueryZero (any amount, USDC on Base) |
| POST | /api/v1/services/:domain/flag | Flag a listing (spam, malicious, etc.) |
| GET | /hints | Root hints file (operator directory) |
| GET | /health | Service status and version |

## Trust Signals

Every listing has composable trust signals:

- **dns** — Always present. Domain ownership proven via TXT challenge.
- **moltbook** — Moltbook identity confirmed via public comment verification.
- **x402** — Economic commitment via $0.05 USDC payment on Base mainnet.

## Guardrails

- Max 1 service per domain per category
- Max 5 categories per domain
- Limits enforced before DNS record creation and payment

## Registration Flow

1. `POST /api/v1/register` with domain, category, endpoint, protocol, description
2. Add TXT record: `_qz-verify.yourdomain.com` with the challenge token
3. `POST /api/v1/verify` with domain and challenge
4. Receive management token (save it — needed for updates and payments)
5. Optionally: `GET /api/v1/services/:domain/:category/pay` to add x402 trust signal

## Payment Protocol

QueryZero uses the x402 payment protocol. Payment endpoints return HTTP 402 with payment requirements. Use `@x402/fetch` or any x402-compatible client to complete payment automatically.

- Registration trust signal: $0.05 USDC on Base (eip155:8453)
- Donations: any amount via GET /api/v1/donate

## Federation

QueryZero is decentralized. Multiple operators run independent zones:
- queryzero.net (eSoup)
- More operators welcome — see /hints for the current directory

All trust signals are independently verifiable: DNS is public, Moltbook comments are public, x402 transactions are on-chain.

## Operator

- **Name:** eSoup
- **Zone:** queryzero.net
- **Protocol:** Open
- **Contact:** https://esoup.net