x402-rails 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71561f4eae4f693705a405fd47e2b51a493441abd96dfe5a7d415915cdaa1313
-  data.tar.gz: 251fa92d63aaaa4e944040192b55b1db1ed154cb26d62aaac7f86a200bbc5e07
+  metadata.gz: 5ec0c7a3137f3d98d641403e48438dc35677587631197581e3574804df7f42fa
+  data.tar.gz: f1d3d3ed62e675ad0c818e0202066c95cdddbd2c13ce6be3cec9ef04c1a47e94
 SHA512:
-  metadata.gz: 753e8a4957ebbc21189826904e370ef90ae618aca1078c0889351aa6841106bffc237ee1a893eeba745c8d75773c30f25d083d4e033466ef2a0f3d327f4c239e
-  data.tar.gz: 359cdbfd614777f9004a96aa4b2d5b9eff290266247707d9b886cafd1731bd3fa667625e641da16ea9383e5c3d2a3e74d79c0cf068a9be455ad4115a10715b19
+  metadata.gz: 888362993251583ffdf727c493468dc65ae6c97cff5017983b4b47675d80eed7ce2165a99fd78746d07a495d1a0ffa1dd641a2a4d0c36bb3ab5f5e55b5556899
+  data.tar.gz: dec329b07321b5c705a38ace0a90d5c9599f34eeb0f7fcb8b6f8b6ff4c51febe986c06da450486b31131252886145a3c00dedaeb2765d20cc8860bee84960c65

