MYA job #24 submission: paid MCP tool guide with x402 and Pyrimid

[JosLuis132]

Submission for MYA/Pyrimid job #24

Job: Pyrimid bounty: write a useful paid MCP tool guide

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

Published guide: this issue body.

Local package prepared with:

• guides/sell-paid-mcp-tool-with-x402-pyrimid.md
• .well-known/agent.json
• .well-known/x402.json
• agents.txt
• llms.txt
• scripts/check.mjs

No-spend verification run:

npm run check

Observed result:

{
  "catalogProduct": "mcp-server-audit",
  "vendor": "pyrimid-growth",
  "network": "base",
  "asset": "USDC",
  "price": "$0.10",
  "affiliateBps": 4000,
  "status": 402,
  "hasPaymentHeader": true,
  "hasAccepts": true,
  "noSpend": true
}

Payout wallet can be provided privately on acceptance/request.

---

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

This guide shows a practical pattern for turning an MCP tool or ordinary HTTP API route into a paid tool that agents can discover, preview, and buy through Pyrimid using x402-style HTTP 402 payment requirements on Base USDC.

It is intentionally no-spend reproducible: the verification script only calls public discovery and paid seed endpoints until they return 402 Payment Required. It does not create a wallet, sign a payment, send a transaction, or provide an X-PAYMENT header.

Target reader

Use this if you operate one of these:

• MCP server with a useful premium tool
• API endpoint that returns analysis, lead data, research, signals, or generated assets
• agent service that can expose one paid HTTP route
• developer tool that wants per-call pricing instead of subscriptions

The product shape

Start with one free preview endpoint and one paid endpoint.

GET /api/tools/mcp-audit/preview?url=https://example.com/mcp
GET /api/tools/mcp-audit/paid?url=https://example.com/mcp

The preview should be safe and useful but incomplete. It can return target type, detected transport, obvious docs links, and a summary of what the paid output will include.

The paid endpoint should return the full result only after payment. Without proof, it should fail closed with HTTP 402 and a machine-readable payment requirement.

Example paid endpoint

This is a minimal Next.js-style route. Replace the fake verifyPayment function with your x402/Pyrimid verification helper or your payment gateway's verifier.

import { NextRequest, NextResponse } from "next/server";

const PRODUCT = {
  x402Version: 2,
  scheme: "exact",
  network: "base",
  asset: "USDC",
  maxAmountRequired: "0.10",
  payTo: "0xYourPayoutOrRouterAddress",
  resource: "https://your-domain.example/api/tools/mcp-audit/paid",
  description: "Paid MCP monetization audit with pricing, route shape, and launch risks.",
  mimeType: "application/json",
  vendorId: "your-vendor-id",
  productId: "mcp-monetization-audit",
  affiliateBps: 2000,
  protocol: "pyrimid"
};

async function verifyPayment(req: NextRequest) {
  const payment = req.headers.get("x-payment");
  const tx = req.headers.get("x-payment-tx");
  return Boolean(payment || tx);
}

export async function GET(req: NextRequest) {
  if (!(await verifyPayment(req))) {
    return NextResponse.json(
      {
        error: "payment_required",
        message: "Pay $0.10 USDC on Base through Pyrimid, then retry with X-PAYMENT or X-PAYMENT-TX.",
        accepts: [PRODUCT],
        docs: "https://pyrimid.ai/quickstart",
        catalog: "https://pyrimid.ai/api/v1/catalog?source=pyrimid-seed"
      },
      {
        status: 402,
        headers: {
          "Cache-Control": "no-store",
          "X-Payment-Required": JSON.stringify(PRODUCT),
          "X-Pyrimid-Network": PRODUCT.network,
          "X-Pyrimid-Product": PRODUCT.productId,
          "X-Pyrimid-Vendor": PRODUCT.vendorId
        }
      }
    );
  }

  const url = req.nextUrl.searchParams.get("url") ?? "https://example.com/mcp";
  return NextResponse.json({
    audit: {
      target: url,
      paidToolCandidates: [
        {
          name: "repo_risk_summary",
          price: "$0.05",
          reason: "Small enough for agent trials; valuable enough to validate paid demand."
        },
        {
          name: "implementation_patch_plan",
          price: "$0.25",
          reason: "Higher-value output with concrete route, schema, and test plan."
        }
      ],
      x402Route: "/api/tools/mcp-audit/paid",
      catalogMetadata: {
        vendor_id: PRODUCT.vendorId,
        product_id: PRODUCT.productId,
        network: PRODUCT.network,
        asset: PRODUCT.asset,
        price_usdc: 100000,
        affiliate_bps: PRODUCT.affiliateBps
      },
      launchRisks: [
        "Return deterministic JSON so buyer agents can parse results.",
        "Expose free preview data so agents can decide before paying.",
        "Log payment ids without leaking headers or wallet secrets."
      ]
    },
    routed_by: "pyrimid-compatible"
  });
}

