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

SDK Implementations

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

| | TypeScript | Rust | Go | Python | Lua | |---|:---:|:---:|:---:|:---:|:---:| | Package | @solana/mpp | — | — | — | — | | Server (charge) | ✅ | ✅ | ✅ | ✅ | ✅ | | Client (auto-402) | ✅ | ✅ | ✅ | ✅ | — | | Payment links | ✅ | ✅ | ✅ | ✅ | ✅ | | Fee sponsorship | ✅ | ✅ | ✅ | ✅ | ✅ | | Split payments | ✅ | ✅ | ✅ | ✅ | ✅ | | SPL tokens | ✅ | ✅ | ✅ | ✅ | ✅ | | Token-2022 | ✅ | ✅ | ✅ | ✅ | ✅ | | Replay protection | ✅ | ✅ | ✅ | ✅ | ✅ | | Session (pay-as-you-go) | — | — | — | — | — |

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 TypeScript/Vitest process harness runs language client and server adapters against Surfpool, proving that enabled clients and servers stay protocol-compatible

The interop harness can run a full client/server cross-product, but CI keeps the default matrix small and intentional: enabled clients are tested against the Rust server, and the Rust client is tested against enabled servers. The harness builds real Solana transactions and verifies on-chain settlement via Surfpool, catching 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 | | cd tests/interop && pnpm test |

See tests/interop/README.md for the process adapter contract used by the Surfpool-backed client/server matrix.

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