mpp-swift

The Swift SDK for the Machine Payments Protocol (MPP): pay for, and charge for, machine-to-machine API calls over HTTP 402.

MPP standardizes machine-to-machine payments using a challenge → credential → receipt flow: a server answers 402 Payment Required with a WWW-Authenticate: Payment challenge, the client replies with an Authorization: Payment credential, and the server returns the resource plus a Payment-Receipt. It works over HTTP, JSON-RPC/MCP, and WebSocket, with pluggable payment rails (Tempo, Stripe, and more).

This is the canonical Swift implementation of the protocol. The client and server are independent: a Swift client can pay any MPP server in any language, and a Swift server can charge any client.

An auto-generated code wiki is browsable at DeepWiki for a quick tour of the codebase. The official badge above keeps it auto-refreshed weekly, but it can still lag the newest modules; this README and ARCHITECTURE.md are the authoritative, current references.

Status: broad and feature-complete, released at 1.0.0, built one module at a time with a strict quality bar (spec-traced tests, cross-SDK conformance vs the reference SDKs, no flaky tests). The protocol core, body-digest, server middleware, the 402 client flow, and the EVM message-signing layer (Keccak-256, secp256k1, EIP-712 proof + session voucher) are implemented. The Tempo rail is well advanced: the zero-amount proof charge, the session-channel server (open/topUp/voucher/close), the blob-free on-chain layer (a JSON-RPC client, the escrow getChannel read, and an RPC-backed channel-state provider), and the bespoke 0x76 transaction builder (open/topUp/close, an opt-in Rust FFI to Tempo's own tempo-primitives, linking on macOS/iOS/Linux) are all in. The full write path is proven on-chain: a gated end-to-end test opens and closes a real payment channel against the live Moderato testnet. The 402 channel-payment client (TempoChannelMethod: open/voucher/topUp/close, an injected deposit policy, on-chain channel recovery, and a separate access-key signer) is in, and the whole channel rail is cross-SDK conformance-proven against the reference SDK in both directions, live on Moderato (open → voucher → close, settled on-chain). Discovery (parse + generate + validate), the 402-protected reverse proxy (MPPProxy, with a live Hummingbird binding MPPHummingbird), and the JSON-RPC / MCP binding (MPPMCP, cross-SDK conformance-proven both directions over stdio) are in. The subscription rail is in, end to end: a signed Tempo key authorization (TempoKeyAuthorization, RLP, byte-verified against the chain's own codec), the client (TempoSubscriptionMethod) and server (TempoSubscriptionVerifier, which re-encodes the expected authorization and compares so it never trusts the client decode), a SubscriptionStore with a two-phase atomic renewal engine, and a concrete on-chain renewer (TempoSubscriptionRenewer over an AccessKeyStore + the 0x76 charge builder) that settles the recurring transferWithMemo live, with fee-payer gas sponsorship so the charge fits the access key's spending limit. It is cross-SDK conformance-proven against the reference SDK in both directions (activation offline, and a recurring charge settled live on Moderato). Metered streaming is in too: a pay-as-you-go SessionStream that meters chunks against a channel over both Server-Sent Events and WebSocket frames, with cross-SDK codec parity for both, plus a live WebSocket transport (MPPWebSocket orchestration + MPPWebSocketLive swift-websocket adapters, server and client) that drives a metered session over a real socket. The Stripe rail is in (MPPStripe client + MPPStripeServer: a Shared Payment Token charge into a PaymentIntent, full Connect parity, live-verified against a real test-mode charge), and so is the x402-on-Base rail (MPPX402 / MPPX402Server: an EIP-3009 transferWithAuthorization over USDC on Base, a version-negotiated bridge between MPP and x402 for v1 and v2, and an x402-facilitator settler). A server can also render a self-contained HTML payment page (MPPHTML / MPPHTMLServer: multi-method tabs + a service worker, content-negotiated by the middleware) for a human-facing 402. Server hardening is in -- single-use replay, idempotency (409), rate limiting (429), sensitive-surface redaction, and opt-in CORS/HEAD -- alongside receipt persistence (the ReceiptStore seam), an atomic running-budget PaymentAuthorizer (BudgetAuthorizer), an mpp.dev/services directory client (ServiceDirectory), and a SwiftNIO AsyncHTTPClient transport (MPPClientAsyncHTTP) for long-lived server / Linux processes. And a shipped mpp command-line tool (pay a 402 URL curl-style, plus sign / discover / account / services / init) rides a vendor-neutral PaymentAuthorizer approval seam (MPPAuth: per-request Touch ID, a TTY prompt, or headless auto with a spending cap). The original 1.0 gate -- server hardening, the HTML page, and conformance-vector completeness -- is now closed, and the package is released at 1.0.0. See what's covered and the module table below.

