mpp-go

mpp-go

Go SDK for the Machine Payments Protocol

MPP lets any client — agents, apps, or humans — pay for any service in the same HTTP request. It standardizes HTTP 402 with an open IETF specification, so servers can charge and clients can pay without API keys, billing accounts, or checkout flows.

Documentation

You can get started today by reading the Go SDK docs, the module-level Go doc reference, exploring the protocol overview, or jumping straight to the quickstart.

Package docs:

• pkg/client
• pkg/server
• pkg/tempo
• pkg/tempo/client
• pkg/tempo/server

Install

go get github.com/tempoxyz/mpp-go

Quick Start

Server

package main

import (
	"encoding/json"
	"log"
	"net/http"

	"github.com/tempoxyz/mpp-go/pkg/server"
	"github.com/tempoxyz/mpp-go/pkg/tempo"
	charge "github.com/tempoxyz/mpp-go/pkg/tempo/server"
)

func main() {
	method, _ := charge.New(charge.Config{
		// Development only; use a shared persistent Store in production.
		Store:     tempo.NewMemoryStore(),
		RPCURL:    "https://rpc.moderato.tempo.xyz",
		Recipient: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
	})

	// Secret must be at least 32 bytes (generate with: openssl rand -base64 32).
	payment, err := server.New(method, "api.example.com", "replace-me-with-a-32-byte-min-secret")
	if err != nil {
		log.Fatal(err)
	}

	handler := server.ChargeMiddleware(payment, server.ChargeParams{
		Amount:      "0.50",
		Description: "Paid content",
	})(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		_ = json.NewEncoder(w).Encode(map[string]any{
			"data":  "paid content",
			"payer": server.CredentialFromContext(r.Context()).Source,
		})
	}))

	_ = http.ListenAndServe(":8080", handler)
}

If the endpoint already uses Authorization (API keys, Bearer tokens), create the server with server.WithRequiresAuth(true). Challenges then advertise header="Payment-Authorization", and clients send the Payment credential in that header instead of Authorization.

payment, err := server.New(method, "api.example.com", secret, server.WithRequiresAuth(true))
if err != nil {
	log.Fatal(err)
}

handler := server.ChargeMiddleware(payment, server.ChargeParams{
	Amount:      "0.50",
	Description: "Paid content",
})(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	_ = json.NewEncoder(w).Encode(map[string]any{"data": "paid content"})
}))

Explicit replay storage

Local verifier construction requires an explicit Store, so an unconfigured server cannot issue payable challenges. All replicas must share persistent replay keys, with atomic PutIfAbsent, no eviction, and fail-closed behavior on storage errors. tempo.NewMemoryStore() is an explicit single-process development choice; it loses replay protection on restart. Existing applications relying on the implicit memory store must configure storage. Relay verification delegates replay protection to the relay.

Client

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/tempoxyz/mpp-go/pkg/client"
	"github.com/tempoxyz/mpp-go/pkg/mpp"
	charge "github.com/tempoxyz/mpp-go/pkg/tempo/client"
)

func main() {
	method, _ := charge.New(charge.Config{
		PrivateKey: os.Getenv("MPP_PRIVATE_KEY"),
		RPCURL:     "https://rpc.moderato.tempo.xyz",
		// Pay at most 0.50 per request, in any of the 6-decimal Tempo stablecoins.
		PaymentPolicy: charge.MaxAmount("", "0.50", 6),
	})

	c := client.New([]client.Method{method})
	response, err := c.Get(context.Background(), "https://api.example.com/paid")
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	receipt, _ := mpp.ParseReceipt(response.Header.Get("Payment-Receipt"))

	var body struct {
		Data  string `json:"data"`
		Payer string `json:"payer"`
	}
	_ = json.NewDecoder(response.Body).Decode(&body)

	fmt.Printf("paid request for %q from %s with receipt %s\n", body.Data, body.Payer, receipt.Reference)
}

Examples

Idempotent POST Charges

For paid POST routes or agent tool calls, bind each logical operation to a stable ExternalID. The value is included in the MPP charge request and echoed back in the Payment-Receipt, so servers can distinguish a safe retry from a different paid operation. ExternalID is receipt metadata; it does not by itself persist or reject duplicate operations. Your application must keep its own idempotency record or response cache keyed by the client idempotency value before running the paid side effect.

If your API already accepts an Idempotency-Key header, pass that value through as ChargeParams.ExternalID when constructing the charge:

externalID := r.Header.Get("Idempotency-Key")
if externalID == "" {
	http.Error(w, "missing Idempotency-Key", http.StatusBadRequest)
	return
}

result, err := payment.Charge(r.Context(), server.ChargeParams{
	Authorization: r.Header.Get("Authorization"),
	Amount:        "0.50",
	Description:   "Create report",
	ExternalID:    externalID,
})

Use the same ExternalID for retries of the same operation. Do not generate a new value for each retry, and avoid reusing one value across different paid operations. On retry, check the stored idempotency result first and return the cached response or receipt instead of executing the POST operation again.

