README

x402 Payment Middleware for Laravel & Symfony — gate routes behind instant USDC micropayments on Solana.

The x402 protocol revives HTTP 402 (Payment Required) to enable automatic, instant payments over HTTP. This package lets you protect any route with a single middleware call — AI agents and API consumers pay per-request in USDC on Solana.

Features

• One-line setup: ->middleware('x402:0.001') gates a route behind $0.001 USDC
• Native Solana verification: No third-party facilitator — verifies and settles transactions directly via Solana JSON-RPC
• Laravel + Symfony: Shared core with framework-specific adapters
• SpherePay compatible: Point X402_PAY_TO to a SpherePay offramp address for automatic fiat conversion
• Charge AI crawlers: Keep content free for humans, charge AI bots automatically
• x402 V2 compliant: Full protocol support with PAYMENT-REQUIRED and PAYMENT-RESPONSE headers

Requirements

• PHP 8.1+
• ext-sodium (built into PHP since 7.2)
• Solana RPC endpoint (public or private via Helius, QuickNode, etc.)

Installation

composer require solanaguide/laravel-x402

Laravel

The service provider is auto-discovered. Publish the config:

php artisan vendor:publish --tag=x402-config

Symfony

Register the bundle in config/bundles.php:

return [
    // ...
    SolanaGuide\X402\X402Bundle::class => ['all' => true],
];

Setup

1. Configure environment

X402_PAY_TO=YourSolanaWalletAddressHere
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

2. Initialize the pay-to wallet

Your X402_PAY_TO wallet must have an active USDC token account before it can receive payments. If the wallet has never held USDC, the token account won't exist and payments will fail.

To initialize it, send a small amount of USDC (e.g., $0.01) to the wallet from:

• A crypto exchange (Coinbase, Kraken, etc.) — withdraw USDC to your Solana address
• A Solana wallet app (Phantom, Solflare, Backpack, etc.)
• Swap SOL for USDC at jup.ag if you already have SOL

This automatically creates the Associated Token Account.

3. Verify your setup

php artisan x402:check

This command validates your configuration and checks on-chain that the token account exists. Run it before going live.

Configuration

Full Config Options

Usage

Laravel — Middleware Parameter (Simplest)

// Routes that cost $0.001 USDC per request
Route::get('/api/weather', WeatherController::class)
    ->middleware('x402:0.001');

// With a description
Route::get('/api/premium', PremiumController::class)
    ->middleware('x402:0.01,Premium weather data');

Laravel — Config-Based Pricing

// config/x402.php
'routes' => [
    'GET /api/premium/*' => ['price' => '0.01', 'description' => 'Premium content'],
    'POST /api/generate' => ['price' => '0.05', 'description' => 'AI generation'],
],

Symfony — Route Attribute

use Symfony\Component\Routing\Annotation\Route;

#[Route('/api/weather')]
public function weather(): Response
{
    // Set _x402_price on the request attributes
    return $this->json(['temp' => 72]);
}

How It Works

1. Client sends a request to a gated route
2. If no PAYMENT-SIGNATURE header is present, the middleware returns HTTP 402 with a PAYMENT-REQUIRED header containing payment details (amount, recipient, token, network)
3. Client constructs and signs a Solana SPL Token transfer transaction
4. Client retries the request with the signed transaction in the PAYMENT-SIGNATURE header
5. The middleware:
   • Deserializes the Solana transaction
   • Verifies the SPL Token transfer instruction (recipient, amount, token mint)
   • Verifies Ed25519 signatures
   • Submits the transaction to Solana via RPC
   • Polls for confirmation
6. On success, the original content is served with a PAYMENT-RESPONSE header containing the transaction hash

402 Response Format

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "maxAmountRequired": "1000",
      "resource": "YourSolanaAddress...",
      "payTo": "YourSolanaAddress...",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "maxTimeoutSeconds": 60,
      "scheme": "exact",
      "description": "",
      "mimeType": "application/json",
      "extra": {}
    }
  ]
}

SpherePay Integration

For automatic fiat conversion, create a SpherePay account and set your offramp Solana address as the pay-to address:

X402_PAY_TO=YourSpherePayOfframpSolanaAddress

All USDC payments are automatically converted to fiat and deposited to your bank account. No code changes needed.

Charging AI Crawlers

AI bots like GPTBot, ClaudeBot, and PerplexityBot scrape your content for training and retrieval. With x402, you can keep your content free for humans while charging AI crawlers automatically.

X402_AI_CRAWLER_PRICE=0.001

Then add the x402 middleware globally or to your web routes (without a price parameter):

// app/Http/Kernel.php — apply to all web routes
protected $middlewareGroups = [
    'web' => [
        // ... existing middleware
        \SolanaGuide\X402\Middleware\PaymentRequiredMiddleware::class,
    ],
];

Human visitors browse your site for free. AI crawlers get a 402 response with payment instructions. If they pay, they get the content.

Routes with an explicit price (x402:0.01) always charge that price regardless of the crawler setting.

The package detects 70+ known AI user agents across categories — agents, assistants, data scrapers, search crawlers, and undocumented bots. The full list is sourced from knownagents.com and includes GPTBot, ChatGPT-User, ClaudeBot, Claude-SearchBot, PerplexityBot, DeepSeekBot, Google-Extended, Bytespider, CCBot, Amazonbot, meta-externalagent, OAI-SearchBot, Manus-User, and many more.

Note: The x402 protocol is in its early days. Most AI crawlers today will not pay — they'll simply receive the 402 and move on. Setting a crawler price effectively blocks non-paying bots while laying the groundwork for a future where crawlers are expected to pay for content access.

Add custom patterns:

$detector = app(AiCrawlerDetector::class);
$detector->addPattern('MyCustomBot');

Testing

composer test

Or directly:

vendor/bin/phpunit

Architecture

src/
├── Core/           # Framework-agnostic x402 logic
├── Data/           # Value objects (PaymentRequirements, PaymentPayload, etc.)
├── Detection/      # AI crawler detection
├── Exceptions/     # Custom exceptions
├── Middleware/      # Laravel + Symfony middleware adapters
├── Solana/         # Solana transaction parsing + RPC (extracted from Attestto SDK)
└── Support/        # Constants (networks, tokens)

Credits

• Solana transaction parsing adapted from Attestto solana-php-sdk (MIT License)
• x402 Protocol

License

MIT License. See LICENSE for details.