Download the PHP package solanaguide/laravel-x402 without Composer

laravel-x402

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

Laravel

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

Symfony

Register the bundle in config/bundles.php:

Setup

1. Configure environment

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

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)

Laravel — Config-Based Pricing

Symfony — Route Attribute

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

SpherePay Integration

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

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.

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

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:

Testing

Or directly:

Architecture

Credits

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

License

MIT License. See LICENSE for details.