OpenAgentPay

March 30, 2026 · View on GitHub

Payment orchestration for the agentic internet.

OpenAgentPay is a payment orchestration layer for machine-to-machine commerce. It connects API providers to every agent payment method through a unified protocol — multi-protocol acceptance, intelligent routing, spend governance, and unified receipts.

API owners install OpenAgentPay server-side. It returns a standardized 402 response with pricing and all accepted payment methods. Agents use the OpenAgentPay client SDK (lightweight, wraps fetch) or any client that understands the OpenAgentPay 402 format to discover pricing, select a method, pay, and retry.

                                OpenAgentPay
                           (installed by API owner)
                                     │
      ┌──────────────────────────────┼──────────────────────────────┐
      │                              │                              │
      │    ┌─────────────────────────▼─────────────────────────┐    │
      │    │              Paywall Middleware                    │    │
      │    │                                                   │    │
      │    │   402 Response ──► Detect ──► Verify ──► Serve    │    │
      │    │   (pricing)        (header)   (adapter)  (data)   │    │
      │    │                                                   │    │
      │    │   Smart Router ──► Cascade ──► Health ──► Receipt  │    │
      │    │   (14 strategies)  (failover)  (tracking) (audit) │    │
      │    └───────────────────────┬───────────────────────────┘    │
      │                            │                                │
      └────────────────────────────┼────────────────────────────────┘
                                   │
        ┌───────┬──────┬───────────┼───────────┬──────┬───────┐
        │       │      │           │           │      │       │
     ┌──▼──┐ ┌─▼──┐ ┌─▼───┐ ┌────▼───┐ ┌───▼──┐ ┌─▼────┐ ┌▼──────┐
     │ MPP │ │x402│ │Solna│ │  Visa  │ │Stripe│ │Lghtn.│ │Credits│
     │     │ │USDC│ │ SPL │ │AgentCrd│ │PayPal│ │BOLT11│ │ Mock  │
     │Tempo│ │Base│ │     │ │  MCP   │ │ UPI  │ │      │ │       │
     └─────┘ └────┘ └─────┘ └────────┘ └──────┘ └──────┘ └───────┘

How it works

The API owner integrates OpenAgentPay (server-side)

import { createPaywall } from '@openagentpay/server-express';
import { mpp } from '@openagentpay/adapter-mpp';
import { x402 } from '@openagentpay/adapter-x402';

const paywall = createPaywall({
  recipient: '0xYourWallet',
  adapters: [
    mpp({ networks: ['tempo', 'stripe'] }),
    x402({ network: 'base' }),
  ],
});

app.get('/api/data', paywall({ price: '0.01' }), (req, res) => {
  res.json({ results: ['premium-data'] });
});

That's it. The endpoint now:

Returns 402 Payment Required with machine-readable pricing if no payment is attached
Detects payment proof from any agent using any supported protocol
Verifies the payment through the appropriate adapter
Serves the response and generates a receipt

Agent-side: lightweight client SDK

The agent installs the OpenAgentPay client — a lightweight fetch wrapper that handles the unified 402 format:

import { withPayment } from '@openagentpay/client';
import { mppWallet } from '@openagentpay/adapter-mpp';

const paidFetch = withPayment(fetch, {
  wallet: mppWallet({ network: 'tempo', privateKey: process.env.KEY }),
  policy: {
    maxPerRequest: '1.00',
    maxPerDay: '50.00',
    allowedDomains: ['*.trusted.dev'],
  },
});

// Receives 402 → parses pricing → checks policy → selects method → pays → retries
await paidFetch('https://api.trusted.dev/data');

The client SDK handles:

Parsing OpenAgentPay's unified 402 response (pricing + all accepted methods)
Selecting the best payment method the agent's wallet supports
Policy enforcement (spend limits, domain rules, approval thresholds)
Payment execution via the wallet adapter
Automatic retry with payment proof
Receipt collection

Payment proof headers are protocol-standard — once the agent pays, the header it sends uses the native protocol format. The server-side adapter verifies it against the real payment processor.

