Pay with MPP sessions

Pre-authorize  →  Open session (deposit)  →  Make requests  →  Close session  →  Record in Conto

import { randomUUID } from 'node:crypto';
import { Conto } from '@conto_finance/sdk';

const conto = new Conto({ apiKey: process.env.CONTO_API_KEY! });

// Your MPP client library. Conto does not provide one.
declare const mppClient: {
  // Reads the service's 402 session challenge.
  getChallenge(url: string): Promise<{ id: string; recipient: string }>;
  openSession(input: { url: string; deposit: string }): Promise<{ channelId: string }>;
  request(input: { channelId: string; url: string; body: unknown }): Promise<{ data: unknown }>;
  // Resolves with the total the service charged, in dollars.
  closeSession(input: { channelId: string }): Promise<{ charged: number }>;
};

const DEPOSIT = 10;

async function runMppSession(serviceUrl: string, queries: string[]) {
  const sessionId = randomUUID(); // your ID for this session in Conto
  const challenge = await mppClient.getChallenge(serviceUrl);

  // 1. Check the session deposit against your Conto policies
  const auth = await conto.mpp.preAuthorize({
    amount: DEPOSIT,
    depositAmount: DEPOSIT,
    intent: 'session',
    sessionId,
    challengeId: challenge.id,
    recipientAddress: challenge.recipient,
    resourceUrl: serviceUrl,
  });
  if (!auth.authorized) {
    throw new Error(`${auth.decision}: ${auth.reasons?.join(' ') ?? auth.message}`);
  }

  // 2. Open the session, make requests, and close it
  const session = await mppClient.openSession({ url: serviceUrl, deposit: DEPOSIT.toFixed(2) });
  const results: unknown[] = [];
  for (const query of queries) {
    const result = await mppClient.request({
      channelId: session.channelId,
      url: `${serviceUrl}/query`,
      body: { query },
    });
    results.push(result.data);
  }
  const { charged } = await mppClient.closeSession({ channelId: session.channelId });

  // 3. Record the charged amount (0 when nothing was charged) before auth.grantExpiresAt and
  // close the session.
  // No txHash: the service settles a session from the Tempo escrow channel.
  await conto.mpp.record({
    amount: charged,
    recipientAddress: challenge.recipient,
    resourceUrl: serviceUrl,
    credentialId: session.channelId,
    intent: 'session',
    depositAmount: DEPOSIT,
    sessionId,
    challengeId: challenge.id,
    grantId: auth.grantId,
    grantSignature: auth.grantSignature,
    closeSession: true,
  });

  return { results, charged };
}

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"
  }'

{
  "authorized": true,
  "decision": "approved",
  "message": "Payment is approved.",
  "grantId": "cmm59z8fj000l49h7bjqza11p",
  "grantSignature": "pg1.3kq...",
  "grantExpiresAt": "2026-09-18T12:10:00.000Z",
  "mpp": {
    "serviceDomain": "api.service.com",
    "amount": 10.0
  }
}

{
  "authorized": false,
  "decision": "declined",
  "message": "Payment was declined by your controls.",
  "reasons": ["This payment exceeds a configured spending limit."],
  "reasonCodes": ["SPENDING_LIMIT"],
  "mpp": {
    "serviceDomain": "api.service.com",
    "amount": 10.0
  }
}

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",
    "resourceUrl": "https://api.service.com/stream",
    "credentialId": "cred_01J...",
    "sessionId": "stream-session-42",
    "scheme": "tempo",
    "challengeId": "challenge_01J...",
    "paymentMethod": "tempo",
    "intent": "session",
    "depositAmount": 10.00,
    "paymentReceipt": "eyJzdGF0dXMiOiJzdWNjZXNzIiw...",
    "grantId": "cmm59z8fj000l49h7bjqza11p",
    "grantSignature": "pg1.3kq...",
    "context": {
      "department": "engineering",
      "project": "streaming"
    }
  }'

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",
    "resourceUrl": "https://api.service.com/stream",
    "credentialId": "settlement_01J...",
    "sessionId": "stream-session-42",
    "intent": "session",
    "grantId": "cmm59z8fj000l49h7bjqza11p",
    "grantSignature": "pg1.3kq...",
    "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" }
    ]
  }'

GET /api/sdk/mpp/services?period=7d&limit=50

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