mpp-client-fetch

MPP Client — mppx.fetch()

Before writing code

Fetch live docs:

1. Fetch https://www.npmjs.com/package/mppx for the current client API and wallet configuration
2. Web-search mppx client fetch payment wallet configuration for client-side setup patterns
3. Web-search site:github.com stripe-samples machine-payments client for official client sample code
4. Fetch https://mpp.dev/overview for the client-side protocol flow description

Conceptual Architecture

What mppx.fetch() Does

mppx.fetch() is a drop-in replacement for the standard fetch() API that transparently handles the full HTTP 402 payment flow:

1. Request — Client sends a normal HTTP request
2. 402 Detection — If server responds with 402, the client parses the WWW-Authenticate: Payment challenge
3. Payment Fulfillment — Client automatically pays using the configured wallet/payment method
4. Credential Submission — Client retries the request with Authorization: Payment credential
5. Receipt Capture — Client captures the Payment-Receipt header from the response
6. Transparent Return — Returns the final 200 response as if the payment never happened

The developer's code sees only the final successful response — all payment negotiation is handled internally.

Client Configuration

import { mppx } from 'mppx/client';

// Configure once
const client = mppx.create({
  wallet: {
    privateKey: process.env.WALLET_PRIVATE_KEY,  // For Tempo/crypto payments
  },
  // OR for Stripe SPT payments:
  stripe: {
    sharedPaymentToken: sptToken,  // Obtained from SPT provisioning
  },
});

// Use like fetch()
const response = await client.fetch('https://api.example.com/paid-resource');
const data = await response.json();

Payment Method Selection

When a server supports multiple payment methods, the client selects based on:

• Configured wallet capabilities
• Method preference order
• Available balance (for crypto methods)
• SPT availability (for Stripe methods)

Spending Controls

Clients should implement spending controls:

• Per-request limit — Maximum amount for a single payment
• Session budget — Maximum total spend per session
• Daily/hourly caps — Rate-based spending limits
• Allowlisted domains — Only pay specific services

Receipt Handling

After a successful payment, the Payment-Receipt header contains:

• Payment status
• Method used
• Timestamp
• Reference identifier

Clients should log receipts for accounting and dispute resolution.

Error Handling

| Scenario | Behavior | |----------|----------| | Insufficient balance | Throw error with details | | Unsupported payment method | Throw error listing supported methods | | Challenge expired | Retry with fresh request | | Network error during payment | Do not retry payment (risk of double-pay) | | Server returns non-402 error | Pass through as normal fetch error |

CLI Usage

The mppx CLI provides a quick way to test payments:

npx mppx https://api.example.com/paid-resource

Multi-Method Client

A client can be configured with multiple payment methods:

const client = mppx.create({
  methods: [
    { type: 'tempo', wallet: { privateKey: process.env.WALLET_KEY } },
    { type: 'stripe', spt: { token: sptToken } },
  ],
  preference: ['tempo', 'stripe'],  // Try Tempo first, fall back to Stripe
});

Best Practices

• Never hardcode wallet private keys or SPTs — use environment variables
• Implement spending limits to prevent runaway costs
• Log all payments with amounts and service URLs for auditing
• Handle payment failures gracefully — distinguish between "can't pay" and "won't pay"
• Cache successful payment sessions where the protocol supports it
• Implement circuit breakers for services that consistently fail

Fetch the latest mppx client documentation for exact configuration options, wallet setup, and error types before implementing.