Getting Started

Treat v0.1.0 as the baseline assessment: this is the first release reviewed, and the release notes are only a changelog link. Pin requestway/laravel-x402 exactly and treat the README, service provider, config file, middleware, and tests as the source of truth.
Minimal setup: composer require requestway/laravel-x402, then inspect the package service provider for the middleware alias and config key. Publish any package config if available and set the facilitator URL, network, asset, pay-to address, and default price via environment variables.
First use case: protect one low-risk JSON API route, such as /api/premium/ping, with the package middleware and exercise it on a testnet using an x402-aware client. Confirm the flow: unpaid request returns 402 with payment requirements, paid retry includes the payment header, and the controller only runs after successful verification/settlement.
Look first at: README usage examples, config/x402.php or equivalent, middleware registration, route examples, and package tests. Since the release notes are thin, verify exact names against the installed source rather than guessing.

Implementation Patterns

Put paid API routes in a dedicated middleware group and keep health checks, docs, auth endpoints, and public metadata outside the paid surface.
Centralize x402 settings in config/env: facilitator endpoint, network, asset, pay-to address, timeout, and default price. Avoid scattering price/network details across route files.
Let the package middleware own the HTTP 402 challenge, payment verification, and settlement path. Controllers should receive already-authorized requests and focus on business logic.
Use per-route pricing where supported, but keep price definitions close to route groups so product pricing is reviewable. For dynamic pricing, wrap or extend the package’s middleware rather than duplicating protocol logic.
Build a small x402-aware client helper for tests and internal callers: request resource, parse 402 requirements, sign/pay, retry with the payment header, and assert the paid response.
Test both sides in Laravel HTTP tests: unpaid request returns 402 with expected requirements; paid request succeeds; malformed/expired/replayed payment is rejected.
Add observability around payment attempts and settlements: request IDs, route, price, network, facilitator result, and settlement status. This is critical for debugging and for proving paid access in production.

v0.1.0 is early-stage. Pin the version, read the changelog diff before upgrading, and expect API/config names to be less stable than a mature package.
Do not treat HTTP 402 as authentication. Combine paid routes with Laravel auth, rate limiting, authorization, and input validation where appropriate.
Be precise about amounts and asset decimals. Keep a single convention for decimal display vs atomic units and verify how the package expects prices to be configured.
The facilitator is an external dependency. Handle timeouts, verification failures, settlement failures, and facilitator 5xx responses explicitly; do not release protected content before the package confirms the payment path.
Middleware order matters. CORS preflight OPTIONS requests and route discovery should not accidentally require payment. Put abuse-prevention rate limits in front of expensive work, but verify how the package expects payment middleware to sit relative to auth and throttling.
Watch for proxy/CDN issues: X-PAYMENT and payment-response headers must be forwarded correctly, and 402 responses generally should not be cached like successful paid responses.
Use testnet and test wallets in local/CI. Never point automated tests at mainnet assets or production pay-to addresses.
Clear Laravel config cache after changing x402 env values. If the package supports events or custom middleware, use those extension points rather than forking the package for small policy changes.