Algorand MPP SDK

Machine Payments Protocol (MPP) for Algorand — HTTP-native micropayments using 402 Payment Required.

Try it live: https://mpp.goplausible.xyz (TestNet)

What is MPP?

The Machine Payments Protocol (MPP) enables any HTTP API to charge for access using standard HTTP headers. When a client requests a paid resource, the server responds with 402 Payment Required and a payment challenge. The client pays on-chain, retries the request with proof of payment, and receives the resource.

MPP is designed for machine-to-machine payments — AI agents, automated systems, and applications that consume paid APIs without human intervention.

What is the Algorand MPP SDK?

This SDK implements MPP for the Algorand blockchain, supporting:

• Native ALGO payments and ASA payments (USDC, etc.)
• Fee sponsorship — server pays transaction fees on behalf of clients
• Lease-based mutual exclusion — protocol-level challenge binding that ensures TxID uniqueness across charges and prevents double-settlement
• Server-broadcast — server broadcasts transactions

Built on @algorandfoundation/algokit-utils v10 (no algosdk dependency) and the mppx protocol library.

Documentation

| Document | Description | |----------|-------------| | Documentation Index | Full documentation table of contents | | What is MPP? | Protocol overview and comparison with traditional payments | | Algorand Charge Spec | Algorand-specific charge method specification | | Architecture | SDK modules, entry points, and design decisions | | Payment Flows | Sequence diagrams for all payment modes | | Demo Guide | Demo app features, scenarios, and walkthrough | | Demo README | Demo quick start, configuration, and API reference | | Cloudflare Demo Guide | Cloudflare Workers deployment — architecture, config, and differences from the Express demo | | Cloudflare Demo README | Cloudflare Workers demo setup, wrangler.toml, and deployment | | Full Specification | Complete IETF-style specification |

Installation

npm install @goplausible/algorand-mpp-sdk mppx
# or
pnpm add @goplausible/algorand-mpp-sdk mppx

Quick Start

Server (Express)

import express from 'express'
import { Mppx, algorand } from '@goplausible/algorand-mpp-sdk/server'

const mppx = Mppx.create({
  secretKey: process.env.MPP_SECRET_KEY,
  methods: [
    algorand.charge({
      recipient: 'YOUR_ALGO_ADDRESS',
      network: 'algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=',
      algodUrl: 'https://testnet-api.4160.nodely.dev',
    }),
  ],
})

const app = express()

app.get('/api/data', async (req, res) => {
  const webReq = toWebRequest(req) // convert Express req to Web Request
  const result = await mppx.charge({
    amount: '10000',       // 0.01 ALGO
    currency: 'ALGO',
    description: 'API data access',
  })(webReq)

  if (result.status === 402) {
    const challenge = result.challenge as Response
    res.writeHead(challenge.status, Object.fromEntries(challenge.headers))
    res.end(await challenge.text())
    return
  }

  const response = result.withReceipt(Response.json({ data: '...' })) as Response
  res.writeHead(response.status, Object.fromEntries(response.headers))
  res.end(await response.text())
})

Client (Browser with use-wallet)

import { Mppx, algorand } from '@goplausible/algorand-mpp-sdk/client'

// signTransactions from @txnlab/use-wallet
const method = algorand.charge({
  signer: signTransactions,
  senderAddress: activeAccount.address,
  algodUrl: 'https://testnet-api.4160.nodely.dev',
})

const mppx = Mppx.create({ methods: [method] })

// Automatically handles 402 → pay → retry
const response = await mppx.fetch('https://api.example.com/api/data')
const data = await response.json()

Server with Fee Sponsorship + USDC

algorand.charge({
  recipient: 'SELLER_ADDRESS',
  network: 'algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=',
  algodUrl: 'https://testnet-api.4160.nodely.dev',
  // ASA payment (USDC)
  asaId: 10458941n,
  // Fee sponsorship
  signer: feePayerSigner,
  signerAddress: 'FEE_PAYER_ADDRESS',
})

Development

Prerequisites

• Node.js >= 18
• pnpm >= 10

Setup

git clone https://github.com/GoPlausible/algorand-mpp-sdk.git
cd algorand-mpp-sdk
pnpm install

Build

pnpm build          # Build the SDK (TypeScript → dist/)

Test

pnpm test           # Run unit tests
pnpm test:watch     # Watch mode
pnpm test:all       # Unit + integration tests

Lint & Format

pnpm lint           # Check for lint errors
pnpm lint:fix       # Auto-fix lint errors
pnpm format         # Format code with Prettier
pnpm typecheck      # Type-check without emitting

Running the Demo

The demo includes a paid API server and a React frontend for interactive testing.

Setup

pnpm build              # Build the SDK first
pnpm demo:install       # Install demo dependencies

# Configure environment
cp demo/server/.env-local demo/server/.env   # Edit with your values
cp demo/app/.env-local demo/app/.env         # Edit with your values

Development (hot reload)

pnpm demo:dev           # Runs server (port 3000) + app (port 5173)

Production

pnpm demo:build         # Build server + app
pnpm demo:start         # Start production server

Cloudflare Workers Demo

An alternative deployment that runs the same endpoints as a single Cloudflare Worker (API + SPA together, no separate server process). Useful for edge deployment or when you want one-command deploys via wrangler.

pnpm build              # Build the SDK first
pnpm demo:cf:install    # Install CF demo dependencies
pnpm demo:cf:dev        # Local dev via wrangler (port 8787)
pnpm demo:cf:build      # Build SPA + wrangler dry-run
pnpm demo:cf:deploy     # Deploy to your Cloudflare account

Configure wrangler.toml vars and secrets (MPP_SECRET_KEY, optional FEE_PAYER_KEY) before deploying — see the Cloudflare Demo Guide for architecture and full setup, or the in-tree README for CLI-level reference.

Demo Endpoints

| Method | Path | Cost | Description | |--------|------|------|-------------| | GET | /api/v1/weather/:city | 0.01 ALGO | Weather data (native ALGO payment) | | GET | /api/v1/marketplace/products | Free | List marketplace products | | GET | /api/v1/marketplace/buy/:id | 0.10-0.17 USDC | Marketplace purchase (USDC payment) | | GET | /api/v1/health | Free | Server status and configuration |

Getting TestNet Funds

1. ALGO — Lora TestNet Faucet
2. USDC — Circle Faucet (select Algorand TestNet)
3. Opt-in to USDC — Add ASA ID 10458941 via your wallet

Project Structure

algorand-mpp-sdk/
├── sdk/src/                # SDK source code
│   ├── client/             # Client-side charge (browser/Node)
│   ├── server/             # Server-side charge (verify, sign, broadcast)
│   ├── utils/              # Transaction building and encoding
│   ├── Methods.ts          # Shared charge method schema
│   └── constants.ts        # Network IDs, algod URLs
├── demo/
│   ├── server/             # Express demo server
│   └── app/                # React + Vite demo frontend
├── demo-cloudflare/        # Cloudflare Workers demo (single-worker API + SPA)
├── docs/                   # Documentation
├── specs/                  # Algorand charge specification
├── dist/                   # Built SDK output
└── package.json

License

MIT

Links

• GoPlausible
• MPP Protocol
• Algorand
• AlgoKit Utils