http/gin
import "github.com/x402-foundation/x402/go/v2/http/gin"
Functions
func NewGinAdapter(ctx *gin.Context) *GinAdapter
Source: http/gin/middleware.go:36
NewGinAdapter creates a new Gin adapter
func PaymentMiddleware(routes x402http.RoutesConfig, server *x402.X402ResourceServer, opts ...MiddlewareOption) gin.HandlerFunc
Source: http/gin/middleware.go:175
PaymentMiddleware creates Gin middleware for x402 payment handling using a pre-configured server.
func PaymentMiddlewareFromConfig(routes x402http.RoutesConfig, opts ...MiddlewareOption) gin.HandlerFunc
Source: http/gin/middleware.go:250
PaymentMiddlewareFromConfig creates Gin middleware for x402 payment handling. This creates the server internally from the provided options.
func PaymentMiddlewareFromHTTPServer(httpServer *x402http.HTTPServer, opts ...MiddlewareOption) gin.HandlerFunc
Source: http/gin/middleware.go:220
PaymentMiddlewareFromHTTPServer creates Gin middleware using a pre-configured HTTPServer. This allows registering hooks (e.g., OnProtectedRequest) on the server before attaching to the router.
Example:
resourceServer := x402.Newx402ResourceServer(
x402.WithFacilitatorClient(facilitator),
).Register("eip155:*", evm.NewExactEvmScheme())
httpServer := x402http.Wrappedx402HTTPResourceServer(routes, resourceServer).
OnProtectedRequest(requestHook)
r.Use(ginmw.PaymentMiddlewareFromHTTPServer(httpServer))func SetSettlementOverrides(c *gin.Context, overrides *x402.SettlementOverrides)
Source: http/gin/middleware.go:22
SetSettlementOverrides sets settlement overrides on the Gin response for partial settlement. The middleware extracts these before settlement and strips the header from the client response.
func SimpleX402Payment(payTo string, price string, network x402.Network, facilitatorURL string) gin.HandlerFunc
Source: http/gin/builder.go:154
SimpleX402Payment creates middleware with minimal configuration. Uses a single route pattern and facilitator for the simplest possible setup.
Args:
payTo: Payment recipient address
price: Payment amount (e.g., "$0.001")
network: Payment network
facilitatorURL: Facilitator server URLReturns:
Gin middleware handlerExample:
r.Use(gin.SimpleX402Payment(
"0x123...",
"$0.001",
"eip155:8453",
"https://facilitator.example.com",
))func WithErrorHandler(handler func(*gin.Context, error)) MiddlewareOption
Source: http/gin/middleware.go:150
WithErrorHandler sets a custom error handler
func WithFacilitatorClient(client x402.FacilitatorClient) MiddlewareOption
Source: http/gin/middleware.go:119
WithFacilitatorClient adds a facilitator client
func WithPaywallConfig(config *x402http.PaywallConfig) MiddlewareOption
Source: http/gin/middleware.go:136
WithPaywallConfig sets the paywall configuration
func WithScheme(network x402.Network, schemeServer x402.SchemeNetworkServer) MiddlewareOption
Source: http/gin/middleware.go:126
WithScheme registers a scheme server
func WithSettlementHandler(handler func(*gin.Context, *x402.SettleResponse)) MiddlewareOption
Source: http/gin/middleware.go:157
WithSettlementHandler sets a custom settlement handler
func WithSyncFacilitatorOnStart(sync bool) MiddlewareOption
Source: http/gin/middleware.go:143
WithSyncFacilitatorOnStart sets whether to sync with facilitator on startup
func WithTimeout(timeout time.Duration) MiddlewareOption
Source: http/gin/middleware.go:164
WithTimeout sets the context timeout for payment operations
func X402Payment(config Config) gin.HandlerFunc
Source: http/gin/builder.go:75
X402Payment creates payment middleware using struct-based configuration. This is a cleaner, more readable alternative to PaymentMiddleware with variadic options.
Args:
config: Payment middleware configurationReturns:
Gin middleware handlerExample:
r.Use(ginmw.X402Payment(ginmw.Config{
Routes: routes,
Facilitator: facilitatorClient,
Schemes: []ginmw.SchemeConfig{
{Network: "eip155:*", Server: evm.NewExactEvmServer()},
{Network: "solana:*", Server: svm.NewExactEvmServer()},
},
SyncFacilitatorOnStart: true,
Timeout: 30 * time.Second,
}))Types
type Config
Source: http/gin/builder.go:13
Config provides struct-based configuration for x402 payment middleware. This is a cleaner alternative to the variadic options pattern.
type Config struct {
// Routes maps HTTP patterns to payment requirements
Routes x402http.RoutesConfig
// Facilitator is a single facilitator client (most common case)
// Use this OR Facilitators (not both)
Facilitator x402.FacilitatorClient
// Facilitators is an array of facilitator clients (for fallback/redundancy)
// Use this OR Facilitator (not both)
Facilitators []x402.FacilitatorClient
// Schemes to register with the server
Schemes []SchemeConfig
// PaywallConfig for browser-based payment UI (optional)
PaywallConfig *x402http.PaywallConfig
// SyncFacilitatorOnStart fetches supported kinds from facilitators on startup
// Default: true
SyncFacilitatorOnStart bool
// Timeout for payment operations
// Default: 30 seconds
Timeout time.Duration
// ErrorHandler for custom error handling (optional)
ErrorHandler func(*gin.Context, error)
// SettlementHandler called after successful settlement (optional)
SettlementHandler func(*gin.Context, *x402.SettleResponse)
}Fields
Routes x402http.RoutesConfigRoutes maps HTTP patterns to payment requirements
Facilitator x402.FacilitatorClientFacilitator is a single facilitator client (most common case) Use this OR Facilitators (not both)
Facilitators []x402.FacilitatorClientFacilitators is an array of facilitator clients (for fallback/redundancy) Use this OR Facilitator (not both)
Schemes []SchemeConfigSchemes to register with the server
PaywallConfig *x402http.PaywallConfigPaywallConfig for browser-based payment UI (optional)
SyncFacilitatorOnStart boolSyncFacilitatorOnStart fetches supported kinds from facilitators on startup Default: true
Timeout time.DurationTimeout for payment operations Default: 30 seconds
ErrorHandler func(*gin.Context, error)ErrorHandler for custom error handling (optional)
SettlementHandler func(*gin.Context, *x402.SettleResponse)SettlementHandler called after successful settlement (optional)
type GinAdapter
Source: http/gin/middleware.go:31
GinAdapter implements HTTPAdapter for Gin framework
type GinAdapter struct {
// contains filtered or unexported fields
}func GetAcceptHeader() string
Source: http/gin/middleware.go:69
GetAcceptHeader gets the Accept header
func GetHeader(name string) string
Source: http/gin/middleware.go:41
GetHeader gets a request header
func GetMethod() string
Source: http/gin/middleware.go:46
GetMethod gets the HTTP method
func GetPath() string
Source: http/gin/middleware.go:51
GetPath gets the request path
func GetURL() string
Source: http/gin/middleware.go:56
GetURL gets the full request URL
func GetUserAgent() string
Source: http/gin/middleware.go:74
GetUserAgent gets the User-Agent header
type MiddlewareConfig
Source: http/gin/middleware.go:83
MiddlewareConfig configures the payment middleware
type MiddlewareConfig struct {
// Routes configuration
Routes x402http.RoutesConfig
// Facilitator client(s)
FacilitatorClients []x402.FacilitatorClient
// Scheme registrations
Schemes []SchemeRegistration
// Paywall configuration
PaywallConfig *x402http.PaywallConfig
// Sync with facilitator on start
SyncFacilitatorOnStart bool
// Custom error handler
ErrorHandler func(*gin.Context, error)
// Custom settlement handler
SettlementHandler func(*gin.Context, *x402.SettleResponse)
// Context timeout for payment operations
Timeout time.Duration
}Fields
Routes x402http.RoutesConfigRoutes configuration
FacilitatorClients []x402.FacilitatorClientFacilitator client(s)
Schemes []SchemeRegistrationScheme registrations
PaywallConfig *x402http.PaywallConfigPaywall configuration
SyncFacilitatorOnStart boolSync with facilitator on start
ErrorHandler func(*gin.Context, error)Custom error handler
SettlementHandler func(*gin.Context, *x402.SettleResponse)Custom settlement handler
Timeout time.DurationContext timeout for payment operations
type MiddlewareOption
Source: http/gin/middleware.go:116
MiddlewareOption configures the middleware
type MiddlewareOption func(*MiddlewareConfig)type SchemeConfig
Source: http/gin/builder.go:47
SchemeConfig configures a payment scheme for a network.
type SchemeConfig struct {
Network x402.Network
Server x402.SchemeNetworkServer
}Fields
Network x402.NetworkServer x402.SchemeNetworkServer
type SchemeRegistration
Source: http/gin/middleware.go:110
SchemeRegistration registers a scheme with the server
type SchemeRegistration struct {
Network x402.Network
Server x402.SchemeNetworkServer
}Fields
Network x402.NetworkServer x402.SchemeNetworkServer
