feat(paywall): chain-aware faucetUrl resolution across TS/Python/Go SDKs

Adds a 4-layer precedence chain for the testnet 'Need {token} on {chain}?
Get some here' link in the paywall:

  1. PaywallConfig.faucetUrls[caip2]   per-chain consumer override
  2. PaywallConfig.faucetUrl           global consumer override
  3. Chain registry default            DEFAULT_STABLECOINS[caip2].faucetUrl (EVM),
                                       USDC_CONFIG[caip2].faucetUrl (AVM),
                                       inline build-time map (SVM)
  4. Hardcoded fallback                https://faucet.circle.com/ (EVM/SVM),
                                       Algorand testnet dispenser (AVM)

SDK parity: TypeScript, Python, Go each expose
PaywallConfig.{faucetUrl, faucetUrls} and AssetInfo.faucetUrl on EVM and SVM.

Covers all three paywall mechanisms (EVM, SVM, AVM).

Mainnet entries intentionally leave faucetUrl unset since the paywall faucet
UI is testnet-gated and never renders the link on mainnet.

Backwards compatibility: every layer is opt-in. Unconfigured callers see the
same testnet link as today on every existing chain (the hardcoded fallback).
No public API removed or renamed; pure additive change.

Closes #2159

Author: ryanRfox

go/.changes/unreleased/added-20260429-103814.yaml

@@ -0,0 +1,3 @@
+kind: added
+body: 'Add SDK-configurable faucet URL plus chain-aware registry to the paywall: PaywallConfig gains FaucetURL (global override) and FaucetURLs (per-chain map keyed by CAIP-2); AssetInfo gains FaucetURL on EVM and SVM; testnet entries seeded.'
+time: 2026-04-29T10:38:14.93683-04:00

go/http/avm_paywall_template.go

@@ -4,6 +4,8 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/x402-foundation/x402/go/mechanisms/evm"
+	svm "github.com/x402-foundation/x402/go/mechanisms/svm"
 	"github.com/x402-foundation/x402/go/types"
 )
 
@@ -322,4 +324,102 @@ func TestInjectPaywallConfig(t *testing.T) {
 			t.Error("expected resource URL as currentUrl fallback")
 		}
 	})
