Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Architecture
@three-ws/x402-payment-modal is a single zero-dependency vanilla-JS ES module
that turns any x402-protected HTTP endpoint into a one-click
checkout. It owns the entire client lifecycle: discovering the payment challenge,
connecting a wallet, signing the payment, retrying the request with proof, and
rendering a receipt plus the endpoint's result.
This document explains how the modal works end to end. For the public surface, see the API reference. For the Solana checkout backend, see server setup.
The x402 flow in one sentence
The merchant answers an unpaid request with HTTP 402 describing what it wants; the modal makes the user sign a payment matching that description; the modal retries the same request with an
X-PAYMENTheader; the merchant settles the payment and returns the real result.
The package never holds funds and never moves money on its own. It only produces a signed payment authorization and hands it back to the merchant, who settles it through an x402 facilitator.
Lifecycle
discover → connect → authorize → verify (retry + settle) → receipt
These map directly to the four visible modal steps:
| Step | Modal label | What happens |
|---|---|---|
discover |
Confirming price | Probe the endpoint, parse the 402 challenge, render price + network. |
connect |
Connect wallet | Detect Phantom / EVM wallet, let the user pick and connect one. |
authorize |
Authorize payment | Produce a signed payment (EVM EIP-3009 typed-data, or Solana signed tx). |
verify |
Verify & complete | Re-send the request with X-PAYMENT; merchant settles; show receipt. |
Each step is rendered as a .x402-step element and carries .x402-active,
.x402-done, or .x402-error modifiers as it progresses. See
theming for styling hooks.
Challenge discovery
When pay() first calls the endpoint (using the configured method, body, and
headers), it inspects the response for a payment challenge. It accepts any of:
- HTTP 402 with a JSON body describing the accepted payment(s).
- HTTP 402 with a
payment-requiredresponse header (the body-less form). - MCP-style HTTP 401 with a
payment-requiredheader — used by Model Context Protocol servers that gate tools behind payment.
The parsed challenge contains one or more accepts entries. Each entry names a
network (e.g. an EVM chain like Base, or a Solana network), an asset, an
amount, the pay-to address, and protocol extra/extensions metadata. If the
challenge advertises SIWX, the modal can offer sign-in re-entry
instead of a fresh payment.
If the very first response is not a payment challenge — e.g. an immediate
200 (the endpoint isn't paid) or any other non-402 status — discovery
throws: the modal renders the error on the discover step rather than
silently succeeding, since pointing the modal at a free or non-x402 endpoint is
almost always a misconfiguration worth surfacing.
Two signing paths
x402 supports multiple settlement rails. The modal implements two, and which one
runs is decided entirely by the network in the selected accepts entry.
EVM path — browser-only (EIP-3009)
EVM stablecoin payments (e.g. USDC on Base) use EIP-3009 "transfer with
authorization." The browser wallet (MetaMask or any injected EIP-1193 provider)
signs an EIP-712 typed-data authorization. This is a pure signature — no funds
move at signing time and no server call is made. The signed authorization
becomes the X-PAYMENT header; the merchant's facilitator submits it on-chain
when it settles.
Because the signature is generated entirely in the browser, EVM-only sites need nothing on the server side of this package.
Solana path — server-assisted (prepare / encode + Phantom)
Phantom signs serialized transactions, not arbitrary typed data, so the Solana path needs a small backend to build the transaction the wallet will sign. The flow:
- Client posts the selected
acceptsentry and the buyer's address to the checkout server:POST /api/x402-checkout?action=prepare. - The server builds a partially-signed SPL
transferCheckedv0 transaction. The fee payer is a facilitator sponsor account (accept.extra.feePayer), so the buyer needs only USDC — no SOL for gas. - The server returns
tx_base64+recent_blockhash. - Phantom signs the transaction (
signTransaction). - Client posts the signed tx to
?action=encode; the server wraps it into a base64 x402 v2 payment envelope and returnsx_payment. - That envelope becomes the
X-PAYMENTheader on the retry.
See server setup for mounting prepare/encode.
Retry, settle, and the 429 auto-retry
Once a signed payment exists, the modal re-issues the original request with the
X-PAYMENT header attached. Outcomes:
- 2xx — the merchant accepted and settled the payment. The modal parses the
body (JSON or text), extracts any
payment/receipt metadata from the response, renders the receipt + result, and resolves thepay()promise. - HTTP 429 (throttled) — the facilitator was rate-limited. Payment is not
settled until the merchant call actually succeeds, so it is safe to re-send
the same signed payment. The modal auto-retries up to 2 additional times
with the identical
X-PAYMENTpayload before surfacing an error. - Other 4xx/5xx — surfaced as an error in the modal (and via the
x402:errorevent), with the reservation rolled back if spending caps were in play.
This retry-on-429 is why the modal keeps the signed payment in memory rather than re-prompting the wallet: re-signing is unnecessary and would annoy the user.
Sequence diagram
User Modal Merchant Checkout server Wallet
| | | | |
| click | | | |
|----------->| pay(opts) | | |
| | GET/POST endpoint | | |
| |------------------->| | |
| | 402 + accepts | | |
| |<-------------------| | |
| | [discover] price | | |
| | | | |
| | [connect] pick wallet ------------------------------------>|
| |<----------------------------------------------- address |
| | | | |
| == EVM path (browser-only) == | | |
| | sign EIP-3009 typed data ----------------------------------->|
| |<-------------------------------------------- signature |
| | | | |
| == Solana path (server-assisted) == | |
| | POST ?action=prepare ------------------->| |
| |<------------------ tx_base64, blockhash --| |
| | signTransaction ------------------------------------------>|
| |<-------------------------------- signed tx |
| | POST ?action=encode --------------------->| |
| |<------------------------- x_payment ------| |
| | | | |
| | [verify] retry with X-PAYMENT | |
| |------------------->| | |
| | (429? re-send same payment, up to 2x) | |
| | 200 + result + receipt | |
| |<-------------------| | |
| receipt | | | |
|<-----------| resolve PayResult | | |
Cancellation
If the user closes the modal at any point, pay() rejects with an Error whose
.code === 'cancelled'. Any spending-cap reservation made for the attempt is
rolled back. Callers should treat cancelled as a no-op, not a failure.
Distribution shape
- Client: one ES module (
src/index.js), also shipped minified (dist/x402.min.js). It self-registerswindow.X402and auto-binds[data-x402-endpoint]elements. Crypto helpers (@solana/web3.js, noble hashes) are loaded on demand from CDN ESM and can be repointed for strict CSP viaconfigure. - Server: optional, only for the Solana rail. Exposed at
@three-ws/x402-payment-modal/serverwith Express and Vercel adapters.