> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MPP Session Payments

> End-to-end walkthrough: open a session, make incremental charges, settle, and track spending with MPP

# 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](/sdk/mpp-payments).

## Prerequisites

<Check>An active agent with an SDK key ([Quickstart](/quickstart/setup))</Check>
<Check>A funded Tempo wallet with `pathUSD` on testnet/demo flows or `USDC.e` on mainnet</Check>
<Check>An MPP-enabled service to call (or use the examples below to simulate)</Check>

## 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

<Steps>
  <Step title="Create the policy">
    Go to **Policies** → **New Policy**.

    | Field       | Value                  |
    | ----------- | ---------------------- |
    | Name        | MPP Session Guardrails |
    | Policy Type | COMPOSITE              |
  </Step>

  <Step title="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.
  </Step>

  <Step title="Assign to agent">
    Go to the agent's **Permissions** tab and assign the policy.
  </Step>
</Steps>

## 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](/sdk/mpp-payments#pre-authorization) 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:

```typescript theme={null}
// 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:

```typescript theme={null}
// 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:

```typescript theme={null}
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](/sdk/mpp-payments#recording-transactions) for the request shape, including per-call `batchItems`.

<Warning>
  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.
</Warning>

## 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](/sdk/mpp-payments#budget-tracking) and [Querying Services](/sdk/mpp-payments#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](/guides/x402-api-payments#full-integration-example):

```typescript theme={null}
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](/policies/advanced#mpp-protocol-rules).

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="MPP only works on Tempo, can I use it on Base?">
    MPP is currently supported only on the Tempo blockchain (see [Supported Chain](/sdk/mpp-payments#supported-chain) for chain IDs, currencies, and explorers). For paid APIs on Base or Ethereum, use the [x402 protocol](/guides/x402-api-payments) instead.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="x402 Payments" icon="bolt" href="/guides/x402-api-payments">
    Per-request API payments on Base and Tempo
  </Card>

  <Card title="MPP SDK Reference" icon="code" href="/sdk/mpp-payments">
    Full API reference for MPP endpoints
  </Card>

  <Card title="Advanced Policies" icon="shield" href="/policies/advanced">
    All MPP policy rule types and value formats
  </Card>

  <Card title="Recipes" icon="book-open" href="/guides/recipes">
    Copy-paste MPP recipes
  </Card>
</CardGroup>