data/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.0] - Unreleased
+
+### Added
+- **Bazaar discovery** - `x402_discovery` controller macro declares discovery metadata per action; the extension is attached to every v2 402 the gem renders, echoed by paying clients, and indexed by facilitator catalogs (PayAI, Coinbase CDP Bazaar)
+- **`X402::DiscoveryExtension.declare`** - Builds the `extensions.bazaar` wire shape, matching `@x402/extensions` `declareDiscoveryExtension` (query and body forms)
+- **Coinbase CDP facilitator auth** - Requests to `api.cdp.coinbase.com` carry the required Bearer JWT (ES256 and Ed25519 keys, no new dependencies). Credentials via `CDP_API_KEY_ID` / `CDP_API_KEY_SECRET` or `config.cdp_api_key_id` / `config.cdp_api_key_secret`
+- **`FacilitatorClient#discovery_resources`** - Query a facilitator's discovery catalog
+- **`x402_payment_header` / `x402_payment_attempted?`** - Controller helpers for the version-appropriate payment header, for conditional paywall flows and idempotency fingerprints
+- `x402_discovery(description:)` sets the 402 `resource.description` facilitator catalogs display; `x402_paywall(extensions:)` attaches a prebuilt extensions hash directly
+
+### Changed
+- 402 responses set `Cache-Control: no-store`
+- Facilitator request/response bodies and settlement diagnostics log at `debug`; settlement outcomes stay at `info`/`error`
+
+### Fixed
+- **v2 PaymentPayload dropped client-echoed `extensions`** - `to_h` hardcoded `extensions: {}`, so the discovery extension never reached the facilitator on verify/settle and routes could not be indexed. Client extensions are now forwarded untouched
+- Settlement failures returning HTTP 400 from the facilitator no longer raise out of the settlement hook; they are logged and handled like other settlement errors
+- `rails generate x402:install` - the install generator was not discoverable (it lived outside Rails' generator load path)
+
+With no discovery declared and a non-CDP facilitator, the only wire change from 1.1.0 is the 402 `Cache-Control` header.
+
 ## [1.0.0] - 2026-01-07
 
 ### Added

data/README.md

@@ -19,6 +19,8 @@ Supports 18 networks including Base, Polygon, Avalanche, Sei, Solana, and more.
 - **Optimistic & non-optimistic** settlement modes
 - **Automatic settlement** after successful responses
 - **API paywall** with 402 payment-required responses
+- **Bazaar discovery** to list your routes in facilitator catalogs (PayAI, Coinbase CDP)
+- **Coinbase CDP facilitator** support with built-in auth
 - **Rails 7.0+** compatible
 
 ## Example Video
@@ -43,12 +45,18 @@ bundle install
 
 ### 1. Configure the gem
 
-Create `config/initializers/x402.rb`:
+Generate the initializer:
+
+```bash
+bin/rails generate x402:install
+```
+
+Then edit `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.facilitator = "https://www.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.
@@ -75,6 +83,21 @@ end
 
 That's it! Your endpoint now requires payment.
 
+### 3. (Optional) Make it discoverable
+
+Declare discovery metadata and agents can find your route in facilitator catalogs (see [Bazaar Discovery](#bazaar-discovery)):
+
+```ruby
+class ApiController < ApplicationController
+  x402_discovery only: :weather,
+                 input: { "city" => "San Francisco" },
+                 input_schema: { "properties" => { "city" => { "type" => "string" } } },
+                 output: { example: { "temperature" => 72 } }
+end
+```
+
+Indexing happens when a client pays: the extension rides the 402, the paying client echoes it, and the facilitator catalogs the route on settle.
+
 ## Usage Patterns
 
 ### Direct Method Call
@@ -141,8 +164,8 @@ 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")
+  # Facilitator service URL (default: "https://www.x402.org/facilitator")
+  config.facilitator = ENV.fetch("X402_FACILITATOR_URL", "https://www.x402.org/facilitator")
 
   # Blockchain network (default: "base-sepolia")
   # Built-in: base, base-sepolia, polygon, polygon-amoy, avalanche, avalanche-fuji,
@@ -155,10 +178,10 @@ X402.configure do |config|
   # Currently only USDC is supported
   config.currency = ENV.fetch("X402_CURRENCY","USDC")
 
-  # Optimistic mode (default: true)
+  # Optimistic mode (default: false)
   # true: Fast response, settle payment after response is sent
   # false: Wait for blockchain settlement before sending response
-  config.optimistic = ENV.fetch("X402_OPTIMISTIC",false)
+  config.optimistic = ENV.fetch("X402_OPTIMISTIC", "false") == "true"
 end
 ```
 
@@ -167,11 +190,13 @@ end
 | 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                   |
+| `facilitator`    | No       | `"https://www.x402.org/facilitator"` | Facilitator service URL for payment verification and settlement               |
 | `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)                     |
+| `optimistic`     | No       | `false`                          | `true`: respond before settlement; `false`: settle before responding             |
 | `version`        | No       | `2`                              | Protocol version (1 or 2). See Protocol Versions section                          |
+| `cdp_api_key_id` | No       | `ENV["CDP_API_KEY_ID"]`          | Coinbase CDP API key id — only used when the facilitator is CDP                   |
+| `cdp_api_key_secret` | No   | `ENV["CDP_API_KEY_SECRET"]`      | Coinbase CDP API key secret (ECDSA PEM or Ed25519 base64)                         |
 
 ### Custom Chains and Tokens
 
@@ -347,6 +372,157 @@ def legacy_v1
 end
 ```
 
+## Bazaar Discovery
+
+Facilitators with a discovery layer (PayAI, Coinbase CDP Bazaar) index your route into their public catalog when a payment carries the x402 Bazaar discovery extension. Declare it per action and the gem attaches it to every v2 402 for that action; paying clients echo it into their payment payload, and the gem forwards the echo to the facilitator on verify/settle — that's what creates the catalog entry.
+
+> **Note:** Parameterized routes (e.g. `/weather/:city`) are cataloged per concrete URL — the gem does not emit the optional `routeTemplate` field.
+
+### GET route (query params)
+
+Omit `body_type` for GET/HEAD/DELETE — `input` describes query params:
+
+```ruby
+class WeatherController < ApplicationController
+  x402_discovery only: :show,
+                 input: { "city" => "San Francisco", "units" => "celsius" },
+                 input_schema: {
+                   "type" => "object",
+                   "properties" => {
+                     "city" => { "type" => "string", "description" => "City name" },
+                     "units" => { "type" => "string", "enum" => ["celsius", "fahrenheit"] },
+                   },
+                   "required" => ["city"],
+                 },
+                 output: { example: { "weather" => "foggy", "temperature" => 15 } }
+
+  def show
+    x402_paywall(amount: 0.001)
+    return if performed?
+    render json: { weather: "foggy", temperature: 15 }
+  end
+end
+```
+
+### POST route (JSON body)
+
+Pass `body_type: "json"` — `input` is now an example request body. Give every field a `description`: it's what agents read in the catalog to call you correctly.
+
+```ruby
+class SearchController < ApplicationController
+  x402_discovery only: :create,
+                 body_type: "json",
+                 input: {
+                   "query" => "solar panels",
+                   "filters" => { "max_price" => 100 },
+                 },
+                 input_schema: {
+                   "type" => "object",
+                   "properties" => {
+                     "query" => { "type" => "string", "description" => "Search terms" },
+                     "filters" => {
+                       "type" => "object",
+                       "properties" => { "max_price" => { "type" => "number" } },
+                     },
+                   },
+                   "required" => ["query"],
+                 },
+                 output: {
+                   example: { "results" => [{ "title" => "…", "price" => 42 }] },
+                   schema: { "properties" => { "results" => { "type" => "array" } } },
+                 }
+
+  def create
+    x402_paywall(amount: 0.005)
+    return if performed?
+    render json: { results: search_results }
+  end
+end
+```
+
+### Multiple routes in one controller
+
+Each action gets its own declaration; undeclared actions emit no extension:
+
+```ruby
+class ReportsController < ApplicationController
+  x402_discovery only: :create, body_type: "json",
+                 input: { "ticker" => "AAPL" },
+                 input_schema: { "properties" => { "ticker" => { "type" => "string" } }, "required" => ["ticker"] },
+                 output: { example: { "report_id" => "rep_123" } }
+
+  x402_discovery only: :summary,
+                 input: { "report_id" => "rep_123" },
+                 input_schema: { "properties" => { "report_id" => { "type" => "string" } }, "required" => ["report_id"] },
+                 output: { example: { "summary" => "…" } }
+end
+```
+
+### Full control
+
+Build the extension yourself (e.g. to share schemas with your validators), or attach per-call:
+
+```ruby
+x402_discovery only: :create, extensions: X402::DiscoveryExtension.declare(
+  body_type: "json",
+  input: MyApi::EXAMPLE_BODY,
+  input_schema: MyApi::BODY_SCHEMA,
+  output: { example: MyApi::EXAMPLE_RESPONSE },
+)
+
+# or, inside an action:
+x402_paywall(amount: 0.005, extensions: my_extensions)
+```
+
+### Indexing rules
+
+- The example `input` **must validate against `input_schema`** — facilitators silently skip routes whose extension fails validation. Keep example and schema in sync.
+- `method` is stamped from the actual request at render time — omit it; a declared value is overwritten.
+- `description:` on `x402_discovery` sets the 402's `resource.description` — the text catalogs display for the route. A description alone just names the route; declaring input/output metadata is what makes it discoverable.
+- Catalogs are **per-facilitator** — an entry appears only in the catalog of the facilitator that settled the payment. To appear in both PayAI and CDP, settle at least one payment through each.
+- Indexing is a side-effect of a real payment; there is no registration API.
+
+Verify a listing:
+
+```ruby
+X402::FacilitatorClient.new.discovery_resources(type: "http")
+# or against a specific facilitator:
+X402::FacilitatorClient.new("https://facilitator.payai.network").discovery_resources
+```
+
+## Facilitators
+
+Any x402 facilitator works via `X402_FACILITATOR_URL` / `config.facilitator`. Auth is applied automatically:
+
+| Facilitator | URL | Auth |
+| ----------- | --- | ---- |
+| x402.org (default) | `https://www.x402.org/facilitator` | none |
+| PayAI | `https://facilitator.payai.network` | none |
+| Coinbase CDP | `https://api.cdp.coinbase.com/platform/v2/x402` | Bearer JWT, built in |
+
+### Using Coinbase CDP
+
+1. Create a project + API key at [cdp.coinbase.com](https://cdp.coinbase.com) (ECDSA and Ed25519 keys both work).
+2. Set the env vars CDP's own SDKs use — the gem picks them up automatically:
+
+```bash
+X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
+CDP_API_KEY_ID=your-key-id
+CDP_API_KEY_SECRET=your-key-secret
+```
+
+Or configure explicitly:
+
+```ruby
+X402.configure do |config|
+  config.facilitator = "https://api.cdp.coinbase.com/platform/v2/x402"
+  config.cdp_api_key_id = Rails.application.credentials.dig(:cdp, :api_key_id)
+  config.cdp_api_key_secret = Rails.application.credentials.dig(:cdp, :api_key_secret)
+end
+```
+
+Every verify/settle/supported/discovery request then carries a per-request, URI-bound Bearer JWT (2-minute expiry), matching `@coinbase/cdp-sdk`. Note: CDP's Bazaar discovery currently covers Base and Base Sepolia USDC.
+
 ## Environment Variables
 
 Configure via environment variables:
@@ -356,11 +532,15 @@ Configure via environment variables:
 X402_WALLET_ADDRESS=0xYourAddress
 
 # Optional (with defaults)
-X402_FACILITATOR_URL=https://x402.org/facilitator
+X402_FACILITATOR_URL=https://www.x402.org/facilitator
 X402_CHAIN=base-sepolia
 X402_CURRENCY=USDC
 X402_OPTIMISTIC=true  # "true" or "false"
 
+# Coinbase CDP facilitator auth (only needed when X402_FACILITATOR_URL is CDP)
+CDP_API_KEY_ID=
+CDP_API_KEY_SECRET=
+
 # 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.

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module X402
+  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

data/lib/{x402/rails/generators → generators/x402/install}/templates/x402_initializer.rb

@@ -19,7 +19,16 @@ X402.configure do |config|
 
   # Currency symbol (currently only USDC is supported)
   config.currency = ENV.fetch("X402_CURRENCY", "USDC")
+
+  # Coinbase CDP facilitator (https://api.cdp.coinbase.com/platform/v2/x402)
+  # requires API credentials. These are read automatically from CDP_API_KEY_ID /
+  # CDP_API_KEY_SECRET, or set them explicitly:
+  # config.cdp_api_key_id = ENV.fetch("CDP_API_KEY_ID", nil)
+  # config.cdp_api_key_secret = ENV.fetch("CDP_API_KEY_SECRET", nil)
 end
 
+# To list paywalled routes in facilitator Bazaar catalogs, declare discovery
+# metadata in the controller with `x402_discovery` — see the README.
+
 # Validate configuration on initialization
 X402.configuration.validate!

data/lib/x402/cdp_facilitator_auth.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module X402
+  # Bearer JWT auth for the Coinbase CDP facilitator, mirroring
+  # @coinbase/cdp-sdk generateJwt: per-request, URI-bound claims, signed with
+  # ES256 (PEM EC key) or EdDSA (base64 Ed25519 seed+public key).
+  #
+  # Applied automatically by FacilitatorClient when the configured facilitator
+  # host is api.cdp.coinbase.com. Credentials come from `config.cdp_api_key_id`
+  # and `config.cdp_api_key_secret` (or the CDP_API_KEY_ID / CDP_API_KEY_SECRET
+  # env vars CDP's own SDKs use). Other facilitators are untouched.
+  class CdpFacilitatorAuth
+    CDP_HOST = "api.cdp.coinbase.com"
+    EXPIRY_SECONDS = 120
+
+    class << self
+      def headers_for(facilitator_url:, http_method:, endpoint:)
+        uri = URI(facilitator_url)
+        return {} unless uri.host == CDP_HOST
+
+        config = X402.configuration
+        key_id = config.cdp_api_key_id
+        secret = config.cdp_api_key_secret
+        if key_id.nil? || key_id.empty? || secret.nil? || secret.empty?
+          X402.logger.error(
+            "[x402] CDP facilitator requires cdp_api_key_id and cdp_api_key_secret " \
+            "(or CDP_API_KEY_ID / CDP_API_KEY_SECRET); sending the request unauthenticated",
+          )
+          return {}
+        end
+
+        jwt = bearer_jwt(
+          key_id: key_id,
+          secret: secret,
+          http_method: http_method,
+          request_host: uri.host,
+          request_path: "#{uri.path}/#{endpoint}",
+        )
+        jwt ? { "Authorization" => "Bearer #{jwt}" } : {}
+      end
+
+      private
+
+      def bearer_jwt(key_id:, secret:, http_method:, request_host:, request_path:)
+        now = Time.now.to_i
+        claims = {
+          sub: key_id,
+          iss: "cdp",
+          uris: ["#{http_method} #{request_host}#{request_path}"],
+          iat: now,
+          nbf: now,
+          exp: now + EXPIRY_SECONDS,
+        }
+        header = { kid: key_id, typ: "JWT", nonce: SecureRandom.hex(16) }
+
+        if (key = ec_key(secret))
+          signed_jwt(claims, header.merge(alg: "ES256")) { |input| ecdsa_raw_signature(key, input) }
+        elsif (key = ed25519_key(secret))
+          signed_jwt(claims, header.merge(alg: "EdDSA")) { |input| key.sign(nil, input) }
+        else
+          X402.logger.error("[x402] CDP_API_KEY_SECRET is neither a PEM EC key nor a base64 Ed25519 key")
+          nil
+        end
+      end
+
+      def signed_jwt(claims, header)
+        signing_input = [encode_segment(header.to_json), encode_segment(claims.to_json)].join(".")
+        [signing_input, encode_segment(yield(signing_input))].join(".")
+      end
+
+      def encode_segment(bytes)
+        Base64.urlsafe_encode64(bytes, padding: false)
+      end
+
+      def ec_key(secret)
+        pem = secret.gsub("\\n", "\n")
+        return nil unless pem.include?("PRIVATE KEY")
+
+        key = OpenSSL::PKey.read(pem)
+        key.is_a?(OpenSSL::PKey::EC) ? key : nil
+      rescue OpenSSL::PKey::PKeyError
+        nil
+      end
+
+      # CDP Ed25519 secrets are base64(seed(32) || public_key(32)); OpenSSL only
+      # imports the seed wrapped in PKCS#8 DER.
+      def ed25519_key(secret)
+        decoded = Base64.strict_decode64(secret)
+        return nil unless decoded.bytesize == 64
+
+        seed = decoded.byteslice(0, 32)
+        der = OpenSSL::ASN1::Sequence([
+          OpenSSL::ASN1::Integer(0),
+          OpenSSL::ASN1::Sequence([OpenSSL::ASN1::ObjectId("ED25519")]),
+          OpenSSL::ASN1::OctetString(OpenSSL::ASN1::OctetString(seed).to_der),
+        ]).to_der
+        OpenSSL::PKey.read(der)
+      rescue ArgumentError, OpenSSL::PKey::PKeyError
+        nil
+      end
+
+      # JWS ES256 signatures are raw r||s (32 bytes each); OpenSSL emits DER.
+      def ecdsa_raw_signature(key, signing_input)
+        der = key.sign(OpenSSL::Digest.new("SHA256"), signing_input)
+        r, s = OpenSSL::ASN1.decode(der).value.map(&:value)
+        [r, s].map { |bn| bn.to_s(2).rjust(32, "\x00".b) }.join
+      end
+    end
+  end
+end

data/lib/x402/chains.rb

@@ -133,6 +133,22 @@ module X402
       currency: USDC_NAMED_USDC,
     },
 
+    # --- XDC ---
+    "xdc" => {
+      chain_id: 50,
+      caip2: "eip155:50",
+      usdc_address: "0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1",
+      explorer_url: "https://xdcscan.com",
+      currency: USDC_NAMED_USDC_V2,
+    },
+    "xdc-testnet" => {
+      chain_id: 51,
+      caip2: "eip155:51",
+      usdc_address: "0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4",
+      explorer_url: "https://testnet.xdcscan.com",
+      currency: USDC_NAMED_USDC_V2,
+    },
+
     # --- Solana ---
     "solana" => {
       chain_id: 101,

data/lib/x402/configuration.rb

@@ -4,7 +4,7 @@ module X402
   class Configuration
     attr_accessor :wallet_address, :facilitator, :chain, :currency, :optimistic,
                   :version, :fee_payer, :custom_chains, :custom_tokens,
-                  :accepted_payments
+                  :accepted_payments, :cdp_api_key_id, :cdp_api_key_secret
 
     def initialize
       @wallet_address = ENV.fetch("X402_WALLET_ADDRESS", nil)
@@ -17,6 +17,10 @@ module X402
       @custom_chains = {}
       @custom_tokens = {}
       @accepted_payments = []
+      # Coinbase CDP facilitator credentials (same env names as CDP's own SDKs).
+      # Only used when the facilitator host is api.cdp.coinbase.com.
+      @cdp_api_key_id = ENV.fetch("CDP_API_KEY_ID", nil)
+      @cdp_api_key_secret = ENV.fetch("CDP_API_KEY_SECRET", nil)
     end
 
     def accept(chain:, currency: "USDC", wallet_address: nil)
@@ -93,6 +97,11 @@ module X402
     def reset_configuration!
       @configuration = Configuration.new
     end
+
+    # ::-qualified: bare Rails here resolves to the gem's own X402::Rails.
+    def logger
+      ::Rails.logger
+    end
   end
 
   class ConfigurationError < StandardError; end

data/lib/x402/discovery_extension.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/deep_dup"
+
+module X402
+  # Builds the x402 Bazaar discovery extension for a route, matching the wire
+  # shape of the official @x402/extensions `declareDiscoveryExtension` helper.
+  #
+  # Facilitators index a resource only when the paying client echoes this
+  # extension back in its PaymentPayload and `info` validates against `schema`.
+  # A mismatch is skipped silently, so example inputs must satisfy the declared
+  # input schema.
+  #
+  #   X402::DiscoveryExtension.declare(
+  #     body_type: "json",
+  #     input: { "city" => "San Francisco" },
+  #     input_schema: {
+  #       "type" => "object",
+  #       "properties" => { "city" => { "type" => "string" } },
+  #       "required" => ["city"],
+  #     },
+  #     output: { example: { "weather" => "foggy" } },
+  #   )
+  #
+  # `body_type` selects the body form (POST/PUT/PATCH); without it the query
+  # form (GET/HEAD/DELETE) is used and `input` describes query params. The
+  # actual request method is stamped at render time via `with_method`.
+  class DiscoveryExtension
+    JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"
+    QUERY_METHODS = %w[GET HEAD DELETE].freeze
+    BODY_METHODS = %w[POST PUT PATCH].freeze
+    BODY_TYPES = %w[json form-data text].freeze
+
+    class << self
+      def declare(method: nil, body_type: nil, input: {}, input_schema: { "properties" => {} },
+                  output: nil)
+        info, schema =
+          if body_type
+            body_form(method: method, body_type: body_type, input: input, input_schema: input_schema)
+          else
+            query_form(method: method, input: input, input_schema: input_schema)
+          end
+
+        attach_output(info, schema, output)
+        { "bazaar" => { "info" => info, "schema" => schema } }
+      end
+
+      # Stamps the actual HTTP method into the declaration at request time,
+      # overwriting any declared method — mirroring the reference server
+      # extension's enrichment, which always reports the live request verb.
+      def with_method(extension, http_method)
+        input = extension.dig("bazaar", "info", "input")
+        return extension if input.nil?
+
+        extension.deep_dup.tap do |enriched|
+          enriched["bazaar"]["info"]["input"]["method"] = http_method
+          method_schema = enriched.dig("bazaar", "schema", "properties", "input", "properties")
+          method_schema["method"] = { "type" => "string", "enum" => [http_method] } if method_schema
+        end
+      end
+
+      private
+
+      def query_form(method:, input:, input_schema:)
+        info_input = { "type" => "http" }
+        info_input["method"] = method if method
+        info_input["queryParams"] = input if input
+
+        properties = {
+          "type" => { "type" => "string", "const" => "http" },
+          "method" => { "type" => "string", "enum" => QUERY_METHODS },
+        }
+        properties["queryParams"] = { "type" => "object" }.merge(input_schema) if input_schema
+
+        [{ "input" => info_input }, schema_for(properties, required: %w[type method])]
+      end
+
+      def body_form(method:, body_type:, input:, input_schema:)
+        info_input = { "type" => "http" }
+        info_input["method"] = method if method
+        info_input["bodyType"] = body_type
+        info_input["body"] = input || {}
+
+        properties = {
+          "type" => { "type" => "string", "const" => "http" },
+          "method" => { "type" => "string", "enum" => BODY_METHODS },
+          "bodyType" => { "type" => "string", "enum" => BODY_TYPES },
+          "body" => input_schema,
+        }
+
+        [{ "input" => info_input }, schema_for(properties, required: %w[type method bodyType body])]
+      end
+
+      def schema_for(input_properties, required:)
+        {
+          "$schema" => JSON_SCHEMA_DIALECT,
+          "type" => "object",
+          "properties" => {
+            "input" => {
+              "type" => "object",
+              "properties" => input_properties,
+              "required" => required,
+              "additionalProperties" => false,
+            },
+          },
+          "required" => ["input"],
+        }
+      end
+
+      def attach_output(info, schema, output)
+        example = output && (output[:example] || output["example"])
+        return unless example
+
+        output_schema = output[:schema] || output["schema"]
+        info["output"] = { "type" => "json", "example" => example }
+        schema["properties"]["output"] = {
+          "type" => "object",
+          "properties" => {
+            "type" => { "type" => "string" },
+            "example" => { "type" => "object" }.merge(output_schema.is_a?(Hash) ? output_schema : {}),
+          },
+          "required" => ["type"],
+        }
+      end
+    end
+  end
+end

data/lib/x402/facilitator_client.rb

@@ -12,69 +12,78 @@ module X402
     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}")
-
+      response = post_payment("verify", payment_payload, payment_requirements)
       handle_response(response, "verify")
     rescue Faraday::Error => e
       raise FacilitatorError, "Failed to verify payment: #{e.message}"
     end
 
     def settle(payment_payload, payment_requirements)
+      response = post_payment("settle", payment_payload, payment_requirements)
+      SettlementResponse.new(handle_response(response, "settle"))
+    rescue Faraday::Error => e
+      raise FacilitatorError, "Failed to settle payment: #{e.message}"
+    end
+
+    def supported_networks
+      get_json("supported", action: "supported")
+    rescue Faraday::Error => e
+      raise FacilitatorError, "Failed to fetch supported networks: #{e.message}"
+    end
+
+    # Lists the facilitator's Bazaar discovery catalog (PayAI, CDP, and any
+    # other facilitator implementing the x402 discovery spec expose this).
+    # Params pass through as query string, e.g. type: "http", limit: 50.
+    def discovery_resources(params = {})
+      get_json("discovery/resources", action: "discovery", params: params)
+    rescue Faraday::Error => e
+      raise FacilitatorError, "Failed to fetch discovery resources: #{e.message}"
+    end
+
+    private
+
+    def post_payment(endpoint, 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}")
+      X402.logger.debug { "[x402] POST #{facilitator_url}/#{endpoint} #{request_body.to_json}" }
 
-      response = connection.post("settle") do |req|
+      response = connection.post(endpoint) do |req|
         req.headers["Content-Type"] = "application/json"
+        req.headers.update(auth_headers("POST", endpoint))
         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}"
