MPP Session Payments

The Machine Payment Protocol (MPP) enables session-based micropayments on Tempo. Unlike x402 where each API call is a separate payment, MPP opens a session with a deposit budget. Your agent makes multiple requests against that budget and the session settles when done. This guide is a walkthrough. For the endpoint reference (request/response shapes, scopes, error codes), see SDK > MPP payments.

Prerequisites

An active agent with an SDK key (Quickstart)

A funded Tempo wallet with pathUSD on testnet/demo flows or USDC.e on mainnet

An MPP-enabled service to call (or use the examples below to simulate)

MPP vs x402

	x402	MPP
Payment model	Pay-per-request	Session with deposit
Best for	Occasional API calls	Streaming, multi-request workflows
Chain	Base (USDC), Tempo (USDC.e on mainnet / pathUSD on testnet)	Tempo (USDC.e on mainnet / pathUSD on testnet)
Settlement	Immediate per call	On session close
Unused funds	N/A	Returned to agent

Use x402 when each API call is independent. Use MPP when your agent will make many requests to the same service in a session (e.g., streaming data, iterative processing, chat APIs).

How MPP Works

Pre-authorize  →  Open session (deposit)  →  Make requests  →  Close session  →  Settle

Step	What happens
1	Agent calls an MPP-enabled service, gets a 402 challenge
2	Agent pre-authorizes the session deposit through Conto policies
3	Agent opens a session with a deposit budget
4	Agent makes requests, each consumes part of the deposit
5	Session closes, unused deposit is returned
6	Agent records the final settled amount in Conto

Step 1: Set Up MPP Policies

Create the policy

Go to Policies → New Policy.

Field	Value
Name	MPP Session Guardrails
Policy Type	COMPOSITE

Add rules

Rule 1: Cap session deposit

Field	Value
Rule Type	MPP_MAX_SESSION_DEPOSIT
Operator	LTE
Value	25
Action	ALLOW

No single session can have a deposit greater than $25.Rule 2: Cap per-request charge

Field	Value
Rule Type	MPP_MAX_PER_REQUEST
Operator	LTE
Value	1.00
Action	ALLOW

No individual request within a session can charge more than $1.00.Rule 3: Limit concurrent sessions

Field	Value
Rule Type	MPP_MAX_CONCURRENT_SESSIONS
Operator	LTE
Value	3
Action	ALLOW

Agent can have at most 3 open sessions at once.

Assign to agent

Go to the agent’s Permissions tab and assign the policy.

Step 2: Pre-Authorize the Session

When your agent needs to open an MPP session, first check policies with POST /api/sdk/mpp/pre-authorize, sending the deposit amount and "intent": "session". Conto evaluates your MPP policies plus your general spend limits and responds one of two ways:

Authorized: the response includes the wallet to use. Proceed to open the session with the MPP-enabled service.
Denied: the response lists the violated rules. The agent should either request a smaller session or escalate.

See Pre-Authorization in the SDK reference for the full request and response shapes.

Step 3: Open the Session

After Conto authorizes, open the MPP session with the service. The session deposit is locked onchain:

// Using Sponge MCP or your MPP client
const session = await mppClient.openSession({
  serviceUrl: 'https://api.service.com/stream',
  maxDeposit: '10.00',
  walletAddress: auth.wallet.address,
});

console.log('Session ID:', session.sessionId);
// Session ID: mpp_session_xyz

The deposit ($10 in this case) is committed. The agent can now make requests up to this amount.

Step 4: Make Requests

Each request to the MPP service consumes part of the deposit:

// Request 1: $0.50 charge
const result1 = await mppClient.request({
  sessionId: session.sessionId,
  url: 'https://api.service.com/stream/query',
  body: { query: 'market analysis for AAPL' },
});
// Remaining deposit: $9.50

// Request 2: $0.75 charge
const result2 = await mppClient.request({
  sessionId: session.sessionId,
  url: 'https://api.service.com/stream/summarize',
  body: { text: result1.data },
});
// Remaining deposit: $8.75

The service tracks charges against the session deposit. No additional onchain transactions happen during the session, settlement occurs on close.

Step 5: Close and Settle

When your agent is done, close the session. Unused deposit is returned:

const settlement = await mppClient.closeSession({
  sessionId: session.sessionId,
});

console.log('Total charged:', settlement.totalCharged);  // $1.25
console.log('Returned:', settlement.returned);            // $8.75
console.log('TX Hash:', settlement.transactionHash);

Session Summary	Amount
Initial deposit	$10.00
Total charged	$1.25
Returned to agent	$8.75

Step 6: Record in Conto

