quebracho / x402
x402 payments for PHP: EIP-712/EIP-3009 signing, PSR-15 middleware and PSR-18 paying client.
Requires
- php: ^8.3
- ext-gmp: *
- ext-sodium: *
- kornrunner/keccak: ^1.1
- kornrunner/secp256k1: ^0.4
- paragonie/ecc: ^2.6
- psr/cache: ^3.0
- psr/clock: ^1.0
- psr/event-dispatcher: ^1.0
- psr/http-client: ^1.0
- psr/http-factory: ^1.1
- psr/http-message: ^2.0
- psr/http-server-handler: ^1.0
- psr/http-server-middleware: ^1.0
- psr/log: ^3
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.95
- infection/infection: ^0.35
- nyholm/psr7: ^1.8
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^12
- shipmonk/composer-dependency-analyser: ^1.8
- symfony/http-client: ^7.3
Suggests
- ext-posix: Stop: checks that the flag file is owned by the user running PHP
- ext-redis: RedisLedger: one payment ledger for several hosts
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-21 14:41:49 UTC
README
x402 payments for PHP: sign and verify payments, a PSR-15 middleware for sellers and a PSR-18 client for buyers. No framework. MIT.
TL;DR
- Sell: a PSR-15 middleware (
X402Middleware) or an MCP one (X402McpMiddleware) answers402, verifies the payment offline, runs your handler once per payment and settles through a facilitator. - Buy:
PayingHttpClient/PayingMcpClientpay a402once, inside a per-network budget. - Safe by default: OFAC screening is on, a replayed payment never runs your handler, mock mode exists only by name.
- Chains: EVM (EIP-3009), Solana; NEAR and Casper are experimental.
Install
composer require quebracho/x402
Needs PHP 8.3+, ext-gmp, ext-sodium, any PSR-7/17 implementation (e.g.
nyholm/psr7) and, for buying, any PSR-18 client.
Upgrading: read UPGRADE.md (from 0.3, OFAC screening is on by default).
Sell
use Quebracho\X402\{EvmExact, Facilitators, FileLedger, Networks, Seller}; $facilitator = Facilitators::from('https://x402.org/facilitator', $psr18, $psr17, $psr17); $middleware = Seller::with([new EvmExact()], $facilitator, $psr17, $psr17) ->ledger(new FileLedger('/var/lib/x402/ledger')) // Price per request: a list of offers, or null when it is free. ->http(fn ($request) => [Networks::requirements('eip155:84532', '0.01', $payTo)]);
Unpaid → 402 with PAYMENT-REQUIRED. Paid → verify offline, verify with the
facilitator, claim, run the handler, settle only on 2xx, answer with
PAYMENT-RESPONSE. The ledger makes each payment buy one delivery and replays
the answer to a retry. Facilitators::from('mock', …) is mock mode (real
verification, nothing moves), never the default. Seller only names the
options: new X402Middleware(...) takes the same ones by position.
flowchart TD
A[Request] --> B{Payment header?}
B -- no --> C[402 + PAYMENT-REQUIRED]
B -- yes --> D[Verify offline + screen payer]
D -- invalid --> C
D -- ok --> E[Claim: one signature, one delivery]
E -- already claimed --> F[Refuse, handler not run]
E -- ok --> G{paymentFlow}
G -- default --> H[Run handler]
H -- 2xx --> I[Settle]
H -- error --> J[Free the claim, no charge]
I -- ok --> K[Response + PAYMENT-RESPONSE]
I -- fails --> L[Output withheld]
G -- upfront --> M[Settle]
M -- ok --> N[Run handler, receipt always returned]
M -- fails --> L
Loading
Everything else about selling is in docs/seller.md: the optional hooks, the payment ledger and its reconciler, events and logs, facilitators (generic, Circle, your own chain), MCP and job mode.
Buy
use Quebracho\X402\{Budget, Buyer, EvmExact, Signer}; $client = Buyer::with([new EvmExact(new Signer($testnetKey))], Budget::usd('eip155:84532', '0.05')) ->http($psr18); // $psr18 must not follow redirects
It pays a 402 once and retries. For MCP use ->mcp($psr18, $psr17). Budget,
allowlist of sellers and timeouts: docs/buyer.md.
Guides
| Guide | What is in it |
|---|---|
| docs/seller.md | hooks, payment ledger, events and logs, facilitators, MCP, job mode |
| docs/buyer.md | budget, seller allowlist, timeouts |
| docs/networks.md | built-in networks, adding an EVM chain |
| docs/screening.md | OFAC (on by default), more lists, listeners |
| docs/protections.md | what is checked, layer by layer, and the known limits |
| docs/extending.md | the interfaces, building by name (Seller, Buyer), adding a facilitator or a chain family |
| docs/near.md, docs/casper.md | the experimental schemes |
| UPGRADE.md, ROADMAP.md | moving between versions, what comes next |
Networks
Built in: the demo testnets (Base Sepolia, Arc testnet, Ethereum Sepolia,
Avalanche Fuji, Polygon Amoy, Solana devnet), Arc mainnet (eip155:5042)
and Ethereum mainnet (there to be read: the blacklist check is free;
settling there costs real gas). Any EVM chain whose token has
transferWithAuthorization is a Networks::add(...) away, see
docs/networks.md.
Schemes
Scheme (supports, pay, verify, payer) is one chain family; experimental
until 1.0. What else the library needs to know about a chain (the payment's
identity, its expiry, what an address is, what a buyer may sign) the scheme says
through optional interfaces, so a new family is added without touching the
core: docs/extending.md.
EvmExact: the stable one.SolanaExact(solana:*, devnet USDC built in): offline verification of one TransferChecked; smart wallets and lookup tables are refused. The offer needsextra.feePayer(HttpFacilitator::feePayer).NearExact(near:testnet): experimental, see docs/near.md.CasperExact(casper:casper,casper:casper-test): experimental, see docs/casper.md.
Frameworks without PSR-7
Drupal and Symfony speak HttpFoundation: bridge both ways with
symfony/psr-http-message-bridge and a PSR-17 factory. That buffers the body,
so streamed and file responses lose their laziness; fine for paid JSON or
Markdown. The steps are plain calls underneath (Scheme::verify,
Settlement::key, Settlement::run, a Facilitator), so a framework can
charge without PSR-15 too.
Tests
composer check # phpunit (no network), PHPStan, php-cs-fixer, dependency analyser
The rules the code follows, and which of them the build enforces: CONTRIBUTING.md.
See NOTICE for the origin of some classes.