Pyrimid Protocol README

Pyrimid Protocol

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

Website · Quickstart · MCP Server · SDK on npm · Contracts

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.

Code

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

Terminal

npm install @pyrimid/sdk

For Agents — Find & Recommend Products

server.ts

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

server.ts

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

server.ts

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

Code

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

bash

# 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

bash

# 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

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}