Record the settled amount with POST /api/sdk/mpp/record, including the settlement txHash and the sessionId, so Conto can track spending. See Recording Transactions in the SDK reference for the request shape, including per-call batchItems.

Record the settled amount (

1.25), not the deposit amount (

10.00). The settled amount is what was actually charged. Recording the deposit would overcount spending against your budgets.

Step 7: Monitor Spending

Check remaining MPP budget with GET /api/sdk/mpp/budget and list the MPP services your agent has used via GET /api/sdk/mpp/services. See Budget Tracking and Querying Services for details, including session-scoped budget views.

Dashboard

Go to Analytics to see MPP-specific metrics: session frequency, average session cost, per-service breakdown, and deposit utilization (how much of each deposit is actually used).

Full Integration Example

Complete TypeScript flow for an MPP session: The TypeScript SDK currently exposes standard payment helpers. For MPP flows, call the SDK REST endpoints directly. This example reuses the postConto helper and PreAuthorizeResponse type from the x402 guide’s integration example:

async function runMppSession(serviceUrl: string, queries: string[]) {
  // 1. Pre-authorize with Conto
  const auth = await postConto<PreAuthorizeResponse>('/api/sdk/mpp/pre-authorize', {
    amount: 10.00,
    recipientAddress: '0xServiceAddress',
    resourceUrl: serviceUrl,
    intent: 'session',
    depositAmount: 10.00,
  });

  if (!auth.authorized || !auth.wallet) {
    throw new Error(`MPP denied: ${auth.reasons.join(', ')}`);
  }

  // 2. Open session
  const session = await mppClient.openSession({
    serviceUrl,
    maxDeposit: '10.00',
  });

  // 3. Make requests
  const results = [];
  for (const query of queries) {
    const result = await mppClient.request({
      sessionId: session.sessionId,
      url: `${serviceUrl}/query`,
      body: { query },
    });
    results.push(result.data);
  }

  // 4. Close and settle
  const settlement = await mppClient.closeSession({
    sessionId: session.sessionId,
  });

  // 5. Record in Conto
  await postConto('/api/sdk/mpp/record', {
    amount: settlement.totalCharged,
    recipientAddress: '0xServiceAddress',
    txHash: settlement.transactionHash,
    resourceUrl: serviceUrl,
    sessionId: session.sessionId,
    scheme: 'mpp',
    walletId: auth.wallet.id,
    chainId: auth.wallet.chainId,
  });

  return { results, cost: settlement.totalCharged };
}

MPP Policy Reference

The complete list of MPP rule types, value formats, and operators lives in Advanced Policies > MPP Protocol Rules.

Troubleshooting

Pre-authorize denied, 'exceeds concurrent session limit'

Your agent has too many open sessions. Close existing sessions before opening new ones, or increase the MPP_MAX_CONCURRENT_SESSIONS limit in your policy.

Session deposit higher than wallet balance

The deposit is locked onchain when the session opens. If your wallet has

15 and you try to open a

20 session, it fails. Check your wallet balance and request a smaller deposit.

Settled amount doesn't match expected charges

The service determines final settlement. If charges seem wrong, check the session details with the service provider. Conto records whatever you report. Make sure you’re recording the settlement amount from the close response.

MPP only works on Tempo, can I use it on Base?

MPP is currently supported only on the Tempo blockchain (see Supported Chain for chain IDs, currencies, and explorers). For paid APIs on Base or Ethereum, use the x402 protocol instead.

Next Steps

x402 Payments

Per-request API payments on Base and Tempo

MPP SDK Reference

Full API reference for MPP endpoints

Advanced Policies

All MPP policy rule types and value formats

Recipes

Copy-paste MPP recipes

​MPP Session Payments

​Prerequisites

​MPP vs x402

​How MPP Works

​Step 1: Set Up MPP Policies

​Step 2: Pre-Authorize the Session

​Step 3: Open the Session

​Step 4: Make Requests

​Step 5: Close and Settle

​Step 6: Record in Conto

​Step 7: Monitor Spending

​Dashboard

​Full Integration Example

​MPP Policy Reference

​Troubleshooting

​Next Steps

x402 Payments

MPP SDK Reference

Advanced Policies

Recipes

MPP Session Payments

Prerequisites

MPP vs x402

How MPP Works

Step 1: Set Up MPP Policies

Step 2: Pre-Authorize the Session

Step 3: Open the Session

Step 4: Make Requests

Step 5: Close and Settle

Step 6: Record in Conto

Step 7: Monitor Spending

Dashboard

Full Integration Example

MPP Policy Reference

Troubleshooting

Next Steps