What's covered

MPP composes along three axes: the transport the 402 flow rides, the rail that moves value, and the side you are (payer/client vs payee/server). Client and server are independent products, so a Swift client can pay any-language server and a Swift server can charge any client. Here is the surface:

Transports (the wire the challenge / credential / receipt flow rides):

• HTTP - MPPServer middleware + MPPClient (over URLSessionTransport); a live server binding (MPPHummingbird) and a 402-protected reverse proxy (MPPProxy).
• JSON-RPC / MCP - MPPMCP gates a tools/call and pays it transparently; conformance-proven both directions over stdio.
• WebSocket + SSE - metered, pay-as-you-go streaming with in-band voucher top-up: MPPWebSocket (transport-agnostic session orchestration, server + client) + MPPWebSocketLive (live swift-websocket adapters), plus the Server-Sent Events codec.
• HTML payment page - MPPHTML / MPPHTMLServer: a self-contained, themeable HTML 402 page (multi-method tabs + a service worker) that MPPServerMiddleware content-negotiates for a human-facing payer, alongside the machine problem+json.

Rails (how value actually settles):

• Tempo (EVM) - MPPTempo / MPPTempoServer: a zero-amount proof-of-wallet-control charge; a full payment-channel session (open / voucher / topUp / close, settled on-chain); a subscription rail (a signed key authorization, a two-phase atomic renewal engine, and a concrete on-chain renewer with fee-payer gas sponsorship); and metered streaming over the channel. The 0x76 channel / charge transactions are built by a pinned Rust FFI (MPPTempoFFI), so only a wallet links it.
• Stripe - MPPStripe / MPPStripeServer: a Shared Payment Token charge into a PaymentIntent, full Stripe Connect parity, live-verified.
• x402 on Base - MPPX402 / MPPX402Server: the Coinbase x402 exact scheme (an EIP-3009 transferWithAuthorization over USDC on Base), plus a version-negotiated bridge between MPP and x402 (v1 + v2) and an x402-facilitator settler, so the SDK interoperates with the real x402 ecosystem in both directions.

Client building blocks:

• PaymentAuthorizer - the vendor-neutral consent/budget seam consulted once at the credential-build chokepoint: AllowAllAuthorizer, SpendingCapAuthorizer, and BudgetAuthorizer (an atomic running-budget check-and-debit, TOCTOU-safe -- the spending-cap / margin enforcer for a long-lived broker).
• ReceiptStore - a persistence seam the client records each Payment-Receipt to after settle (auditing, never a gate).
• MPPClientAsyncHTTP - a SwiftNIO AsyncHTTPClient transport, the Linux/server counterpart to URLSessionTransport for a long-lived gateway or broker process.

Server hardening: single-use ReplayStore, IdempotencyStore (safe-retry, 409), RateLimiter (429), sensitive-surface redaction, and an opt-in CORS/HEAD policy on the discovery surfaces -- all in MPPServer / MPPProxy.

Tooling:

• mpp - a shipped command-line tool: pay a 402 URL (curl-like), sign a challenge, discover / validate, account (macOS Keychain), services, init. Approval rides a vendor-neutral PaymentAuthorizer seam (MPPAuth): per-request Touch ID, a TTY prompt, or headless auto with a spending cap.
• MPPDiscovery - OpenAPI x-payment-info discovery (parse, generate, validate) plus a ServiceDirectory client that reads the mpp.dev/services directory.

Cross-SDK conformance: every rail and transport with a reference peer is proven against the reference TypeScript SDK (mppx) in both directions (our client against their server, and their client against our server), offline in CI and, for the on-chain Tempo paths, live on the Moderato testnet. See CONFORMANCE.md.

Installation

Swift Package Manager:

.package(url: "https://github.com/amitach/mpp-swift", from: "1.0.0")

Then depend on the products you need (you pull only those):

.product(name: "MPPCore", package: "mpp-swift"),

