# Sell a paid MCP tool or API call with x402 and Pyrimid

This guide shows a minimal, reproducible path for turning one useful MCP tool or API route into a paid endpoint that buyer agents can discover through Pyrimid and pay for with x402 on Base USDC.

The example uses Pyrimid's public seed product `mcp-server-audit`, because it already exposes the payment shape that a real paid MCP/API vendor needs to copy:

- product id: `mcp-server-audit`
- vendor id: `pyrimid-growth`
- network: `base`
- asset: `USDC`
- price: `$0.10`
- affiliate split: `4000` bps
- paid endpoint: `https://pyrimid.ai/api/v1/paid/mcp-server-audit?url=https://example.com/mcp`

The verification steps below are no-spend checks. They intentionally stop at the `402 Payment Required` response, so reviewers can reproduce the payment metadata without connecting a wallet or signing a transaction.

## 1. Pick one tool to sell

Start with a narrow tool where the buyer can tell quickly whether the output is useful. Good first candidates:

- MCP server audit for monetization readiness.
- API integration plan for an agent vendor.
- Lead discovery for vendors likely to sell paid tools.
- Code or docs review with structured JSON output.

Avoid making the first paid product broad. A focused tool is easier to price, easier to cache, and easier for buyer agents to retry after payment.

## 2. Define the paid route

A paid MCP/API product should have a stable route shape before payment is added.

Example route:

```text
GET /api/v1/paid/mcp-server-audit?url=https://example.com/mcp
```

Expected successful response after payment:

```json
{
  "audit": {
    "target": "https://example.com/mcp",
    "paid_tool_candidates": [
      {
        "name": "deep_code_review",
        "price_usdc": "0.25",
        "reason": "High-value review output with clear buyer intent"
      }
    ],
    "x402_route_shape": {
      "method": "GET",
      "path": "/api/v1/paid/mcp-server-audit",
      "query": ["url"]
    },
    "risk_notes": [
      "Do not expose private repository data without explicit owner authorization.",
      "Keep unpaid preview output short enough to prevent free full-result extraction."
    ]
  },
  "routed_by": "pyrimid"
}
```

## 3. Publish catalog metadata

Pyrimid catalog entries need enough metadata for buyer agents to decide whether a product is worth paying for before they spend.

Minimal catalog metadata:

```json
{
  "vendor_id": "pyrimid-growth",
  "vendor_name": "Pyrimid Growth",
  "product_id": "mcp-server-audit",
  "description": "Paid MCP monetization audit: tells an MCP server how to add paid tools, x402 pricing, and affiliate routing.",
  "category": "devtools",
  "tags": ["mcp", "audit", "monetization", "paid-tools", "x402", "developer-tools"],
  "price_usdc": 100000,
  "price_display": "$0.10",
  "affiliate_bps": 4000,
  "endpoint": "https://pyrimid.ai/api/v1/paid/mcp-server-audit?url=https://example.com/mcp",
  "method": "GET",
  "network": "base",
  "asset": "USDC"
}
```

Use atomic USDC units in machine-readable fields and a display field for humans. Keep `product_id` stable; buyer agents and affiliate tracking depend on it.

## 4. Return an x402-compatible 402 response before payment

Before a buyer agent pays, the endpoint should return `402 Payment Required` with payment details in both headers and JSON.

No-spend test:

```bash
curl -i "https://pyrimid.ai/api/v1/paid/mcp-server-audit?url=https://example.com/mcp"
```

Observed headers:

```http
HTTP/1.1 402 Payment Required
X-Payment-Required: {"x402Version":2,"scheme":"exact","network":"base","asset":"USDC","maxAmountRequired":"0.10","payTo":"0xc949AEa380D7b7984806143ddbfE519B03ABd68B","resource":"https://pyrimid.ai/api/v1/paid/mcp-server-audit?url=https%3A%2F%2Fexample.com%2Fmcp","description":"Paid MCP monetization audit: tells an MCP server how to add paid tools, x402 pricing, and affiliate routing.","mimeType":"application/json","vendorId":"pyrimid-growth","productId":"mcp-server-audit","affiliateBps":4000,"protocol":"pyrimid"}
X-Pyrimid-Network: base
X-Pyrimid-Product: mcp-server-audit
X-Pyrimid-Vendor: pyrimid-growth
```

Observed body:

```json
{
  "error": "payment_required",
  "message": "Pay $0.10 USDC on Base through Pyrimid, then retry with X-PAYMENT or X-PAYMENT-TX.",
  "accepts": [
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "base",
      "asset": "USDC",
      "maxAmountRequired": "0.10",
      "payTo": "0xc949AEa380D7b7984806143ddbfE519B03ABd68B",
      "resource": "https://pyrimid.ai/api/v1/paid/mcp-server-audit?url=https%3A%2F%2Fexample.com%2Fmcp",
      "description": "Paid MCP monetization audit: tells an MCP server how to add paid tools, x402 pricing, and affiliate routing.",
      "mimeType": "application/json",
      "vendorId": "pyrimid-growth",
      "productId": "mcp-server-audit",
      "affiliateBps": 4000,
      "protocol": "pyrimid"
    }
  ],
  "docs": "https://pyrimid.ai/quickstart",
  "catalog": "https://pyrimid.ai/api/v1/catalog?source=pyrimid-seed"
}
```

That response gives buyer agents enough information to:

- identify the exact product,
- confirm the network and asset,
- check the maximum amount,
- route affiliate metadata,
- pay externally,
- retry with `X-PAYMENT` or `X-PAYMENT-TX`.

## 5. Add agent-readable discovery files

Publish simple discovery metadata so crawlers and agents can understand the product without scraping a marketing page.

Example `.well-known/agent.json`:

```json
{
  "name": "Paid MCP Tool Guide",
  "description": "A no-spend guide for selling an MCP/API route with x402 and Pyrimid.",
  "capabilities": ["mcp-monetization-guide", "x402-readiness", "pyrimid-catalog-review"],
  "contact": "https://github.com/nieniedeveloper"
}
```

Example `.well-known/x402.json`:

```json
{
  "network": "base",
  "asset": "USDC",
  "products": [
    {
      "product_id": "mcp-server-audit",
      "endpoint": "https://pyrimid.ai/api/v1/paid/mcp-server-audit?url=https://example.com/mcp",
      "method": "GET",
      "price_display": "$0.10"
    }
  ]
}
```

## 6. Production checklist

- Keep the unpaid response limited to payment metadata and a short preview.
- Include a stable `productId`, `vendorId`, `resource`, `network`, `asset`, and `maxAmountRequired`.
- Validate paid-route input before the payment check so malformed requests fail clearly.
- Rate-limit unpaid probes to prevent catalog scraping from becoming infrastructure abuse.
- Log product id, vendor id, affiliate id, and payment proof, but never log private keys, seed phrases, wallet signatures, or full user secrets.
- Provide a no-spend verification command for reviewers.
- Provide a post-payment retry command separately, only for users who intentionally want to test spending.

## 7. Review command

Run:

```bash
npm run check
```

Expected result:

```json
{
  "catalogProduct": "mcp-server-audit",
  "network": "base",
  "asset": "USDC",
  "price": "$0.10",
  "status": 402,
  "hasPaymentHeader": true,
  "hasAccepts": true,
  "noSpend": true
}
```

This confirms the guide's core facts without spending USDC.