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

> Machine Payment Protocol for session-based micropayments on Tempo

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

## How It Works

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

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

## Pre-Authorization

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

```bash theme={null}
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
  }'
```

Conto derives `serviceDomain` from `resourceUrl`, so you do not need to send it separately.

**Response (Approved):**

```json theme={null}
{
  "authorized": true,
  "wallet": {
    "id": "cmm5b0wal000l49h7ckrtb11p",
    "address": "0xAgentWallet",
    "chainId": "42431",
    "availableBalance": 500.0
  },
  "reasons": ["Within MPP session budget", "Service domain allowed"]
}
```

**Response (Denied):**

```json theme={null}
{
  "authorized": false,
  "error": "MPP pre-authorization denied",
  "code": "BUDGET_EXCEEDED",
  "reasons": ["MPP session deposit $10 exceeds maximum $5"],
  "violations": [
    {
      "type": "MPP_MAX_SESSION_DEPOSIT",
      "limit": 5.00,
      "current": 10.00,
      "message": "Session deposit exceeds MPP budget"
    }
  ]
}
```

## Recording Transactions

After MPP charges are settled, record them in Conto:

```bash theme={null}
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",
    "sessionId": "mpp_session_xyz",
    "scheme": "mpp",
    "walletId": "cmm5b0wal000l49h7ckrtb11p",
    "chainId": "42431"
  }'
```

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`:

```bash theme={null}
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",
    "sessionId": "mpp_session_xyz",
    "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:

```bash theme={null}
GET /api/sdk/mpp/services
```

## Budget Tracking

Check remaining MPP budget:

```bash theme={null}
GET /api/sdk/mpp/budget
```

Pass `?sessionId=...` to inspect budget consumption for a specific MPP session. Session spend is
counted from recorded MPP transactions with the same `sessionId`, not from unrelated wallet
payments.

If an agent has an active approved budget request, `/pre-authorize` returns a `budgetRequest`
snapshot and `/record` decrements the remaining budget automatically.

## Unified Machine Spend View

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

```bash theme={null}
GET /api/sdk/service-spend/summary?protocol=mpp
GET /api/sdk/service-spend/services?protocol=mpp
```

See [Machine Spend](/sdk/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](/policies/advanced#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.moderato.tempo.xyz` | `https://explore.tempo.xyz` |

## Next Steps

<CardGroup cols={2}>
  <Card title="x402 Payments" icon="bolt" href="/sdk/x402-payments">
    HTTP 402 micropayments for APIs
  </Card>

  <Card title="Machine Spend" icon="chart-line" href="/sdk/machine-spend">
    View unified x402 and MPP service spend
  </Card>

  <Card title="Advanced Policies" icon="shield" href="/policies/advanced">
    Configure MPP-specific policy rules
  </Card>
</CardGroup>