Documentation
¶
Index ¶
- Variables
- 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) MetricsHandler() http.Handler
- func (v *Verifier) Reload(cfg *PricingConfig) error
- func (v *Verifier) SetRegistration(reg *erc8004.AgentRegistration)
Constants ¶
This section is empty.
Variables ¶
var EthereumMainnet = x402lib.ChainConfig{
NetworkID: "ethereum",
USDCAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
Decimals: 6,
EIP3009Name: "USD Coin",
EIP3009Version: "2",
}
EthereumMainnet is the x402 ChainConfig for Ethereum mainnet USDC.
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 WithOfferInfo ¶ added in v0.7.0
func WithOfferInfo(namespace, name string) RouteOption
WithOfferInfo records the originating ServiceOffer identity.
func WithPayTo ¶
func WithPayTo(payTo string) RouteOption
WithPayTo sets a per-route payTo address (overrides global wallet).
func WithPriceMetadata ¶ added in v0.7.0
func WithPriceMetadata(model, perMTok string, approxTokensPerRequest int) RouteOption
WithPriceMetadata records the source pricing model behind the enforced Price.
func WithUpstreamAuth ¶ added in v0.7.0
func WithUpstreamAuth(upstreamAuth string) RouteOption
WithUpstreamAuth sets the upstream Authorization header injected on success.
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"`
// UpstreamAuth is injected as the Authorization header on approved requests.
// The x402-verifier sets this header in its 200 response; Traefik copies it
// to the forwarded request via authResponseHeaders. This lets the upstream
// (e.g., LiteLLM) authenticate the request without exposing the key to buyers.
UpstreamAuth string `yaml:"upstreamAuth,omitempty"`
// PriceModel records which price field produced the enforced request price.
// It is metadata only; the verifier always enforces Price.
PriceModel string `yaml:"priceModel,omitempty"`
// PerMTok stores the original per-million-token price when Price was
// approximated for phase 1 request-based gating.
PerMTok string `yaml:"perMTok,omitempty"`
// ApproxTokensPerRequest stores the fixed token estimate used to derive
// Price from PerMTok during phase 1.
ApproxTokensPerRequest int `yaml:"approxTokensPerRequest,omitempty"`
// OfferNamespace identifies the originating ServiceOffer namespace.
OfferNamespace string `yaml:"offerNamespace,omitempty"`
// OfferName identifies the originating ServiceOffer name.
OfferName string `yaml:"offerName,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) MetricsHandler ¶ added in v0.7.0
MetricsHandler exposes Prometheus metrics for the verifier.
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.