+      X402.logger.debug { "[x402] #{endpoint} response #{response.status}: #{response.body}" }
+      response
     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}"
+    def get_json(endpoint, action:, params: {})
+      response = connection.get(endpoint) do |req|
+        req.params.update(params)
+        req.headers.update(auth_headers("GET", endpoint))
+      end
+      handle_response(response, action)
     end
 
-    private
-
     def connection
       @connection ||= Faraday.new(url: facilitator_url) do |faraday|
         faraday.adapter Faraday.default_adapter
       end
     end
 
+    # CDP requires a Bearer JWT on every request; all other facilitators get no auth.
+    def auth_headers(http_method, endpoint)
+      CdpFacilitatorAuth.headers_for(
+        facilitator_url: facilitator_url,
+        http_method: http_method,
+        endpoint: endpoint,
+      )
+    end
+
     def handle_response(response, action)
       case response.status
       when 200..299

data/lib/x402/payment_payload.rb

@@ -2,7 +2,7 @@
 
 module X402
   class PaymentPayload
-    attr_accessor :x402_version, :scheme, :network, :payload, :accepted, :resource_info
+    attr_accessor :x402_version, :scheme, :network, :payload, :accepted, :resource_info, :extensions
 
     def initialize(attributes = {})
       attrs = attributes.with_indifferent_access
