x402 协议是 Coinbase 推出的开放支付标准，利用 HTTP 402 “Payment Required” 状态码实现链上微支付（如 USDC），特别适合 API 或内容服务的按需付费场景。它与 Rails 的 RESTful 架构高度契合，通过 middleware 或轻量 SDK 集成，能最小化代码变更。以下是最简洁的接入指南，基于 Coinbase 的官方 SDK 和社区扩展（如 l402_middleware gem，它直接支持 x402 的 L402 变体）。整个过程只需 5-10 行核心代码，优雅地嵌入 Rails 的 Rack 栈。

前提条件

• Rails 7+ 项目（确保有 Gemfile 和 config/routes.rb）。
• Node.js 和 Yarn（用于可选的客户端侧集成）。
• Coinbase 开发者账户：注册 Coinbase Developer Platform，获取 API 密钥（用于 facilitator 服务，处理链上结算）。
• Base 网络钱包：测试时用 Testnet USDC（无需真实资金）。

步骤 1: 安装依赖

在 Gemfile 中添加以下 gem：

# Coinbase 官方 Ruby SDK，用于钱包生成、交易签名和 facilitator 集成
gem 'coinbase-sdk-ruby', '~> 1.0'  # 处理 x402 的链上部分

# L402 middleware（社区 gem，支持 x402 的 HTTP 402 响应和支付验证）
gem 'l402_middleware', git: 'https://github.com/rits1272/l402_middleware.git'  # 或发布版 gem

运行 bundle install。如果需要客户端侧支持（如浏览器支付），安装 @coinbase/x402-sdk（JS）：

yarn add @coinbase/x402-sdk

步骤 2: 配置 x402 Facilitator

x402 的“facilitator” 是核心，它处理支付验证和结算（Coinbase 托管版免费）。在 config/initializers/x402.rb 中配置：

# config/initializers/x402.rb
require 'coinbase/sdk'

Coinbase::SDK.configure do |config|
  config.api_key = ENV['COINBASE_API_KEY']  # 从环境变量加载
  config.base_url = 'https://api.coinbase.com'  # 或 Testnet
end

# 定义支付参数（示例：0.01 USDC per API 调用）
X402_CONFIG = {
  amount: '0.01',
  currency: 'USDC',
  chain: 'base',  # Base Layer 2 网络
  facilitator_url: 'https://facilitator.coinbase.com/x402'  # Coinbase 托管
}.freeze

步骤 3: 集成 Middleware（最优雅的部分）

Rails 的 Rack middleware 是接入 x402 的最佳方式：它拦截请求，检查支付，返回 402 响应，并在支付后放行。无需修改控制器逻辑。

在 config/application.rb 中添加：

# config/application.rb
module YourApp
  class Application < Rails::Application
    config.middleware.use L402Middleware, X402_CONFIG  # 自动处理 402 响应和验证
  end
end

• 如何工作：Middleware 解析请求头中的 x402-payment（如果支付已完成），验证链上交易（调用 Coinbase SDK）。未支付时，返回 JSON 元数据（金额、地址、链 ID），客户端（如 AI 代理）据此发起支付。
• 优雅点：零侵入性——你的路由和控制器不变，只需在需要付费的路径上启用（见步骤 4）。

步骤 4: 在 Controller 中启用 x402

假设你有一个付费 API（如 /api/data），在控制器中标记付费端点：

# app/controllers/api/data_controller.rb
class Api::DataController < ApplicationController
  before_action :require_x402_payment, only: :show  # 只对 show 动作要求支付

  def show
    # 你的业务逻辑：返回付费数据
    render json: { data: 'Premium content unlocked!' }
  end

  private

  def require_x402_payment
    # Middleware 已处理 402，但这里可自定义逻辑
    unless request.headers['x402-payment']
      # 手动触发 402（fallback）
      response.set_header('WWW-Authenticate', "x402 #{X402_CONFIG.to_json}")
      render json: { error: 'Payment required' }, status: :payment_required
    end
  end
end

在 config/routes.rb 中定义路由：

# config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    resources :data, only: :show  # /api/data
  end
end

步骤 5: 处理客户端支付（可选，针对 AI/浏览器）

对于服务器端（seller），以上已够；如果你的 Rails app 也需作为 buyer（e.g., AI 代理调用外部 API），在服务层添加：

# app/services/x402_payment_service.rb
class X402PaymentService
  include Coinbase::SDK::Wallets  # 从 SDK 导入

  def pay_for_resource(url, amount = X402_CONFIG[:amount])
    # 1. 发送 HEAD 请求检查 402
    response = HTTP.head(url)
    if response.status == 402
      payment_req = JSON.parse(response.headers['WWW-Authenticate'].split('x402 ')[1])
      
      # 2. 生成临时钱包并支付（抽象 crypto 细节）
      wallet = create_wallet  # SDK 方法
      tx_hash = wallet.transfer(payment_req['address'], amount, payment_req['chain'])
      
      # 3. 重发请求带支付证明
      HTTP.get(url, headers: { 'x402-payment' => { tx_hash: tx_hash, amount: amount }.to_json })
    else
      response.body  # 无需支付
    end
  end
end

使用示例：在控制器或 job 中调用 X402PaymentService.new.pay_for_resource('https://external-api.com/data')。

测试与部署

• 本地测试：运行 rails server，用 curl 测试：

  curl -v http://localhost:3000/api/data  # 应返回 402 + 支付元数据
  # 模拟支付后：curl -H "x402-payment: {tx_hash: 'dummy'}" http://localhost:3000/api/data
  

• Testnet：用 Coinbase Playground（https://x402.coinbase.com/playground）模拟 AI 代理支付。
• 生产部署：设置 ENV 变量，确保 HTTPS（Rails 默认支持）。监控链上交易 via Coinbase Dashboard。
• 性能：Base 网络确认 <1s，Gas 费 <0.01 USD。Middleware 开销 negligible。

为什么简洁优雅？

• 最小变更：只需 middleware + 配置，无需重构控制器或添加复杂认证。
• Rails 原生：利用 Rack/HTTP 扩展，符合“约定优于配置”。
• 可扩展：易加限额（e.g., 用户模型中 track 余额）或多链支持。
• 社区支持：基于 coinbase/x402 GitHub 和 l402_middleware，未来更新无缝。

#x402 #coinbase #USDC #402