Protocol	Payment header sent by agent	Verified by
MPP	`Authorization: MPP <credential>`	Tempo RPC / Stripe API
x402	`X-PAYMENT: <base64 EIP-3009>`	x402 facilitator
Solana	`X-SOLANA-PAYMENT: <base64 proof>`	Solana RPC
Lightning	`X-LIGHTNING-PAYMENT: <base64 proof>`	LND REST API
Visa	`X-VISA-TOKEN: <tokenized card>`	Visa MCP / payment gateway
Stripe	`X-STRIPE-SESSION: <intent ID>`	Stripe REST API
PayPal	`X-PAYPAL-ORDER: <order ID>`	PayPal REST API
UPI	`X-UPI-REFERENCE: <tx ref>`	Razorpay / Cashfree API
Credits	`X-CREDITS: <account:sig>`	Internal credit store

What the API owner gets

1. Multi-protocol acceptance

Accept payments from agents using any payment method — through one middleware.

const paywall = createPaywall({
  recipient: '0xYourWallet',
  adapters: [
    mpp({ networks: ['tempo', 'stripe'] }),    // MPP agents
    x402({ network: 'base' }),                  // x402 agents
    solana({ rpcUrl: '...' }),                  // Solana SPL agents
    lightning({ nodeUrl: '...' }),              // Lightning agents
    visa(),                                      // Visa agents
    stripe({ secretKey: '...' }),               // Stripe agents
    credits({ store }),                         // Prepaid credit agents
  ],
});

2. Intelligent routing (14 strategies)

When an agent sends payment, the middleware detects which adapter matches and verifies it. When configured with the Smart Router, it selects the optimal verification path:

import { createRouter } from '@openagentpay/router';

const router = createRouter({
  adapters: [
    { adapter: mpp({ ... }), costPerTransaction: '0.001' },
    { adapter: x402({ ... }), costPerTransaction: '0.001' },
    { adapter: stripe({ ... }), costPerTransaction: '0.30', costPercentage: 2.9, minimumAmount: '0.50' },
  ],
  strategy: 'smart',
  cascade: true,
});

Strategy	What it does
`priority`	Static priority order
`lowest-cost`	Cheapest adapter for the amount
`highest-success`	Best recent success rate
`lowest-latency`	Fastest response time
`round-robin`	Even distribution
`weighted`	Probabilistic (A/B testing)
`smart`	Composite: success x 0.5 + cost x 0.3 + latency x 0.2
`adaptive`	Multi-armed bandit (10% exploration, 90% exploit)
`conditional`	Rule-based if/else routing
`amount-tiered`	Different strategy per amount range
`geo-aware`	Region-based preferences
`time-aware`	Time-of-day optimization
`failover-only`	Primary/secondary with recovery probes
`custom`	User-defined scoring function

3. Cascade failover

If the first matching adapter's verification fails, the middleware automatically tries the next one. Returns 402 only after all adapters have been tried.

4. Subscriptions

Agents that call your API repeatedly can subscribe instead of paying per call.

const paywall = createPaywall({
  recipient: '0x...',
  adapters: [mpp({ ... })],
  subscriptions: {
    plans: [
      { id: 'daily-unlimited', amount: '5.00', currency: 'USDC', period: 'day', calls: 'unlimited' },
    ],
  },
});

app.use(paywall.routes());
// POST /openagentpay/subscribe    — pay + activate (payment verified via adapter)
// GET  /openagentpay/subscription — check status
// POST /openagentpay/unsubscribe  — cancel

Active subscriptions use X-SUBSCRIPTION header — no per-call payment.

5. Service discovery

Expose your API's payment capabilities so agents can discover pricing programmatically:

import { discoveryMiddleware } from '@openagentpay/server-express';

app.use(discoveryMiddleware({
  version: '1.0',
  provider: 'My API',
  methods: ['mpp', 'x402', 'solana'],
  currencies: ['USD', 'USDC'],
  endpoints: [
    { path: '/api/search', methods: ['GET'], pricing: { amount: '0.01', currency: 'USD', unit: 'per_request' } },
  ],
  capabilities: { subscriptions: true, streaming: true, sessions: true, receipts: true },
}));
// GET /.well-known/agent-pay → machine-readable discovery document