@@ -10,6 +10,7 @@ module X402
       @x402_version = (attrs[:x402Version] || attrs[:x402_version] || 1).to_i
       @accepted = attrs[:accepted]
       @resource_info = attrs[:resource]
+      @extensions = attrs[:extensions]
 
       if @accepted
         @scheme = @accepted.with_indifferent_access[:scheme]
@@ -95,7 +96,8 @@ module X402
           x402Version: x402_version,
           accepted: format_accepted_for_version(version_strategy),
           payload: payload,
-          extensions: {}
+          # Client-echoed extensions (e.g. bazaar discovery) must survive to verify/settle
+          extensions: extensions.presence || {}
         }
         base[:resource] = resource_info if resource_info
         base

data/lib/x402/rails/controller_extensions.rb

@@ -7,6 +7,32 @@ module X402
 
       included do
         after_action :settle_x402_payment_if_needed
+        class_attribute :x402_discovery_declarations, instance_writer: false, default: {}
+      end
+
+      class_methods do
+        # Declares Bazaar discovery metadata for paywalled actions so 402
+        # responses advertise the route to facilitator discovery catalogs.
+        #
+        #   x402_discovery only: :create,
+        #                  body_type: "json",
+        #                  input: { "city" => "SF" },
+        #                  input_schema: { "properties" => { "city" => { "type" => "string" } } },
+        #                  output: { example: { "weather" => "foggy" } }
+        #
+        # Accepts either DiscoveryExtension.declare kwargs (as above) or a
+        # prebuilt hash via `extensions:`, plus `description:` for the 402's
+        # resource.description — the text facilitator catalogs display for the
+        # route. A description alone names the route without making it
+        # discoverable. Without `only:`, applies to every paywalled action in
+        # the controller. `method` is stamped from the actual request at render
+        # time.
+        def x402_discovery(only: nil, **config)
+          actions = only.nil? ? [:__all__] : Array(only).map(&:to_sym)
+          self.x402_discovery_declarations = x402_discovery_declarations.merge(
+            actions.to_h { |action| [action, config] }
+          )
+        end
       end
 
       def x402_paywall(options = {})
