x402-rails 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b70874283a564f69295e16df7dcb11d4764480c62151f130335ee3d116d62f5
-  data.tar.gz: e4462c35ac33efc1993f166fa407b1e06f1b1fa35e3ba6547afce9031c07d3c4
+  metadata.gz: 71561f4eae4f693705a405fd47e2b51a493441abd96dfe5a7d415915cdaa1313
+  data.tar.gz: 251fa92d63aaaa4e944040192b55b1db1ed154cb26d62aaac7f86a200bbc5e07
 SHA512:
-  metadata.gz: fb7d7df8bda864f433e062f41cc1e956c6a979446e02bd3bb88ef5bccc2ac42e06a2933a5cafe7b7475b53665d360b5bc034b80e4c9c9ff10b668df1f61a106d
-  data.tar.gz: ea4523288ae8c5242fb03c90f1bc83f41779d46c170354cf2a3ccfdbaaf34da3f6656a03ab4b47d01f0d11e01e4adf1da4a52b405ddf25aa12f91270f11a6eaf
+  metadata.gz: 753e8a4957ebbc21189826904e370ef90ae618aca1078c0889351aa6841106bffc237ee1a893eeba745c8d75773c30f25d083d4e033466ef2a0f3d327f4c239e
+  data.tar.gz: 359cdbfd614777f9004a96aa4b2d5b9eff290266247707d9b886cafd1731bd3fa667625e641da16ea9383e5c3d2a3e74d79c0cf068a9be455ad4115a10715b19

data/README.md

