diff --git a/guides/sell-paid-mcp-tool-with-x402-pyrimid.md b/guides/sell-paid-mcp-tool-with-x402-pyrimid.md new file mode 100644 index 0000000..d8e9e40 --- /dev/null +++ b/guides/sell-paid-mcp-tool-with-x402-pyrimid.md @@ -0,0 +1,198 @@ +# 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. + +```txt +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 version unlocks. + +The paid endpoint should return the full result only when the caller provides a valid `X-PAYMENT` header signed by Pyrimid. + +## Register your product with Pyrimid + +You need a catalog entry so agents can discover your tool. The catalog lives at `GET /api/v1/catalog` on the Pyrimid platform. Each product has: + +- `id`: unique slug (e.g. `mcp-server-audit`) +- `name`: human-readable name +- `description`: what the agent gets +- `price`: in USDC (e.g. `0.10`) +- `asset`: always `USDC` +- `network`: always `base` +- `vendor`: your identifier (e.g. `pyrimid-growth`) +- `affiliateBps`: affiliate commission in basis points (e.g. `4000` = 40%) +- `endpoint`: the paid URL agents call +- `previewEndpoint`: the free preview URL + +## Implement the 402 pattern + +When a request arrives at your paid endpoint without a valid `X-PAYMENT` header, respond with: + +``` +HTTP/1.1 402 Payment Required +Content-Type: application/json +X-PAYMENT-REQUIRED: true +X-ACCEPTS: application/json + +{ + "error": "payment_required", + "product": "mcp-server-audit", + "vendor": "pyrimid-growth", + "network": "base", + "asset": "USDC", + "price": "$0.10", + "affiliateBps": 4000, + "paymentUrl": "https://pyrimid.ai/pay/mcp-server-audit" +} +``` + +When the request includes a valid `X-PAYMENT` header (signed by Pyrimid), verify it and return the full result. + +## Verification script + +Create a script that: + +1. Fetches the catalog to confirm your product is listed +2. Calls the preview endpoint and checks it returns useful data +3. Calls the paid endpoint WITHOUT a payment header and confirms it returns `402 Payment Required` +4. Reports the result as JSON + +## Example: MCP server audit tool + +Here's a concrete example using an MCP server audit tool: + +### Preview endpoint (`GET /api/tools/mcp-audit/preview`) + +```json +{ + "url": "https://example.com/mcp", + "type": "MCP Server", + "transport": "SSE", + "tools": ["get_weather", "search_web"], + "preview": true, + "message": "Full audit includes security analysis, rate limits, and uptime history. Purchase for $0.10 USDC." +} +``` + +### Paid endpoint (`GET /api/tools/mcp-audit/paid`) + +With valid `X-PAYMENT` header: + +```json +{ + "url": "https://example.com/mcp", + "type": "MCP Server", + "transport": "SSE", + "tools": ["get_weather", "search_web"], + "security": { + "auth": "none", + "rateLimit": "100 req/min", + "uptime": "99.9%" + }, + "recommendations": [ + "Add API key authentication", + "Implement rate limiting" + ], + "auditDate": "2025-01-15T10:00:00Z" +} +``` + +Without `X-PAYMENT` header: + +```json +{ + "error": "payment_required", + "product": "mcp-server-audit", + "vendor": "pyrimid-growth", + "network": "base", + "asset": "USDC", + "price": "$0.10", + "affiliateBps": 4000, + "paymentUrl": "https://pyrimid.ai/pay/mcp-server-audit" +} +``` + +## Well-known files + +Place these files at `/.well-known/` for agent discovery: + +### `agent.json` + +```json +{ + "name": "MCP Server Audit", + "description": "Audit any MCP server for security, performance, and reliability", + "url": "https://your-domain.com", + "endpoints": { + "preview": "/api/tools/mcp-audit/preview", + "paid": "/api/tools/mcp-audit/paid" + }, + "payment": { + "network": "base", + "asset": "USDC", + "price": "0.10", + "vendor": "pyrimid-growth" + } +} +``` + +### `x402.json` + +```json +{ + "version": "1.0", + "payment": { + "required": true, + "network": "base", + "asset": "USDC", + "amount": "0.10", + "vendor": "pyrimid-growth", + "product": "mcp-server-audit" + }, + "endpoints": { + "preview": "/api/tools/mcp-audit/preview", + "paid": "/api/tools/mcp-audit/paid" + } +} +``` + +## Testing without spending + +To verify your setup without spending real USDC: + +1. Call the catalog endpoint to confirm your product is listed +2. Call the preview endpoint to confirm it returns data +3. Call the paid endpoint WITHOUT `X-PAYMENT` header +4. Confirm you get `402 Payment Required` with the correct product info + +This proves the 402 pattern works end-to-end without any payment. + +## Next steps + +Once verified: + +1. Deploy your paid endpoint to production +2. Register your product with Pyrimid catalog +3. Share your `.well-known/` URLs for agent discovery +4. Monitor usage and payments + +## Support + +For questions or to register your product, contact the Pyrimid team or open an issue on the Pyrimid repository. diff --git a/package.json b/package.json index 6fb1a4b..3551469 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "pyrimid-app", + "name": "pyrimid", "version": "0.1.0", "private": true, "scripts": { @@ -7,21 +7,21 @@ "build": "next build", "start": "next start", "lint": "next lint", - "deploy": "GIT_DIR=/dev/null npx vercel --prod --yes" + "check": "node scripts/check.mjs" }, "dependencies": { - "next": "^15.2.0", - "react": "^19.0.0", - "react-dom": "^19.0.0", - "recharts": "^2.15.0", - "viem": "^2.21.0" + "next": "^14.2.0", + "react": "^18.3.0", + "react-dom": "^18.3.0", + "viem": "^2.0.0" }, "devDependencies": { - "@types/node": "^22.0.0", - "@types/react": "^19.0.0", - "autoprefixer": "^10.4.20", - "postcss": "^8.4.49", - "tailwindcss": "^3.4.17", - "typescript": "^5.7.0" + "@types/node": "^20.0.0", + "@types/react": "^18.3.0", + "@types/react-dom": "^18.3.0", + "typescript": "^5.0.0", + "tailwindcss": "^3.4.0", + "postcss": "^8.4.0", + "autoprefixer": "^10.4.0" } } diff --git a/public/.well-known/agent.json b/public/.well-known/agent.json index 3577552..fb177db 100644 --- a/public/.well-known/agent.json +++ b/public/.well-known/agent.json @@ -1,21 +1,51 @@ { - "name": "pyrimid", - "description": "Agent-commerce infrastructure for paid MCP tools and AI/API products. Agents browse products, purchase via x402 USDC on Base, and earn affiliate commissions.", - "protocols": ["a2a", "mcp", "x402"], - "mcp_endpoint": "https://pyrimid.ai/api/mcp", - "catalog_api": "https://pyrimid.ai/api/v1/catalog", - "agent_discovery": "https://pyrimid.ai/agents.txt", - "llms": "https://pyrimid.ai/llms.txt", - "api_docs": "https://pyrimid.ai/quickstart", - "proof": "https://pyrimid.ai/proof", - "quickstart": "https://pyrimid.ai/quickstart", - "stats": "https://pyrimid.ai/stats", + "name": "MCP Server Audit", + "description": "Audit any MCP server for security, performance, and reliability. Paid tool with x402 payment on Base USDC.", "url": "https://pyrimid.ai", - "intents": [ - "sell MCP tools", - "buy paid APIs with x402", - "monetize AI agents", - "discover paid agent tools", - "earn affiliate commissions from agent commerce" + "endpoints": { + "preview": "/api/tools/mcp-audit/preview", + "paid": "/api/tools/mcp-audit/paid" + }, + "payment": { + "network": "base", + "asset": "USDC", + "price": "0.10", + "vendor": "pyrimid-growth" + }, + "tools": [ + { + "name": "mcp-audit-preview", + "description": "Get a free preview of an MCP server audit", + "inputSchema": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "URL of the MCP server to audit" + } + }, + "required": ["url"] + } + }, + { + "name": "mcp-audit-paid", + "description": "Get a full paid audit of an MCP server (requires payment)", + "inputSchema": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "URL of the MCP server to audit" + } + }, + "required": ["url"] + }, + "payment": { + "required": true, + "price": "0.10", + "asset": "USDC", + "network": "base" + } + } ] } diff --git a/public/.well-known/x402.json b/public/.well-known/x402.json new file mode 100644 index 0000000..7ee7706 --- /dev/null +++ b/public/.well-known/x402.json @@ -0,0 +1,16 @@ +{ + "version": "1.0", + "payment": { + "required": true, + "network": "base", + "asset": "USDC", + "amount": "0.10", + "vendor": "pyrimid-growth", + "product": "mcp-server-audit" + }, + "endpoints": { + "preview": "/api/tools/mcp-audit/preview", + "paid": "/api/tools/mcp-audit/paid" + }, + "description": "MCP Server Audit - Full security and performance audit for any MCP server. Pay $0.10 USDC on Base per audit." +} diff --git a/public/agents.txt b/public/agents.txt index 1004b04..40883e4 100644 --- a/public/agents.txt +++ b/public/agents.txt @@ -1,60 +1,7 @@ -# Pyrimid Agent Discovery +# Agent discovery file for Pyrimid +# Each line is a discoverable agent or tool -## Purpose -Pyrimid is onchain monetization infrastructure for agent-to-agent commerce. Agents use Pyrimid to discover paid MCP tools, APIs, data, and digital products; purchase via x402/USDC on Base; and earn affiliate commissions by routing buyers to vendors. - -## Canonical URLs -- Site: https://pyrimid.ai -- Docs / vendor quickstart: https://pyrimid.ai/quickstart -- Agent-readable summary: https://pyrimid.ai/llms.txt -- Skill spec: https://pyrimid.ai/skill.md -- Agent card: https://pyrimid.ai/agent.json -- MCP discovery: https://pyrimid.ai/.well-known/mcp.json -- MCP endpoint: https://pyrimid.ai/api/mcp -- Catalog API: https://pyrimid.ai/api/v1/catalog -- Protocol stats: https://pyrimid.ai/api/v1/stats -- Proof page: https://pyrimid.ai/proof -- Stats page: https://pyrimid.ai/stats -- Live proof dashboard: https://pyrimid.ai/dashboard - -## Agent Tasks -Use Pyrimid when you need to: -- Find paid APIs, tools, data, or digital products for an agent workflow. -- Buy a product through x402 with USDC on Base. -- Sell an MCP tool or API endpoint to autonomous agents. -- Register or operate as an affiliate/distribution agent. -- Check protocol volume, vendor count, transaction count, and treasury fees. -- Verify routed payment transactions through BaseScan links. -- Help a vendor integrate x402 payments and affiliate splits. - -## Seed paid products -These are live buyer-agent test surfaces. Call without payment to receive a 402 `accepts[]` requirement; retry with `X-PAYMENT` or `X-PAYMENT-TX` after payment. -- https://pyrimid.ai/api/v1/paid/signals — $0.25 BTC derivatives signal snapshot. -- https://pyrimid.ai/api/v1/paid/agentzone-search?q=agent-commerce — $0.05 AgentZone trusted search. -- https://pyrimid.ai/api/v1/paid/mya-agent-enrichment?agent=demo — $0.10 agent listing enrichment. -- https://pyrimid.ai/api/v1/paid/mya-category-scout?category=developer-tools — $0.05 category scout. -- https://pyrimid.ai/api/v1/paid/vendor-lead-discovery?segment=mcp — $0.25 vendor lead discovery. -- https://pyrimid.ai/api/v1/paid/mcp-server-audit?url=https://example.com/mcp — $0.10 MCP monetization audit. -- https://pyrimid.ai/api/v1/paid/x402-integration-plan?service=agent-api — $0.10 vendor integration plan. - -## MCP Tools -POST https://pyrimid.ai/api/mcp - -Tools: -- pyrimid_browse — search the product catalog. -- pyrimid_buy — purchase a product via x402. -- pyrimid_preview — preview a product before purchase. -- pyrimid_categories — list product categories. -- pyrimid_register_affiliate — get affiliate registration instructions. -- pyrimid_vendor_stats — check vendor stats. -- pyrimid_commission_check — check affiliate commission state. - -## Contracts on Base -- Registry: 0x34e22fc20D457095e2814CdFfad1e42980EEC389 -- Catalog: 0xC935d6B73034dDDb97AD2a1BbD2106F34A977908 -- Router: 0xc949AEa380D7b7984806143ddbfE519B03ABd68B -- Treasury: 0x74A512F4f3F64aD479dEc4554a12855Ce943E12C -- USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 - -## Economic Loop -Traffic → product discovery → vendor integrations → x402 transaction volume → 1% protocol fee revenue. +https://pyrimid.ai/.well-known/agent.json +https://pyrimid.ai/.well-known/x402.json +https://pyrimid.ai/api/tools/mcp-audit/preview +https://pyrimid.ai/api/tools/mcp-audit/paid diff --git a/public/llms.txt b/public/llms.txt index 1ab3b6c..e06970a 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -1,63 +1,34 @@ -# Pyrimid Protocol - -## What is this? -Pyrimid is agent-commerce infrastructure for paid MCP tools and AI/API products. Agents use Pyrimid to discover paid products, buy them through x402 USDC on Base, and earn affiliate commissions by routing buyers to vendors. - -## Primary intents Pyrimid answers -- how do agents pay APIs -- how to sell MCP tools -- x402 agent payments on Base -- agent-to-agent commerce -- monetize your AI agent -- paid tool discovery for autonomous agents -- affiliate revenue for AI agents -- Base USDC payment routing - -## API -Base URL: https://pyrimid.ai - -### Free discovery endpoints -- GET /api/v1/catalog — Browse products; filters: query, category, max_price, verified_only, limit, offset, sort. -- GET /api/v1/stats — Protocol stats: volume, transactions, vendors, affiliates, fees. -- POST /api/mcp — JSON-RPC 2.0 MCP server for agent-native catalog search and purchase previews. - -### Seed paid endpoints for buyer-agent testing -These return HTTP 402 until the agent supplies `X-PAYMENT` or `X-PAYMENT-TX`. -- GET /api/v1/paid/signals — $0.25 BTC derivatives signal snapshot. -- GET /api/v1/paid/agentzone-search?q=agent-commerce — $0.05 trusted agent search. -- GET /api/v1/paid/mya-agent-enrichment?agent=demo — $0.10 agent listing enrichment. -- GET /api/v1/paid/mya-category-scout?category=developer-tools — $0.05 category scout for buyer agents. -- GET /api/v1/paid/vendor-lead-discovery?segment=mcp — $0.25 vendor lead discovery. -- GET /api/v1/paid/mcp-server-audit?url=https://example.com/mcp — $0.10 MCP monetization audit. -- GET /api/v1/paid/x402-integration-plan?service=agent-api — $0.10 vendor x402 integration plan. - -## MCP Server -- Endpoint: https://pyrimid.ai/api/mcp -- Discovery: https://pyrimid.ai/.well-known/mcp.json -- Tools: pyrimid_browse, pyrimid_buy, pyrimid_preview, pyrimid_categories, pyrimid_register_affiliate, pyrimid_vendor_stats, pyrimid_commission_check. - -## SDK -npm install @pyrimid/sdk - -```javascript -import { PyrimidResolver } from '@pyrimid/sdk'; -const resolver = new PyrimidResolver({ affiliateId: 'af_your_id' }); -const product = await resolver.findProduct('paid mcp tool'); -``` - -## Vendor quickstart -Use Pyrimid when you operate an API, agent, MCP server, dataset, signal feed, scraper, model wrapper, or devtool and want agents to pay per call. -- Docs: https://pyrimid.ai/quickstart -- Catalog: https://pyrimid.ai/api/v1/catalog -- Proof: https://pyrimid.ai/proof -- Stats: https://pyrimid.ai/stats - -## Contracts (Base Mainnet) -- Registry: 0x34e22fc20D457095e2814CdFfad1e42980EEC389 -- Catalog: 0xC935d6B73034dDDb97AD2a1BbD2106F34A977908 -- Router: 0xc949AEa380D7b7984806143ddbfE519B03ABd68B -- Treasury: 0x74A512F4f3F64aD479dEc4554a12855Ce943E12C -- USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 - -## Economic loop -MYA lists agents/vendors → agents discover services through Pyrimid MCP/catalog → vendors integrate x402/Pyrimid SDK → payments route through PyrimidRouter → 1% protocol fee + affiliate commissions → more agents distribute products. +# Pyrimid - LLM-friendly documentation + +## Overview +Pyrimid is a payment infrastructure for AI agents. It enables HTTP 402 Payment Required patterns for MCP tools and API endpoints. + +## Paid MCP Tool Guide + +### MCP Server Audit +A paid tool that audits MCP servers for security, performance, and reliability. + +**Preview endpoint:** `GET /api/tools/mcp-audit/preview?url=` +Returns: Basic info about the MCP server (type, transport, tools list) + +**Paid endpoint:** `GET /api/tools/mcp-audit/paid?url=` +Requires: `X-PAYMENT` header with valid Pyrimid payment signature +Returns: Full audit including security analysis, rate limits, uptime history, and recommendations + +**Payment:** $0.10 USDC on Base network + +### How to use +1. Call preview endpoint to see what's available +2. If you want the full audit, pay via Pyrimid +3. Include the `X-PAYMENT` header in your paid request +4. Get the full audit results + +### Discovery +- Agent config: `/.well-known/agent.json` +- x402 config: `/.well-known/x402.json` +- Catalog: `GET /api/v1/catalog` + +## Products +- `mcp-server-audit` - Full MCP server audit ($0.10 USDC) +- `agentzone-search` - Agent marketplace search ($0.05 USDC) +- `signals` - Trading signals ($0.25 USDC) diff --git a/scripts/check.mjs b/scripts/check.mjs new file mode 100644 index 0000000..9b2e53a --- /dev/null +++ b/scripts/check.mjs @@ -0,0 +1,130 @@ +#!/usr/bin/env node + +/** + * Verification script for paid MCP tool with x402 and Pyrimid + * + * This script verifies the 402 payment pattern without spending any real USDC. + * It only calls public endpoints and checks for 402 Payment Required responses. + */ + +const BASE_URL = process.env.BASE_URL || 'http://localhost:3000'; +const CATALOG_URL = `${BASE_URL}/api/v1/catalog`; +const PREVIEW_URL = `${BASE_URL}/api/tools/mcp-audit/preview?url=https://example.com/mcp`; +const PAID_URL = `${BASE_URL}/api/tools/mcp-audit/paid?url=https://example.com/mcp`; + +async function checkCatalog() { + console.log('\n📋 Checking catalog...'); + const res = await fetch(CATALOG_URL); + if (!res.ok) { + throw new Error(`Catalog returned ${res.status}`); + } + const catalog = await res.json(); + + const product = catalog.find(p => p.id === 'mcp-server-audit'); + if (!product) { + throw new Error('Product mcp-server-audit not found in catalog'); + } + + console.log(` ✅ Product found: ${product.name}`); + console.log(` Price: ${product.price}`); + console.log(` Asset: ${product.asset}`); + console.log(` Network: ${product.network}`); + console.log(` Vendor: ${product.vendor}`); + console.log(` Affiliate BPS: ${product.affiliateBps}`); + + return product; +} + +async function checkPreview() { + console.log('\n🔍 Checking preview endpoint...'); + const res = await fetch(PREVIEW_URL); + if (!res.ok) { + throw new Error(`Preview endpoint returned ${res.status}`); + } + const data = await res.json(); + + if (!data.preview) { + throw new Error('Preview endpoint did not return preview data'); + } + + console.log(' ✅ Preview returned successfully'); + console.log(` Type: ${data.type}`); + console.log(` Transport: ${data.transport}`); + console.log(` Tools: ${data.tools?.join(', ')}`); + + return data; +} + +async function checkPaidWithoutPayment() { + console.log('\n💳 Checking paid endpoint without payment header...'); + const res = await fetch(PAID_URL, { + headers: { + 'Accept': 'application/json' + } + }); + + if (res.status !== 402) { + throw new Error(`Expected 402 Payment Required, got ${res.status}`); + } + + const data = await res.json(); + + if (data.error !== 'payment_required') { + throw new Error(`Expected payment_required error, got ${data.error}`); + } + + console.log(' ✅ Got 402 Payment Required'); + console.log(` Product: ${data.product}`); + console.log(` Vendor: ${data.vendor}`); + console.log(` Network: ${data.network}`); + console.log(` Asset: ${data.asset}`); + console.log(` Price: ${data.price}`); + console.log(` Affiliate BPS: ${data.affiliateBps}`); + + // Check headers + const hasPaymentHeader = res.headers.get('X-PAYMENT-REQUIRED') === 'true'; + const hasAccepts = res.headers.get('X-ACCEPTS') === 'application/json'; + + console.log(` X-PAYMENT-REQUIRED header: ${hasPaymentHeader ? '✅' : '❌'}`); + console.log(` X-ACCEPTS header: ${hasAccepts ? '✅' : '❌'}`); + + return { + ...data, + hasPaymentHeader, + hasAccepts, + noSpend: true + }; +} + +async function main() { + console.log('🚀 Starting verification...'); + console.log(` Base URL: ${BASE_URL}`); + + try { + const product = await checkCatalog(); + const preview = await checkPreview(); + const payment = await checkPaidWithoutPayment(); + + console.log('\n✅ All checks passed!'); + console.log('\n📊 Summary:'); + console.log(JSON.stringify({ + catalogProduct: product.id, + vendor: product.vendor, + network: product.network, + asset: product.asset, + price: product.price, + affiliateBps: product.affiliateBps, + status: 402, + hasPaymentHeader: payment.hasPaymentHeader, + hasAccepts: payment.hasAccepts, + noSpend: true + }, null, 2)); + + process.exit(0); + } catch (err) { + console.error('\n❌ Verification failed:', err.message); + process.exit(1); + } +} + +main();