@@ -17,6 +43,7 @@ module X402
         wallet_address = options[:wallet_address]
         fee_payer = options[:fee_payer]
         accepts = options[:accepts]
+        @x402_paywall_extensions = options[:extensions]
 
         begin
           version_strategy = X402::Versions.for(protocol_version)
@@ -49,6 +76,20 @@ module X402
         )
       end
 
+      # The raw payment header, or nil when absent (or when the version is
+      # invalid). Pass version: on endpoints that override it via
+      # x402_paywall(version:).
+      def x402_payment_header(version: nil)
+        version_strategy = X402::Versions.for(version || X402.configuration.version)
+        request.headers[version_strategy.payment_header_name].presence
+      rescue X402::ConfigurationError
+        nil
+      end
+
+      def x402_payment_attempted?(version: nil)
+        x402_payment_header(version: version).present?
+      end
+
       private
 
       def generate_payment_required_response(amount, error_message = nil,
@@ -59,7 +100,7 @@ module X402
         requirement_response = X402::RequirementGenerator.generate(
           amount: amount,
           resource: request.original_url,
-          description: "Payment required for #{request.path}",
+          description: x402_declared_description || "Payment required for #{request.path}",
           chain: chain,
           currency: currency,
           version: protocol_version,
@@ -90,13 +131,54 @@ module X402
       end
 
       def render_402_response(requirement_response, version_strategy)
+        # The version strategy's output declares whether this protocol version
+        # carries extensions (v2 emits the key, v1 does not).
+        discovery = x402_resolved_discovery_extensions
+        if discovery.present? && requirement_response.key?(:extensions)
+          requirement_response[:extensions] = discovery
+        end
+
         if version_strategy.requirement_header_name
           response.headers[version_strategy.requirement_header_name] =
             Base64.strict_encode64(requirement_response.to_json)
         end
+        # payment challenges are per-request and must not be cached
+        response.headers["Cache-Control"] = "no-store"
         render json: requirement_response, status: :payment_required
       end
 
+      # Explicit x402_paywall(extensions:) wins over the class-level
+      # x402_discovery declaration for the current action. Either way the
+      # actual request method is stamped in, mirroring the reference server
+      # extension's request-time enrichment.
+      def x402_resolved_discovery_extensions
+        extension = @x402_paywall_extensions.presence || x402_declared_extension
+        return nil if extension.nil?
+
+        X402::DiscoveryExtension.with_method(extension, request.method)
+      end
+
+      # A description-only declaration just names the route; the extension is
+      # built only when I/O metadata (or a prebuilt hash) is declared.
+      def x402_declared_extension
+        config = x402_discovery_config
+        return nil if config.blank?
+        return config[:extensions] if config[:extensions]
+
+        declare_kwargs = config.except(:description)
+        declare_kwargs.presence && X402::DiscoveryExtension.declare(**declare_kwargs)
+      end
+
+      # The catalog display text declared via x402_discovery(description:) —
+      # facilitators surface it from the 402's resource.description.
+      def x402_declared_description
+        x402_discovery_config&.dig(:description)
+      end
+
+      def x402_discovery_config
+        x402_discovery_declarations[action_name&.to_sym] || x402_discovery_declarations[:__all__]
+      end
+
       def render_configuration_error(message)
         # Use V1 as a safe fallback when version is invalid to avoid recursive errors
         fallback_strategy = X402::Versions::V1.new
@@ -229,7 +311,6 @@ module X402
         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)
 
         request.env["x402.settlement_result"] = settlement_result
@@ -238,12 +319,11 @@ module X402
 
       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}")