6. Receipts and observability

Every payment generates a structured AgentPaymentReceipt — same schema regardless of payment method.

paywall.on('payment:received', (receipt) => {
  console.log(`${receipt.payment.method}: $${receipt.payment.amount} from ${receipt.payer.identifier}`);
});

Store, query, and export receipts:

import { createReceiptStore } from '@openagentpay/receipts';
const store = createReceiptStore({ type: 'file', path: './receipts' });
const csv = await store.export({ format: 'csv' });

OpenTelemetry integration:

import { createPaymentTracer, createPaymentMetrics } from '@openagentpay/otel-exporter';
paywall.on('payment:received', (receipt) => {
  createPaymentTracer().recordPayment(receipt);
  createPaymentMetrics().recordPayment(receipt);
});

7. Dynamic pricing

// Static
app.get('/api/search', paywall({ price: '0.01' }), handler);

// Dynamic — price as a function of the request
app.post('/api/process', paywall((req) => ({
  price: (0.01 * req.body.pages).toFixed(3),
  description: `Process ${req.body.pages} pages`,
})), handler);

8. Zero-code payment proxy

Wrap any existing API with payment gating — no code changes to the upstream service:

import { createProxy } from '@openagentpay/proxy';

const proxy = createProxy({
  upstream: 'https://internal-api.example.com',
  pricing: { amount: '0.01', currency: 'USD' },
  recipient: '0xYourWallet',
  freePaths: ['/health', '/docs/*'],
});

await proxy.start(3000);
// All requests to port 3000 now require payment (except /health, /docs/*)

9. Tax awareness

Automatic tax calculation and reporting for agent transactions:

import { createCalculator, createReporter } from '@openagentpay/tax';

const tax = createCalculator({ defaultJurisdiction: 'US-CA' });
const calc = tax.calculate('10.00', 'USD', 'stripe', 'US-CA');
// { grossAmount: '10.00', taxAmount: '0.73', netAmount: '10.73', taxRate: 0.0725 }

const reporter = createReporter({ defaultJurisdiction: 'US-CA' });
reporter.addTransaction(receipt);
const report = reporter.generateReport({ from: '2026-01-01', to: '2026-03-31' });
const csv = reporter.exportCSV(report);

All 26 packages

Core

Package	What it does
`core`	Types, schemas, builders, parsers, error classes. Zero deps. Foundation for everything.
`router`	14 routing strategies, health tracking, cost estimation, cascade failover.
`policy`	Spend governance engine — 12 rules including identity-required, budgets, domain globs.
`client`	`withPayment(fetch)` — parses unified 402, selects method, pays, retries, collects receipts.

Server frameworks

Package	What it does
`server-express`	Express paywall middleware + subscription endpoints + service discovery.
`server-hono`	Hono paywall middleware + subscription endpoints + service discovery.
`server-cloudflare`	Cloudflare Workers paywall handler + KV receipt storage.
`proxy`	Zero-code reverse proxy — wrap any API with 402 payment gating.

Payment adapters (10)

Package	Protocol	Networks
`adapter-mpp`	MPP (Machine Payments Protocol)	Tempo, Stripe, Lightning. Sessions + streaming.
`adapter-x402`	x402 (EIP-3009)	USDC on Base / Base Sepolia. Production secp256k1 ECDSA signing.
`adapter-solana`	Solana SPL tokens	USDC on Solana mainnet / devnet. Ed25519 signing.
`adapter-lightning`	Lightning Network	BOLT11 invoices via LND REST. Preimage verification.
`adapter-visa`	Visa Intelligent Commerce	Visa MCP + AgentCard virtual debit cards.
`adapter-stripe`	Stripe	PaymentIntents + credit bridge via Checkout.
`adapter-paypal`	PayPal	Orders API + credit bridge. OAuth2.
`adapter-upi`	UPI (India)	Reserve Pay (SBMD), AutoPay mandates, QR codes, refunds, webhooks. Razorpay + Cashfree.
`adapter-credits`	Prepaid credits	Atomic deductions from in-memory or persistent balance.
`adapter-mock`	Mock	Simulated payments for development and testing.

