Download the PHP package itsjustmoha/laravel-x402 without Composer

On this page you can find all versions of the php package itsjustmoha/laravel-x402. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package laravel-x402

laravel-x402

Latest Version on Packagist Total Downloads PHP Version Tests

Charge AI agents (and any other HTTP client) per request from a Laravel API using the x402 protocol: HTTP 402 Payment Required plus stablecoin payments that a third-party facilitator verifies and settles on a chain.

Status: 0.1.0, early. The core payment logic and the Laravel integration are tested here, but no real payment has gone through it yet. Read Verification status before you rely on it, and start on testnet.

The package is published as itsjustmoha/laravel-x402 (namespace Itsjustmoha\X402). If you fork it, change the vendor name in composer.json and the namespace with a search and replace; nothing else depends on it.

What is x402?

x402 is an open protocol that uses the HTTP 402 Payment Required status code to tell a client the price of a resource in machine-readable form. The client (often an AI agent with a wallet) signs a payment authorization, for example, an EIP-3009 USDC transfer, and retries the request with that authorization in a header. The server asks a facilitator to verify the authorization, serves the response, and then has the facilitator settle the transfer on chain, straight from the payer to your wallet.

This package is noncustodial. It never sees private keys and never holds funds; it only forwards signed authorizations to the facilitator. Money moves from the payer to your pay_to address.

Requirements

Installation

.env:

Protect a route in three lines

That's it. Calls without a payment get a 402 with the payment requirements; calls with a valid payment run your controller and are charged 0.01 USDC.

Alternatives and options:

Prices are strings: "$0.01", "0.01" and "1" all work. They are converted to atomic units exactly (string arithmetic, no floats). A price with more decimals than the token supports (USDC: 6) is rejected with an exception instead of being rounded.

Testnet quickstart

  1. Create a wallet (any EVM wallet) and copy its public address into X402_PAY_TO.
  2. Keep the defaults: network eip155:84532 (Base Sepolia) and facilitator https://x402.org/facilitator (the public testnet facilitator documented by the x402 project).
  3. Protect a route with ->paid('$0.01') and run php artisan serve.
  4. curl -i http://127.0.0.1:8000/api/report returns 402 with a PAYMENT-REQUIRED header.
  5. Fund a separate test buyer wallet with Base Sepolia USDC from https://faucet.circle.com/ and pay with an x402 client (next section).
  6. The paid response carries a PAYMENT-RESPONSE header with the transaction hash; look it up on https://sepolia.basescan.org.

Going to mainnet

Facilitators that need credentials

Implement AuthHeadersProvider and name the class in X402_FACILITATOR_AUTH. It is called for every facilitator request, so it can mint short-lived tokens:

Coinbase CDP expects a per-request JWT signed with your CDP API key. Generating that JWT is not included in this version (see Open decisions).

How an agent pays

Any x402 v2 client works. With the official TypeScript client (@x402/fetch, @x402/evm):

The buyer key belongs to the agent, never to your Laravel app. On the wire:

If browsers call your API directly, expose the headers in config/cors.php: 'exposed_headers' => ['PAYMENT-REQUIRED', 'PAYMENT-RESPONSE'].

Behaviour

The middleware follows the default authorization payment flow of the specification (verify, then run the resource, then settle) and mirrors the official Express/FastAPI middleware.

Situation Response Facilitator calls Handler runs Charged
No payment header 402, PAYMENT-REQUIRED header, same object as JSON body, Cache-Control: no-store none no no
Header is not base64 JSON / wrong shape 402, error invalid_payload none no no
Payment for other terms (amount, payTo, asset, network, ...) 402, error No matching payment requirements none no no
Same signed payment already in flight or just settled 402, error duplicate_payment none no no
Facilitator says invalid 402, error = facilitator invalidReason (e.g. insufficient_funds) verify no no
Facilitator unreachable, timeout, 5xx or malformed during verify 502 {"error":"facilitator_unavailable"} verify no no
Valid payment, handler returns 2xx handler response + PAYMENT-RESPONSE, Cache-Control: private verify, settle yes yes
Valid payment, handler returns non-2xx or throws handler response / exception unchanged verify yes no
Settlement rejected by facilitator 402, PAYMENT-RESPONSE with success:false, handler output discarded verify, settle yes no
settlement_pending settle is retried once (like the reference server); if still pending: 402 with the pending PAYMENT-RESPONSE verify, settle x2 yes maybe, check the tx hash
Facilitator unreachable during settle 502 {"error":"facilitator_unavailable"}, handler output discarded verify, settle yes unknown, the payment stays locked

Differences from the reference middleware, on purpose:

Streamed responses (StreamedResponse, file downloads) are settled before the body is streamed.

Events and logging

Event When Useful fields
Itsjustmoha\X402\Laravel\Events\PaymentVerified facilitator accepted the payment; handler runs next requirements, payer, version
Itsjustmoha\X402\Laravel\Events\PaymentSettled money moved settlement->transaction, settlement->network, requirements->amount
Itsjustmoha\X402\Laravel\Events\PaymentFailed a presented payment did not unlock the resource stage (verify/settle), reason, status, payer

