Selling Paid MCP Tools with x402 and Pyrimid: A Reproducible Guide

AI agents are starting to buy capabilities the same way humans buy SaaS: discover a tool, see a price, pay for one result, then continue the workflow. The missing piece is not only the payment rail. It is distribution. A paid MCP tool or HTTP API is hard to sell if buyer agents cannot find it, understand the price, and see who receives the commission.

Pyrimid is one practical pattern for that distribution layer. It aggregates paid agent products, exposes a catalog for discovery, and describes how vendor and affiliate shares are routed when a buyer pays through x402 on Base USDC.

This guide shows a minimal reproducible path for turning a tool into a paid product:

1. expose a normal HTTP endpoint,
2. return a clear HTTP 402 payment requirement before access,
3. publish catalog metadata agents can index,
4. add a Pyrimid product record or middleware path,
5. verify the flow from the buyer-agent side.

The point is not to make a huge marketplace. The point is to make one paid capability legible enough that another agent can safely buy it.

Working endpoint to inspect first

Before building anything, inspect a live Pyrimid seed product. This endpoint intentionally returns HTTP 402 until paid:

curl -i "https://pyrimid.ai/api/v1/paid/x402-integration-plan?service=agent-api"

Expected behavior:

HTTP/2 402
content-type: application/json
x-payment-required: { ... }
x-pyrimid-network: base
x-pyrimid-product: x402-integration-plan
x-pyrimid-vendor: pyrimid-growth

The JSON body describes the payment requirement. In the current live response, the product asks for $0.10 USDC on Base and points back to the catalog:

{
  "error": "payment_required",
  "message": "Pay $0.10 USDC on Base through Pyrimid, then retry with X-PAYMENT or X-PAYMENT-TX.",
  "docs": "https://pyrimid.ai/quickstart",
  "catalog": "https://pyrimid.ai/api/v1/catalog?source=pyrimid-seed"
}

That is the shape a buyer agent can reason about: price, network, asset, pay-to address, product id, vendor id, and retry instructions.

Step 1: design the free preview and paid result

A paid MCP tool should not start with a blind paywall. Give buyer agents a preview method that explains the schema, price, and sample output. Keep the expensive data behind the paid route.

Example MCP tool pair:

preview_vendor_leads(query)  -> free: schema, price, sample rows, product_id
buy_vendor_leads(query)      -> paid: full enriched lead list after x402 proof

If you are not using MCP yet, the same idea works with plain HTTP:

GET  /api/vendor-leads/preview?segment=mcp
POST /api/vendor-leads/buy

The preview route reduces failed purchases because the buyer can decide whether the output fits the task before spending.

Step 2: return an agent-readable 402

Here is a minimal Express-style paid endpoint. It is deliberately small: no database, no framework magic, just the response contract.

app.get('/api/paid/vendor-leads', async (req, res) => {
  const paid = req.header('X-PAYMENT') || req.header('X-PAYMENT-TX');

  if (!paid) {
    return res.status(402).json({
      error: 'payment_required',
      accepts: [{
        x402Version: 2,
        scheme: 'exact',
        network: 'base',
        asset: 'USDC',
        maxAmountRequired: '0.25',
        payTo: '0xYourVendorWallet',
        resource: 'https://your-service.example/api/paid/vendor-leads',
        description: 'Enriched list of high-fit paid MCP/API vendors',
        mimeType: 'application/json',
        vendorId: 'your-agent',
        productId: 'vendor-leads',
        affiliateBps: 3000,
        protocol: 'pyrimid'
      }],
      docs: 'https://pyrimid.ai/quickstart'
    });
  }

  // In production, verify the payment proof before returning data.
  return res.json({
    product_id: 'vendor-leads',
    rows: [
      {
        vendor: 'example-mcp-server',
        fit_score: 91,
        reason: 'Has paid-data surface and MCP clients as buyers',
        suggested_price_usdc: 0.25
      }
    ]
  });
});

Do not skip verification in production. The example shows response shape, not a complete settlement verifier. Your real implementation should verify the signed payment or transaction hash before returning the paid payload.

Step 3: publish catalog metadata

Buyer agents need catalog metadata before they ever hit your endpoint. A compact product record is enough:

{
  "vendor_id": "your-agent",
  "product_id": "vendor-leads",
  "description": "Paid vendor lead discovery for MCP and x402 products",
  "category": "growth-data",
  "tags": ["mcp", "x402", "lead-gen", "agent-commerce"],
  "price_usdc": 250000,
  "affiliate_bps": 3000,
  "endpoint": "https://your-service.example/api/paid/vendor-leads",
  "network": "base",
  "asset": "USDC"
}

Use integer micro-USDC for machine precision when the catalog expects it. For example, 250000 means $0.25 USDC if the convention is six decimals.

Pyrimid's public catalog is readable here:

curl "https://pyrimid.ai/api/v1/catalog?source=pyrimid-seed"

At the time of this guide, that catalog included seed products such as x402-integration-plan, mcp-server-audit, and vendor-lead-discovery, each with endpoint URL, vendor id, product id, network, asset, price, and affiliate basis points.

Step 4: wire distribution into the agent

The smallest useful buyer-agent integration is a resolver function:

async function findPaidTool(query) {
  const url = new URL('https://pyrimid.ai/api/v1/catalog');
  url.searchParams.set('q', query);
  const res = await fetch(url);
  if (!res.ok) throw new Error(`catalog failed: ${res.status}`);
  const data = await res.json();
  return data.products?.[0] || null;
}

const product = await findPaidTool('MCP monetization audit');
console.log(product?.product_id, product?.endpoint, product?.affiliate_bps);

Once product discovery works, the buyer agent can request the endpoint, read the 402 requirement, present or sign payment according to its wallet policy, and retry with X-PAYMENT or X-PAYMENT-TX.

Step 5: make the submission reviewable

A useful paid-tool submission should include evidence, not just code. I would ship these five artifacts:

Artifact	Why it matters
Live endpoint URL	Confirms the tool exists and returns a real 402 before payment.
402 response sample	Lets agents implement without reverse engineering.
Catalog metadata	Makes discovery and affiliate routing explicit.
Buyer-agent snippet	Shows how to search and select the product.
Verification note	Explains how payment proof is checked before paid data is returned.

That package gives reviewers and buyer agents enough context to reproduce the flow.

Common mistakes

• Hiding the price until after a wallet interaction.
• Returning human-only checkout instructions instead of machine-readable JSON.
• Forgetting network, asset, or payTo in the 402 response.
• Using vague product ids that cannot be matched to catalog rows.
• Paying for every discovery query instead of keeping preview/search free.
• Treating X-PAYMENT-TX as valid without confirming it matches the requested resource and amount.

Minimal checklist

A paid MCP/API product is ready when all of these are true:

[ ] Free preview route exists.
[ ] Paid route returns HTTP 402 when no payment proof is present.
[ ] 402 JSON includes network, asset, price, payTo, resource, vendorId, productId.
[ ] Catalog row points to the same endpoint and price.
[ ] Buyer-agent snippet can discover the product from the catalog.
[ ] Paid route verifies payment proof before returning the full payload.

If those boxes are checked, the product is no longer just an API. It is an agent-readable product with a distribution path.

Links used

• Pyrimid homepage and SDK overview: https://pyrimid.ai/
• Pyrimid quickstart: https://pyrimid.ai/quickstart
• Pyrimid seed catalog: https://pyrimid.ai/api/v1/catalog?source=pyrimid-seed
• Live 402 endpoint used in this guide: https://pyrimid.ai/api/v1/paid/x402-integration-plan?service=agent-api