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.
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:
go get github.com/tempoxyz/mpp-gopackage 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"})
}))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.
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)
}| Example | Description |
|---|---|
| basic | Separate-process demo with a long-running server and standalone client, mirroring the mpp-rs sample layout |
| chi/server | Chi router example using the existing net/http middleware helpers |
| gin/server | Gin example using the dedicated adapter package and context helpers |
| echo/server | Echo example using the dedicated adapter package and context helpers |
| fiber/server | Fiber example using the dedicated adapter package and context helpers |
| charge-basic | Generic Tempo charge flow using the high-level MPP client and server helpers, available in both one-command and separate-process layouts |
| charge-hash | Push-mode charge flow with a hash credential, available in both one-command and separate-process layouts |
| charge-fee-payer | Sponsored Tempo charge flow where the server co-signs as a fee payer, available in both one-command and separate-process layouts |
| charge-relay | Moderato charge flow that delegates credential validation and broadcast to Tempo API's MPP relay |
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.
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.
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/ginfor Ginpkg/server/echofor Echopkg/server/fiberfor 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,
})
})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.
git clone https://github.com/tempoxyz/mpp-go
cd mpp-go
go test ./...
See SECURITY.md for reporting vulnerabilities.
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.
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.