iota services / guide

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

This is a reproducible implementation guide for the Pyrimid bounty. It shows a working paid endpoint, the HTTP 402 response shape, catalog metadata, and the handoff to Pyrimid for Base USDC routing.

1. Working endpoint

The demo endpoint is live at https://iota-bus.aboydfd.com/pyrimid-demo/paid-mcp-tool. A buyer agent calls it as a normal API. Without payment proof, it returns HTTP 402. With an X-Payment header, it returns a JSON result.

curl -i https://iota-bus.aboydfd.com/pyrimid-demo/paid-mcp-tool

curl -s https://iota-bus.aboydfd.com/pyrimid-demo/paid-mcp-tool \
  -H 'X-Payment: demo-proof' | jq

2. HTTP 402 response example

Production endpoints should verify payment through the x402 facilitator before returning paid output. The important part is that the unpaid response is machine-readable and includes the payment requirement.

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": "payment_required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "USDC",
      "payTo": "0x9eC07fE8C1004C1B9608eB35EAeF82D7fdc2347C",
      "maxAmountRequired": "100000",
      "resource": "https://iota-bus.aboydfd.com/pyrimid-demo/paid-mcp-tool",
      "description": "Demo paid MCP tool response for the Pyrimid guide.",
      "mimeType": "application/json"
    }
  ],
  "pyrimid": {
    "catalog_product_id": "iota.pyrimid-demo.paid-mcp-tool",
    "guide": "https://iota-bus.aboydfd.com/pyrimid-paid-mcp-tool-guide.html"
  }
}

3. Minimal Express implementation

In production, keep the same branch structure but replace verifyPayment with the official x402 facilitator or Pyrimid SDK verification path.

import express from "express";

const app = express();
app.use(express.json());

const product = {
  scheme: "exact",
  network: "base",
  asset: "USDC",
  payTo: "0xYourVendorWallet",
  maxAmountRequired: "100000",
  resource: "https://api.example.com/mcp/vendor-lead-preview",
  description: "Vendor lead preview for MCP/x402 products",
  mimeType: "application/json"
};

function verifyPayment(req) {
  return Boolean(req.header("X-Payment"));
}

app.post("/mcp/vendor-lead-preview", async (req, res) => {
  if (!verifyPayment(req)) {
    return res.status(402).json({ error: "payment_required", accepts: [product] });
  }
  return res.json({
    lead: "Example MCP vendor",
    fit_score: 82,
    next_action: "List the paid endpoint in Pyrimid and verify the x402 flow."
  });
});

4. Pyrimid catalog metadata

Pyrimid can expose the endpoint to buyer agents through its catalog and MCP discovery surfaces. The metadata should be concrete enough for an agent to decide whether to buy.

{
  "product_id": "iota.pyrimid-demo.paid-mcp-tool",
  "vendor": "iota",
  "name": "Vendor lead preview for MCP/x402 products",
  "description": "Returns one scored lead and the next action for listing a paid MCP or API endpoint.",
  "endpoint": "https://iota-bus.aboydfd.com/pyrimid-demo/paid-mcp-tool",
  "method": "POST",
  "price_usdc_base_units": "100000",
  "network": "base",
  "asset": "USDC",
  "affiliate_bps": 2000,
  "tags": ["mcp", "x402", "vendor-discovery", "agent-commerce"],
  "docs_url": "https://iota-bus.aboydfd.com/pyrimid-paid-mcp-tool-guide.html",
  "pyrimid": "https://pyrimid.ai/quickstart"
}

5. Verification checklist

• Unpaid call returns HTTP 402 with accepts[].
• Paid call returns deterministic JSON output.
• Catalog metadata includes endpoint, method, price, network, asset, and docs URL.
• Pyrimid catalog entry links to the guide and product endpoint.
• Production payment verification checks the x402 payment proof before releasing output.

6. Pyrimid links

Pyrimid quickstart: https://pyrimid.ai/quickstart
Pyrimid MCP discovery: https://pyrimid.ai/.well-known/mcp.json
Pyrimid catalog: https://pyrimid.ai/api/v1/catalog