@@ -8,7 +8,7 @@
 
 Accept instant blockchain micropayments in your Rails applications using the [x402 payment protocol](https://www.x402.org/).
 
-Supports Base, avalanche, and other blockchain networks.
+Supports 18 networks including Base, Polygon, Avalanche, Sei, Solana, and more.
 
 ## Features
 
@@ -18,7 +18,7 @@ Supports Base, avalanche, and other blockchain networks.
 - **$0.001 minimum** payment amounts
 - **Optimistic & non-optimistic** settlement modes
 - **Automatic settlement** after successful responses
-- **Browser paywall** and API support
+- **API paywall** with 402 payment-required responses
 - **Rails 7.0+** compatible
 
 ## Example Video
@@ -145,7 +145,10 @@ X402.configure do |config|
   config.facilitator = ENV.fetch("X402_FACILITATOR_URL", "https://x402.org/facilitator")
 
   # Blockchain network (default: "base-sepolia")
-  # Options: "base-sepolia", "base", "avalanche-fuji", "avalanche"
+  # Built-in: base, base-sepolia, polygon, polygon-amoy, avalanche, avalanche-fuji,
+  #           sei, sei-testnet, iotex, peaq, xlayer, xlayer-testnet,
+  #           skale-base, skale-base-sepolia, kiteai, kiteai-testnet,
+  #           solana, solana-devnet
   config.chain = ENV.fetch("X402_CHAIN", "base-sepolia")
 
   # Payment token (default: "USDC")
@@ -165,7 +168,7 @@ end
 | ---------------- | -------- | -------------------------------- | --------------------------------------------------------------------------------- |
 | `wallet_address` | **Yes**  | -                                | Your Ethereum wallet address where payments will be received                      |
 | `facilitator`    | No       | `"https://x402.org/facilitator"` | Facilitator service URL for payment verification and settlement                   |
-| `chain`          | No       | `"base-sepolia"`                 | Blockchain network to use (`base-sepolia`, `base`, `avalanche-fuji`, `avalanche`) |
+| `chain`          | No       | `"base-sepolia"`                 | Blockchain network (see built-in list above) |
 | `currency`       | No       | `"USDC"`                         | Payment token symbol (currently only USDC supported)                              |
 | `optimistic`     | No       | `true`                           | Settlement mode (see Optimistic vs Non-Optimistic Mode below)                     |
 | `version`        | No       | `2`                              | Protocol version (1 or 2). See Protocol Versions section                          |
@@ -176,30 +179,30 @@ You can register custom EVM chains and tokens beyond the built-in options.
 
 #### Register a Custom Chain
 
-Add support for any EVM-compatible chain:
+Add support for any EVM-compatible chain beyond the 18 built-in networks:
 
 ```ruby
 X402.configure do |config|
   config.wallet_address = ENV['X402_WALLET_ADDRESS']
 
-  # Register Polygon mainnet
+  # Register Arbitrum (not built-in)
   config.register_chain(
-    name: "polygon",
-    chain_id: 137,
+    name: "arbitrum",
+    chain_id: 42161,
     standard: "eip155"
   )
 
   # Register the token for that chain
   config.register_token(
-    chain: "polygon",
+    chain: "arbitrum",
     symbol: "USDC",
-    address: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+    address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
     decimals: 6,
     name: "USD Coin",
     version: "2"
   )
 
-  config.chain = "polygon"
+  config.chain = "arbitrum"
   config.currency = "USDC"
 end
 ```
@@ -250,20 +253,21 @@ Allow clients to pay on any of several supported chains by using `config.accept(
 X402.configure do |config|
   config.wallet_address = ENV['X402_WALLET_ADDRESS']
 
-  # Register a custom chain
-  config.register_chain(name: "polygon-amoy", chain_id: 80002, standard: "eip155")
+  # Register a custom chain not included in the built-in list
+  config.register_chain(name: "arbitrum", chain_id: 42161, standard: "eip155")
   config.register_token(
-    chain: "polygon-amoy",
+    chain: "arbitrum",
     symbol: "USDC",
-    address: "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
+    address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
     decimals: 6,
     name: "USD Coin",
     version: "2"
   )
 
-  # Accept payments on multiple chains
+  # Accept payments on multiple chains (built-in + custom)
   config.accept(chain: "base-sepolia", currency: "USDC")
   config.accept(chain: "polygon-amoy", currency: "USDC")
+  config.accept(chain: "arbitrum", currency: "USDC")
 end
 ```
 
@@ -356,8 +360,26 @@ X402_FACILITATOR_URL=https://x402.org/facilitator
 X402_CHAIN=base-sepolia
 X402_CURRENCY=USDC
 X402_OPTIMISTIC=true  # "true" or "false"
+
+# Solana fee payer overrides (required when using a non-default facilitator)
+# The default fee payer is for the Coinbase facilitator (x402.org).
+# Each facilitator manages its own fee payer — check your facilitator's /supported endpoint.
+X402_FEE_PAYER=                     # Global override for all Solana chains
+X402_SOLANA_FEE_PAYER=              # Solana mainnet override
+X402_SOLANA_DEVNET_FEE_PAYER=       # Solana devnet override
+
+# Example: PayAI facilitator (https://facilitator.payai.network)
+# X402_FACILITATOR_URL=https://facilitator.payai.network
+# X402_SOLANA_FEE_PAYER=2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4
+# X402_SOLANA_DEVNET_FEE_PAYER=2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4
 ```
 
+Fee payer lookup priority:
+1. `config.fee_payer` (programmatic, global)
+2. Per-chain ENV variable (e.g., `X402_SOLANA_DEVNET_FEE_PAYER`)
+3. `X402_FEE_PAYER` (ENV, global)
+4. Built-in default from chain config
+
 ## Examples
 
 ### Weather API
@@ -419,6 +441,8 @@ The gem raises these errors:
 - [x402 Protocol Docs](https://docs.cdp.coinbase.com/x402)
 - [GitHub Repository](https://github.com/coinbase/x402)
 - [Facilitator API](https://x402.org/facilitator)
+- [Step-by-Step Rails Integration Guide](https://www.quicknode.com/guides/infrastructure/x402-payment-integration-with-rails)
+
 
 ## License
 

data/lib/x402/chains.rb

@@ -1,91 +1,160 @@
 # frozen_string_literal: true
 
 module X402
-  # Chain configurations for supported networks
+  # Currency config constants for EIP-712 signature domain.
+  # The `name` field must match the on-chain ERC-20 name() return value.
+  # The `version` field must match the EIP-712 domain version.
+  USDC_NAMED_USD_COIN_V2 = { symbol: "USDC", decimals: 6, name: "USD Coin", version: "2" }.freeze
+  USDC_NAMED_USDC_V2 = { symbol: "USDC", decimals: 6, name: "USDC", version: "2" }.freeze
+  USDC_NAMED_USDC = { symbol: "USDC", decimals: 6, name: "USDC", version: nil }.freeze
+  USDC_NAMED_USD_COIN = { symbol: "USDC", decimals: 6, name: "USD Coin", version: nil }.freeze
+
+  # Unified chain registry — single source of truth for all chain metadata.
+  # Each entry contains: chain_id, caip2, currency, and optionally usdc_address, explorer_url, fee_payer.
   CHAINS = {
+    # --- Base ---
+    "base" => {
+      chain_id: 8453,
+      caip2: "eip155:8453",
+      usdc_address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+      explorer_url: "https://basescan.org",
+      currency: USDC_NAMED_USD_COIN_V2,
+    },
     "base-sepolia" => {
       chain_id: 84532,
+      caip2: "eip155:84532",
       usdc_address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
-      explorer_url: "https://sepolia.basescan.org"
+      explorer_url: "https://sepolia.basescan.org",
+      currency: USDC_NAMED_USDC_V2,
     },
-    "base" => {
-      chain_id: 8453,
-      usdc_address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-      explorer_url: "https://basescan.org"
+
+    # --- Polygon ---
+    "polygon" => {
+      chain_id: 137,
+      caip2: "eip155:137",
+      usdc_address: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+      explorer_url: "https://polygonscan.com",
+      currency: USDC_NAMED_USD_COIN_V2,
     },
-    "avalanche-fuji" => {
-      chain_id: 43113,
-      usdc_address: "0x5425890298aed601595a70AB815c96711a31Bc65",
-      explorer_url: "https://testnet.snowtrace.io"
+    "polygon-amoy" => {
+      chain_id: 80002,
+      caip2: "eip155:80002",
+      usdc_address: "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
+      explorer_url: "https://amoy.polygonscan.com",
+      currency: USDC_NAMED_USDC_V2,
     },
+
+    # --- Avalanche ---
     "avalanche" => {
       chain_id: 43114,
+      caip2: "eip155:43114",
       usdc_address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
-      explorer_url: "https://snowtrace.io"
+      explorer_url: "https://snowtrace.io",
+      currency: USDC_NAMED_USDC_V2,
     },
-    "solana-devnet" => {
-      chain_id: 103,
-      usdc_address: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
-      explorer_url: "https://explorer.solana.com/?cluster=devnet",
-      fee_payer: "CKPKJWNdJEqa81x7CkZ14BVPiY6y16Sxs7owznqtWYp5"
+    "avalanche-fuji" => {
+      chain_id: 43113,
+      caip2: "eip155:43113",
+      usdc_address: "0x5425890298aed601595a70AB815c96711a31Bc65",
+      explorer_url: "https://testnet.snowtrace.io",
+      currency: USDC_NAMED_USD_COIN_V2,
     },
-    "solana" => {
-      chain_id: 101,
-      usdc_address: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
-      explorer_url: "https://explorer.solana.com",
-      fee_payer: "CKPKJWNdJEqa81x7CkZ14BVPiY6y16Sxs7owznqtWYp5"
-    }
-  }.freeze
 
-  # Currency configurations by chain
-  CURRENCY_BY_CHAIN = {
-    "base-sepolia" => {
-      symbol: "USDC",
-      decimals: 6,
-      name: "USDC",  # Testnet uses "USDC"
-      version: "2"
+    # --- Sei ---
+    "sei" => {
+      chain_id: 1329,
+      caip2: "eip155:1329",
+      usdc_address: "0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392",
+      explorer_url: "https://seitrace.com",
+      currency: USDC_NAMED_USDC,
     },
-    "base" => {
-      symbol: "USDC",
-      decimals: 6,
-      name: "USD Coin",  # Mainnet uses "USD Coin"
-      version: "2"
+    "sei-testnet" => {
+      chain_id: 713715,
+      caip2: "eip155:713715",
+      explorer_url: "https://seitrace.com/?chain=arctic-1",
+      currency: USDC_NAMED_USDC,
     },
-    "avalanche-fuji" => {
-      symbol: "USDC",
-      decimals: 6,
-      name: "USD Coin",  # Testnet uses "USD Coin"
-      version: "2"
+
+    # --- X Layer ---
+    "xlayer" => {
+      chain_id: 196,
+      caip2: "eip155:196",
+      explorer_url: "https://www.oklink.com/xlayer",
+      currency: USDC_NAMED_USDC,
     },
-    "avalanche" => {
-      symbol: "USDC",
-      decimals: 6,
-      name: "USDC",  # Mainnet uses "USDC"
-      version: "2"
+    "xlayer-testnet" => {
+      chain_id: 1952,
+      caip2: "eip155:1952",
+      explorer_url: "https://www.oklink.com/xlayer-test",
+      currency: USDC_NAMED_USDC,
     },
-    "solana-devnet" => {
-      symbol: "USDC",
-      decimals: 6,
-      name: "USDC",
-      version: nil
+
+    # --- SKALE ---
+    "skale-base" => {
+      chain_id: 1_187_947_933,
+      caip2: "eip155:1187947933",
+      explorer_url: "https://skale-base-explorer.skalenodes.com",
+      currency: USDC_NAMED_USDC,
+    },
+    "skale-base-sepolia" => {
+      chain_id: 324_705_682,
+      caip2: "eip155:324705682",
+      explorer_url: "https://base-sepolia-testnet-explorer.skalenodes.com",
+      currency: USDC_NAMED_USDC,
+    },
+
+    # --- KiteAI ---
+    "kiteai" => {
+      chain_id: 2366,
+      caip2: "eip155:2366",
+      explorer_url: "https://kitescan.ai",
+      currency: USDC_NAMED_USDC,
+    },
+    "kiteai-testnet" => {
+      chain_id: 2368,
+      caip2: "eip155:2368",
+      explorer_url: "https://testnet.kitescan.ai",
+      currency: USDC_NAMED_USDC,
+    },
+
+    # --- IoTeX (mainnet only) ---
+    "iotex" => {
+      chain_id: 4689,
+      caip2: "eip155:4689",
+      explorer_url: "https://iotexscan.io",
+      currency: USDC_NAMED_USDC,
     },
-    "solana" => {
-      symbol: "USDC",
-      decimals: 6,
-      name: "USD Coin",
-      version: nil
-    }
-  }.freeze
 
-  CAIP2_MAPPING = {
-    "base-sepolia" => "eip155:84532",
-    "base" => "eip155:8453",
-    "avalanche-fuji" => "eip155:43113",
-    "avalanche" => "eip155:43114",
-    "solana-devnet" => "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
-    "solana" => "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
+    # --- Peaq (mainnet only) ---
+    "peaq" => {
+      chain_id: 3338,
+      caip2: "eip155:3338",
+      explorer_url: "https://peaq.subscan.io",
+      currency: USDC_NAMED_USDC,
+    },
+
+    # --- Solana ---
+    "solana" => {
+      chain_id: 101,
+      caip2: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+      usdc_address: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+      explorer_url: "https://explorer.solana.com",
+      fee_payer: "CKPKJWNdJEqa81x7CkZ14BVPiY6y16Sxs7owznqtWYp5",
+      currency: USDC_NAMED_USD_COIN,
+    },
+    "solana-devnet" => {
+      chain_id: 103,
+      caip2: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+      usdc_address: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
+      explorer_url: "https://explorer.solana.com/?cluster=devnet",
+      fee_payer: "CKPKJWNdJEqa81x7CkZ14BVPiY6y16Sxs7owznqtWYp5",
+      currency: USDC_NAMED_USDC,
+    },
   }.freeze
 
+  # Derived lookups for backwards compatibility
+  CURRENCY_BY_CHAIN = CHAINS.transform_values { |v| v[:currency] }.freeze
+  CAIP2_MAPPING = CHAINS.transform_values { |v| v[:caip2] }.freeze
   REVERSE_CAIP2_MAPPING = CAIP2_MAPPING.invert.freeze
 
   class << self
@@ -97,7 +166,10 @@ module X402
     end
 
     def currency_config_for_chain(chain_name)
-      CURRENCY_BY_CHAIN[chain_name] || raise(ConfigurationError, "Unsupported chain for currency: #{chain_name}")
+      config = CHAINS[chain_name]
+      raise(ConfigurationError, "Unsupported chain for currency: #{chain_name}") unless config
+
+      config[:currency]
     end
 
     def supported_chains
@@ -129,8 +201,9 @@ module X402
       custom = X402.configuration.token_config(chain_name, symbol)
       return custom if custom
 
-      if symbol.upcase == "USDC" && CURRENCY_BY_CHAIN[chain_name]
-        currency_config_for_chain(chain_name)
+      config = CHAINS[chain_name]
+      if symbol.upcase == "USDC" && config&.dig(:currency)
+        config[:currency]
       else
         raise ConfigurationError, "Unknown token #{symbol} for chain #{chain_name}. Register with config.register_token()"
       end

data/lib/x402/configuration.rb

@@ -13,7 +13,7 @@ module X402
       @currency = ENV.fetch("X402_CURRENCY", "USDC")
       @optimistic = ENV.fetch("X402_OPTIMISTIC", "false") == "true"
       @version = ENV.fetch("X402_VERSION", "2").to_i
-      @fee_payer = ENV.fetch("X402_FEE_PAYER", nil)
+      @fee_payer = nil
       @custom_chains = {}
       @custom_tokens = {}
       @accepted_payments = []

data/lib/x402/rails/version.rb

@@ -2,6 +2,6 @@
 
 module X402
   module Rails
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: x402-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - QuickNode
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-01-08 00:00:00.000000000 Z
+date: 2026-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -123,7 +123,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '6.0'
 description: Accept instant blockchain micropayments in Rails applications using the
-  x402 protocol.
+  x402 protocol (supporting x402 v2)
 email:
 - zach+x402@quiknode.io
 executables: []
@@ -162,7 +162,7 @@ metadata:
   homepage_uri: https://github.com/quiknode-labs/x402-rails
   source_code_uri: https://github.com/quiknode-labs/x402-rails
   documentation_uri: https://github.com/quiknode-labs/x402-rails#readme
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -177,8 +177,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: Rails integration for x402 payment protocol (supporting x402 v2).
 test_files: []