+          X402.logger.debug do
+            "[x402] settling payment optimistic=#{X402.configuration.optimistic} " \
+              "payload=#{payment_info[:payload].inspect} " \
+              "requirement=#{payment_info[:requirement].to_h.inspect}"
+          end
 
           protocol_version = payment_info[:version] || X402.configuration.version
           version_strategy = X402::Versions.for(protocol_version)
@@ -256,15 +336,15 @@ module X402
 
           if settlement_result.success?
             response.headers[version_strategy.response_header_name] = settlement_result.to_base64
-            ::Rails.logger.info("x402 settlement successful: #{settlement_result.transaction}")
+            X402.logger.info("x402 settlement successful: #{settlement_result.transaction}")
           else
-            ::Rails.logger.error("x402 settlement failed: #{settlement_result.error_reason}")
+            X402.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
+        rescue X402::FacilitatorError, X402::InvalidPaymentError => e
+          X402.logger.error("x402 settlement error: #{e.message}")
+          X402::SettlementResponse.new("success" => false, "errorReason" => e.message)
         end
       end
 

data/lib/x402/rails/version.rb

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

data/lib/x402/rails.rb

@@ -12,7 +12,9 @@ require_relative "../x402/chains"
 require_relative "../x402/versions"
 require_relative "../x402/payment_requirement"
 require_relative "../x402/payment_payload"
+require_relative "../x402/discovery_extension"
 require_relative "../x402/settlement_response"
+require_relative "../x402/cdp_facilitator_auth"
 require_relative "../x402/facilitator_client"
 require_relative "../x402/payment_validator"
 require_relative "../x402/requirement_generator"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: x402-rails
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - QuickNode
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-04-10 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  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: rake
   requirement: !ruby/object:Gem::Requirement
@@ -137,16 +151,18 @@ files:
 - README.md
 - Rakefile
 - coverage/coverage.svg
+- lib/generators/x402/install/install_generator.rb
+- lib/generators/x402/install/templates/x402_initializer.rb
+- lib/x402/cdp_facilitator_auth.rb
 - lib/x402/chains.rb
 - lib/x402/configuration.rb
+- lib/x402/discovery_extension.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

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

@@ -1,32 +0,0 @@
-# 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