Infrastructure

Package	What it does
`receipts`	Receipt storage (memory/file), query, CSV/JSON export.
`vault`	Credential vault + agent identity (DIDs, Ed25519 attestations, KYA profiles).
`otel-exporter`	OpenTelemetry spans + metrics.
`tax`	Tax calculator (US/EU/India/Japan/Singapore), reporter, CSV export, capital gains.
`cli`	CLI tool: `agentpay probe`, `pay`, `receipt`, `discover`, `simulate`.

Integrations

Package	What it does
`mcp`	`paidTool()` — wrap MCP tool handlers with payment verification.
`mcp-mpp`	MCP-to-MPP bridge — discover and pay for MCP tools via MPP protocol.
`razorpay-mcp`	Razorpay MCP server client — 48+ payment tools via JSON-RPC 2.0.

Payment method comparison

Method	Min Amount	Per-Call Fee	Settlement	Agent wallet adapter
MPP (Tempo)	~$0.001	~$0.001	Instant	`@openagentpay/adapter-mpp`
x402 (USDC)	~$0.001	~$0.001	~200ms	`@openagentpay/adapter-x402`
Solana (SPL)	~$0.001	~$0.001	~400ms	`@openagentpay/adapter-solana`
Lightning	~1 sat	~1 sat	Instant	`@openagentpay/adapter-lightning`
Visa MCP	~$1.00	Card rates	1-3 days	`@openagentpay/adapter-visa`
AgentCard	$1.00	Card rates	1-3 days	`@openagentpay/adapter-visa`
Stripe	$0.50	2.9%+$0.30	2-7 days	`@openagentpay/adapter-stripe`
PayPal	~$1.00	3.49%+$0.49	1-3 days	`@openagentpay/adapter-paypal`
UPI	Rs 1	~0%	T+1	`@openagentpay/adapter-upi`
UPI Reserve Pay	Rs 1	~0%	T+1	`@openagentpay/adapter-upi`
Credits	$0.001	$0	Instant	`@openagentpay/adapter-credits`

UPI Reserve Pay (agentic payments)

OpenAgentPay supports NPCI's UPI Reserve Pay (SBMD — Single Block Multi Debit), the UPI-native framework for AI agent payments:

import { UPIReservePayManager } from '@openagentpay/adapter-upi';

const reservePay = new UPIReservePayManager({
  gateway: 'razorpay',
  apiKey: 'rzp_live_...',
  apiSecret: 'secret_...',
});

// Agent authorizes a Rs 5,000 spending limit (90-day max)
const block = await reservePay.createBlock({
  payerIdentifier: 'agent-1',
  amount: 500_000,       // Rs 5,000 in paise
  description: 'API usage budget',
  expiryDays: 30,
});
// → { blockId, authUrl, expiresAt }

// After user authorizes via UPI app, debit freely without PIN/OTP
const debit = await reservePay.executeDebit(block.blockId, 1000, 'API call');
// → { transactionId, amount: 1000, remainingAmount: 499000 }

Razorpay MCP server integration for AI agent frameworks:

import { createRazorpayMCP } from '@openagentpay/razorpay-mcp';

const rzp = createRazorpayMCP({
  apiKeyId: 'rzp_live_...',
  apiKeySecret: 'secret_...',
});

// Use Razorpay's 48+ MCP tools
const link = await rzp.tools.createPaymentLink({
  amount: 50000, currency: 'INR',
  description: 'API credits', upiLink: true,
});

// Verify payment
const payment = await rzp.verifyPayment('pay_...', '500.00');

MCP tool monetization

// Server: charge per MCP tool invocation
import { paidTool } from '@openagentpay/mcp';

const search = paidTool({
  price: '0.01',
  adapters: [mpp({ ... }), x402({ ... })],
  recipient: '0x...',
}, async (params) => {
  return { results: await engine.search(params.query) };
});

Bridge MCP tools with MPP for discovery and payment:

import { createBridge, createDiscovery } from '@openagentpay/mcp-mpp';

