x402-payments 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 42c2b33d7692d31886f45dde66a23fc750502aa7fe44db52d2c11ebd6d59b069
+  data.tar.gz: '081a125a98b562d5202396f96ceaaf950980f575d112b7c20dc2c3e96e2a235c'
+SHA512:
+  metadata.gz: 6d79fed8b305baa86cc5378229bc039715cd70a4cfbce99424e84501d5890301698e80efc82b9d61d55ccd907aea2ec71eeaf1a7056dfe788b8ce8c99fffc683
+  data.tar.gz: 1fdc0978f6443a9d34de4e9596410fddf000461de27a2573a2e3adece08aeaae979d2029a1c569637541179a6902acb39cf0fda6e1c3b6f8af913339bbace821

data/.github/workflows/dependency-review.yml

@@ -0,0 +1,14 @@
+name: "Dependency Review"
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout Repository"
+        uses: actions/checkout@v4
+      - name: "Dependency Review"
+        uses: actions/dependency-review-action@v4

data/.github/workflows/pull_requests.yml

@@ -0,0 +1,40 @@
+name: Pull Request Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+
+      - name: Run tests
+        run: bundle exec rake
+
+      - name: Commit coverage badge
+        if: github.ref == 'refs/heads/main'
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add coverage/coverage.svg
+          git diff --staged --quiet || git commit -m "Update coverage badge [skip ci]"
+          git push

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,215 @@
+# X402::Payments
+
+![Coverage](./coverage/coverage.svg)
+
+Ruby gem for generating signed payment HTTP headers and links using the [x402 protocol](https://www.x402.org/).
+
+Supports USDC payments on Base, Avalanche, and other EVM networks with EIP-712 signing.
+
+## Installation
+
+### System Requirements
+
+This gem depends on the `eth` gem which requires native extensions for cryptographic operations. You'll need to install system dependencies first:
+
+#### macOS
+
+```bash
+brew install automake openssl libtool pkg-config gmp libffi
+```
+
+#### Ubuntu/Debian
+
+```bash
+sudo apt-get install build-essential libgmp-dev libssl-dev
+```
+
+#### Alpine Linux
+
+```bash
+apk add build-base gmp-dev openssl-dev autoconf automake libtool
+```
+
+### Installing the Gem
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'x402-payments'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install x402-payments
+```
+
+## Configuration
+
+The gem uses environment variables for configuration with sensible defaults:
+
+```bash
+# Required
+export X402_PAY_TO="0xYourWalletAddress"          # Default address to receive payments
+export X402_PRIVATE_KEY="0xYourPrivateKey"        # Private key for signing
+
+# Optional (with defaults shown)
+export X402_CHAIN="base-sepolia"                  # Network to use
+export X402_MAX_TIMEOUT_SECONDS="600"             # Payment validity timeout
+
+# Optional: Custom RPC URLs (override default RPC endpoints)
+export X402_BASE_RPC_URL="https://your-custom-rpc.com"
+export X402_BASE_SEPOLIA_RPC_URL="https://your-sepolia-rpc.com"
+export X402_AVALANCHE_RPC_URL="https://your-avax-rpc.com"
+export X402_AVALANCHE_FUJI_RPC_URL="https://your-avax-testnet-rpc.com"
+```
+
+### Supported Networks
+
+- `base-sepolia` (testnet) - Default
+- `base` (mainnet)
+- `avalanche-fuji` (testnet)
+- `avalanche` (mainnet)
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'x402/payments'
+
+# Generate a signed payment header
+header = X402::Payments.generate_header(
+  amount: 0.001,                                    # Amount in USD
+  resource: "http://localhost:3000/api/weather",   # Protected resource URL
+  description: "Payment for weather API access",   # Optional description
+  pay_to: "0xRecipientAddress"                     # Optional: override recipient (defaults to config)
+)
+
+# Use the header in an HTTP request
+# curl -H "X-PAYMENT: #{header}" http://localhost:3000/api/weather
+```
+
+**Note**: The `pay_to` parameter allows you to specify a different recipient wallet address per payment. If not provided, it uses the configured `default_pay_to`.
+
+### Using in Rails
+
+The gem works seamlessly in Rails applications:
+
+```ruby
+# config/initializers/x402.rb
+X402::Payments.configure do |config|
+  config.default_pay_to = ENV['X402_PAY_TO']
+  config.private_key = ENV['X402_PRIVATE_KEY']
+  config.chain = Rails.env.production? ? 'base' : 'base-sepolia'
+
+  # Optional: Override RPC URLs programmatically
+  # config.rpc_urls = {
+  #   'base' => 'https://your-custom-base-rpc.com',
+  #   'base-sepolia' => 'https://your-sepolia-rpc.com'
+  # }
+end
+
+# In your controller or service
+class PaymentService
+  def self.generate_payment_for(resource_url, amount)
+    X402::Payments.generate_header(
+      amount: amount,
+      resource: resource_url,
+      description: "Payment for #{resource_url}"
+    )
+  end
+end
+```
+
+### Using Standalone (Non-Rails)
+
+```ruby
+#!/usr/bin/env ruby
+require 'x402/payments'
+
+# Set environment variables or configure directly
+X402::Payments.configure do |config|
+  config.default_pay_to = "0xYourDefaultRecipient"
+  config.private_key = "0xYourPrivateKeyHere"
+  config.chain = "base-sepolia"
+  # config.rpc_urls = { 'base-sepolia' => 'https://your-custom-rpc.com' }
+end
+
+# Generate payment
+header = X402::Payments.generate_header(
+  amount: 0.001,
+  resource: "http://localhost:3000/api/data",
+  # network: "avalanche",                    # Override default network
+  # private_key: "0xDifferentKey",          # Override default key
+  # pay_to: "0xRecipientWalletAddress",     # Override recipient address
+  # extra: {                                 # Override EIP-712 domain
+  #   name: "Custom Token",
+  #   version: "1"
+  # }
+)
+
+puts "Payment Header:"
+puts header
+
+HTTParty.get("http://localhost:3000/api/data", headers: { "X-PAYMENT" => header })
+```
+
+## How It Works
+
+1. **Payment Requirements**: The gem creates a payment requirement specifying the amount (in USDC atomic units), network, and resource
+2. **EIP-712 Signing**: Uses EIP-3009 `TransferWithAuthorization` to create a signature that authorizes the payment
+3. **Header Encoding**: Encodes the signed payment data as a base64 string for the `X-PAYMENT` HTTP header
+4. **Server Validation**: The server validates the signature and settles the payment on-chain
+
+## Example Script
+
+A complete example script is provided in `examples/generate_payment.rb`:
+
+```bash
+# Create your .env file in examples directory
+cd examples
+cp .env.example .env
+# Edit .env with your credentials
+
+# Run the example
+cd ..
+export $(cat examples/.env | xargs)
+ruby examples/generate_payment.rb
+```
+
+This will generate a signed payment header and provide a ready-to-use curl command for testing. See `examples/README.md` for more details.
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bin/setup        # Install dependencies
+bundle exec rake spec   # Run tests
+bin/console      # Interactive prompt for experimentation
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/x402-payments.
+
+## Requirements
+
+- Ruby 3.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/examples/.env.example

@@ -0,0 +1,14 @@
+# X402 Payments Configuration
+# Copy this file to .env and fill in your actual values
+
+# Required: Private key for signing payments
+X402_PRIVATE_KEY=0xYourPrivateKeyHere
+
+# Required: Default recipient wallet address for payments
+X402_PAY_TO=0xYourRecipientAddressHere
+
+# Optional: Network/chain to use (default: base-sepolia)
+X402_CHAIN=base-sepolia
+
+# Optional: Payment timeout in seconds (default: 600)
+X402_MAX_TIMEOUT_SECONDS=600

data/examples/.gitignore

@@ -0,0 +1,2 @@
+# Environment variables with sensitive credentials
+.env

data/examples/README.md

@@ -0,0 +1,88 @@
+# X402 Payments Examples
+
+This directory contains example scripts demonstrating how to use the x402-payments gem.
+
+## generate_payment.rb
+
+Generates a signed payment header and curl command for testing x402 payments.
+
+### Setup
+
+First, create a `.env` file in the `examples/` directory with your credentials:
+
+```bash
+cd examples
+cp .env.example .env
+# Edit .env with your actual values
+```
+
+### Usage
+
+```bash
+# From the gem root directory
+cd /Users/zachp/Dev/gems/x402-payments
+
+# Load environment variables and run
+export $(cat examples/.env | xargs)
+ruby examples/generate_payment.rb
+
+# Or set variables inline
+X402_PRIVATE_KEY="0xYourPrivateKey" \
+X402_PAY_TO="0xYourRecipientAddress" \
+X402_CHAIN="base-sepolia" \
+ruby examples/generate_payment.rb
+```
+
+### Environment Variables
+
+- `X402_PRIVATE_KEY` - Private key for signing (required)
+- `X402_PAY_TO` - Default recipient wallet address for payments (required)
+- `X402_CHAIN` - Network to use: `base-sepolia`, `base`, `avalanche-fuji`, or `avalanche` (default: `base-sepolia`)
+
+### Example Output
+
+```
+=== X402 Payment Generator ===
+Default Pay To: 0xYourRecipientAddress
+Chain: base-sepolia
+
+Generating payment for:
+  Resource: http://localhost:3000/api/weather/current
+  Amount: $0.001 USD
+
+Payment Header (X-PAYMENT):
+eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoi...
+
+Curl Command:
+curl -i -H "X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6..." http://localhost:3000/api/weather/current
+
+To test the payment, run:
+  curl -i -H "X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6..." http://localhost:3000/api/weather/current
+```
+
+You can copy and paste the curl command to test your x402-enabled API endpoint.
+
+## Customizing the Script
+
+You can modify `generate_payment.rb` to:
+
+- Change the amount (e.g., `amount = 0.005` for $0.005)
+- Target different resources (e.g., `resource_url = "https://api.example.com/data"`)
+- Use different networks (set `X402_CHAIN` environment variable)
+- Add custom descriptions
+
+### Example: Generate Payment for Different Resource
+
+```ruby
+# At the end of generate_payment.rb, add:
+
+puts "\n=== Custom Payment ==="
+custom_link = X402::Payments.generate_link(
+  amount: 0.005,
+  resource: "http://localhost:3000/api/premium/data",
+  description: "Premium API access"
+)
+
+puts "Custom Curl Command:"
+puts custom_link[:curl_command]
+```

data/examples/generate_payment.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "x402/payments"
+
+# Load .env file if it exists in the examples directory
+env_file = File.join(__dir__, ".env")
+if File.exist?(env_file)
+  File.readlines(env_file).each do |line|
+    line = line.strip
+    next if line.empty? || line.start_with?("#")
+    key, value = line.split("=", 2)
+    ENV[key] = value if key && value
+  end
+end
+
+# Configuration
+# NOTE: Replace these with your actual credentials via environment variables
+PRIVATE_KEY = ENV.fetch("X402_PRIVATE_KEY")
+DEFAULT_PAY_TO = ENV.fetch("X402_PAY_TO")
+CHAIN = ENV.fetch("X402_CHAIN", "base-sepolia")
+RESOURCE_URL = "http://localhost:3000/api/weather/paywalled_info"
+
+# Configure the gem
+X402::Payments.configure do |config|
+  config.default_pay_to = DEFAULT_PAY_TO
+  config.private_key = PRIVATE_KEY
+  config.chain = CHAIN
+  config.max_timeout_seconds = 600
+end
+
+puts "=== X402 Payment Generator ==="
+puts "Default Pay To: #{DEFAULT_PAY_TO}"
+puts "Chain: #{CHAIN}"
+
+# Generate payment for a resource
+amount = 0.001  # $0.001 USD
+
+puts "Generating payment for:"
+puts "  Resource: #{RESOURCE_URL}"
+puts "  Amount: $#{amount} USD"
+puts
+
+# Generate the payment link with curl command
+link = X402::Payments.generate_link(
+  amount: amount,
+  resource: RESOURCE_URL,
+  description: "Payment required for #{RESOURCE_URL}",
+  # pay_to: "0xDifferentRecipientAddress"  # Optional: override recipient
+)
+
+puts "Payment Header (X-PAYMENT):"
+puts link[:payment_header]
+puts
+puts "Curl Command:"
+puts link[:curl_command]

data/lib/x402/payments/chains.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module X402
+  module Payments
+    # Chain configurations for supported networks
+    CHAINS = {
+      "base-sepolia" => {
+        chain_id: 84532,
+        rpc_url: "https://clean-snowy-hexagon.base-sepolia.quiknode.pro",
+        usdc_address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+        explorer_url: "https://sepolia.basescan.org"
+      },
+      "base" => {
+        chain_id: 8453,
+        rpc_url: "https://snowy-compatible-ensemble.base-mainnet.quiknode.pro",
+        usdc_address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        explorer_url: "https://basescan.org"
+      },
+      "avalanche-fuji" => {
+        chain_id: 43113,
+        rpc_url: "https://muddy-sly-field.avalanche-testnet.quiknode.pro/ext/bc/C/rpc",
+        usdc_address: "0x5425890298aed601595a70AB815c96711a31Bc65",
+        explorer_url: "https://testnet.snowtrace.io"
+      },
+      "avalanche" => {
+        chain_id: 43114,
+        rpc_url: "https://floral-patient-panorama.avalanche-mainnet.quiknode.pro/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",
+        version: "2"
+      },
+      "base" => {
+        symbol: "USDC",
+        decimals: 6,
+        name: "USD Coin",
+        version: "2"
+      },
+      "avalanche-fuji" => {
+        symbol: "USDC",
+        decimals: 6,
+        name: "USD Coin",
+        version: "2"
+      },
+      "avalanche" => {
+        symbol: "USDC",
+        decimals: 6,
+        name: "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 chain_id_for(chain_name)
+        chain_config(chain_name)[:chain_id]
+      end
+
+      def currency_decimals_for_chain(chain_name)
+        currency_config_for_chain(chain_name)[:decimals]
+      end
+
+      def rpc_url_for(chain_name)
+        # Priority: 1) Programmatic config, 2) ENV variable, 3) Default from CHAINS
+        config = X402::Payments.configuration
+
+        # Check programmatic configuration
+        return config.rpc_urls[chain_name] if config.rpc_urls[chain_name]
+
+        # Check environment variable
+        env_var_name = "X402_#{chain_name.upcase.gsub('-', '_')}_RPC_URL"
+        env_rpc = ENV[env_var_name]
+        return env_rpc if env_rpc && !env_rpc.empty?
+
+        # Fall back to default
+        chain_config(chain_name)[:rpc_url]
+      end
+    end
+  end
+end

data/lib/x402/payments/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module X402
+  module Payments
+    class Configuration
+      attr_accessor :default_pay_to, :private_key, :chain, :max_timeout_seconds, :rpc_urls
+
+      def initialize
+        @default_pay_to = ENV.fetch("X402_PAY_TO", nil)
+        @private_key = ENV.fetch("X402_PRIVATE_KEY", nil)
+        @chain = ENV.fetch("X402_CHAIN", "base-sepolia")
+        @max_timeout_seconds = ENV.fetch("X402_MAX_TIMEOUT_SECONDS", "600").to_i
+        @rpc_urls = {}
+      end
+
+      def validate!
+        raise ConfigurationError, "default_pay_to is required" if default_pay_to.nil? || default_pay_to.empty?
+        raise ConfigurationError, "private_key is required" if private_key.nil? || private_key.empty?
+        raise ConfigurationError, "chain is required" if chain.nil? || chain.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
+end

data/lib/x402/payments/generator.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "eth"
+require "json"
+require "base64"
+require "securerandom"
+require "time"
+
+module X402
+  module Payments
+    class Generator
+      attr_reader :config
+
+      def initialize(config = X402::Payments.configuration)
+        @config = config
+      end
+
+      def generate_header(amount:, resource:, description: nil, network: nil, private_key: nil, pay_to: nil, extra: nil)
+        config.validate!
+
+        chain_name = network || config.chain
+        key = private_key || config.private_key
+        recipient = pay_to || config.default_pay_to
+
+        chain_config = X402::Payments.chain_config(chain_name)
+        currency_config = X402::Payments.currency_config_for_chain(chain_name)
+
+        # Convert amount to atomic units
+        atomic_amount = convert_to_atomic(amount, currency_config[:decimals])
+
+        # Get the Ethereum account from private key
+        account = Eth::Key.new(priv: key)
+        sender_address = account.address.to_s
+
+        # Create nonce (32 random bytes)
+        nonce = SecureRandom.random_bytes(32)
+
+        # Build payment requirements
+        payment_requirements = {
+          scheme: "exact",
+          network: chain_name,
+          max_amount_required: atomic_amount.to_s,
+          asset: chain_config[:usdc_address],
+          pay_to: recipient,
+          resource: resource,
+          description: description || "Payment required for #{resource}",
+          max_timeout_seconds: config.max_timeout_seconds,
+          mime_type: "application/json",
+          extra: extra || {
+            name: currency_config[:name],
+            version: currency_config[:version]
+          }
+        }
+
+        # Prepare unsigned payment header
+        valid_after = (Time.now.to_i - 60).to_s
+        valid_before = (Time.now.to_i + config.max_timeout_seconds).to_s
+
+        header = {
+          x402Version: 1,
+          scheme: "exact",
+          network: chain_name,
+          payload: {
+            signature: nil,
+            authorization: {
+              from: sender_address,
+              to: recipient,
+              value: atomic_amount.to_s,
+              validAfter: valid_after,
+              validBefore: valid_before,
+              nonce: "0x#{nonce.unpack1('H*')}"
+            }
+          }
+        }
+
+        # Sign the payment header
+        signature = sign_payment(account, header, payment_requirements, nonce)
+        header[:payload][:signature] = signature
+
+        # Encode to base64
+        encode_payment(header)
+      end
+
+      def generate_link(amount:, resource:, description: nil, network: nil, private_key: nil, pay_to: nil, extra: nil)
+        header = generate_header(
+          amount: amount,
+          resource: resource,
+          description: description,
+          network: network,
+          private_key: private_key,
+          pay_to: pay_to,
+          extra: extra
+        )
+
+        {
+          payment_header: header,
+          curl_command: "curl -s -H \"X-PAYMENT: #{header}\" #{resource} | jq ."
+        }
+      end
+
+      private
+
+      def convert_to_atomic(amount, decimals)
+        (amount.to_f * (10**decimals)).to_i
+      end
+
+      def sign_payment(account, header, payment_requirements, nonce_bytes)
+        auth = header[:payload][:authorization]
+        extra = payment_requirements[:extra]
+        chain_name = payment_requirements[:network]
+        asset = payment_requirements[:asset]
+
+        # Build EIP-712 typed data
+        typed_data = {
+          types: {
+            EIP712Domain: [
+              { name: "name", type: "string" },
+              { name: "version", type: "string" },
+              { name: "chainId", type: "uint256" },
+              { name: "verifyingContract", type: "address" }
+            ],
+            TransferWithAuthorization: [
+              { name: "from", type: "address" },
+              { name: "to", type: "address" },
+              { name: "value", type: "uint256" },
+              { name: "validAfter", type: "uint256" },
+              { name: "validBefore", type: "uint256" },
+              { name: "nonce", type: "bytes32" }
+            ]
+          },
+          primaryType: "TransferWithAuthorization",
+          domain: {
+            name: extra[:name],
+            version: extra[:version],
+            chainId: X402::Payments.chain_id_for(chain_name),
+            verifyingContract: asset
+          },
+          message: {
+            from: auth[:from],
+            to: auth[:to],
+            value: auth[:value].to_i,
+            validAfter: auth[:validAfter].to_i,
+            validBefore: auth[:validBefore].to_i,
+            nonce: nonce_bytes
+          }
+        }
+
+        # Sign using eth gem
+        signature = account.sign_typed_data(typed_data)
+
+        # Ensure signature has 0x prefix
+        signature = "0x#{signature}" unless signature.start_with?("0x")
+        signature
+      end
+
+      def encode_payment(payment_payload)
+        json_str = JSON.generate(payment_payload)
+        Base64.strict_encode64(json_str)
+      end
+    end
+  end
+end

data/lib/x402/payments/version.rb

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

data/lib/x402/payments.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "payments/version"
+require_relative "payments/configuration"
+require_relative "payments/chains"
+require_relative "payments/generator"
+
+module X402
+  module Payments
+    class Error < StandardError; end
+
+    class << self
+      def generate_header(amount:, resource:, description: nil, network: nil, private_key: nil, pay_to: nil, extra: nil)
+        generator = Generator.new
+        generator.generate_header(
+          amount: amount,
+          resource: resource,
+          description: description,
+          network: network,
+          private_key: private_key,
+          pay_to: pay_to,
+          extra: extra
+        )
+      end
+
+      def generate_link(amount:, resource:, description: nil, network: nil, private_key: nil, pay_to: nil, extra: nil)
+        generator = Generator.new
+        generator.generate_link(
+          amount: amount,
+          resource: resource,
+          description: description,
+          network: network,
+          private_key: private_key,
+          pay_to: pay_to,
+          extra: extra
+        )
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: x402-payments
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- QuickNode
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-10-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: eth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.11
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.11
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !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'
+description: Ruby gem for generating signed payment headers and links using the x402
+  protocol. Supports USDC payments on Base and other EVM networks with EIP-712 signing.
+email:
+- zach+402@quiknode.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/dependency-review.yml"
+- ".github/workflows/pull_requests.yml"
+- LICENSE.txt
+- README.md
+- Rakefile
+- coverage/coverage.svg
+- examples/.env.example
+- examples/.gitignore
+- examples/README.md
+- examples/generate_payment.rb
+- lib/x402/payments.rb
+- lib/x402/payments/chains.rb
+- lib/x402/payments/configuration.rb
+- lib/x402/payments/generator.rb
+- lib/x402/payments/version.rb
+homepage: https://github.com/quiknode-labs/x402-payments
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/quiknode-labs/x402-payments
+  source_code_uri: https://github.com/quiknode-labs/x402-payments
+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: Generate x402 payment signatures and links for blockchain micropayments
+test_files: []