x402

package
v0.7.0-rc1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 18, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

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

func EnsureVerifier(cfg *config.Config) error

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

func Setup(cfg *config.Config, wallet, chain, facilitatorURL string) error

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

func ValidateFacilitatorURL(u string) error

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

func ValidateWallet(addr string) error

ValidateWallet checks that addr is a valid 0x-prefixed 20-byte hex Ethereum address.

func WatchConfig

func WatchConfig(ctx context.Context, path string, v *Verifier, interval time.Duration)

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

func (v *Verifier) MetricsHandler() http.Handler

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.

Directories

Path Synopsis
Package buyer implements an x402 buyer sidecar that handles payments using pre-signed ERC-3009 TransferWithAuthorization vouchers.
Package buyer implements an x402 buyer sidecar that handles payments using pre-signed ERC-3009 TransferWithAuthorization vouchers.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL