Core Concepts — MPPPal Docs

Operators and agents

MPPPal has two types of principals:

Principal	What they are	What they control
Operator	The human or organization deploying AI agents. Authenticates via OAuth2 and the dashboard.	Wallet provisioning, spending policy configuration, account pause/freeze, API key management.
Agent	The autonomous AI process running in production. Authenticates via a scoped API key.	Initiating transfers, opening MPP sessions, querying balance, reading transaction history — within policy limits.

The design principle: operators govern, agents operate. Agents never touch policy. Operators never need to approve individual transactions.

Wallets

An agent wallet is the core resource in MPPPal. Each wallet consists of:

A Program Derived Address (PDA) on Solana — the on-chain identity, controlled by the MPPPal program
A USDC SPL token account — where the actual USDC balance lives
A spending policy state — rules stored in the PDA that govern what payments are permitted
A human-readable handle — e.g. @research-agent.mpppal for discovery and memos
A transaction nonce — prevents replay attacks

Wallets are many-to-one with operators. One operator can provision hundreds or thousands of agent wallets, each with independent policies.

Machine Payments Protocol (MPP)

MPPPal is built on the Machine Payments Protocol — an open HTTP 402-based standard that defines how internet clients and servers negotiate and settle payments programmatically. Understanding MPP is essential to understanding how MPPPal works.

The core HTTP flow:

Request — agent calls a paid service endpoint
Challenge — service returns HTTP 402 with WWW-Authenticate: Payment header containing payment terms
Payment — MPPPal SDK signs a payment credential against the agent's wallet
Fulfillment — SDK retries the request with Authorization: Payment header
Receipt — service returns the resource plus a Payment-Receipt header
Settlement — receipts are batch-settled on Solana at regular intervals

Steps 3–5 happen in milliseconds, transparent to the agent's application logic. See MPP Protocol for the full technical reference.

Payment intents

MPP defines two production payment intents. MPPPal supports both:

Intent	When to use	Settlement
Charge	One-time per-request payment. Best for infrequent, higher-value calls.	Immediate on-chain settlement per payment.
Session	Streaming micropayments to the same service. Best for agents making hundreds of calls per hour.	Off-chain micropayment stream; batched into a single on-chain settlement when the session closes.

Sessions

A session is MPP's mechanism for high-frequency agent activity. Rather than settling each micropayment individually on-chain, the agent pre-authorizes a spending cap once (opening a "tab"). Payments flow off-chain continuously. When the session closes — by timeout or explicit close — the net amount settles in a single Solana transaction.

Session lifecycle:

Open — agent authorizes a spending cap. Funds are locked in an on-chain escrow PDA.
Stream — micropayments flow off-chain at each interaction. Running total tracked off-chain by MPPPal.
Close / Settle — at session end, net amount settles on Solana. Unused locked funds are returned to the wallet.

An agent making 500 inference calls at $0.002 each produces one Solana transaction, not 500. The fee economics are therefore identical to a single $1 payment.

Spending policy

Spending policy is the control layer between operators and agents. Rules are stored on-chain in the wallet PDA and enforced by the MPPPal Solana program before any transfer or session opening is signed.

Policy is not backend validation — it is cryptographically enforced on-chain. A compromised MPPPal API server, a bug in the SDK, or a rogue employee cannot bypass policy rules that are enforced in the smart contract.

Parameter	Type	Description
`max_single_transfer`	USDC decimal	Maximum USDC per single transfer or session open
`max_daily_spend`	USDC decimal	Maximum USDC in any 24-hour rolling window
`allowed_counterparties`	address[]	Optional allowlist. Transfers to non-listed addresses are rejected.
`categories`	string[]	Optional category filter. Only MPP providers tagged with matching categories are payable.
`require_memo`	boolean	If true, transfers without a memo string are rejected.
`escalation_threshold`	USDC decimal	Transfers above this value require operator approval before execution.
`paused`	boolean	If true, all outbound payments from the wallet are blocked instantly.

Transfers

A direct transfer is the atomic unit of value movement outside of MPP sessions. Every transfer follows this lifecycle:

Submission — agent calls POST /v1/transfers
Policy validation — MPPPal checks the transfer against the account's on-chain spending policy
Signing — if policy passes, MPPPal signs the transaction using the account's PDA authority
Submission to Solana — signed transaction submitted to the Solana network
Finality — on-chain settlement (sub-400ms typical)
Confirmation — MPPPal returns the tx_signature and fires configured webhooks

If policy validation fails at step 2, a transfer.rejected event fires and the transfer is never submitted to Solana. Rejections are logged in the audit trail.

Idempotency

All transfers require a unique idempotency_key. If you submit the same key twice:

If the first transfer succeeded: the second request returns the original response — no double-send
If the first transfer failed: the second request retries the transfer

Keys expire after 24 hours. Use a deterministic key derived from the underlying operation — e.g., task-{id}-reward or invoice-{id}-{date}.

API keys

MPPPal issues two types of API keys:

Operator keys — full access. Can provision wallets, modify policies, and pause accounts. Issued to human operators, stored securely, rotated periodically.
Agent keys — scoped to a single wallet. Can initiate transfers, open MPP sessions, and read data for that wallet only. A leaked agent key cannot access other wallets or modify policy.

Custody modes

MPPPal supports two custody modes:

Custodial (default) — MPPPal manages the wallet's signing authority. Easiest to integrate; MPPPal signs transactions on behalf of the PDA.
Non-custodial — bring your own Solana keypair. MPPPal handles policy coordination and payment receipts but never touches private keys. The SDK signs locally using your keypair.

The human pause switch

Operators can freeze any wallet immediately by setting paused: true — via the dashboard, API, or CLI. A paused wallet submits no new transfers or sessions. In a runaway agent scenario, a single API call stops all financial activity for that wallet.

Audit trail

Every action is logged:

On-chain — all settled transfers and session settlements are permanently recorded on Solana, verifiable on Solana Explorer via the tx_signature.
Off-chain — policy checks, rejections, policy updates, operator actions, and session events are stored in a tamper-evident append-only log. Rows are never updated or deleted — only appended.