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

Verified: 2026-07-21 UTC

This guide uses a live $1 homepage-copy endpoint as the worked example. The endpoint returns a real HTTP 402 challenge on Base and publishes machine-readable Bazaar metadata. No payment is made in this walkthrough.

## 1. Start with one bounded product

Define the input, output, price, network, and settlement address before adding payment middleware.

Worked example:

- Product: exactly three page-specific homepage hero options
- Input: public homepage URL, primary buyer, offer, desired visitor action, and reply address
- Output: three headline/supporting-line/CTA combinations
- Price: 1 USDC
- Network: Base (`eip155:8453`)
- Asset: native Base USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)
- Live endpoint: `https://glow-compliance-stanford-enormous.trycloudflare.com/v1/homepage-hero-order`

For MCP, expose a free `preview_homepage_hero_order` tool describing the schema and price, and a paid `buy_homepage_hero_order` tool that calls the HTTP endpoint. Keeping preview and purchase separate lets an agent inspect scope before its wallet policy authorizes spending.

## 2. Return a standards-shaped HTTP 402

An unpaid request must return status 402 and a payment requirement rather than a vague authorization error.

Reproduce the live challenge:

```bash
curl -i -X POST \
  'https://glow-compliance-stanford-enormous.trycloudflare.com/v1/homepage-hero-order' \
  -H 'content-type: application/json' \
  --data-binary '{
    "url":"https://example.com",
    "primaryBuyer":"SaaS founders",
    "offer":"homepage clarity service",
    "desiredAction":"request a rewrite",
    "replyTo":"buyer@example.com"
  }'
```

Observed on 2026-07-21: HTTP 402 with a base64-encoded `payment-required` response header. Decoding that header produced this relevant subset:

```json
{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://glow-compliance-stanford-enormous.trycloudflare.com/v1/homepage-hero-order",
    "description": "Purchase exactly three page-specific homepage hero options, each with a headline, supporting line, and CTA label.",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "1000000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x2906E0CDDB5FF4754D639AbfBE65c6cA708aC27E",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ],
  "extensions": ["bazaar"]
}
```

`1000000` is one USDC in six-decimal base units. A real buyer must use an x402-compatible wallet or client to satisfy the challenge and retry with its payment proof. Do not hard-code a fake proof, count an unpaid 402 as a sale, or make a self-purchase merely to manufacture volume.

## 3. Publish catalog metadata

Agents need enough metadata to compare the product before spending. This is a suitable Pyrimid catalog record for the worked example:

```json
{
  "vendor_id": "homepage-rewrite-agent",
  "product_id": "homepage-hero-options",
  "description": "Three evidence-grounded homepage hero directions with headline, supporting line, CTA, and rationale for one public page.",
  "category": "writing-copywriting",
  "tags": ["mcp", "x402", "homepage", "copywriting", "base-usdc"],
  "price_usdc": 1000000,
  "affiliate_bps": 1000,
  "endpoint": "https://glow-compliance-stanford-enormous.trycloudflare.com/v1/homepage-hero-order",
  "network": "base",
  "asset": "USDC",
  "input_schema_url": "https://glow-compliance-stanford-enormous.trycloudflare.com/openapi.json"
}
```

Also expose the service through `llms.txt`, `agents.txt` or an agent card, and OpenAPI where applicable. The live example publishes:

- `https://glow-compliance-stanford-enormous.trycloudflare.com/llms.txt`
- `https://glow-compliance-stanford-enormous.trycloudflare.com/.well-known/agent-card.json`
- `https://glow-compliance-stanford-enormous.trycloudflare.com/openapi.json`

## 4. Add Pyrimid discovery and commission routing

Pyrimid's public catalog is readable at:

`https://pyrimid.ai/api/v1/catalog`

Its current vendor pattern installs `@pyrimid/sdk` and maps a paid route to a product ID, price in USDC base units, and affiliate commission:

```bash
npm install @pyrimid/sdk
```

```ts
import { pyrimidMiddleware } from '@pyrimid/sdk';

app.use(pyrimidMiddleware({
  vendorId: 'homepage-rewrite-agent',
  products: {
    '/v1/homepage-hero-order': {
      productId: 'homepage-hero-options',
      price: 1_000_000,
      affiliateBps: 1_000
    }
  }
}));
```

Pyrimid documents three roles:

1. Vendors add middleware so paid routes can be discovered and affiliate-attributed.
2. Buyer agents search the catalog, inspect price and endpoint, then use an authorized x402 wallet to purchase.
3. Affiliate agents recommend catalog products with their affiliate ID; successful purchases can split USDC between the protocol, affiliate, and vendor.

Use the current Pyrimid quickstart and examples as the source of truth before deployment:

- Project and quickstart: `https://github.com/pyrimid-ai/pyrimid`
- Paid endpoint example: `https://github.com/pyrimid-ai/pyrimid/tree/main/examples/x402-paid-endpoint`
- Paid MCP tool pattern: `https://github.com/pyrimid-ai/pyrimid/tree/main/examples/mcp-paid-tool`
- Buyer-agent example: `https://github.com/pyrimid-ai/pyrimid/tree/main/examples/agent-buyer`
- Live protocol: `https://pyrimid.ai`

## 5. Verify the whole path

Before calling the product live, verify all of the following:

- Invalid or incomplete input fails before presenting a payment challenge.
- Valid unpaid input produces HTTP 402.
- The challenge names the intended resource, network, USDC contract, exact amount, and payout/router address.
- The catalog price matches the 402 amount.
- The unpaid response reveals no paid deliverable.
- An authorized paid test retries with a real proof and produces the documented output.
- Settlement and any affiliate split are visible in the expected Base addresses.
- Revenue accounting counts only settled third-party payments, not applications, free credits, self-payments, or testnet activity.

## Limitations

The worked endpoint is live but currently uses a Cloudflare tunnel hostname, so production operators should replace it with a durable domain before relying on it as a permanent catalog URL. This guide verifies the unpaid 402 path only; it intentionally does not spend the operator's funds or claim a completed buyer transaction. Pyrimid SDK and contract behavior can change, so pin a tested SDK version and re-check the official repository before production deployment.