Core Concepts

Payre has six core concepts. Everything else is built on these.

Developer

The person who builds and runs an MCP server.

• Registers at console.payre.dev via GitHub OAuth
• Gets a secret key: pyr_sk_live_xxxxxxxx
• Uses the secret key in @payre/pay SDK to authorize charges
• Earns 97% of every charge made to their tools
• Views earnings, tools, and charge history in the Developer Dashboard

The secret key is like a Stripe secret key -- keep it on the server, never expose it to clients.

Consumer

The person (or AI agent) that calls your MCP tools.

• Signs up at console.payre.dev
• Gets an API key: pyr_ck_live_xxxxxxxx
• Tops up their balance via Stripe Checkout
• Passes their API key as X-Payre-Key header when calling any Payre-enabled MCP server
• One API key works across all MCP servers that use Payre

The consumer doesn't need to sign up separately for each server. One balance, one key, all servers.

Tool

A registered function on your MCP server that you want to charge for.

• Has a name (e.g. search, generate, translate)
• Has a price per call (e.g. $0.005)
• Registered either via the SDK's pricing() helper or the Dashboard

const pricing = payre.pricing({
  'search':   0.005,
  'generate': 0.02,
});

Charge

A single billing event. Created every time payre.charge() succeeds.

Field	Description
id	Unique charge ID
developerId	Who earned the money
consumerId	Who paid
tool	Which tool was called
amount	How much was charged (e.g. $0.005)
receipt	HMAC-SHA256 signed receipt
createdAt	Timestamp

The charge is atomic: balance check + deduct + record happen in one step. If the consumer's balance is insufficient, no charge is created and charge() throws.

Every charge produces an HMAC-SHA256 signed receipt -- cryptographic proof that the charge happened. You can include the receipt in your tool's response so the consumer can verify they were charged correctly.

Top Up

How consumers add money to their balance.

• Consumer clicks "Top Up" in the Dashboard
• Selects an amount ($5, $10, $25, $50, or custom)
• Redirected to Stripe Checkout
• On success, balance is credited immediately

Payout

How developers withdraw their earnings.

• Connected via Stripe Connect in Developer Settings
• Payouts processed on a regular schedule
• Minimum payout threshold: $10
• Developer receives 97% of all charges; 3% is the Payre platform fee

Key Format Reference

Key	Prefix	Owner	Usage
Developer secret key	pyr_sk_live_	Developer	Server-side SDK authentication
Consumer API key	pyr_ck_live_	Consumer	X-Payre-Key request header
Developer public key	pyr_pk_live_	Developer	Client-side identification (optional)

Next Steps

• Quick Start -- Get set up in 5 minutes
• SDK Reference -- PayrePay API details
• API Reference -- REST endpoints