A consumer that builds Tempo channel transactions (a wallet) additionally depends on MPPTempoFFI; on Apple this downloads the checksum-pinned tempo-tx-ffi xcframework (no Rust toolchain). Every other product links zero Rust.

Modules

The bespoke Tempo 0x76 transaction (channel open/topUp/close) is the one piece we deliberately do not build in Swift. Swift could encode it, but the format is Tempo-specific and evolving, so binding Tempo's own tempo-primitives (the chain's canonical implementation) gives byte-for-byte parity and turns an upgrade into a version bump, instead of a drift-prone Swift port we would have to chase by hand. It is produced by rust/tempo-tx-ffi and exposed to Swift over an FFI boundary. It is only needed by a consumer that builds Tempo channel transactions (a wallet): a non-Tempo consumer, or a Tempo server that only verifies and reads, should link none of it. It builds the three channel-bookend transactions (open / topUp / close) and the recurring subscription charge (a transferWithMemo, signed by an access key as a Tempo V2 keychain signature, with an optional fee-payer gas sponsor), and is wired into the Swift package behind the dedicated opt-in MPPTempoFFI product (the FFITempoTxBuilder and FFISubscriptionChargeTxBuilder), so only a transaction-building consumer pulls the binary and the default graph links zero Rust (see ARCHITECTURE.md). It links on macOS (universal), iOS (device + simulator), and Linux. It is a build input that ships in the artifact (unlike the dev-only npm test tooling); its dependency tree is pinned (Cargo.lock), built in CI on macOS and Linux, byte-golden-tested, and cargo audit-scanned. Its output is proven on-chain: a gated live Moderato e2e opens and closes a real channel through it. It is published as a checksummed GitHub-release xcframework (.github/workflows/release-ffi.yml, tag tempo-tx-ffi-v*), so an external Apple consumer installs it with no env var and no Rust toolchain. The from-source MPP_TEMPO_FFI path remains for dev/CI, and a Linux consumer always builds from source (SwiftPM has no Linux library binary artifact). See SECURITY.md.

Development (running locally)

Prerequisites: a Swift 6.2 toolchain (Xcode 26+ on macOS, or the Swift 6.2 toolchain on Linux). The 6.2 floor comes from MPPMCP's dependency on the official MCP Swift SDK, whose transitive graph (swift-log 1.13) requires tools 6.2. The Rust FFI crate additionally needs a Rust toolchain >= 1.93 (rustup update stable), but only if you build that crate - the Swift package builds and tests with no Rust.

git clone https://github.com/amitach/mpp-swift && cd mpp-swift
swift build            # builds all products
swift test             # runs the full suite (hermetic; no network)

Both must pass on macOS and Linux. Lint matches CI:

swiftformat --lint .   # formatting
swiftlint --strict     # style; zero warnings

Cross-SDK conformance (exercises the wire format against the reference TypeScript SDK; needs Node):

Scripts/conformance/run.sh             # offline, vs a local mppx server
Scripts/conformance/run.sh --testnet   # against the live Moderato node

Live-chain tests (read path against the real Moderato testnet) are gated so the default suite stays hermetic; opt in with an env var:

MPP_MODERATO_E2E=1 swift test --filter Moderato

The Rust FFI crate (the 0x76 transaction builder) is separate from the Swift package:

cd rust/tempo-tx-ffi
cargo test     # builds the crate (clones tempo + compiles the tree) and runs the byte-golden test
cargo audit    # scans the Rust dependency tree against the RustSec advisory DB

CI runs all of the above; the Swift Tests jobs and the Rust FFI job both run on macOS and Linux. See the architecture overview for how the pieces fit and SECURITY.md for the supply-chain posture.

Design

• Client and server are separate products: depend on one without the other.
• Spec is the source of truth. The SDK defaults to the published MPP drafts; where an interoperating peer diverges, the divergence is handled explicitly via a compatibility configuration, never silently inherited.
• Conventions follow the Swift ecosystem: Apple's API Design Guidelines and the swift-* package norms.

License

Dual-licensed under either of Apache License 2.0 or MIT license at your option.

Acknowledgments

This product includes software developed by Marcin Krzyzanowski (https://krzyzanowskim.com/), the CryptoSwift library, used for Keccak-256.

Security policy: see SECURITY.md. Contributing: see CONTRIBUTING.md.