Documentation
¶
Index ¶
- func AddRoute(cfg *config.Config, pattern, price, description string, opts ...RouteOption) error
- func EnsureVerifier(cfg *config.Config) error
- func ResolveChain(name string) (x402lib.ChainConfig, error)
- func Setup(cfg *config.Config, wallet, chain, facilitatorURL string) error
- func ValidateFacilitatorURL(u string) error
- func ValidateWallet(addr string) error
- func WatchConfig(ctx context.Context, path string, v *Verifier, interval time.Duration)
- func WritePricingConfig(cfg *config.Config, pcfg *PricingConfig) error
- type PricingConfig
- type RouteOption
- type RouteRule
- type Verifier
- func (v *Verifier) HandleHealthz(w http.ResponseWriter, r *http.Request)
- func (v *Verifier) HandleReadyz(w http.ResponseWriter, r *http.Request)
- func (v *Verifier) HandleVerify(w http.ResponseWriter, r *http.Request)
- func (v *Verifier) HandleWellKnown(w http.ResponseWriter, r *http.Request)
- func (v *Verifier) Reload(cfg *PricingConfig) error
- func (v *Verifier) SetRegistration(reg *erc8004.AgentRegistration)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddRoute ¶
func AddRoute(cfg *config.Config, pattern, price, description string, opts ...RouteOption) error
AddRoute adds a pricing route to the x402 ConfigMap. Optional per-route payTo and network override the global config when set.
func EnsureVerifier ¶
EnsureVerifier deploys the x402 verifier subsystem if it doesn't exist. Idempotent — kubectl apply is safe to run multiple times.
func ResolveChain ¶
func ResolveChain(name string) (x402lib.ChainConfig, error)
ResolveChain maps a chain name string to an x402 ChainConfig.
func Setup ¶
Setup configures x402 pricing in the cluster by patching the ConfigMap and Secret. Stakater Reloader auto-restarts the verifier pod. If facilitatorURL is empty, the default (https://facilitator.x402.rs) is used.
func ValidateFacilitatorURL ¶
ValidateFacilitatorURL checks that the facilitator URL uses HTTPS. Payment proofs sent over plain HTTP could be intercepted. Loopback addresses (localhost, 127.0.0.1, [::1]) and k3d/Docker internal addresses are exempted for local development and testing.
func ValidateWallet ¶
ValidateWallet checks that addr is a valid 0x-prefixed 20-byte hex Ethereum address.
func WatchConfig ¶
WatchConfig polls a YAML config file for changes and reloads the Verifier when the file is modified. It checks the file's modification time every interval. This handles ConfigMap volume mount updates (kubelet symlink swaps) without requiring fsnotify.
WatchConfig blocks until the context is cancelled.
func WritePricingConfig ¶
func WritePricingConfig(cfg *config.Config, pcfg *PricingConfig) error
WritePricingConfig writes the pricing config to the cluster ConfigMap.
Types ¶
type PricingConfig ¶
type PricingConfig struct {
// Wallet is the USDC recipient address for all payments.
Wallet string `yaml:"wallet"`
// Chain is the blockchain network name (e.g., "base-sepolia", "base").
Chain string `yaml:"chain"`
// FacilitatorURL is the x402 facilitator service URL.
FacilitatorURL string `yaml:"facilitatorURL"`
// VerifyOnly skips blockchain settlement after successful verification.
VerifyOnly bool `yaml:"verifyOnly"`
// Routes defines per-route pricing rules. First match wins.
Routes []RouteRule `yaml:"routes"`
}
PricingConfig is the top-level configuration for the x402 ForwardAuth verifier. It defines global payment parameters and per-route pricing rules.
func GetPricingConfig ¶
func GetPricingConfig(cfg *config.Config) (*PricingConfig, error)
GetPricingConfig reads the current x402 pricing ConfigMap from the cluster.
func LoadConfig ¶
func LoadConfig(path string) (*PricingConfig, error)
LoadConfig reads and parses a pricing configuration YAML file.
type RouteOption ¶
type RouteOption func(*RouteRule)
RouteOption is a functional option for AddRoute.
func WithNetwork ¶
func WithNetwork(network string) RouteOption
WithNetwork sets a per-route network (overrides global chain).
func WithPayTo ¶
func WithPayTo(payTo string) RouteOption
WithPayTo sets a per-route payTo address (overrides global wallet).
type RouteRule ¶
type RouteRule struct {
// Pattern is a path matching pattern. Supports:
// - Exact match: "/health"
// - Prefix match: "/rpc/*" (matches /rpc/anything)
// - Glob match: "/inference-*/v1/*"
Pattern string `yaml:"pattern"`
// Price is the USDC amount per request (e.g., "0.0001").
Price string `yaml:"price"`
// Description is a human-readable label for this route (optional).
Description string `yaml:"description"`
// PayTo overrides the global wallet for this route (x402: payTo).
// If empty, falls back to PricingConfig.Wallet.
PayTo string `yaml:"payTo,omitempty"`
// Network overrides the global chain for this route (human-friendly).
// If empty, falls back to PricingConfig.Chain.
Network string `yaml:"network,omitempty"`
}
RouteRule maps a URL pattern to x402 payment requirements. Per-route fields (PayTo, Network) override the global PricingConfig values when set, enabling multiple ServiceOffers with different wallets/chains.
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
Verifier is a ForwardAuth-compatible HTTP handler that enforces x402 micropayments on a per-route basis. Traefik sends every incoming request to /verify; the Verifier either returns 200 (allow) or 402 (pay-wall).
func NewVerifier ¶
func NewVerifier(cfg *PricingConfig) (*Verifier, error)
NewVerifier creates a Verifier with the given initial configuration.
func (*Verifier) HandleHealthz ¶
func (v *Verifier) HandleHealthz(w http.ResponseWriter, r *http.Request)
HandleHealthz returns 200 OK for liveness probes.
func (*Verifier) HandleReadyz ¶
func (v *Verifier) HandleReadyz(w http.ResponseWriter, r *http.Request)
HandleReadyz returns 200 OK if pricing config is loaded, 503 otherwise.
func (*Verifier) HandleVerify ¶
func (v *Verifier) HandleVerify(w http.ResponseWriter, r *http.Request)
HandleVerify is the ForwardAuth endpoint. Traefik forwards the original request headers; the Verifier inspects X-Forwarded-Uri to determine which pricing rule applies.
Response semantics (ForwardAuth contract):
- 200: allow the request through to the backend
- 402: deny with x402 payment requirements in the response body
- 500: internal error (Traefik returns 500 to the client)
func (*Verifier) HandleWellKnown ¶
func (v *Verifier) HandleWellKnown(w http.ResponseWriter, r *http.Request)
HandleWellKnown serves the ERC-8004 agent registration document.
func (*Verifier) Reload ¶
func (v *Verifier) Reload(cfg *PricingConfig) error
Reload atomically swaps the pricing configuration.
func (*Verifier) SetRegistration ¶
func (v *Verifier) SetRegistration(reg *erc8004.AgentRegistration)
SetRegistration atomically sets the ERC-8004 agent registration data served at /.well-known/agent-registration.json.
Source Files