Split Credential Lifecycle

Server intents can register separate advisory validation and settlement hooks:

intent, err := server.NewIntent("charge", server.IntentHooks{
	Validate:  validateCredential,
	Broadcast: broadcastCredential,
})

The constructed intent satisfies the public server.BroadcastingIntent interface as well as the backwards-compatible server.Intent interface. Custom intents can implement server.ValidatingIntent or server.BroadcastingIntent directly. Servers can run the phases independently:

validation, err := payment.ValidateCredential(ctx, credential)
receipt, err := payment.BroadcastCredential(ctx, credential)

ValidateCredential requires a server.ValidatingIntent and must not consume replay state, sign fee-payer transactions, or broadcast. BroadcastCredential re-validates before settlement. VerifyCredential remains an alias for the mutating broadcast path, and legacy intents that only implement Verify continue to work for paid routes and broadcasts.

The built-in Tempo charge intent implements the split lifecycle locally. Tempo relay methods implement the same lifecycle by delegating validation to POST /v1/mpp/validate and finalization to POST /v1/mpp/broadcast.

Web Frameworks

The most common Go HTTP stacks today are net/http, Gin, Echo, Chi, and Fiber. MPP already integrates directly with net/http, which also covers Chi because Chi handlers and middleware use the standard http.Handler interfaces.

For the most common non-stdlib frameworks, mpp-go ships first-class adapters:

• pkg/server/gin for Gin
• pkg/server/echo for Echo
• pkg/server/fiber for Fiber

Chi needs no special adapter:

router.With(server.ChargeMiddleware(payment, server.ChargeParams{
	Amount:      "0.50",
	Description: "Paid content",
})).Get("/paid", func(w http.ResponseWriter, r *http.Request) {
	credential := server.CredentialFromContext(r.Context())
	receipt := server.ReceiptFromContext(r.Context())
	_ = json.NewEncoder(w).Encode(map[string]any{
		"payer":   credential.Source,
		"receipt": receipt.Reference,
	})
})

Gin route middleware:

router.GET("/paid", ginadapter.ChargeMiddleware(payment, server.ChargeParams{
	Amount:      "0.50",
	Description: "Paid content",
}), func(c *gin.Context) {
	credential := ginadapter.Credential(c)
	receipt := ginadapter.Receipt(c)
	c.JSON(http.StatusOK, gin.H{
		"payer":   credential.Source,
		"receipt": receipt.Reference,
	})
})

Echo route middleware:

e.GET("/paid", func(c echo.Context) error {
	credential := echoadapter.Credential(c)
	receipt := echoadapter.Receipt(c)
	return c.JSON(http.StatusOK, map[string]any{
		"payer":   credential.Source,
		"receipt": receipt.Reference,
	})
}, echoadapter.ChargeMiddleware(payment, server.ChargeParams{
	Amount:      "0.50",
	Description: "Paid content",
}))

Fiber route middleware:

app.Get("/paid", fiberadapter.ChargeMiddleware(payment, server.ChargeParams{
	Amount:      "0.50",
	Description: "Paid content",
}), func(c *fiber.Ctx) error {
	credential := fiberadapter.Credential(c)
	receipt := fiberadapter.Receipt(c)
	return c.Status(http.StatusOK).JSON(fiber.Map{
		"payer":   credential.Source,
		"receipt": receipt.Reference,
	})
})

Protocol

Built on the "Payment" HTTP Authentication Scheme, an open specification proposed to the IETF. See mpp.dev/protocol for the full protocol overview, or the IETF specification for the wire format.

Contributing

git clone https://github.com/tempoxyz/mpp-go
cd mpp-go
go test ./...

Security

See SECURITY.md for reporting vulnerabilities.

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Payment request safety

Hash-mode clients validate the credential header size before broadcasting. For custom clients, serialize with mpp.FormatCredential(credential) and handle its error.

With server.WithChallengeNonce(true), server-issued challenges have random opaque _mpp_nonce metadata. Do not set that reserved key. Bind authenticated application context with ChargeParams{Meta: map[string]string{"account": authenticatedAccountID}} when a payment must authorize a specific caller. Derive this ID from trusted session authentication, never directly from request input. Nonces prevent challenge collisions; they do not make leaked complete credentials safe. Low-level challenge constructors remain deterministic, so custom issuance must supply its own unique, authenticated context. Existing challenges remain valid until their original expiry.

Nonce issuance is opt-in for upgrade safety. First deploy this release everywhere with nonce issuance off (the default). Verification already accepts nonces, while issuance stays compatible with old replicas. After all verifiers are upgraded, create the server with server.WithChallengeNonce(true) (or set VerifyParams.EnableChallengeNonce when calling VerifyOrChallenge). The shared-challenge collision risk remains until issuance is enabled. Old replicas reject nonced credentials, potentially after a hash payment has settled; do not enable issuance while old verifiers remain. Version-sticky retries are an alternative rollout strategy.