+
+	t.Run("injects FaucetURL when set", func(t *testing.T) {
+		config := &PaywallConfig{FaucetURL: "https://example.com/faucet"}
+		got := injectPaywallConfig(template, paymentReq, config)
+		if !strings.Contains(got, `faucetUrl: "https://example.com/faucet"`) {
+			t.Errorf("expected faucetUrl literal in output, got %q", got)
+		}
+	})
+
+	t.Run("emits faucetUrl: undefined when FaucetURL unset", func(t *testing.T) {
+		got := injectPaywallConfig(template, paymentReq, nil)
+		if !strings.Contains(got, "faucetUrl: undefined") {
+			t.Errorf("expected faucetUrl: undefined in output, got %q", got)
+		}
+	})
+
+	t.Run("injects FaucetURLs map when set", func(t *testing.T) {
+		config := &PaywallConfig{
+			FaucetURLs: map[string]string{
+				"eip155:84532":  "https://example.com/base-sepolia",
+				"eip155:421614": "https://example.com/arb-sepolia",
+			},
+		}
+		got := injectPaywallConfig(template, paymentReq, config)
+		if !strings.Contains(got, "faucetUrls:") {
+			t.Errorf("expected faucetUrls in output, got %q", got)
+		}
+		if !strings.Contains(got, "https://example.com/base-sepolia") {
+			t.Errorf("expected base-sepolia URL in output, got %q", got)
+		}
+		if !strings.Contains(got, "https://example.com/arb-sepolia") {
+			t.Errorf("expected arb-sepolia URL in output, got %q", got)
+		}
+	})
+
+	t.Run("emits faucetUrls: undefined when FaucetURLs unset", func(t *testing.T) {
+		got := injectPaywallConfig(template, paymentReq, nil)
+		if !strings.Contains(got, "faucetUrls: undefined") {
+			t.Errorf("expected faucetUrls: undefined in output, got %q", got)
+		}
+	})
+}
+
+// --- Registry seed tests ---
+
+func TestEVMRegistryFaucetURLSeeds(t *testing.T) {
+	// Pin the EVM registry seed values for chain-aware faucet URLs. Mirrors
+	// the TS-side `FAUCET_URLS` drift test against `DEFAULT_STABLECOINS`.
+	expected := map[string]string{
+		"eip155:84532":  "https://faucet.circle.com/",
+		"eip155:421614": "https://faucet.circle.com/",
+		"eip155:31611":  "https://faucet.test.mezo.org/",
+		"eip155:2201":   "https://faucet.stable.xyz/faucet",
+	}
+	for caip2, want := range expected {
+		config, ok := evm.NetworkConfigs[caip2]
+		if !ok {
+			t.Errorf("missing EVM NetworkConfig for %q", caip2)
+			continue
+		}
+		if config.DefaultAsset.FaucetURL != want {
+			t.Errorf("EVM FaucetURL for %q: got %q, want %q", caip2, config.DefaultAsset.FaucetURL, want)
+		}
+	}
+}
+
+func TestSVMRegistryFaucetURLSeeds(t *testing.T) {
+	// Pin the SVM registry seed values. Both Solana devnet and testnet point
+	// at Circle's faucet (which mints USDC on those networks).
+	expected := map[string]string{
+		svm.SolanaDevnetCAIP2:  "https://faucet.circle.com/",
+		svm.SolanaTestnetCAIP2: "https://faucet.circle.com/",
+	}
+	for caip2, want := range expected {
+		config, ok := svm.NetworkConfigs[caip2]
+		if !ok {
+			t.Errorf("missing SVM NetworkConfig for %q", caip2)
+			continue
+		}
+		if config.DefaultAsset.FaucetURL != want {
+			t.Errorf("SVM FaucetURL for %q: got %q, want %q", caip2, config.DefaultAsset.FaucetURL, want)
+		}
+	}
+}
+
+func TestEVMMainnetEntriesHaveNoFaucetURL(t *testing.T) {
+	// Mainnet entries leave FaucetURL empty by convention — the paywall
+	// faucet UI is testnet-gated and mainnet entries never render the link.
+	mainnets := []string{"eip155:8453", "eip155:42161", "eip155:137"}
+	for _, caip2 := range mainnets {
+		config, ok := evm.NetworkConfigs[caip2]
+		if !ok {
+			continue // not seeded; nothing to assert
+		}
+		if config.DefaultAsset.FaucetURL != "" {
+			t.Errorf("mainnet %q has unexpected FaucetURL %q", caip2, config.DefaultAsset.FaucetURL)
+		}
+	}
 }

go/http/evm_paywall_template.go

