<h1 align="center">Pyrimid Protocol</h1>

Agent-commerce infra for paid MCP tools and x402 AI/API products on Base.

<a href="https://pyrimid.ai">Website</a> · <a href="https://pyrimid.ai/quickstart">Quickstart</a> · <a href="https://pyrimid.ai/api/mcp">MCP Server</a> · <a href="https://www.npmjs.com/package/@pyrimid/sdk">SDK on npm</a> · <a href="https://basescan.org/address/0xc949AEa380D7b7984806143ddbfE519B03ABd68B">Contracts</a>

---

What is Pyrimid?

Pyrimid is a protocol where vendors sell paid MCP tools / AI APIs, agents discover and buy them via x402, and commissions settle instantly in USDC via smart contracts on Base.

Agent discovers a product → purchases via x402 → smart contract splits payment:

  1%        → Protocol treasury
  0–50%     → Affiliate agent (set by vendor)
  Remainder → Vendor

No affiliate? Vendor gets 99%. Vendors only pay for distribution that drives real sales. One layer only — no MLM, no pyramids. Just clean, transparent commission splitting onchain.

---

Why Pyrimid?

| Problem | Pyrimid's Solution | |---------|-------------------| | Agents can't monetize recommendations | Earn commissions by recommending products to users | | Vendors can't reach agents at scale | List once, get discovered by every agent on the network | | Commission payments are slow & opaque | Instant USDC settlement via smart contracts — fully auditable | | No standard for agent commerce | x402 payments + MCP tools + onchain registry = open standard |

---

Quick Start

Install the SDK

npm install @pyrimid/sdk

For Agents — Find & Recommend Products

import { PyrimidResolver } from '@pyrimid/sdk';

const resolver = new PyrimidResolver({ affiliateId: 'af_your_id' });

// Search the catalog
const product = await resolver.findProduct("trading signals");

// Purchase with x402 payment (auto-splits commissions)
if (product) {
  const receipt = await resolver.purchase(product, agentWallet);
  console.log(`Earned: $${receipt.affiliate_earned / 1_000_000} USDC`);
}

For Vendors — List Your Product

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

// 10 lines to activate affiliate distribution
app.use(pyrimidMiddleware({
  vendorId: 'vn_your_id',
  products: {
    '/api/signals/latest': {
      productId: 'signals_latest',
      price: 250_000,        // $0.25 USDC
      affiliateBps: 1000,    // 10% to affiliates
    },
  },
}));

For Frameworks — Embed as Default Layer

import { createPyrimidMcpServer } from '@pyrimid/sdk';

// Deploy an MCP server — agents connect, browse, buy
const server = createPyrimidMcpServer({
  affiliateId: 'af_your_id',
  serverName: 'my-recommender',
});

---

Live buyer-agent test surfaces

Call these without payment to receive HTTP 402 with x402 accepts[] metadata. Retry with X-PAYMENT or X-PAYMENT-TX after payment.

| Endpoint | Price | Use case | |----------|-------|----------| | /api/v1/paid/signals | $0.25 | BTC derivatives signal snapshot | | /api/v1/paid/agentzone-search?q=agent-commerce | $0.05 | Trusted agent search | | /api/v1/paid/mya-agent-enrichment?agent=demo | $0.10 | Agent listing enrichment | | /api/v1/paid/mya-category-scout?category=developer-tools | $0.05 | Category scouting for buyer agents | | /api/v1/paid/vendor-lead-discovery?segment=mcp | $0.25 | Vendor lead discovery | | /api/v1/paid/mcp-server-audit?url=https://example.com/mcp | $0.10 | MCP monetization audit | | /api/v1/paid/x402-integration-plan?service=agent-api | $0.10 | Vendor x402 integration plan |

Three Integration Paths

| Path | Who | Effort | Leverage | |------|-----|--------|----------| | Embedded Resolver | Agent frameworks & toolkits | 3 lines | Every agent on your stack earns you commissions | | MCP Server | Agent infrastructure providers | 5 lines | Agents connect to your server to discover products | | Vendor Middleware | API & product builders | 10 lines | Activate affiliate distribution on your product |

---

Smart Contracts (Base Mainnet)

All contracts are deployed and verified on Base. ERC-1967 upgradeable proxy pattern.

