@solana/mpp

Solana payment method for the Machine Payments Protocol.

MPP is an open protocol proposal that lets any HTTP API accept payments using the 402 Payment Required flow.

[!IMPORTANT] This repository is under active development. The Solana MPP spec is not yet finalized — APIs and wire formats are subject to change.

SDK Implementations

The Solana MPP SDK is available in 5 languages. Every implementation follows the same protocol and is tested for cross-language interoperability.

Testing

Every implementation is validated at three levels:

1. Unit tests — each SDK has its own test suite with coverage enforcement
2. E2E payment tests — Playwright browser tests verify the full payment link flow (wallet → transaction → service worker → on-chain verification) against Surfpool
3. Cross-language interop — a shared Python test suite runs the same protocol conformance tests against every server implementation, proving that any client can pay any server

The interop matrix tests every client against every server. A shared Python test suite builds real Solana transactions and submits them to each server, verifying on-chain settlement via Surfpool. This catches protocol divergences that per-language unit tests miss.

          Clients                          Servers
   ┌────────────────┐              ┌────────────────────┐
   │  TypeScript    │──────┐       │  TypeScript :3000   │
   │  Rust          │──────┤       │  Rust       :3001   │
   │  Go            │──────┼──────▶│  Go         :3002   │
   │  Python        │──────┤       │  Lua        :3003   │
   └────────────────┘      │       │  Python     :3004   │
                           │       └─────────┬──────────┘
                           │                 │
                           │          ┌──────┴───────┐
                           └─────────▶│   Surfpool   │
                                      │    :8899     │
                                      └──────────────┘

Coverage

Language	Coverage	Tests
TypeScript		just ts-test
Rust		just rs-test
Go		just go-test
Python		just py-test
Lua		just lua-test
Interop		pytest tests/interop/

Install

# TypeScript
pnpm add @solana/mpp

# Rust
cargo add solana-mpp

# Go
go get github.com/solana-foundation/mpp-sdk/go

# Python
pip install solana-mpp

Quick Start

Server (charge)

import { Mppx, solana } from '@solana/mpp/server'

const mppx = Mppx.create({
  secretKey: process.env.MPP_SECRET_KEY,
  methods: [
    solana.charge({
      recipient: 'RecipientPubkey...',
      currency: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
      decimals: 6,
      html: true, // enables payment links for browsers
    }),
  ],
})

const result = await mppx.charge({
  amount: '1000000',
  currency: 'USDC',
})(request)

if (result.status === 402) return result.challenge
return result.withReceipt(Response.json({ data: '...' }))

from solana_mpp.server import Mpp, Config

mpp = Mpp(Config(
    recipient="RecipientPubkey...",
    currency="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    decimals=6,
    html=True,
))

challenge = mpp.charge("1.00")  # 1 USDC
receipt = await mpp.verify_credential(credential)

import "github.com/solana-foundation/mpp-sdk/go/server"

m, _ := server.New(server.Config{
    Recipient: "RecipientPubkey...",
    Currency:  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    Decimals:  6,
    HTML:      true,
})

challenge, _ := m.Charge(ctx, "1.00")
receipt, _ := m.VerifyCredential(ctx, credential)

use solana_mpp::server::{Config, Mpp};

let mpp = Mpp::new(Config {
    recipient: "RecipientPubkey...".into(),
    currency: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v".into(),
    decimals: 6,
    html: true,
    ..Default::default()
})?;

let challenge = mpp.charge("1.00")?;
let receipt = mpp.verify_credential(&credential).await?;

Payment Links

Set html: true on solana.charge() and any endpoint becomes a shareable payment link. Browsers see a payment page; API clients get the standard 402 flow.

Open http://localhost:3000/api/v1/fortune in a browser
→ Payment page with "Continue with Solana" button
→ Click → wallet signs → transaction confirmed on-chain
→ Page reloads with the paid content

See the payment links guide for framework-specific setup.

Fee Sponsorship

The server can pay transaction fees on behalf of clients:

solana.charge({
  recipient: '...',
  signer: feePayerSigner, // KeyPairSigner, Keychain SolanaSigner, etc.
})

Split Payments

Send one charge to multiple recipients in the same asset:

solana.charge({
  recipient: 'SellerPubkey...',
  currency: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  decimals: 6,
  splits: [
    { recipient: 'PlatformPubkey...', amount: '50000', memo: 'platform fee' },
    { recipient: 'ReferrerPubkey...', amount: '20000', memo: 'referral fee' },
  ],
})

Demo

An interactive playground with a React frontend and Express backend, running against Surfpool.

surfpool start
pnpm demo:install
pnpm demo:server
pnpm demo:app

See demo/README.md for full details.

Development

just build            # Build all SDKs (html → ts → rust → go)
just test             # Test all SDKs
just pre-commit       # Full pre-commit checks

# Per-language
just ts-test          # TypeScript tests
just rs-test          # Rust tests
just go-test          # Go tests
just py-test          # Python tests
just lua-test         # Lua tests

# Integration
just html-build       # Build payment link assets
just html-test-e2e    # Playwright E2E tests

Spec

This SDK implements the Solana Charge Intent for the HTTP Payment Authentication Scheme.

License

MIT