MPP (Machine Payment Protocol) Payments

Conto supports the Machine Payment Protocol (MPP) for session-based micropayments on the Tempo blockchain. MPP enables agents to open payment sessions, make incremental charges, and settle when done.

MPP endpoints enforce explicit API-key scopes. Pre-authorization requires payments:request, recording settlement requires payments:execute, and budget or service analytics require analytics:read.

How It Works

Agent opens session  →  Makes requests (charges accrue)  →  Session closes  →  Settlement

Agent calls an MPP-enabled service and receives a 402 challenge
Agent pre-authorizes the session deposit through Conto policies
Agent opens an MPP session with a deposit budget
Agent makes requests, each consuming part of the deposit
Session closes and unused deposit is returned

Pre-Authorization

Before opening an MPP session, validate against policies and budget limits:

curl -X POST https://conto.finance/api/sdk/mpp/pre-authorize \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.00,
    "recipientAddress": "0xServiceAddress",
    "resourceUrl": "https://api.service.com/stream",
    "intent": "session",
    "depositAmount": 10.00,
    "sessionId": "stream-session-42",
    "scheme": "tempo",
    "credentialId": "cred_01J...",
    "challengeId": "challenge_01J...",
    "paymentMethod": "tempo"
  }'

Conto derives serviceDomain from resourceUrl, so you do not need to send it separately. Send the scheme, credential, challenge, payment method, and stable session ID when available so MPP service, method, and session-lifecycle controls have the context they require. sessionId is required when intent is session. Response (Approved):

{
  "authorized": true,
  "decision": "approved",
  "message": "Payment is approved.",
  "mpp": {
    "serviceDomain": "api.service.com",
    "amount": 10.0
  }
}

Response (Denied):

{
  "authorized": false,
  "decision": "declined",
  "message": "Payment was declined by your controls.",
  "mpp": {
    "serviceDomain": "api.service.com",
    "amount": 10.0
  }
}

Recording Transactions

After MPP charges are settled, record them in Conto:

curl -X POST https://conto.finance/api/sdk/mpp/record \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 3.50,
    "recipientAddress": "0xServiceAddress",
    "txHash": "0xabc123...",
    "resourceUrl": "https://api.service.com/stream",
    "credentialId": "cred_01J...",
    "sessionId": "stream-session-42",
    "scheme": "tempo",
    "challengeId": "challenge_01J...",
    "paymentMethod": "tempo",
    "paymentReceipt": "eyJzdGF0dXMiOiJzdWNjZXNzIiw...",
    "context": {
      "department": "engineering",
      "project": "streaming"
    }
  }'

When paymentReceipt is supplied, Conto rejects unsuccessful or challenge-mismatched receipts with 400 and amount mismatches with 409. Because the receipt is caller supplied, passing its structural and consistency checks does not confirm settlement. Receipt-only records remain PENDING. When txHash is supplied, Conto confirms the record only after the on-chain transfer matches the wallet sender, recipient, amount, and currency; pending transfers return 409, and mismatches return 422. Reuse the same credentialId and sessionId on retries; a session ID cannot be reused by another agent. Use optional context.department and context.project values during pre-authorization and recording to apply scoped budgets. Conto persists the same dimensions on the aggregate settlement transaction. Use the flat top-level settlement fields for the aggregate payment. For multiple per-call charges, send those details in batchItems; the record endpoint does not accept a top-level payments array. If you settle multiple calls together, keep the top-level fields for the aggregate settlement and send per-call detail records in batchItems:

curl -X POST https://conto.finance/api/sdk/mpp/record \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 3.50,
    "recipientAddress": "0xServiceAddress",
    "txHash": "0xsettlement123...",
    "resourceUrl": "https://api.service.com/stream",
    "credentialId": "settlement_01J...",
    "batchItems": [
      { "amount": 1.00, "resourceUrl": "https://api.service.com/stream?chunk=1", "credentialId": "cred_1" },
      { "amount": 2.50, "resourceUrl": "https://api.service.com/stream?chunk=2", "credentialId": "cred_2" }
    ]
  }'

Querying Services

View MPP services your agent has used:

GET /api/sdk/mpp/services

Budget Tracking

Check remaining MPP budget:

GET /api/sdk/mpp/budget?sessionId=stream-session-42

The response contains the authenticated agent’s aggregate daily, weekly, and monthly spend, effective limits, and usage trend. Those periods use UTC calendar boundaries, include confirming transactions, and count each item in a recorded batch as one call. When sessionId is supplied, spend.session also reports the call count and amount recorded with that customer-defined ID.

Unified Machine Spend View

If this agent also uses x402 or multiple paid services, use the shared machine-spend endpoints for a combined view:

GET /api/sdk/service-spend/summary?protocol=mpp
GET /api/sdk/service-spend/services?protocol=mpp

See Machine Spend for the combined x402 + MPP analytics view.

MPP Policy Rules

Configure MPP-specific policies to control session-based payments. The complete list of MPP rule types, value formats, and operators lives in Advanced Policies > MPP Protocol Rules.

Supported Chain

MPP payments are supported on the Tempo blockchain, on both testnet and mainnet. The examples in this guide use Tempo Testnet.

Property	Tempo Testnet	Tempo Mainnet
Chain ID	`42431`	`4217`
Currency	`pathUSD`	`USDC.e`
Explorer	`https://explore.testnet.tempo.xyz`	`https://explore.tempo.xyz`

Next Steps

x402 Payments

HTTP 402 micropayments for APIs

Machine Spend

View unified x402 and MPP service spend

Advanced Policies

Configure MPP-specific policy rules

Start

Products

Build

Guides

Reference

Changelog

MPP Payments

MPP (Machine Payment Protocol) Payments

How It Works

Pre-Authorization

Recording Transactions

Querying Services

Budget Tracking

Unified Machine Spend View

MPP Policy Rules

Supported Chain

Next Steps

x402 Payments

Machine Spend

Advanced Policies

​MPP (Machine Payment Protocol) Payments

​How It Works

​Pre-Authorization

​Recording Transactions

​Querying Services

​Budget Tracking

​Unified Machine Spend View

​MPP Policy Rules

​Supported Chain

​Next Steps

x402 Payments

Machine Spend

Advanced Policies

MPP (Machine Payment Protocol) Payments

How It Works

Pre-Authorization

Recording Transactions

Querying Services

Budget Tracking

Unified Machine Spend View

MPP Policy Rules

Supported Chain

Next Steps