Http

http/gin

github.com/x402-foundation/x402/go/v2/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 URL

Returns:

Gin middleware handler

Example:

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 configuration

Returns:

Gin middleware handler

Example:

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.RoutesConfig

    Routes maps HTTP patterns to payment requirements

  • Facilitator x402.FacilitatorClient

    Facilitator is a single facilitator client (most common case) Use this OR Facilitators (not both)

  • Facilitators []x402.FacilitatorClient

    Facilitators is an array of facilitator clients (for fallback/redundancy) Use this OR Facilitator (not both)

  • Schemes []SchemeConfig

    Schemes to register with the server

  • PaywallConfig *x402http.PaywallConfig

    PaywallConfig for browser-based payment UI (optional)

  • SyncFacilitatorOnStart bool

    SyncFacilitatorOnStart fetches supported kinds from facilitators on startup Default: true

  • Timeout time.Duration

    Timeout 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.RoutesConfig

    Routes configuration

  • FacilitatorClients []x402.FacilitatorClient

    Facilitator client(s)

  • Schemes []SchemeRegistration

    Scheme registrations

  • PaywallConfig *x402http.PaywallConfig

    Paywall configuration

  • SyncFacilitatorOnStart bool

    Sync with facilitator on start

  • ErrorHandler func(*gin.Context, error)

    Custom error handler

  • SettlementHandler func(*gin.Context, *x402.SettleResponse)

    Custom settlement handler

  • Timeout time.Duration

    Context 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.Network
  • Server 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.Network
  • Server x402.SchemeNetworkServer