Exceptions thrown by PaymentSettled listeners are reported but do not replace the paid response (the payer has already been charged). Put slow work in queued listeners (ShouldQueue).

Logs go to X402_LOG_CHANNEL (default channel if empty; X402_LOGGING=false turns them off). They contain path, network, amount, asset, reason and transaction hash. They never contain payer addresses, payment headers, or signatures. The events do carry the payer address, so if you persist it, treat it as personal data.

Bazaar discovery metadata

Facilitators that implement the bazaar extension can list your endpoint in a discovery catalog so agents find it. Add a discovery option; the package builds the extensions.bazaar object (info + JSON Schema) like the reference declareDiscoveryExtension() helper:

For routes with parameters (/users/{user}), routeTemplate (/users/:user) and pathParams are added automatically. Service-level metadata comes from config('x402.service') (name, tags, icon_url); values that break the specification's rules (non-ASCII or over 32 characters, more than 5 tags, IP or localhost icon URLs) are dropped silently, as the spec requires.

Use (object) [] for empty JSON objects inside your own schemas.

Protocol versions

x402 v2 (default) x402 v1 (opt-in: X402_V1_COMPATIBILITY=true)
Requirements PAYMENT-REQUIRED header (base64) + JSON body JSON body {x402Version:1, accepts:[...]}; the v2 header is still sent
Client payment header PAYMENT-SIGNATURE X-PAYMENT
Settlement header PAYMENT-RESPONSE X-PAYMENT-RESPONSE
Networks CAIP-2 (eip155:84532) legacy names (base-sepolia)
Amount field amount maxAmountRequired
Matching full requirements must match (extra may only be extended) scheme + network
Discovery extensions.bazaar outputSchema (best effort)

The version is taken from the payload's x402Version; PAYMENT-SIGNATURE wins if both headers are present. With v1 compatibility off (the default, like the official v2 servers), v1 payments get 402 invalid_x402_version. Turning it on changes the 402 JSON body to the v1 format; v2 clients are unaffected because they read the header first.

Supported scheme: exact on EVM networks with EIP-3009 tokens. Built-in USDC: Base Sepolia eip155:84532, Arbitrum Sepolia eip155:421614, Base eip155:8453, Ethereum eip155:1, Polygon eip155:137, Arbitrum One eip155:42161, Avalanche eip155:43114 (addresses and EIP-712 domains from typescript/packages/mechanisms/evm/src/defaultAssets.ts). Add more under x402.assets. Not supported yet: Solana/SVM, Permit2 tokens, the upto and batch-settlement schemes, the paywall HTML page.

Security

FAQ

Do I need a crypto wallet for the server? Only a public address to receive funds.

Can I charge in EUR? Not yet. Prices are USD stablecoin amounts.

What happens if my controller fails? Nothing is charged; the client can retry with the same signed payment.

Can I use different prices per route? Yes, every ->paid() call has its own price.

Can I use this without Laravel? src/Core has no framework dependencies: build a PaymentRequired with RequirementsBuilder, call PaymentGate::evaluate(), run your handler, then PaymentGate::settle(). Use CurlHttpTransport and your own PaymentLock.

How do I test my app? Use Http::fake() for the facilitator URL (/verify and /settle), or bind Core\Testing\FakeHttpTransport to HttpTransport and Core\Testing\InMemoryPaymentLock to PaymentLock.

Clients get a 502 from nginx on the 402 response. The PAYMENT-REQUIRED header grows with large discovery schemas. Raise fastcgi_buffer_size / proxy_buffer_size (e.g. 16k) or keep discovery schemas small.

Is there something similar already? Yes, see Related projects.

Verification status

What has been verified for 0.1.0:

CI (.github/workflows/tests.yml) runs Pint and Larastan, plus both test suites on PHP 8.3 and 8.4 with the highest and lowest dependencies. All jobs pass. The lowest set resolves to Laravel 12.69.0, Testbench 10.2.0, and PHPUnit 12.5.8, so Laravel 12 is covered as well as Laravel 13.

Not verified yet:

Specification sources

Implemented against coinbase/x402 at commit 0e6e8c55d86b4f14234fb6e49a4052074fb93e57 (2026-10-15), protocol version 2 (SDK 2.28.0):

Related projects

Other PHP implementations existed before this package; compare before choosing:

Roadmap / open decisions

License

MIT, see LICENSE.


All versions of laravel-x402 with dependencies

PHP Build Version
Package Version
Requires php Version ^8.3
ext-json Version *
illuminate/cache Version ^12.0|^13.0
illuminate/contracts Version ^12.0|^13.0
illuminate/http Version ^12.0|^13.0
illuminate/log Version ^12.0|^13.0
illuminate/routing Version ^12.0|^13.0
illuminate/support Version ^12.0|^13.0
psr/log Version ^2.0|^3.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package itsjustmoha/laravel-x402 contains the following files

Loading the files please wait ...