x402-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 411abe38109c401d64e94078fd5b69bb3937b78e7bb6b1518921897ca28ad904
+  data.tar.gz: 2fe5f74f481df1a9b2e74cbd268ad02033d5250f9624eeb7a4912742409a53a5
+SHA512:
+  metadata.gz: f1bbcaee8f5a30a99fb857f9983bc6ec638d9a6f10c2651e14ab65e3bb68bd4087fac81c5c2db25b1cabd1c92209cb6754a82b369e9f76dbf21998a43cf303c3
+  data.tar.gz: ac5aa6785d6cf1a9284cd4ac776200199d7c53696ae462c3775e226218727be30cbc2acabd39329aec6d8ec6918805fd52b609cddd185262d159b46856817da8

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Quicknode, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,236 @@
+# x402-rails
+
+![Coverage](./coverage/coverage.svg)
+
+Accept instant blockchain micropayments in your Rails applications using the [x402 payment protocol](https://www.x402.org/).
+
+Supports Base, avalanche, and other blockchain networks.
+
+## Features
+
+- **1 line of code** to accept digital dollars (USDC)
+- **No fees** on supported networks (Base)
+- **~1 second** response times (optimistic mode)
+- **$0.001 minimum** payment amounts
+- **Optimistic & non-optimistic** settlement modes
+- **Automatic settlement** after successful responses
+- **Browser paywall** and API support
+- **Rails 7.0+** compatible
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'x402-rails'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### 1. Configure the gem
+
+Create `config/initializers/x402.rb`:
+
+```ruby
+X402.configure do |config|
+  config.wallet_address = ENV['X402_WALLET_ADDRESS']  # Your recipient wallet
+  config.facilitator = "https://x402.org/facilitator"
+  config.chain = "base-sepolia"  # or "base" for base mainnet
+  config.currency = "USDC"
+  config.optimistic = false  # Forces to check for settlement before giving response.
+end
+```
+
+### 2. Protect your endpoints
+
+Use `x402_paywall` in any controller action:
+
+```ruby
+class ApiController < ApplicationController
+  def weather
+    x402_paywall(amount: 0.001)  # $0.001 in USD
+
+    render json: {
+      temperature: 72,
+      paid_by: request.env['x402.payment'][:payer]
+    }
+  end
+end
+```
+
+That's it! Your endpoint now requires payment.
+
+## Usage Patterns
+
+### Direct Method Call
+
+Call `x402_paywall` in any action:
+
+```ruby
+def show
+  x402_paywall(amount: 0.01)
+  # Action continues after payment verified
+  render json: @data
+end
+```
+
+### Before Action Hook
+
+Protect multiple actions:
+
+```ruby
+class PremiumController < ApplicationController
+  before_action :require_payment, only: [:show, :index]
+
+  def show
+    # Payment already verified
+    render json: @premium_content
+  end
+
+  private
+
+  def require_payment
+    x402_paywall(amount: 0.001, chain: "base")
+  end
+end
+```
+
+### Per-Action Pricing
+
+Different prices for different actions:
+
+```ruby
+def basic_data
+  x402_paywall(amount: 0.001)
+  render json: basic_info
+end
+
+def premium_data
+  x402_paywall(amount: 0.01)
+  render json: premium_info
+end
+```
+
+## Configuration Options
+
+### Global Configuration
+
+Set defaults in `config/initializers/x402.rb`:
+
+```ruby
+X402.configure do |config|
+  # Required: Your wallet address where payments will be received
+  config.wallet_address = ENV['X402_WALLET_ADDRESS']
+
+  # Facilitator service URL (default: "https://x402.org/facilitator")
+  config.facilitator = ENV.fetch("X402_FACILITATOR_URL", "https://x402.org/facilitator")
+
+  # Blockchain network (default: "base-sepolia")
+  # Options: "base-sepolia", "base", "avalanche-fuji", "avalanche"
+  config.chain = ENV.fetch("X402_CHAIN", "base-sepolia")
+
+  # Payment token (default: "USDC")
+  # Currently only USDC is supported
+  config.currency = ENV.fetch("X402_CURRENCY","USDC")
+
+  # Optimistic mode (default: true)
+  # true: Fast response, settle payment after response is sent
+  # false: Wait for blockchain settlement before sending response
+  config.optimistic = ENV.fetch("X402_OPTIMISTIC",false)
+end
+```
+
+### Configuration Attributes
+
+| Attribute        | Required | Default                          | Description                                                                       |
+| ---------------- | -------- | -------------------------------- | --------------------------------------------------------------------------------- |
+| `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`) |
+| `currency`       | No       | `"USDC"`                         | Payment token symbol (currently only USDC supported)                              |
+| `optimistic`     | No       | `true`                           | Settlement mode (see Optimistic vs Non-Optimistic Mode below)                     |
+
+## Environment Variables
+
+Configure via environment variables:
+
+```bash
+# Required
+X402_WALLET_ADDRESS=0xYourAddress
+
+# Optional (with defaults)
+X402_FACILITATOR_URL=https://x402.org/facilitator
+X402_CHAIN=base-sepolia
+X402_CURRENCY=USDC
+X402_OPTIMISTIC=true  # "true" or "false"
+```
+
+## Examples
+
+### Weather API
+
+```ruby
+class WeatherController < ApplicationController
+  def current
+    x402_paywall(amount: 0.001)
+    render json: { temp: 72, condition: "sunny" }
+  end
+
+  def forecast
+    x402_paywall(amount: 0.01)
+    render json: { forecast: [...] }
+  end
+end
+```
+
+## x402 Architecture
+
+```
+┌──────────┐      ┌──────────┐      ┌─────────────┐
+│  Client  │─────▶│   Rails  │─────▶│ Facilitator │
+│          │      │   x402   │      │   (x402.org) │
+└──────────┘      └──────────┘      └─────────────┘
+     │                  │                    │
+     │                  │                    ▼
+     │                  │             ┌──────────────┐
+     │                  │             │  Blockchain  │
+     │                  │             │   (Base)     │
+     └──────────────────┴─────────────┴──────────────┘
+```
+
+## Error Handling
+
+The gem raises these errors:
+
+- `X402::ConfigurationError` - Invalid configuration
+- `X402::InvalidPaymentError` - Invalid payment payload
+- `X402::FacilitatorError` - Facilitator communication issues
+
+## Security
+
+- Payments validated via EIP-712 signatures
+- Nonce prevents replay attacks
+- Time windows limit authorization validity
+- Facilitator verifies all parameters
+- Settlement happens on-chain (immutable)
+
+## Requirements
+
+- Ruby 3.0+
+- Rails 7.0+
+
+## Resources
+
+- [x402 Protocol Docs](https://docs.cdp.coinbase.com/x402)
+- [GitHub Repository](https://github.com/coinbase/x402)
+- [Facilitator API](https://x402.org/facilitator)
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/coverage/coverage.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="94" height="20">
+<linearGradient id="b" x2="0" y2="100%">
+  <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+  <stop offset="1" stop-opacity=".1"/>
+</linearGradient>
+<clipPath id="a">
+  <rect width="94" height="20" rx="3" fill="#fff"/>
+</clipPath>
+<g clip-path="url(#a)">
+  <path fill="#555" d="M0 0h59v20H0z"/>
+  <path fill="#4c1" d="M59 0h35v20H59z"/>
+  <path fill="url(#b)" d="M0 0h94v20H0z"/>
+</g>
+<g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110">
+  <text x="305" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="490">coverage</text>
+  <text x="305" y="140" transform="scale(.1)" textLength="490">coverage</text>
+  <text x="755" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="250">100%</text>
+  <text x="755" y="140" transform="scale(.1)" textLength="250">100%</text></g>
+</svg>

data/lib/x402/chains.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module X402
+  # Chain configurations for supported networks
+  CHAINS = {
+    "base-sepolia" => {
+      chain_id: 84532,
+      rpc_url: "https://sepolia.base.org",
+      usdc_address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+      explorer_url: "https://sepolia.basescan.org"
+    },
+    "base" => {
+      chain_id: 8453,
+      rpc_url: "https://mainnet.base.org",
+      usdc_address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+      explorer_url: "https://basescan.org"
+    },
+    "avalanche-fuji" => {
+      chain_id: 43113,
+      rpc_url: "https://api.avax-test.network/ext/bc/C/rpc",
+      usdc_address: "0x5425890298aed601595a70AB815c96711a31Bc65",
+      explorer_url: "https://testnet.snowtrace.io"
+    },
+    "avalanche" => {
+      chain_id: 43114,
+      rpc_url: "https://api.avax.network/ext/bc/C/rpc",
+      usdc_address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
+      explorer_url: "https://snowtrace.io"
+    }
+  }.freeze
+
+  # Currency configurations by chain
+  CURRENCY_BY_CHAIN = {
+    "base-sepolia" => {
+      symbol: "USDC",
+      decimals: 6,
+      name: "USDC",  # Testnet uses "USDC"
+      version: "2"
+    },
+    "base" => {
+      symbol: "USDC",
+      decimals: 6,
+      name: "USD Coin",  # Mainnet uses "USD Coin"
+      version: "2"
+    },
+    "avalanche-fuji" => {
+      symbol: "USDC",
+      decimals: 6,
+      name: "USD Coin",  # Testnet uses "USD Coin"
+      version: "2"
+    },
+    "avalanche" => {
+      symbol: "USDC",
+      decimals: 6,
+      name: "USDC",  # Mainnet uses "USDC"
+      version: "2"
+    }
+  }.freeze
+
+  class << self
+    def chain_config(chain_name)
+      CHAINS[chain_name] || raise(ConfigurationError, "Unsupported chain: #{chain_name}")
+    end
+
+    def currency_config_for_chain(chain_name)
+      CURRENCY_BY_CHAIN[chain_name] || raise(ConfigurationError, "Unsupported chain for currency: #{chain_name}")
+    end
+
+    def supported_chains
+      CHAINS.keys
+    end
+
+    def usdc_address_for(chain_name)
+      chain_config(chain_name)[:usdc_address]
+    end
+
+    def currency_decimals_for_chain(chain_name)
+      currency_config_for_chain(chain_name)[:decimals]
+    end
+  end
+end

data/lib/x402/configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module X402
+  class Configuration
+    attr_accessor :wallet_address, :facilitator, :chain, :currency, :optimistic
+
+    def initialize
+      @wallet_address = ENV.fetch("X402_WALLET_ADDRESS", nil)
+      @facilitator = ENV.fetch("X402_FACILITATOR_URL", "https://x402.org/facilitator")
+      @chain = ENV.fetch("X402_CHAIN", "base-sepolia")
+      @currency = ENV.fetch("X402_CURRENCY", "USDC")
+      @optimistic = ENV.fetch("X402_OPTIMISTIC", "false") == "true"  # Default to optimistic mode (fast response, settle after)
+    end
+
+    def validate!
+      raise ConfigurationError, "wallet_address is required" if wallet_address.nil? || wallet_address.empty?
+      raise ConfigurationError, "facilitator URL is required" if facilitator.nil? || facilitator.empty?
+      raise ConfigurationError, "chain is required" if chain.nil? || chain.empty?
+      raise ConfigurationError, "currency is required" if currency.nil? || currency.empty?
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+
+  class ConfigurationError < StandardError; end
+end

data/lib/x402/facilitator_client.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module X402
+  class FacilitatorClient
+    attr_reader :facilitator_url
+
+    def initialize(facilitator_url = nil)
+      @facilitator_url = facilitator_url || X402.configuration.facilitator
+    end
+
+    def verify(payment_payload, payment_requirements)
+      request_body = {
+        x402Version: payment_payload.x402_version,
+        paymentPayload: payment_payload.to_h,
+        paymentRequirements: payment_requirements
+      }
+
+      ::Rails.logger.info("=== X402 Verify Request ===")
+      ::Rails.logger.info("URL: #{facilitator_url}/verify")
+      ::Rails.logger.info("Request body: #{request_body.to_json}")
+
+      response = connection.post("verify") do |req|
+        req.headers["Content-Type"] = "application/json"
+        req.body = request_body.to_json
+      end
+
+      ::Rails.logger.info("Response status: #{response.status}")
+      ::Rails.logger.info("Response body: #{response.body}")
+
+      handle_response(response, "verify")
+    rescue Faraday::Error => e
+      raise FacilitatorError, "Failed to verify payment: #{e.message}"
+    end
+
+    def settle(payment_payload, payment_requirements)
+      request_body = {
+        x402Version: payment_payload.x402_version,
+        paymentPayload: payment_payload.to_h,
+        paymentRequirements: payment_requirements
+      }
+
+      ::Rails.logger.info("=== X402 Settlement Request ===")
+      ::Rails.logger.info("URL: #{facilitator_url}/settle")
+      ::Rails.logger.info("Request body: #{request_body.to_json}")
+
+      response = connection.post("settle") do |req|
+        req.headers["Content-Type"] = "application/json"
+        req.body = request_body.to_json
+      end
+
+      ::Rails.logger.info("Response status: #{response.status}")
+      ::Rails.logger.info("Response body: #{response.body}")
+
+      settlement_data = handle_response(response, "settle")
+      SettlementResponse.new(settlement_data)
+    rescue Faraday::Error => e
+      raise FacilitatorError, "Failed to settle payment: #{e.message}"
+    end
+
+    def supported_networks
+      response = connection.get("supported")
+      handle_response(response, "supported")
+    rescue Faraday::Error => e
+      raise FacilitatorError, "Failed to fetch supported networks: #{e.message}"
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: facilitator_url) do |faraday|
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+
+    def handle_response(response, action)
+      case response.status
+      when 200..299
+        JSON.parse(response.body)
+      when 400
+        error_body = JSON.parse(response.body) rescue {}
+        raise InvalidPaymentError, "Invalid payment: #{error_body['error'] || response.body}"
+      when 500..599
+        raise FacilitatorError, "Facilitator error (#{action}): #{response.status}"
+      else
+        raise FacilitatorError, "Unexpected response (#{action}): #{response.status}"
+      end
+    rescue JSON::ParserError => e
+      raise FacilitatorError, "Failed to parse facilitator response: #{e.message}"
+    end
+  end
+
+  class FacilitatorError < StandardError; end
+  class InvalidPaymentError < StandardError; end
+end

data/lib/x402/payment_payload.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module X402
+  class PaymentPayload
+    attr_accessor :x402_version, :scheme, :network, :payload
+
+    def initialize(attributes = {})
+      attrs = attributes.with_indifferent_access
+
+      @x402_version = attrs[:x402Version] || attrs[:x402_version] || 1
+      @scheme = attrs[:scheme]
+      @network = attrs[:network]
+      @payload = attrs[:payload]
+    end
+
+    def self.from_header(header_value)
+      return nil if header_value.nil? || header_value.empty?
+
+      begin
+        decoded = Base64.strict_decode64(header_value)
+        json = JSON.parse(decoded)
+        new(json)
+      rescue StandardError => e
+        raise InvalidPaymentError, "Failed to decode payment payload: #{e.message}"
+      end
+    end
+
+    def authorization
+      @authorization ||= payload&.with_indifferent_access&.[](:authorization)
+    end
+
+    def signature
+      payload&.with_indifferent_access&.[](:signature)
+    end
+
+    def from_address
+      authorization&.with_indifferent_access&.[](:from)
+    end
+
+    def to_address
+      authorization&.with_indifferent_access&.[](:to)
+    end
+
+    def value
+      authorization&.with_indifferent_access&.[](:value)
+    end
+
+    def valid_after
+      authorization&.with_indifferent_access&.[](:validAfter) || authorization&.with_indifferent_access&.[](:valid_after)
+    end
+
+    def valid_before
+      authorization&.with_indifferent_access&.[](:validBefore) || authorization&.with_indifferent_access&.[](:valid_before)
+    end
+
+    def nonce
+      authorization&.with_indifferent_access&.[](:nonce)
+    end
+
+    def to_h
+      {
+        x402Version: x402_version,
+        scheme: scheme,
+        network: network,
+        payload: payload
+      }
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end

data/lib/x402/payment_requirement.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module X402
+  class PaymentRequirement
+    attr_accessor :scheme, :network, :max_amount_required, :asset, :pay_to, :resource, :description, :max_timeout_seconds, :mime_type, :output_schema, :extra
+
+    def initialize(attributes = {})
+      attrs = attributes.with_indifferent_access
+
+      @scheme = attrs[:scheme] || "exact"
+      @network = attrs[:network]
+      @max_amount_required = attrs[:maxAmountRequired] || attrs[:max_amount_required]
+      @asset = attrs[:asset]
+      @pay_to = attrs[:payTo] || attrs[:pay_to]
+      @resource = attrs[:resource]
+      @description = attrs[:description]
+      @max_timeout_seconds = attrs[:maxTimeoutSeconds] || attrs[:max_timeout_seconds] || 600
+      @mime_type = attrs[:mimeType] || attrs[:mime_type] || "application/json"
+      @output_schema = attrs[:outputSchema] || attrs[:output_schema]
+      @extra = attrs[:extra]
+    end
+
+    def to_h
+      h = {
+        scheme: scheme,
+        network: network,
+        maxAmountRequired: max_amount_required.to_s,
+        asset: asset,
+        payTo: pay_to,
+        resource: resource,
+        description: description,
+        maxTimeoutSeconds: max_timeout_seconds,
+        mimeType: mime_type
+      }
+      h[:outputSchema] = output_schema if output_schema
+      h[:extra] = extra if extra
+      h
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end

data/lib/x402/payment_validator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module X402
+  class PaymentValidator
+    attr_reader :facilitator_client
+
+    def initialize(facilitator_client = nil)
+      @facilitator_client = facilitator_client || FacilitatorClient.new
+    end
+
+    def validate(payment_payload, requirement)
+      # Validate scheme
+      unless payment_payload.scheme == requirement.scheme
+        return validation_error("Scheme mismatch: expected #{requirement.scheme}, got #{payment_payload.scheme}")
+      end
+
+      # Validate network
+      unless payment_payload.network == requirement.network
+        return validation_error("Network mismatch: expected #{requirement.network}, got #{payment_payload.network}")
+      end
+
+      # Validate recipient address
+      unless payment_payload.to_address&.downcase == requirement.pay_to&.downcase
+        return validation_error("Recipient mismatch: expected #{requirement.pay_to}, got #{payment_payload.to_address}")
+      end
+
+      # Validate amount
+      payment_value = payment_payload.value.to_i
+      required_value = requirement.max_amount_required.to_i
+
+      if payment_value < required_value
+        return validation_error("Insufficient amount: expected at least #{required_value}, got #{payment_value}")
+      end
+
+      # Call facilitator to verify payment (does NOT settle on blockchain yet)
+      begin
+        verify_result = facilitator_client.verify(payment_payload, requirement.to_h)
+
+        unless verify_result["isValid"]
+          return validation_error("Facilitator validation failed: #{verify_result['invalidReason']}")
+        end
+
+        if verify_result["payer"].nil?
+          return validation_error("Verification failed: no payer address returned")
+        end
+
+        validation_success(verify_result["payer"], verify_result)
+      rescue InvalidPaymentError => e
+        validation_error("Facilitator validation failed: #{e.message}")
+      rescue FacilitatorError => e
+        validation_error("Facilitator error: #{e.message}")
+      end
+    end
+
+    private
+
+    def validation_success(payer_address, data = {})
+      {
+        valid: true,
+        payer: payer_address,
+        data: data
+      }
+    end
+
+    def validation_error(message)
+      {
+        valid: false,
+        error: message
+      }
+    end
+  end
+end

data/lib/x402/rails/controller_extensions.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module X402
+  module Rails
+    module ControllerExtensions
+      extend ActiveSupport::Concern
+
+      included do
+        after_action :settle_x402_payment_if_needed
+      end
+
+      def x402_paywall(options = {})
+        amount = options[:amount] or raise ArgumentError, "amount is required"
+        chain = options[:chain] || X402.configuration.chain
+        currency = options[:currency] || X402.configuration.currency
+
+        # Check if payment header is present
+        payment_header = request.headers["X-PAYMENT"]
+
+        if payment_header.nil? || payment_header.empty?
+          # No payment provided, return 402 with requirements
+          return render_payment_required(amount, chain, currency)
+        end
+
+        # Payment provided, validate it
+        process_payment(payment_header, amount, chain, currency)
+      end
+
+      private
+
+      def generate_payment_required_response(amount, chain, currency, error_message = nil)
+        requirement_response = X402::RequirementGenerator.generate(
+          amount: amount,
+          resource: request.original_url,
+          description: "Payment required for #{request.path}",
+          chain: chain,
+          currency: currency
+        )
+        requirement_response[:error] = error_message if error_message
+        requirement_response
+      end
+
+      def render_payment_required(amount, chain, currency)
+        requirement_response = generate_payment_required_response(amount, chain, currency)
+
+        # Detect if request is from browser or API client
+        # if browser_request?
+        #   render_html_paywall(requirement_response)
+        # else
+          render json: requirement_response, status: :payment_required
+        # end
+      end
+
+      def process_payment(payment_header, amount, chain, currency)
+        # Parse payment payload
+        payment_payload = X402::PaymentPayload.from_header(payment_header)
+
+        # Generate requirement for validation (must match the 402 response exactly!)
+        requirement_data = X402::RequirementGenerator.generate(
+          amount: amount,
+          resource: request.original_url,
+          description: "Payment required for #{request.path}",
+          chain: chain,
+          currency: currency
+        )
+
+        requirement = X402::PaymentRequirement.new(requirement_data[:accepts].first)
+
+        # Validate payment (verify signature, but don't settle on blockchain yet)
+        validator = X402::PaymentValidator.new
+        validation_result = validator.validate(payment_payload, requirement)
+
+        unless validation_result[:valid]
+          requirement_response = generate_payment_required_response(amount, chain, currency, validation_result[:error])
+          return render json: requirement_response, status: :payment_required
+        end
+
+        # Store payment info and requirement in request environment
+        request.env["x402.payment"] = {
+          payer: validation_result[:payer],
+          amount: payment_payload.value,
+          network: payment_payload.network,
+          payload: payment_payload,
+          requirement: requirement
+        }
+
+        # If non-optimistic mode, settle payment synchronously before continuing
+        unless X402.configuration.optimistic
+          settlement_result = settle_payment_now
+
+          # If settlement failed, abort and return 402 with payment requirements
+          if settlement_result.nil? || !settlement_result.success?
+            error_message = settlement_result&.error_reason || "Settlement failed"
+            requirement_response = generate_payment_required_response(amount, chain, currency, "failed to settle payment: #{error_message}")
+            return render json: requirement_response, status: :payment_required
+          end
+        end
+
+        # Payment verified, continue with action
+        # In optimistic mode, settlement will happen automatically via after_action callback
+      rescue X402::InvalidPaymentError => e
+        requirement_response = generate_payment_required_response(amount, chain, currency, "Invalid payment: #{e.message}")
+        render json: requirement_response, status: :payment_required
+      rescue X402::FacilitatorError => e
+        requirement_response = generate_payment_required_response(amount, chain, currency, "Verification error: #{e.message}")
+        render json: requirement_response, status: :payment_required
+      end
+
+      def settle_x402_payment_if_needed
+        # Only run in optimistic mode (non-optimistic settles synchronously)
+        return unless X402.configuration.optimistic
+
+        # Only settle if payment was verified
+        payment_info = request.env["x402.payment"]
+        return unless payment_info
+
+        # Only settle if response is 2xx (success)
+        return unless response.status >= 200 && response.status < 300
+
+        perform_settlement(payment_info)
+      end
+
+      def settle_payment_now
+        payment_info = request.env["x402.payment"]
+        return unless payment_info
+
+        ::Rails.logger.info("=== X402 Non-Optimistic Settlement (before response) ===")
+        settlement_result = perform_settlement(payment_info)
+
+        # Store settlement result for later use (e.g., adding to response body)
+        request.env["x402.settlement_result"] = settlement_result
+        settlement_result
+      end
+
+      def perform_settlement(payment_info)
+        begin
+          ::Rails.logger.info("=== X402 Settlement Attempt ===")
+          ::Rails.logger.info("Optimistic mode: #{X402.configuration.optimistic}")
+          ::Rails.logger.info("Payment payload class: #{payment_info[:payload].class}")
+          ::Rails.logger.info("Payment payload: #{payment_info[:payload].inspect}")
+          ::Rails.logger.info("Requirement class: #{payment_info[:requirement].class}")
+          ::Rails.logger.info("Requirement hash: #{payment_info[:requirement].to_h.inspect}")
+
+          facilitator_client = X402::FacilitatorClient.new
+          settlement_result = facilitator_client.settle(
+            payment_info[:payload],
+            payment_info[:requirement].to_h
+          )
+
+          if settlement_result.success?
+            # Add settlement response header
+            response.headers["X-PAYMENT-RESPONSE"] = settlement_result.to_base64
+            ::Rails.logger.info("x402 settlement successful: #{settlement_result.transaction}")
+          else
+            # Settlement failed - in optimistic mode, user already got the service
+            # In non-optimistic mode, this will be caught before the response is sent
+            ::Rails.logger.error("x402 settlement failed: #{settlement_result.error_reason}")
+          end
+
+          settlement_result
+        rescue X402::FacilitatorError => e
+          ::Rails.logger.error("x402 settlement error: #{e.message}")
+          nil
+        end
+      end
+
+      def browser_request?
+        # If Accept header explicitly requests JSON, return JSON even from browsers
+        accept_header = request.headers["Accept"].to_s
+        return false if accept_header.include?("application/json")
+
+        # Otherwise, check User-Agent for browser indicators
+        user_agent = request.headers["User-Agent"].to_s
+        user_agent.match?(/(Mozilla|Chrome|Safari|Firefox|Edge|Opera)/i)
+      end
+
+      def render_html_paywall(requirement_response)
+        html = <<~HTML
+          <!DOCTYPE html>
+          <html>
+          <head>
+            <title>Payment Required</title>
+            <style>
+              body {
+                font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+                display: flex;
+                justify-content: center;
+                align-items: center;
+                min-height: 100vh;
+                margin: 0;
+                background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+              }
+              .paywall-container {
+                background: white;
+                padding: 3rem;
+                border-radius: 1rem;
+                box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+                max-width: 500px;
+                text-align: center;
+              }
+              h1 {
+                color: #333;
+                margin-bottom: 1rem;
+                font-size: 2rem;
+              }
+              p {
+                color: #666;
+                line-height: 1.6;
+                margin-bottom: 2rem;
+              }
+              .amount {
+                font-size: 2.5rem;
+                font-weight: bold;
+                color: #667eea;
+                margin: 1.5rem 0;
+              }
+              .info {
+                background: #f7f7f7;
+                padding: 1rem;
+                border-radius: 0.5rem;
+                margin: 1.5rem 0;
+                font-size: 0.9rem;
+              }
+              code {
+                background: #e0e0e0;
+                padding: 0.2rem 0.5rem;
+                border-radius: 0.25rem;
+                font-family: monospace;
+              }
+            </style>
+          </head>
+          <body>
+            <div class="paywall-container">
+              <h1>💳 Payment Required</h1>
+              <p>This resource requires payment to access.</p>
+              <div class="amount">$#{format('%.3f', requirement_response[:accepts].first[:maxAmountRequired].to_i / 1_000_000.0)}</div>
+              <div class="info">
+                <p><strong>Network:</strong> #{requirement_response[:accepts].first[:network]}</p>
+                <p><strong>Asset:</strong> USDC</p>
+                <p><strong>Resource:</strong> #{requirement_response[:accepts].first[:resource]}</p>
+              </div>
+              <p style="font-size: 0.85rem; color: #999;">
+                This resource uses the x402 payment protocol.
+                API clients can make payments programmatically by including the X-PAYMENT header.
+              </p>
+            </div>
+          </body>
+          </html>
+        HTML
+
+        render html: html.html_safe, status: :payment_required
+      end
+    end
+  end
+end

data/lib/x402/rails/generators/install_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module X402
+  module Rails
+    module Generators
+      class InstallGenerator < ::Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Creates X402 initializer for your application"
+
+        def copy_initializer
+          template "x402_initializer.rb", "config/initializers/x402.rb"
+
+          puts ""
+          puts "✅ X402 initializer created at config/initializers/x402.rb"
+          puts ""
+          puts "Next steps:"
+          puts "1. Set your X402_WALLET_ADDRESS environment variable"
+          puts "2. Configure your preferred chain (base-sepolia for testing, base for production)"
+          puts "3. Add x402_paywall(amount: 0.001) to any controller action"
+          puts ""
+          puts "Example usage:"
+          puts "  def show"
+          puts "    x402_paywall(amount: 0.001)  # $0.001 payment required"
+          puts "    render json: @data"
+          puts "  end"
+          puts ""
+        end
+      end
+    end
+  end
+end

data/lib/x402/rails/generators/templates/x402_initializer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# X402 Payment Protocol Configuration
+# For more information, see: https://docs.cdp.coinbase.com/x402
+
+X402.configure do |config|
+  # Your wallet address (where payments will be received)
+  # Set this via environment variable: X402_WALLET_ADDRESS
+  config.wallet_address = ENV.fetch("X402_WALLET_ADDRESS", nil)
+
+  # Facilitator URL (default: https://x402.org/facilitator)
+  # The facilitator handles payment verification and settlement
+  config.facilitator = ENV.fetch("X402_FACILITATOR_URL", "https://x402.org/facilitator")
+
+  # Blockchain network to use
+  # Options: "base-sepolia" (testnet), "base" (mainnet), "avalanche-fuji" (testnet), "avalanche" (mainnet)
+  # For testing, use "base-sepolia". For production, use "base" (no fees!)
+  config.chain = ENV.fetch("X402_CHAIN", "base-sepolia")
+
+  # Currency symbol (currently only USDC is supported)
+  config.currency = ENV.fetch("X402_CURRENCY", "USDC")
+end
+
+# Validate configuration on initialization
+X402.configuration.validate!

data/lib/x402/rails/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module X402
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer "x402.controller_extensions" do
+        ActiveSupport.on_load(:action_controller) do
+          include X402::Rails::ControllerExtensions
+        end
+      end
+
+      initializer "x402.configuration" do
+        # Configuration will be loaded from initializers/x402.rb if present
+      end
+    end
+  end
+end

data/lib/x402/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module X402
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/x402/rails.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_job"
+require "action_controller"
+require "json"
+require "base64"
+
+require_relative "rails/version"
+require_relative "../x402/configuration"
+require_relative "../x402/chains"
+require_relative "../x402/payment_requirement"
+require_relative "../x402/payment_payload"
+require_relative "../x402/settlement_response"
+require_relative "../x402/facilitator_client"
+require_relative "../x402/payment_validator"
+require_relative "../x402/requirement_generator"
+require_relative "../x402/rails/controller_extensions"
+require_relative "../x402/rails/railtie" if defined?(::Rails::Railtie)
+
+module X402
+  module Rails
+    class Error < StandardError; end
+  end
+end

data/lib/x402/requirement_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module X402
+  class RequirementGenerator
+    def self.generate(amount:, resource:, description: nil, chain: nil, currency: nil)
+      config = X402.configuration
+      chain_name = chain || config.chain
+
+      # Get chain and currency configuration for this specific chain
+      chain_config = X402.chain_config(chain_name)
+      currency_config = X402.currency_config_for_chain(chain_name)
+
+      # Convert amount to atomic units
+      atomic_amount = convert_to_atomic(amount, currency_config[:decimals])
+
+      # Get asset address (USDC contract address for the chain)
+      asset_address = X402.usdc_address_for(chain_name)
+
+      # Build EIP-712 domain info (required for signature verification)
+      # IMPORTANT: The name must match what the USDC contract returns for name()
+      # Testnets use "USDC", mainnets use "USD Coin" or "USDC" depending on chain
+      eip712_domain = {
+        name: currency_config[:name],
+        version: currency_config[:version]
+      }
+
+      # Create payment requirement
+      requirement = PaymentRequirement.new(
+        scheme: "exact",
+        network: chain_name,
+        max_amount_required: atomic_amount,
+        asset: asset_address,
+        pay_to: config.wallet_address,
+        resource: resource,
+        description: description || "Payment required for #{resource}",
+        max_timeout_seconds: 600,
+        mime_type: "application/json",
+        extra: eip712_domain
+      )
+
+      # Build full response
+      {
+        x402Version: 1,
+        error: "Payment required to access this resource",
+        accepts: [requirement.to_h]
+      }
+    end
+
+    def self.convert_to_atomic(amount, decimals)
+      # Convert USD amount to atomic units
+      # For USDC with 6 decimals: $0.001 = 1000 atomic units
+      (amount.to_f * (10**decimals)).to_i
+    end
+  end
+end

data/lib/x402/settlement_response.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module X402
+  class SettlementResponse
+    attr_accessor :success, :transaction, :network, :payer, :error_reason
+
+    def initialize(attributes = {})
+      @success = attributes[:success] || attributes["success"]
+      @transaction = attributes[:transaction] || attributes["transaction"]
+      @network = attributes[:network] || attributes["network"]
+      @payer = attributes[:payer] || attributes["payer"]
+      @error_reason = attributes[:error_reason] || attributes["errorReason"]
+    end
+
+    def success?
+      success == true
+    end
+
+    def to_h
+      {
+        success: success,
+        transaction: transaction,
+        network: network,
+        payer: payer,
+        errorReason: error_reason
+      }
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    def to_base64
+      Base64.strict_encode64(to_json)
+    end
+  end
+end

metadata

@@ -0,0 +1,178 @@
+--- !ruby/object:Gem::Specification
+name: x402-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- QuickNode
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-10-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-follow_redirects
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Accept instant blockchain micropayments in Rails applications using the
+  x402 protocol. Enable HTTP 402 Payment Required with USDC payments on Base and other
+  networks.
+email:
+- zach@quiknode.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- LICENSE.txt
+- README.md
+- Rakefile
+- coverage/coverage.svg
+- lib/x402/chains.rb
+- lib/x402/configuration.rb
+- lib/x402/facilitator_client.rb
+- lib/x402/payment_payload.rb
+- lib/x402/payment_requirement.rb
+- lib/x402/payment_validator.rb
+- lib/x402/rails.rb
+- lib/x402/rails/controller_extensions.rb
+- lib/x402/rails/generators/install_generator.rb
+- lib/x402/rails/generators/templates/x402_initializer.rb
+- lib/x402/rails/railtie.rb
+- lib/x402/rails/version.rb
+- lib/x402/requirement_generator.rb
+- lib/x402/settlement_response.rb
+homepage: https://github.com/quiknode-labs/x402-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/quiknode-labs/x402-rails
+  source_code_uri: https://github.com/quiknode-labs/x402-rails
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Rails integration for x402 payment protocol
+test_files: []