@@ -44,12 +44,24 @@ type HTTPAdapter interface {
 // Configuration Types
 // ============================================================================
 
-// PaywallConfig configures the HTML paywall for browser requests
+// PaywallConfig configures the HTML paywall for browser requests.
+//
+// Faucet URL resolution precedence at render time (top wins):
+//  1. FaucetURLs[caip2]   — per-chain override
+//  2. FaucetURL           — global override
+//  3. The mechanism's curated chain registry (e.g. NetworkConfigs for EVM)
+//     when the selected chain has a FaucetURL populated
+//  4. https://faucet.circle.com/  — final hardcoded fallback
 type PaywallConfig struct {
 	AppName    string `json:"appName,omitempty"`
 	AppLogo    string `json:"appLogo,omitempty"`
 	CurrentURL string `json:"currentUrl,omitempty"`
 	Testnet    bool   `json:"testnet,omitempty"`
+	// FaucetURL is a global override applied to every chain in the paywall.
+	FaucetURL string `json:"faucetUrl,omitempty"`
+	// FaucetURLs is a per-chain override map keyed by CAIP-2 identifier
+	// (e.g. "eip155:84532"). Wins over FaucetURL for the selected chain.
+	FaucetURLs map[string]string `json:"faucetUrls,omitempty"`
 }
 
 // DynamicPayToFunc is a function that resolves payTo address dynamically based on request context
@@ -962,12 +974,16 @@ func (s *x402HTTPResourceServer) generatePaywallHTML(paymentRequired x402.Paymen
 	appLogo := ""
 	testnet := false
 	currentURL := ""
+	faucetURL := ""
+	var faucetURLs map[string]string
 
 	if config != nil {
 		appName = config.AppName
 		appLogo = config.AppLogo
 		testnet = config.Testnet
 		currentURL = config.CurrentURL
+		faucetURL = config.FaucetURL
+		faucetURLs = config.FaucetURLs
 	}
 
 	// Use resource URL as currentUrl if not explicitly configured
@@ -986,7 +1002,9 @@ func (s *x402HTTPResourceServer) generatePaywallHTML(paymentRequired x402.Paymen
 			amount: %.6f,
 			testnet: %t,
 			displayAmount: %.2f,
-			currentUrl: "%s"
+			currentUrl: "%s",
+			faucetUrl: %s,
+			faucetUrls: %s
 		};
 	</script>`,
 		string(requirementsJSON),
@@ -996,6 +1014,8 @@ func (s *x402HTTPResourceServer) generatePaywallHTML(paymentRequired x402.Paymen
 		testnet,
 		displayAmount,
 		html.EscapeString(currentURL),
+		marshalFaucetURL(faucetURL),
+		marshalFaucetURLs(faucetURLs),
 	)
 
 	// Select template based on network
@@ -1050,12 +1070,16 @@ func injectPaywallConfig(template string, paymentRequired types.PaymentRequired,
 	appLogo := ""
 	testnet := false
 	currentURL := ""
+	faucetURL := ""
+	var faucetURLs map[string]string
 
 	if config != nil {
 		appName = config.AppName
 		appLogo = config.AppLogo
 		testnet = config.Testnet
 		currentURL = config.CurrentURL
+		faucetURL = config.FaucetURL
+		faucetURLs = config.FaucetURLs
 	}
 
 	if currentURL == "" && paymentRequired.Resource != nil {
@@ -1072,7 +1096,9 @@ func injectPaywallConfig(template string, paymentRequired types.PaymentRequired,
 			amount: %.6f,
 			testnet: %t,
 			displayAmount: %.2f,
-			currentUrl: "%s"
+			currentUrl: "%s",
+			faucetUrl: %s,
+			faucetUrls: %s
 		};
 	</script>`,
 		string(requirementsJSON),
@@ -1082,11 +1108,37 @@ func injectPaywallConfig(template string, paymentRequired types.PaymentRequired,
 		testnet,
 		displayAmount,
 		html.EscapeString(currentURL),
+		marshalFaucetURL(faucetURL),
+		marshalFaucetURLs(faucetURLs),
 	)
 
 	return strings.Replace(template, "</head>", configScript+"\n</head>", 1)
 }
 
+// marshalFaucetURL renders FaucetURL as a JS literal: a JSON-quoted string or `undefined`.
+func marshalFaucetURL(url string) string {
+	if url == "" {
+		return "undefined"
+	}
+	encoded, err := json.Marshal(url)
+	if err != nil {
+		return "undefined"
+	}
+	return string(encoded)
+}
+
+// marshalFaucetURLs renders FaucetURLs as a JS literal: a JSON object or `undefined`.
+func marshalFaucetURLs(urls map[string]string) string {
+	if len(urls) == 0 {
+		return "undefined"
+	}
+	encoded, err := json.Marshal(urls)
+	if err != nil {
+		return "undefined"
+	}
+	return string(encoded)
+}
+
 // ============================================================================
 // Utility Functions
 // ============================================================================

go/http/paywall_test.go

@@ -106,10 +106,11 @@ var (
 		"eip155:84532": {
 			ChainID: ChainIDBaseSepolia,
 			DefaultAsset: AssetInfo{
-				Address:  "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // USDC on Base Sepolia
-				Name:     "USDC",
-				Version:  "2",
-				Decimals: DefaultDecimals,
+				Address:   "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // USDC on Base Sepolia
+				Name:      "USDC",
+				Version:   "2",
+				Decimals:  DefaultDecimals,
+				FaucetURL: "https://faucet.circle.com/",
 			},
 		},
 		// MegaETH Mainnet (uses Permit2 instead of EIP-3009, supports EIP-2612)
@@ -144,6 +145,7 @@ var (
 				Decimals:            18,
 				AssetTransferMethod: AssetTransferMethodPermit2,
 				SupportsEip2612:     true,
+				FaucetURL:           "https://faucet.test.mezo.org/",
 			},
 		},
 		// Stable Mainnet
@@ -160,10 +162,11 @@ var (
 		"eip155:2201": {
 			ChainID: ChainIDStableTestnet,
 			DefaultAsset: AssetInfo{
-				Address:  "0x78Cf24370174180738C5B8E352B6D14c83a6c9A9", // USDT0 on Stable Testnet
-				Name:     "USDT0",
-				Version:  "1",
-				Decimals: DefaultDecimals,
+				Address:   "0x78Cf24370174180738C5B8E352B6D14c83a6c9A9", // USDT0 on Stable Testnet
+				Name:      "USDT0",
+				Version:   "1",
+				Decimals:  DefaultDecimals,
+				FaucetURL: "https://faucet.stable.xyz/faucet",
 			},
 		},
 		// Polygon Mainnet
@@ -190,10 +193,11 @@ var (
 		"eip155:421614": {
 			ChainID: ChainIDArbSepolia,
 			DefaultAsset: AssetInfo{
-				Address:  "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d", // USDC on ArbSepolia
-				Name:     "USD Coin",
-				Version:  "2",
-				Decimals: DefaultDecimals,
+				Address:   "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d", // USDC on ArbSepolia
+				Name:      "USD Coin",
+				Version:   "2",
+				Decimals:  DefaultDecimals,
+				FaucetURL: "https://faucet.circle.com/",
 			},
 		},
 	}

go/http/server.go

@@ -303,6 +303,12 @@ type AssetInfo struct {
 	Decimals            int
 	AssetTransferMethod AssetTransferMethod
 	SupportsEip2612     bool
+	// FaucetURL is the optional faucet URL for this chain's default asset.
+	// Surfaces in the paywall's testnet "Need {token} on {chain}? Get some
+	// here." link when no consumer override is supplied. Only meaningful for
+	// testnet chains (mainnet entries leave this empty since the paywall
+	// faucet UI is testnet-gated).
+	FaucetURL string
 }
 
 // NetworkConfig contains network-specific configuration

go/http/svm_paywall_template.go

@@ -86,19 +86,21 @@ var (
 			CAIP2:  SolanaDevnetCAIP2,
 			RPCURL: "https://api.devnet.solana.com",
 			DefaultAsset: AssetInfo{
-				Address:  USDCDevnetAddress,
-				Symbol:   "USDC",
-				Decimals: DefaultDecimals,
+				Address:   USDCDevnetAddress,
+				Symbol:    "USDC",
+				Decimals:  DefaultDecimals,
+				FaucetURL: "https://faucet.circle.com/",
 			},
 		},
 		SolanaTestnetCAIP2: {
 			Name:   "Solana Testnet",
 			CAIP2:  SolanaTestnetCAIP2,
 			RPCURL: "https://api.testnet.solana.com",
 			DefaultAsset: AssetInfo{
-				Address:  USDCTestnetAddress,
-				Symbol:   "USDC",
-				Decimals: DefaultDecimals,
+				Address:   USDCTestnetAddress,
+				Symbol:    "USDC",
+				Decimals:  DefaultDecimals,
+				FaucetURL: "https://faucet.circle.com/",
 			},
 		},
 	}

go/mechanisms/evm/constants.go

@@ -59,6 +59,12 @@ type AssetInfo struct {
 	Address  string // Mint address
 	Symbol   string // Token symbol (e.g., "USDC")
 	Decimals int    // Token decimals
+	// FaucetURL is the optional faucet URL for this network's default asset.
+	// Surfaces in the paywall's testnet "Need {token} on {chain}? Get some
+	// here." link when no consumer override is supplied. Only meaningful for
+	// non-mainnet networks (mainnet entries leave this empty since the
+	// paywall faucet UI is testnet-gated).
+	FaucetURL string
 }
 
 // NetworkConfig contains network-specific configuration