Technical architecture
Protocol first. Then x402. Then Elysium. Then a product.
Three layers, each with a job it does not share.
Off-chain commerce state is never confused with on-chain settlement state. The commerce layer coordinates; x402 moves the payment over HTTP; Elysium executes and makes it verifiable.
off-chain · signed objects
EPP-402 commerce layer
Coordinates the economic interaction around a payment.
- Service discovery
- Provider metadata
- Pricing and quotes
- Commerce sessions
- Payment intents
- Spending policies
- Transaction coordination
- Receipt generation
- Commerce history
HTTP · official v2 wire format
x402 payment layer
Requests, communicates, verifies and settles a payment over HTTP.
- HTTP 402 negotiation
- Payment requirements
- Payment payloads
- Payment schemes (exact)
- Payment verification
- Settlement interfaces
- Settlement responses
on-chain · EVM
Elysium settlement layer
Moves the money and makes it verifiable.
- EVM-compatible execution
- Supported payment assets
- Wallet signatures
- Smart contracts where required
- Transaction monitoring
- On-chain verification
| Package | Responsibility |
|---|---|
@epp402/protocol | Canonical schemas, types, identifiers, canonical hashing, EIP-712 typed data, state machines |
@epp402/sdk | The developer SDK: agent and provider helpers over the packages below |
@epp402/client | Buyer and agent-side payment handling on top of the official x402 client |
@epp402/server | Merchant-side payment middleware (Hono) on top of the official x402 resource server |
@epp402/facilitator | Verification and settlement: the x402 facilitator interface, idempotency, persistence |
@epp402/registry | Provider discovery crawler, index and public API; on-chain registry sync |
@epp402/session | Commerce session manager and stores |
@epp402/authorization | Spending policies and Payment Intents |
@epp402/receipts | Receipt issuance and independent verification |
@epp402/elysium | Elysium network adapter: verified parameters, chain, explorer, assets, deployments |
@epp402/db | PostgreSQL schema, migrations and repositories |
@epp402/cli | init, dev, inspect, simulate, publish, registry, receipts, session, doctor |
Stack: TypeScript, Node.js, pnpm, Solidity and Foundry, viem, the official x402 TypeScript packages, Hono, PostgreSQL, zod and JSON Schema, vitest, Next.js and Tailwind CSS.
The official v2 lifecycle, header for header.
x402 provides the mechanism by which an application requests payment, communicates requirements, receives a signed payload and verifies or settles it. EPP-402 preserves interoperability: an ordinary x402-compatible client can pay an EPP-402 endpoint without a different handshake.
- 01An agent requests a paid API resource.
- 02The provider responds with HTTP 402 Payment Required.
- 03The response carries the supported payment requirements in PAYMENT-REQUIRED.
- 04The agent selects a supported payment option.
- 05The agent constructs and signs the payment payload (an EIP-3009 authorization).
- 06The agent retries the request with PAYMENT-SIGNATURE.
- 07The provider asks the facilitator to verify the payment.
- 08The facilitator settles the payment on Elysium.
- 09The provider delivers the requested service.
- 10The response carries the settlement in PAYMENT-RESPONSE.
- 11EPP-402 issues the signed commerce receipt in EPP-RECEIPT.
Elysium Testnet first. Chain-independent at the core.
Network values are centralised in the network adapter and verified against the live chain, never hardcoded through the codebase. The initial payment asset is an EIP-3009 test token the protocol deploys; nothing assumes a stablecoin exists or supports gasless transfers until its contract has been read.
Payment authorization
- Wallet signatures
- Payment requirements
- Spending limits
- Authorization verification
- Nonce management
Transaction execution
- EVM transaction construction
- Supported asset transfers
- Facilitator execution
- Confirmation monitoring
- Settlement status
Commerce accounting
- Session accounting
- Provider attribution
- Quote reconciliation
- Receipt generation
- Payment history
| Contract | Purpose |
|---|---|
EPP402TestUSD.sol | The testnet payment asset: 6 decimals, EIP-3009 transferWithAuthorization, EIP-2612 permit, ERC-5267 domain, a rate-limited public faucet. |
EPP402Registry.sol | Optional on-chain provider registration: owner key, settlement recipient, discovery URI and hash, status, operator verification. |
EPP402Settlement.sol | An optional settlement relay for the exact scheme: executes the payer's authorization and records a commerce reference on-chain. |
EPP402Escrow.sol | Reserved for conditional payments, multi-party execution and refunds. Not part of the initial release. |
Not every x402 payment needs a custom contract: the exact scheme settles with the token's own transferWithAuthorization. The relay and the registry are extensions, and the facilitator never takes custody of user funds.
Fourteen protections in the first release, not the eighth.
Testing is not a phase that happens after the protocol is built. Each phase is implemented, tested, validated on testnet and accepted before the next begins, and the rules below hold in every component.
Mandatory protections
- 01Signature validation
- 02Nonce-based replay protection
- 03Payment expiry
- 04Chain ID verification
- 05Asset allowlisting
- 06Recipient verification
- 07Amount verification
- 08Quote integrity
- 09Duplicate settlement prevention
- 10Idempotent payment processing
- 11Facilitator authentication and rate limiting
- 12Secure private-key handling
- 13Receipt signature verification
- 14Provider impersonation protection
Execution rules
- Never release a paid resource based solely on an unverified payment payload.
- Never treat an HTTP 200 response as proof of blockchain settlement.
- Never treat an unconfirmed transaction as a completed settlement.
- Never permit expired authorization to be replayed.
- Never expose private keys in logs.
- Never trust provider-supplied settlement status without independent verification.
- Never assume successful payment means successful service delivery.
Failure handling in the initial release
- Payment verification failure
- Transaction submission failure
- Insufficient funds
- Expired quotes
- Provider unavailability
- Duplicate payment submissions
- Network congestion
- Payment success followed by resource-delivery failure
For multi-provider commerce, partial settlement and compensation requirements are tracked explicitly. Advanced escrow and arbitration are not part of the initial release.