const bridge = createBridge({
  recipient: '0x...',
  mppConfig: { networks: ['tempo', 'stripe'] },
  defaultPricing: { amount: '0.01', currency: 'USD' },
});

bridge.registerTool('search', schema, handler, { amount: '0.02', currency: 'USD' });
const catalog = createDiscovery(bridge).describeTools();
// → JSON-LD catalog of paid tools with pricing

Agent identity and compliance

Verifiable agent identity via DIDs and Ed25519 attestations:

import { AgentIdentityManager } from '@openagentpay/vault';

const identity = new AgentIdentityManager({
  privateKey: '0xabc...',  // Ed25519 seed
  label: 'my-agent',
});

const did = identity.getDID();           // did:key:z6Mk...
const attestation = identity.createAttestation(
  did, 'payment-authorization',
  { maxSpend: '100.00', allowedDomains: ['api.example.com'] }
);

// KYA (Know Your Agent) compliance profile
const kya = identity.buildKYAProfile('MyAgent', 'MyCompany', ['payments', 'data-access']);

CLI tool

# Probe an endpoint for pricing
agentpay probe https://api.example.com/data

# Discover payment capabilities
agentpay discover https://api.example.com

# Simulate 100 requests and see stats
agentpay simulate https://api.example.com/data --count 100

# Parse a receipt
agentpay receipt ./receipt.json

Getting paid

OpenAgentPay is not a payment processor. Money flows directly from agent to API owner through the payment rail:

x402: USDC to your wallet on Base
MPP: settlement via Tempo/Stripe depending on network
Solana: SPL tokens to your Solana address
Lightning: sats to your Lightning node
Stripe/PayPal: settlement to your Stripe/PayPal account
UPI: settlement to your bank account (T+1 via NPCI)
Credits: you already hold the money (prepaid)

See Getting Paid Guide and Fiat Payment Methods.

Deployment options

Express / Node.js

import { createPaywall } from '@openagentpay/server-express';

Hono (Bun, Deno, Node.js)

import { createPaywall } from '@openagentpay/server-hono';

Cloudflare Workers

import { createPaywallHandler } from '@openagentpay/server-cloudflare';

export default {
  fetch: createPaywallHandler({
    pricing: { amount: '0.01', currency: 'USD' },
    recipient: '0x...',
    adapters: [mpp({ ... })],
  }, {
    handler: async (request) => new Response('Premium data'),
  }),
};

Zero-code proxy

import { createProxy } from '@openagentpay/proxy';
const proxy = createProxy({ upstream: 'https://your-api.com', ... });
await proxy.start(3000);

Examples

cd examples/paid-weather-api && pnpm start    # API with pricing + subscriptions
cd examples/agent-client && pnpm start         # Agent with policy engine (optional client)
cd examples/end-to-end-demo && pnpm start      # Full flow in one script

Documentation

Guide	Covers
Getting Started	Install, server setup, optional client setup
Concepts	402 flow, adapters, policy, receipts
Smart Router	14 strategies, health tracking, cascade, cost estimation
Server SDK	Middleware, pricing, subscriptions, events
Client SDK	Optional agent-side client for policy + multi-method
Payment Adapters	All 10 adapters + custom adapter guide
MPP Integration	MPP protocol, sessions, streaming, IETF Payment auth
Visa Integration	Visa MCP, AgentCard
Fiat Methods	Stripe/PayPal/UPI architecture + fees
Getting Paid	Wallet setup, fiat conversion, tax
Policy Engine	12 rules, domain globs, identity, spend tracking
Receipts	Storage, querying, export
MCP Tools	Paid MCP tools, MCP-MPP bridge

Specifications

402 Response Format — machine-readable pricing
Agent Payment Receipt — structured audit record

Development

git clone https://github.com/alokemajumder/OpenAgentPay.git
cd OpenAgentPay
pnpm install && pnpm build && pnpm test

26 packages · 155 TypeScript source files · 68,000+ lines · 264 tests TypeScript · Turborepo · pnpm · Biome · Vitest · Apache 2.0

Contributing

CONTRIBUTING.md · SECURITY.md · CODE_OF_CONDUCT.md