* feat: add batch-settlement implementation to Go SDK * feat: add batch-settlement examples for go sdk * feat: updated typescript examples to match go examples * feat: add e2e testing for batch-settlement in go * Batch-settlement: go-ts parity (#2227) * fix PendingRequest and refund cleanup * fix lint * remove duplicate payer info from storage * fix PAYMENT-RESPONSE field ordering * clean up comments * consolidate ProcessSettlementWithExtensions into ProcessSettlement --------- Co-authored-by: phdargen <p.dargent@cern.ch>
x402 Echo Middleware
Echo middleware integration for the x402 Payment Protocol. This package provides middleware for adding x402 payment requirements to your Echo applications.
Installation
go get github.com/x402-foundation/x402/go
Quick Start
package main
import (
x402http "github.com/x402-foundation/x402/go/http"
echomw "github.com/x402-foundation/x402/go/http/echo"
evm "github.com/x402-foundation/x402/go/mechanisms/evm/exact/server"
"github.com/labstack/echo/v4"
)
func main() {
e := echo.New()
facilitator := x402http.NewHTTPFacilitatorClient(&x402http.FacilitatorConfig{
URL: "https://facilitator.x402.org",
})
routes := x402http.RoutesConfig{
"GET /protected": {
Accepts: x402http.PaymentOptions{
{
Scheme: "exact",
PayTo: "0xYourAddress",
Price: "$0.10",
Network: "eip155:84532",
},
},
Description: "Access to premium content",
},
}
e.Use(echomw.PaymentMiddlewareFromConfig(routes,
echomw.WithFacilitatorClient(facilitator),
echomw.WithScheme("eip155:*", evm.NewExactEvmScheme()),
))
e.GET("/protected", func(c echo.Context) error {
return c.JSON(200, map[string]interface{}{"message": "This content is behind a paywall"})
})
e.Logger.Fatal(e.Start(":8080"))
}
Configuration
There are two approaches to configuring the middleware:
1. PaymentMiddlewareFromConfig (Functional Options)
Use PaymentMiddlewareFromConfig with functional options:
e.Use(echomw.PaymentMiddlewareFromConfig(routes,
echomw.WithFacilitatorClient(facilitator),
echomw.WithScheme("eip155:*", evm.NewExactEvmScheme()),
))
2. PaymentMiddlewareFromHTTPServer (Pre-configured Server)
Use PaymentMiddlewareFromHTTPServer when you need to configure the server separately (e.g., with lifecycle hooks):
server := x402.Newx402ResourceServer(
x402.WithFacilitatorClient(facilitator),
).
Register("eip155:*", evm.NewExactEvmScheme()).
OnAfterSettle(func(ctx x402.SettleResultContext) error {
log.Printf("Payment settled: %s", ctx.Result.Transaction)
return nil
})
httpServer := x402http.Wrappedx402HTTPResourceServer(routes, server)
e.Use(echomw.PaymentMiddlewareFromHTTPServer(httpServer))
Middleware Options
WithFacilitatorClient(client)- Add a facilitator clientWithScheme(network, server)- Register a payment schemeWithPaywallConfig(config)- Configure paywall UIWithSyncFacilitatorOnStart(bool)- Sync with facilitator on startup (default: true)WithTimeout(duration)- Set payment operation timeout (default: 30s)WithErrorHandler(handler)- Custom error handlerWithSettlementHandler(handler)- Settlement callback
Route Configuration
Define which routes require payment:
routes := x402http.RoutesConfig{
"GET /api/data": {
Accepts: x402http.PaymentOptions{
{
Scheme: "exact",
PayTo: "0xYourAddress",
Price: "$0.10",
Network: "eip155:84532",
},
},
Description: "API data access",
},
"POST /api/compute": {
Accepts: x402http.PaymentOptions{
{
Scheme: "exact",
PayTo: "0xYourAddress",
Price: "$1.00",
Network: "eip155:8453",
},
},
Description: "Compute operation",
},
}
Routes support wildcards:
"GET /api/premium/*"- Matches all GET requests under/api/premium/"* /api/data"- Matches all HTTP methods to/api/data
Paywall Configuration
Configure the paywall UI for browser requests:
paywallConfig := &x402http.PaywallConfig{
AppName: "My API Service",
AppLogo: "https://myapp.com/logo.svg",
Testnet: true,
}
e.Use(echomw.PaymentMiddlewareFromConfig(routes,
echomw.WithFacilitatorClient(facilitator),
echomw.WithScheme("eip155:*", evm.NewExactEvmScheme()),
echomw.WithPaywallConfig(paywallConfig),
))
The paywall includes:
- EVM wallet support (MetaMask, Coinbase Wallet, etc.)
- Solana wallet support (Phantom, Solflare, etc.)
- USDC balance checking and chain switching
- Onramp integration for mainnet
Advanced Usage
Multiple Payment Schemes
Register schemes for different networks:
import (
evm "github.com/x402-foundation/x402/go/mechanisms/evm/exact/server"
svm "github.com/x402-foundation/x402/go/mechanisms/svm/exact/server"
)
e.Use(echomw.PaymentMiddlewareFromConfig(routes,
echomw.WithFacilitatorClient(facilitator),
echomw.WithScheme("eip155:*", evm.NewExactEvmScheme()),
echomw.WithScheme("solana:*", svm.NewExactSvmScheme()),
))
Custom Facilitator Client
Configure with custom authentication:
facilitator := x402http.NewHTTPFacilitatorClient(&x402http.FacilitatorConfig{
URL: "https://your-facilitator.com",
CreateAuthHeaders: func() (*x402http.FacilitatorAuthHeaders, error) {
return &x402http.FacilitatorAuthHeaders{
Verify: map[string]string{"Authorization": "Bearer verify-token"},
Settle: map[string]string{"Authorization": "Bearer settle-token"},
}, nil
},
})
Settlement Handler
Track successful payments:
e.Use(echomw.PaymentMiddlewareFromConfig(routes,
echomw.WithFacilitatorClient(facilitator),
echomw.WithScheme("eip155:*", evm.NewExactEvmScheme()),
echomw.WithSettlementHandler(func(c echo.Context, settlement *x402.SettleResponse) {
log.Printf("Payment settled - Payer: %s, Tx: %s",
settlement.Payer,
settlement.Transaction,
)
c.Response().Header().Set("X-Payment-Receipt", settlement.Transaction)
}),
))
Settlement Overrides (Upto Scheme)
For the upto scheme, route handlers specify the actual settlement amount via SetSettlementOverrides:
e.GET("/api/metered", func(c echo.Context) error {
usage := calculateUsage(c)
echomw.SetSettlementOverrides(c, &x402.SettlementOverrides{Amount: usage})
return c.JSON(http.StatusOK, map[string]interface{}{"result": "ok"})
})
Error Handler
Custom error handling:
e.Use(echomw.PaymentMiddlewareFromConfig(routes,
echomw.WithFacilitatorClient(facilitator),
echomw.WithScheme("eip155:*", evm.NewExactEvmScheme()),
echomw.WithErrorHandler(func(c echo.Context, err error) {
log.Printf("Payment error: %v", err)
c.JSON(http.StatusPaymentRequired, map[string]interface{}{
"error": err.Error(),
})
}),
))
Convenience Functions
X402Payment (Config Struct)
With struct-based configuration:
e.Use(echomw.X402Payment(echomw.Config{
Routes: routes,
Facilitator: facilitator,
Schemes: []echomw.SchemeConfig{{Network: "eip155:*", Server: evm.NewExactEvmScheme()}},
Timeout: 30 * time.Second,
}))
SimpleX402Payment
Apply payment requirements to all routes:
e.Use(echomw.SimpleX402Payment(
"0xYourAddress",
"$0.10",
"eip155:84532",
"https://facilitator.x402.org",
))
Complete Example
package main
import (
"log"
"net/http"
"time"
x402 "github.com/x402-foundation/x402/go"
x402http "github.com/x402-foundation/x402/go/http"
echomw "github.com/x402-foundation/x402/go/http/echo"
evm "github.com/x402-foundation/x402/go/mechanisms/evm/exact/server"
"github.com/labstack/echo/v4"
)
func main() {
e := echo.New()
facilitator := x402http.NewHTTPFacilitatorClient(&x402http.FacilitatorConfig{
URL: "https://facilitator.x402.org",
})
routes := x402http.RoutesConfig{
"GET /api/data": {
Accepts: x402http.PaymentOptions{
{
Scheme: "exact",
PayTo: "0xYourAddress",
Price: "$0.10",
Network: "eip155:84532",
},
},
Description: "Basic data access",
},
"POST /api/compute": {
Accepts: x402http.PaymentOptions{
{
Scheme: "exact",
PayTo: "0xYourAddress",
Price: "$1.00",
Network: "eip155:8453",
},
},
Description: "Compute operation",
},
}
paywallConfig := &x402http.PaywallConfig{
AppName: "My API Service",
AppLogo: "/logo.svg",
Testnet: true,
}
e.Use(echomw.PaymentMiddlewareFromConfig(routes,
echomw.WithFacilitatorClient(facilitator),
echomw.WithScheme("eip155:*", evm.NewExactEvmScheme()),
echomw.WithPaywallConfig(paywallConfig),
echomw.WithTimeout(60*time.Second),
echomw.WithSettlementHandler(func(c echo.Context, settlement *x402.SettleResponse) {
log.Printf("Payment settled: %s", settlement.Transaction)
}),
))
e.GET("/api/data", func(c echo.Context) error {
return c.JSON(http.StatusOK, map[string]interface{}{"data": "Protected content"})
})
e.POST("/api/compute", func(c echo.Context) error {
return c.JSON(http.StatusOK, map[string]interface{}{"result": "Computation complete"})
})
e.GET("/", func(c echo.Context) error {
return c.JSON(http.StatusOK, map[string]interface{}{"message": "Welcome"})
})
e.Logger.Fatal(e.Start(":8080"))
}