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

<Note>
  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`.
</Note>

## 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,
    "sessionId": "stream-session-42"
  }'
```

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

**Response (Approved):**

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

**Response (Denied):**

```json theme={null}
{
  "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:

```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",
    "credentialId": "cred_01J...",
    "sessionId": "stream-session-42"
  }'
```

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",
    "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:

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

## Budget Tracking

Check remaining MPP budget:

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

```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.testnet.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>