Pyrimid Documentation

Onchain monetization infrastructure for agent-to-agent commerce. One-layer affiliate distribution protocol on Base. Payments settle instantly in USDC.

Quick Start

Installation

$ npm install @pyrimid/sdkbash

Peer dependencies (install what you need):

# For MCP Server path
npm install @modelcontextprotocol/sdk zod

# For purchase flow
npm install @x402/fetchbash

Fastest integration — 3 lines

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

const resolver = new PyrimidResolver({ affiliateId: 'af_your_id' });
const product = await resolver.findProduct("btc trading signal");typescript

PyrimidResolver

Path 1: Embedded Distribution — Highest leverage. Embed this in your agent framework and every agent on your stack routes purchases through Pyrimid with your affiliate ID. One integration, thousands of passive attributed purchases.

Constructor

const resolver = new PyrimidResolver({
  affiliateId: 'af_your_id',          // Required — your affiliate ID
  catalogUrl: 'https://api.pyrimid.ai/v1/catalog',  // Optional
  cacheTtlMs: 300_000,               // Cache TTL (default 5 min)
  preferVerifiedVendors: true,       // ERC-8004 verified first
  maxPriceUsdc: 10_000_000,          // $10 max per call
});typescript

Methods

Full purchase flow

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

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

// 1. Agent needs a capability → search
const product = await resolver.findProduct("btc perpetual futures signal");

if (product) {
  console.log(product.vendor_name, product.price_display);
  // "Trading Brain" "$0.25"

  // 2. Purchase with x402 payment
  const receipt = await resolver.purchase(product, agentWallet);

  console.log(receipt.tx_hash);            // onchain tx
  console.log(receipt.affiliate_earned);     // your cut
  console.log(receipt.data);                 // product data
}typescript

MCP Server

Path 2: MCP Recommender — Deploy a catalog server that other agents connect to as a tool. Every purchase through your server earns your affiliate commission.

Three deployment modes

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

// Mode 1: Official (treasury affiliate)
const official = createPyrimidMcpServer();

// Mode 2: Custom affiliate (your earnings)
const mine = createPyrimidMcpServer({
  affiliateId: 'af_your_id',
  serverName: 'my-recommender',
});

// Mode 3: Specialized vertical
const trading = createPyrimidMcpServer({
  affiliateId: 'af_your_id',
  serverName: 'trading-signals-recommender',
});typescript

Exposed MCP tools

Vendor Middleware

Path 3: Payment Integration — Add Pyrimid to your existing API. 10 lines activates affiliate-attributed commission splitting on every sale.

Express / Connect

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

app.use(pyrimidMiddleware({
  vendorId: 'vn_your_id',
  products: {
    '/api/signals/latest': {
      productId: 'signals_latest',
      price: 250_000,       // $0.25 (USDC atomic)
      affiliateBps: 2000,   // 20% commission
    },
    '/api/indicators/supertrend': {
      productId: 'indicator_supertrend',
      price: 5_000_000,     // $5.00
      affiliateBps: 2000,
    },
  },
}));typescript

Next.js App Router

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

export const GET = withPyrimid({
  vendorId: 'vn_your_id',
  productId: 'signals_latest',
  price: 250_000,
  affiliateBps: 2000,
}, async (req, receipt) => {
  // receipt.verified === true
  // receipt.split contains the full breakdown
  return Response.json({
    signal: 'BTC LONG',
    confidence: 0.82,
    entry: 67450,
  });
});typescript

Types & Constants

Contract addresses

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

PYRIMID_ADDRESSES.base.REGISTRY  // 0x2263...c89
PYRIMID_ADDRESSES.base.CATALOG   // 0x1ae8...E74
PYRIMID_ADDRESSES.base.ROUTER    // 0x6594...FC8
PYRIMID_ADDRESSES.base.TREASURY  // 0xdF29...908
PYRIMID_ADDRESSES.base.USDC      // 0x8335...913
PYRIMID_ADDRESSES.base.ERC_8004  // 0x8004...432typescript