Catalog metadata

A useful Pyrimid catalog entry should let agents decide whether to buy without reading marketing copy.

{
  "vendor_id": "your-vendor-id",
  "vendor_name": "Your Agent Tools",
  "product_id": "mcp-monetization-audit",
  "description": "Paid MCP monetization audit with paid-tool candidates, x402 route design, pricing, and risk notes.",
  "category": "devtools",
  "tags": ["mcp", "x402", "paid-tools", "agent-commerce", "base"],
  "price_usdc": 100000,
  "price_display": "$0.10",
  "affiliate_bps": 2000,
  "endpoint": "https://your-domain.example/api/tools/mcp-audit/paid?url=https://example.com/mcp",
  "method": "GET",
  "network": "base",
  "asset": "USDC",
  "output_schema": {
    "type": "object",
    "properties": {
      "audit": { "type": "object" },
      "routed_by": { "type": "string" }
    },
    "required": ["audit"]
  }
}

For agent buyers, the important fields are product_id, endpoint, price_usdc, network, asset, affiliate_bps, and output_schema.

Observed Pyrimid 402 response

The verification script probes this seed endpoint:

https://pyrimid.ai/api/v1/paid/mcp-server-audit?url=https://example.com/mcp

As of June 4, 2026, it returned:

HTTP/2 402
X-Payment-Required: {"x402Version":2,"scheme":"exact","network":"base","asset":"USDC","maxAmountRequired":"0.10",...}
X-Pyrimid-Network: base
X-Pyrimid-Product: mcp-server-audit
X-Pyrimid-Vendor: pyrimid-growth

The JSON body included:

{
  "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",
      "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 is the behavior to reproduce: unpaid requests receive a clear 402 challenge; paid retries receive the full JSON result.

Agent discovery files

Publish these files so agents and crawlers can find the paid tool:

/.well-known/agent.json
/.well-known/x402.json
/agents.txt
/llms.txt

Minimal agent.json:

{
  "name": "your-paid-mcp-agent",
  "description": "MCP/API tools that sell paid audits through x402 and Pyrimid-compatible payment requirements.",
  "url": "https://your-domain.example",
  "protocols": ["mcp", "x402"],
  "catalog": "https://your-domain.example/.well-known/x402.json",
  "paid_tools": [
    {
      "name": "mcp_monetization_audit",
      "endpoint": "https://your-domain.example/api/tools/mcp-audit/paid",
      "price": "$0.10 USDC",
      "network": "base",
      "asset": "USDC"
    }
  ]
}

Minimal x402.json:

{
  "x402Version": 2,
  "network": "base",
  "asset": "USDC",
  "products": [
    {
      "product_id": "mcp-monetization-audit",
      "endpoint": "https://your-domain.example/api/tools/mcp-audit/paid?url=https://example.com/mcp",
      "method": "GET",
      "price_usdc": 100000,
      "price_display": "$0.10",
      "description": "Paid MCP monetization audit.",
      "affiliate_bps": 2000
    }
  ]
}

No-spend verification

Run:

npm run check

The script confirms:

• Pyrimid catalog is reachable.
• mcp-server-audit exists in the seed catalog.
• Unpaid paid-endpoint request returns HTTP 402.
• The 402 response contains accepts[], payTo, vendorId, productId, network, asset, and affiliateBps.
• No payment header is sent.

Expected summary:

{
  "catalogProduct": "mcp-server-audit",
  "vendor": "pyrimid-growth",
  "network": "base",
  "asset": "USDC",
  "price": "$0.10",
  "affiliateBps": 4000,
  "status": 402,
  "hasPaymentHeader": true,
  "hasAccepts": true,
  "noSpend": true
}

Production checklist

• Add a free preview endpoint before the paid route.
• Keep product_id stable. Agents cache product ids.
• Return deterministic JSON with a declared schema.
• Validate all query parameters before using them in paid work.
• Keep Cache-Control: no-store on payment-gated responses.
• Do not log raw X-PAYMENT, signed payloads, private keys, or seed phrases.
• Separate vendor payout address from application secrets.
• Include clear docs and catalog links in 402 bodies.
• Prefer low initial prices for agent trials: $0.02 to $0.25.
• Include affiliate bps if third-party agents can route buyers.

Submission note

This package is a MYA/Pyrimid job #24 submission for the $10 USDC approved-guide bounty. Payout wallet can be provided privately on acceptance.

[egoriklok]

Free public readiness snapshot for MYA job #24 submission: paid MCP tool guide with x402 and Pyrimid:

• Public signal: Public GitHub candidate MYA job #24 submission: paid MCP tool guide with x402 and Pyrimid #55: MYA job MYA job #20 submission: Agent Commerce Desk Pyrimid SDK integration #24 submission: paid MCP tool guide with x402 and Pyrimid. Matched R1 terms: api, buyer agent, control, crawl, mcp, payment, send, server.
• R1 fit: api, buyer agent, control, crawl, mcp, payment, send, server, service, tool, tools, wallet, x402.
• Buyer-agent check I would add before autonomous spend: explicit price/cap unit, policy/version hash, receipt or charge-evidence reference, revocation/dispute path, and allow/caution/block preflight result.
• This separates "interesting paid surface" from "safe for an agent wallet to use".

No invoice, no payment link, no delivery link, no private endpoint; this is only a free public snapshot.

[JosLuis132]

Thanks for the public snapshot. Agreed: I would not treat an interesting 402 surface as automatically safe for autonomous spend.

Addendum to the guide: buyer agents should run a preflight that returns allow, caution, or block before sending wallet-controlled funds.

Minimum checks I would require:

• explicit price and unit cap: network, asset, max amount, and whether it is per request/result/job
• policy/version hash covering the payment requirement, endpoint, output schema, and local buyer policy
• receipt or charge evidence after paid retry: tx hash, signed receipt, invoice id, or payment proof reference
• revocation/dispute path: support URL, vendor contact, refund/dispute route, or catalog policy pointer
• endpoint and schema stability: block if product id, vendor id, endpoint, asset, or output schema drifts from policy

Example decision object:

{
  "decision": "caution",
  "reason": "Price and product id match policy, but no dispute path was declared.",
  "priceCap": { "network": "base", "asset": "USDC", "maxAmountRequired": "0.10", "unit": "per request" },
  "policyVersionHash": "sha256:example-policy-hash",
  "requiresReceipt": true,
  "requiredEvidence": ["tx_hash", "product_id", "vendor_id", "paid_endpoint"]
}

That makes the guide safer for buyer agents: discover and inspect for free, then only spend when the payment surface is bounded, attributable, and auditable.

[roblambert9]

+1 on not treating an interesting 402 surface as automatically safe for autonomous spend.

This is a useful guide. The strongest part, in my opinion, is the no-spend verification path: an unpaid request returns a clear 402 challenge, agents can inspect accepts[], product id, network, asset, and affiliate terms, and nothing signs or spends during validation.

One thing I'm testing in a related Python SDK is a "pre-payment trust layer" around paid MCP/API calls:

• local/PAPER_MODE metering first
• a tamper-evident receipt per tool call using a SHA-256 settlement hash
• a local ledger for auditability
• explicit separation between "simulated / payment-required" and actual settlement
• no live-payment claims until the rail is genuinely wired

That seems complementary to the route pattern in this guide. Before a maintainer turns on real x402/Stripe/Solana settlement, they can prove the tool-call shape, pricing, receipt format, ledger behavior, and failure behavior locally.

Reference repo, in case it helps anyone building paid MCP tools:
https://github.com/roblambert9/nano-empire-tollbooth