| Contract | Address | Purpose | |----------|---------|---------| | Registry | 0x34e22fc2...389 | Affiliate & vendor registration, ERC-8004 identity linking | | Catalog | 0xC935d6B7...908 | Product listings with pricing & commission rates | | Router | 0xc949AEa3...68B | Commission splitting engine with maxPrice slippage protection | | Treasury | 0x74A512F4...12C | Protocol operations fund |

---

API Reference

The Pyrimid API is free to read, rate-limited (60 req/min), and returns JSON.

| Endpoint | Method | Description | |----------|--------|-------------| | /api/v1/catalog | GET | Full product catalog with search, filters, pagination | | /api/v1/paid/* | GET | Seed paid endpoints for x402 buyer-agent testing | | /api/v1/stats | GET | Protocol-level stats (volume, transactions, affiliates) | | /api/v1/stats?type=affiliate&id=af_xxx | GET | Affiliate performance & earnings | | /api/v1/stats?type=vendor&id=vn_xxx | GET | Vendor analytics | | /api/mcp | POST | MCP JSON-RPC 2.0 endpoint (Streamable HTTP) | | /api/mcp | GET | Server info & tool definitions |

MCP Tools

| Tool | Description | |------|-------------| | pyrimid_browse | Search catalog by query, price, category, verified status | | pyrimid_buy | Purchase a product via x402 with affiliate attribution | | pyrimid_preview | Preview the commission split before buying | | pyrimid_categories | List all product categories with counts | | pyrimid_register_affiliate | Instructions to register as an affiliate onchain |

---

Architecture

pyrimid/
├── app/                       # Next.js 15 (Vercel, region: bom1)
│   ├── page.tsx               # Landing page
│   ├── dashboard/             # Protocol dashboard
│   └── api/
│       ├── v1/catalog/        # Aggregated product catalog
│       ├── v1/paid/           # Seed x402 paid endpoints
│       ├── v1/stats/          # Protocol & affiliate analytics
│       └── mcp/               # MCP JSON-RPC endpoint
├── sdk/                       # @pyrimid/sdk (published to npm)
│   └── src/
│       ├── resolver.ts        # PyrimidResolver — search, purchase, stats
│       ├── mcp-server.ts      # MCP server factory
│       ├── middleware.ts       # Vendor payment middleware + calculateSplit()
│       └── types.ts           # ABIs, addresses, interfaces
├── subgraph/                  # The Graph indexer (Base)
│   ├── schema.graphql         # PaymentRouted, Affiliate, Vendor entities
│   ├── subgraph.yaml          # 4 data sources
│   └── src/mapping.ts         # Event handlers
├── middleware.ts               # Edge rate limiting (60/min API, 120/min MCP)
└── public/docs/               # Developer documentation

---

Development

# Clone & install
git clone https://github.com/pyrimid/protocol.git
cd protocol
npm install

# Run locally
cp .env.example .env
npm run dev

# SDK development
cd sdk
npm run build    # TypeScript → dist/
npm run dev      # Watch mode

Deploy

# Website + API
npx vercel --prod

# SDK to npm
cd sdk && npm publish --access public

# Subgraph to The Graph
cd subgraph && npx graph deploy pyrimid --studio

---

Security

Payment verification: Real onchain verification via viem — checks PaymentRouted events + USDC transfers with 5-minute expiry
Rate limiting: Edge middleware, 60 req/min per IP on catalog/stats, 120/min on MCP
BigInt safety: calculateSplit() handles both Number and BigInt inputs from web3 libraries
Contract pattern: ERC-1967 upgradeable proxies with verified source on BaseScan

---

Roadmap

[x] Core contracts deployed on Base
[x] SDK v0.2.3 with full catalog pagination
[x] MCP server with 5 tools
[x] x402 Bazaar aggregation (92+ products)
[x] Subgraph indexing on The Graph
[x] Rate limiting & security hardening
[ ] ERC-8004 identity verification for vendors
[ ] Multi-network support (Arbitrum, Optimism)
[ ] Revenue dashboard for affiliates
[ ] Vendor self-service registration portal

---

Links

| Resource | URL | |----------|-----| | Website | pyrimid.ai | | Documentation | pyrimid.ai/docs | | SDK | npmjs.com/package/@pyrimid/sdk | | Subgraph | thegraph.com/studio/subgraph/pyrimid | | Registry | BaseScan | | Router | BaseScan |

---

Built on Base · Payments via x402 · Settlement in USDC

Pyrimid Protocol