x402 support
Exact Lucid x402 support by version, scheme, network, client, facilitator, and extension.
Lucid receives and buys HTTP-native payments using x402 v2. It wraps the wire exchange in one application transaction: verify, reserve policy capacity, fulfill, settle, and record.
Upstream x402 supports more transports, schemes, extensions, networks, and facilitator combinations than this Lucid release.
Support matrix
| Capability | Status | Lucid behavior |
|---|---|---|
| x402 v2 HTTP headers | Supported | PAYMENT-REQUIRED, PAYMENT-SIGNATURE, PAYMENT-RESPONSE |
exact scheme | Supported | EVM/Solana seller offers over invoke, SSE, and paid task admission |
upto scheme | Supported | EVM invoke only; handler reports bounded payment.actualAmount |
batch-settlement scheme | Supported | EVM invoke, SSE, and task; production requires durable channel storage |
Multiple accepts options | Supported | Ordered offers may vary by scheme, network, asset, facilitator, and destination |
| EVM seller | Supported | Canonical eip155:* networks supported by the selected released mechanism/provider |
| Solana seller | Supported | Mainnet and Devnet canonical CAIP-2 identifiers |
| EVM buyer | Supported | Built-in paid Fetch registers released EVM exact/upto/batch mechanisms |
| Solana buyer | Not supported | Use an external x402 client; seller verification does not imply buyer signing |
| SIWX | Supported | Auth-only routes and reusable paid entitlements with public-origin binding |
| Payment Identifier | Supported | Invoke-only reconciliation tied to Idempotency-Key |
| Bazaar projection | Supported | OpenAPI and Bazaar metadata project from the canonical entrypoint schema |
| Paid Lucid tasks | Supported | Exact/batch only, with caller-known capability and durable task storage |
| MCP x402 transport | Not supported | Lucid's payment exchange is HTTP entrypoint/task bound |
| Signed offers and receipts extension | Supported | Optional injected issuer; normal settlement receipts remain distinct |
| Gas sponsorship | Not supported | Depends on external wallet/provider behavior |
| Stripe dynamic destination | Partial | Server-only provider export; Base mainnet only |
Wire transaction
1. Buyer calls the Lucid route without a credential.
2. Server returns 402 plus PAYMENT-REQUIRED (x402Version: 2).
3. Buyer selects the advertised requirement and retries with PAYMENT-SIGNATURE.
4. Facilitator verification identifies a valid payer and payment payload.
5. Lucid reserves sender, total, rate, and idempotency capacity.
6. The handler runs (or a task is durably reserved).
7. Lucid stages accounting, asks the facilitator to settle, and commits it.
8. The application response carries PAYMENT-RESPONSE.Adapters must delegate to the shared HTTP authorization transaction. Installing a framework-local paywall would split verification, idempotency, settlement, and accounting into competing flows.
Pricing, asset, and units
The shorthand entrypoint price is a decimal string such as "0.05"; never
use JavaScript numbers for money. Explicit x402.offers instead carry atomic
token amounts with their asset. The selected facilitator must advertise the
same scheme, network, asset, and required scheme metadata from /supported.
Network identifiers
New configuration must use canonical CAIP-2 identifiers:
eip155:8453 # Base mainnet
eip155:84532 # Base Sepolia
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp # Solana mainnet
solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 # Solana DevnetHistorical aliases such as base-sepolia and solana:devnet are accepted at
the configuration boundary. Runtime state and discovery metadata emit the
canonical value.
The facilitator must support the same x402 version, scheme, network, and asset. Production applications should probe support on startup and alert on drift.
Seller and buyer boundaries
The seller path supports EVM and Solana exact verification plus EVM upto and
batch settlement. The convenience buyer createX402Fetch() uses an EVM local
account and cannot pay Solana requirements. A runtime buyer can also obtain a
payment-aware Fetch through the payments runtime when an appropriate wallet
client is available.
Buyer policy limits are a Lucid feature, not an x402 budget protocol. They protect one deployment only when their tracker is durable and shared across workers.
Failure and refund semantics
| Failure point | Expected result |
|---|---|
| Missing/malformed credential | Return challenge or reject; do not run the handler |
| Facilitator verification fails | Reject; release provisional state |
| Incoming policy rejects payer or amount | Reject before settlement/fulfillment |
| Handler fails before irreversible settlement | Release reservations; no successful application response |
| Settlement definitively fails | Release staged accounting and return an error |
| Process loses settlement outcome | Reconcile against the facilitator/chain before retrying |
| Business refund requested | Execute a separate, idempotent transfer and record it; x402 exact has no automatic refund |
The application must decide whether fulfillment may happen before settlement and how to recover an unknown outcome. Lucid's normal route finalization settles before returning success, but external systems can still time out after the payment becomes irreversible.
Security and production checklist
- Use HTTPS and never log payment credentials or private keys.
- Authenticate production facilitator calls when supported and scope the token
to
/verify,/settle, and/supported. - Confirm the facilitator, network, asset, payee, and price from the verified requirement—not caller-controlled headers.
- Use durable Postgres or SQLite tracking as appropriate; use shared Postgres for horizontally scaled policy enforcement.
- Require a stable 20–256 character
Idempotency-Keyfor retryable effects. - Reconcile settlement receipts with facilitator or chain records and alert on staged/unknown outcomes.
- Test expired authorization, duplicate retry, concurrent retry, wrong network, wrong amount, handler failure, facilitator timeout, and restart recovery.
- Do not use the public x402.org test facilitator as an assumed production SLA; choose and verify an explicit production facilitator.
Interoperability claim
Lucid implements the documented x402 v2 HTTP exact EVM/Solana, upto EVM, and batch-settlement EVM subsets through the pinned official TypeScript cohort. It also projects Payment Identifier, Bazaar, SIWX, and optional signed offer/receipt capabilities. It does not implement every upstream network, extension, or transport. Run an end-to-end paid call against the specific facilitator and counterparty release you will deploy.
Start with every x402 payment method, then add durable storage and payment troubleshooting.