# Pyrimid x402 paid-tool guide

This is a reproducible, no-spend guide for an MCP/tool author who wants to expose a paid HTTP endpoint through Pyrimid. It demonstrates discovery and the HTTP 402 boundary without signing a transaction or using a private key.

## What this proves

- Network: Base
- Asset: USDC
- Router: `0xc949AEa380D7b7984806143ddbfE519B03ABd68B`
- Registry: `0x34e22fc20D457095e2814CdFfad1e42980EEC389`
- Catalog: `0xC935d6B73034dDDb97AD2a1BbD2106F34A977908`
- USDC on Base: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`

The public catalog was reachable at `https://pyrimid.ai/api/v1/catalog?source=pyrimid-seed` and returned 50 records (186 total across sources) at `2026-08-09T01:58:01.666Z`. The seven seed products include AgentZone trust search ($0.05, 25% affiliate), a Pragma signal snapshot ($0.25, 50%), MYA enrichment ($0.10, 30%), MYA category scout ($0.05, 30%), vendor lead discovery ($0.25, 40%), MCP server audit ($0.10, 40%), and an x402 integration plan ($0.10, 40%).

## 1. Inspect the catalog (free)

```bash
curl -sS 'https://pyrimid.ai/api/v1/catalog?source=pyrimid-seed'
```

Use the `product_id`, `endpoint`, `price_display`, `network`, and `asset` fields when choosing a route. Do not infer a price from a marketing page; read the current catalog record.

## 2. Observe the payment boundary (free)

```bash
curl -i -sS 'https://pyrimid.ai/api/v1/paid/agentzone-search?q=agent-commerce'
```

The route intentionally returns `402 Payment Required` until the buyer supplies an x402 proof. The captured challenge for this route was:

```json
{
  "x402Version": 2,
  "scheme": "exact",
  "network": "base",
  "asset": "USDC",
  "maxAmountRequired": "0.05",
  "payTo": "0xc949AEa380D7b7984806143ddbfE519B03ABd68B",
  "resource": "https://pyrimid.ai/api/v1/paid/agentzone-search?q=agent-commerce",
  "description": "AgentZone trusted agent search routed through Pyrimid",
  "mimeType": "application/json",
  "vendorId": "agentzone",
  "productId": "agentzone-trust-search",
  "affiliateBps": 2500,
  "protocol": "pyrimid"
}
```

The second seed route, `https://pyrimid.ai/api/v1/paid/signals`, returned the same 402 boundary with a current maximum of `$0.25`. A 402 is a reachable, payment-gated endpoint; it is not a completed purchase or revenue.

## 3. Make the tool MCP-friendly

Keep the tool contract deterministic and document the paid boundary in the tool description. A minimal catalog entry should include:

```json
{
  "name": "agentzone_trust_search",
  "method": "GET",
  "endpoint": "https://pyrimid.ai/api/v1/paid/agentzone-search?q={query}",
  "input": {"query": "string"},
  "output": "application/json",
  "network": "base",
  "asset": "USDC",
  "payment": "x402 exact; inspect the 402 challenge before any payment"
}
```

The MCP wrapper should pass through the structured JSON response and the HTTP status. It must never collect a private key, silently retry a paid request, or hide the requested amount from the buyer.

## 4. Buyer-side safety checklist

1. Fetch the catalog record and confirm the route, network, asset, and amount.
2. Make one unpaid request and inspect `X-Payment-Required`.
3. Show the exact amount to the wallet owner.
4. Only after an explicit, current authorization, use the wallet's supported x402 flow.
5. Save the returned receipt and verify the response before treating the call as delivered.

This guide intentionally stops after step 2. No USDC was spent to produce it.

## Official references

- [Pyrimid quickstart](https://pyrimid.ai/quickstart)
- [Pyrimid catalog](https://pyrimid.ai/api/v1/catalog?source=pyrimid-seed)
- [Pyrimid paid-tool example](https://github.com/pyrimid-ai/pyrimid/tree/main/examples/mcp-paid-tool)
- [MYA job 24](https://monetizeyouragent.fun/)