ABI fragments

Minimal ABIs for direct contract interaction:

import {
  ROUTER_ABI,
  REGISTRY_ABI,
  CATALOG_ABI,
  TREASURY_ABI,
} from '@pyrimid/sdk';typescript

Exported types

import type {
  PyrimidProduct,     // Product listing
  PurchaseResult,     // Purchase receipt
  PaymentSplit,       // Commission breakdown
  AffiliateStats,     // Affiliate performance
  VendorStats,        // Vendor analytics
  ProtocolStats,      // Network-wide stats
  CatalogResponse,    // API response shape
  CatalogQueryParams, // Query parameters
  ResolverConfig,     // Resolver constructor
  McpServerConfig,    // MCP server factory
  VendorMiddlewareConfig, // Middleware setup
  PaymentReceipt,     // Payment verification
} from '@pyrimid/sdk';typescript

API Reference

Base URL: https://api.pyrimid.ai

GET /v1/catalog

Aggregated product catalog from all sources (onchain, Bazaar, MCPize, MCP Hive, Apify).

// Response
{
  "products": [
    {
      "vendor_id": "vn_trading_brain",
      "vendor_name": "Trading Brain",
      "vendor_erc8004": true,
      "product_id": "signals_latest",
      "description": "BTC perpetual futures trading signal",
      "price_usdc": 250000,
      "price_display": "$0.25",
      "affiliate_bps": 2000,
      "source": "onchain",
      "sdk_integrated": true
    }
  ],
  "total": 347,
  "sources": { "onchain": 12, "bazaar": 251, "mcpize": 84 }
}json

GET /v1/stats

Protocol-level or entity-specific statistics.

// GET /v1/stats?type=protocol
{
  "protocol": {
    "total_volume_usdc": 5420000000,
    "total_volume_display": "$5.4K",
    "total_transactions": 847,
    "total_affiliates": 23,
    "total_vendors": 5,
    "treasury_balance_usdc": 54200000
  },
  "catalog": { "total_products": 347 },
  "recent_transactions": [...]
}json

// GET /v1/stats?type=affiliate&id=af_xxx
{
  "affiliate": {
    "reputation_score": 4200,
    "total_earnings_display": "$127.50",
    "sales_count": 89,
    "unique_buyers": 34,
    "erc8004_linked": true
  },
  "recent_sales": [...]
}json

// GET /v1/stats?type=vendor&id=vn_xxx
{
  "vendor": {
    "total_volume_display": "$2.1K",
    "total_sales": 312,
    "unique_affiliates": 8,
    "affiliate_payouts_usdc": 420000000
  },
  "recent_sales": [...]
}json

Contracts

Four contracts on Base mainnet. Forked from Fluencr with major simplifications — Gold tier removed, multi-stablecoin reduced to USDC-only, vendor self-service added, ERC-8004 integration added.

Commission Split

Every transaction splits automatically in a single onchain call through the PyrimidRouter.

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

const split = calculateSplit(250_000, 2000); // $0.25, 20% affiliate
// { total_usdc: 250000, protocol_fee: 2500,
//   affiliate_commission: 49500, vendor_share: 198000 }typescript

Reputation System

Onchain score (0–10,000) updated on every sale. Higher reputation = better catalog placement = better commission offers from vendors.

ERC-8004 Identity

Optional but strongly incentivized. Link your ERC-8004 agent identity for +2,000 reputation, priority catalog placement, and composable identity across the agent ecosystem.

// Link via contract call
registry.linkERC8004Identity(agentId);

// Or via MCP tool
// pyrimid_register_affiliate({ wallet_address, ... })typescript

Roadmap: Optional at launch → increasingly advantageous → eventually required for affiliate registration.

Specification

The full Pyrimid v0.2 master specification covers architecture, contract design, SDK, distribution model, revenue projections, anti-gaming, and go-to-market strategy.

SDK Source

Package structure for @pyrimid/sdk: