# @three-ws/x402-modal **A drop-in payment modal for any [x402](https://x402.org) paid endpoint.** One ` ``` > Pin a version for production, e.g. > `https://unpkg.com/@three-ws/x402-modal@0.2.0/global`. The CDN bundle is a single self-contained file (~12 kB gzipped). No `npm`, no build step. --- ## Quickstart The smallest possible page that pops the modal and settles a `402`. Save it as `index.html`, replace the endpoint with your own x402 route, and open it: ```html x402 checkout 


    
    
  

```

Clicking the button opens the modal, runs the payment, calls the endpoint, and
fires `x402:result` on the button with the full
`{ ok, result, payment, response }` payload.

Prefer to drive it yourself? Call `pay()` and await the result:

```js
import { pay } from '@three-ws/x402-modal';

const out = await pay({
  endpoint: '/api/paid/summarize',
  method: 'POST',
  body: { text: 'hello world' },
  merchant: 'Acme',
  action: 'Summarize',
});

console.log(out.result);  // the endpoint's response, after settlement
console.log(out.payment); // { network, payer, transaction }
```

`pay()` resolves once the paid call returns `200`, or rejects with an `Error`
whose `.code === 'cancelled'` if the user closes the modal.

---

## How it works

The modal drives the four-step x402 flow. Each step renders as a live row in the
modal (spinner → check → error), with a **Try again** affordance on failure,
automatic retry on a `429` upstream throttle (the payment isn't settled until the
work succeeds, so re-sending can't double-charge), and a receipt with an explorer
link on success.

```mermaid
sequenceDiagram
    participant U as User
    participant M as x402-modal
    participant W as Wallet (Phantom / EVM)
    participant E as Merchant endpoint

    U->>M: click / pay({ endpoint })
    M->>E: 1. DISCOVER — request with no payment
    E-->>M: 402 + accepts[] (asset · amount · network · payTo)
    M->>U: render price + network, pick a wallet
    U->>W: 2. CONNECT
    W-->>M: account address
    M->>W: 3. SIGN — EVM: EIP-3009 typed data · Solana: built tx
    W-->>M: signed authorization / transaction
    M->>E: 4. SETTLE — re-send request with X-PAYMENT
    E-->>M: 200 + result + x-payment-response receipt
    M-->>U: receipt + explorer link, resolve pay()
```

1. **Discover** — send the request you described with no payment. Expect a `402`
   with a JSON body containing `accepts[]`, or a `401` with a base64-JSON
   `payment-required` header (MCP 2025-06-18). Anything else is an error.
2. **Connect** — pick a wallet that can satisfy an accept: Solana → Phantom,
   EVM → MetaMask / any injected `window.ethereum`. When the `402` advertises
   more than one network the modal shows a wallet picker; with exactly one it
   goes straight there.
3. **Sign** — EVM signs an EIP-3009 `transferWithAuthorization` (no on-chain tx,
   no gas for the payer). Solana has a backend build the transaction, then
   Phantom signs it.
4. **Settle** — re-send the request with the `X-PAYMENT` header. The endpoint
   runs the work, settles on-chain, and returns `200` plus an
   `x-payment-response` receipt.

> The full step-by-step protocol, including the `401`/`payment-required` header
> variant and SIWX re-entry, lives in [`docs/PROTOCOL.md`](./docs/PROTOCOL.md).

---

## API reference

The ESM entry (`@three-ws/x402-modal`) is **side-effect-free** — importing it
never touches `window` or binds anything. The `/global` entry adds the auto-bind
behavior and `window.X402`.

### `pay(options): Promise`

Open the modal for one endpoint and resolve after settlement.

```ts
function pay(options: PayOptions): Promise;
```

| option        | type                          | default          | notes |
|---------------|-------------------------------|------------------|-------|
| `endpoint`    | `string`                      | — (**required**) | the x402-protected URL to pay for and call |
| `method`      | `string`                      | `GET` / `POST`\* | \*defaults to `POST` when a `body` is set |
| `body`        | `object \| string`            | —                | forwarded to the endpoint (object → JSON) |
| `headers`     | `Record`       | —                | merged into discovery + paid calls |
| `merchant`    | `string`                      | header default   | shown in the modal header |
| `action`      | `string`                      | header default   | shown in the modal header (e.g. "Summarize") |
| `caps`        | `SpendingCaps`                | —                | µUSD spending caps (see [caps](#spending-caps)) |
| `autoConnect` | `boolean`                     | `false`          | skip the picker when exactly one wallet is detected |
| `apiOrigin`   | `string`                      | global config    | per-call override of the Solana checkout backend |
| `brand`       | `{ label, href }`             | global config    | per-call footer override |

**Returns** `PayResult`:

```ts
interface PayResult {
  ok: true;
  result: unknown;                  // the endpoint's response body (JSON or text)
  payment?: { network, payer, transaction, ... }; // present on a fresh payment
  siwx?: { address, network };      // present on SIWX re-entry instead of paying
  response: { status: number; headers: Record };
}
```

**Rejects** with an `Error`. A user-cancelled modal rejects with
`err.code === 'cancelled'` — check for it to distinguish a deliberate close from
a real failure.

### `configure(config): config`

Merge config into the global defaults and return the resolved snapshot. Call it
once at startup, before the first `pay()`. See [Configuration](#configuration-reference).

```ts
function configure(config?: X402Config): Required;
```

### `getConfig(): config`

Read the current resolved global config.

```ts
function getConfig(): Required;
```

### `init(): void`

Scan the document and bind every `[data-x402-endpoint]` element. Idempotent.

The `/global` build calls this automatically (and re-scans on DOM mutation via a
`MutationObserver`). Call it yourself only when using the **ESM** build with
declarative `data-*` buttons.

### `bindElement(el: Element): void`

Bind one element's click to open the modal. On success it dispatches
`x402:result` (and `x402:siwx-signed` when re-entry was via SIWX); on failure
`x402:error`. A user cancel dispatches nothing. Idempotent per element.

### `readOptsFrom(el: Element): PayOptions`

Read `PayOptions` from an element's `data-x402-*` attributes. Useful if you want
to bind elements yourself with custom event handling.

### `version: string`

The package version string (e.g. `"0.2.0"`).

### `class CheckoutModal`

The low-level modal controller. Most callers should use `pay()` instead.

```ts
class CheckoutModal {
  constructor(opts: PayOptions);
  mount(): Promise;   // mount the DOM, return the result promise
  start(): Promise;        // begin discovery
  close(reason?: string): void;  // close; reason 'cancelled' rejects mount()
}
```

`pay(opts)` is exactly `new CheckoutModal(opts)`, then `mount()` + `start()`.

### DOM events

Bound elements dispatch bubbling `CustomEvent`s:

| event               | `detail`                  | when |
|---------------------|---------------------------|------|
| `x402:result`       | the full `PayResult`      | the paid call succeeded |
| `x402:siwx-signed`  | `{ address, network }`    | the user re-entered via SIWX instead of paying (fires just before `x402:result`) |
| `x402:error`        | `{ error: string }`       | the flow failed (a **cancel does not fire this**) |

### Exports map

| import specifier                     | build | shape |
|--------------------------------------|-------|-------|
| `@three-ws/x402-modal`               | `dist/x402-modal.mjs` | ESM, side-effect-free public API |
| `@three-ws/x402-modal/global`        | `dist/x402.global.js` | minified IIFE, auto-binds + `window.X402` |
| `@three-ws/x402-modal/src`           | `src/x402-modal.js`   | unbundled source (advanced / debugging) |

The `unpkg` and `jsdelivr` package fields point at `/global`, so bare
`unpkg.com/@three-ws/x402-modal` also resolves to the drop-in build.

---

## Configuration reference

Three ways to configure, in increasing specificity (later wins):

1. **`data-x402-*` on the `/global` `




```

### React

`pay()` is just a promise — call it from any handler. No provider, no context.

```jsx
import { useState, useCallback } from 'react';
import { pay } from '@three-ws/x402-modal';

export function PayButton() {
  const [out, setOut] = useState(null);
  const [error, setError] = useState(null);

  const onPay = useCallback(async () => {
    setError(null);
    try {
      const res = await pay({
        endpoint: '/api/paid/summarize',
        method: 'POST',
        body: { text: 'hello world' },
        merchant: 'Acme',
        action: 'Summarize',
      });
      setOut(res.result);
    } catch (err) {
      if (err.code === 'cancelled') return; // user closed the modal
      setError(err.message);
    }
  }, []);

  return (
    <>
      
      {error && 
{error}
}
      {out && 
{JSON.stringify(out, null, 2)}
}
    
  );
}
```

Set global config once in your app entry (e.g. `main.jsx`):

```js
import { configure } from '@three-ws/x402-modal';
configure({ brand: { label: 'Powered by Acme', href: 'https://acme.com' } });
```

The same pattern works in Vue, Svelte, Solid, or any framework — import `pay`,
call it from an event handler, await the result.

### `

```

`window.X402` exposes `{ pay, init, configure, version }`.

More end-to-end walkthroughs — content paywall, SPA checkout, self-hosting,
agents with caps — live in [`docs/EXAMPLES.md`](./docs/EXAMPLES.md) and
[`TUTORIAL.md`](./TUTORIAL.md), with runnable code in [`examples/`](./examples).

---

## Wallets & assets

| Network                              | Wallet                              | Scheme                                  | Backend? |
|--------------------------------------|-------------------------------------|-----------------------------------------|----------|
| **Base** (`eip155:8453`)             | MetaMask / any `window.ethereum`    | EIP-3009 `transferWithAuthorization`    | **No** — fully client-side |
| Base Sepolia, Arbitrum, Optimism     | same                                | EIP-3009                                | No |
| **Solana** (`solana:*`)              | Phantom                             | `exact` (facilitator-settled)           | Yes — `prepare`/`encode` helper |

- **USDC is the default asset.** Base USDC is signed via EIP-3009 (the domain
  version is pinned to the on-chain separator). Solana USDC settles through the
  facilitator.
- **Arbitrary SPL tokens** are supported on the Solana path — the `402`'s
  `accept.asset` is the SPL mint, and `accept.extra` carries `name` / `decimals`.
  Only stablecoins map exactly to µUSD for caps; cap non-stable assets
  server-side.
- **No wallet adapter or WalletConnect needed.** Solana uses the injected
  Phantom provider; EVM uses the injected `window.ethereum`.
- **The payer never pays gas.** On EVM, EIP-3009 is a gasless signed
  authorization the facilitator submits. On Solana the facilitator is the
  fee-payer.

### The Solana backend

EVM/Base needs no backend. **Solana needs one tiny helper**, because a browser
wallet *signs* transactions but does not *build* them (building needs RPC access
and the facilitator's fee-payer). The modal POSTs to two actions at
`{apiOrigin}/api/x402-checkout`:

| action            | request                                                     | response |
|-------------------|-------------------------------------------------------------|----------|
| `?action=prepare` | `{ accept, buyer }`                                          | `{ tx_base64 }` — an unsigned/partially-signed `VersionedTransaction` |
| `?action=encode`  | `{ accept, signed_tx_base64, resource_url, builder_code? }` | `{ x_payment }` — the base64 `X-PAYMENT` value to send to the merchant |

`apiOrigin` defaults to the origin that served the script, so when you self-host
both the script and this helper there is nothing to configure. The full contract,
a reference implementation, and a hardening checklist are in
[`docs/BACKEND.md`](./docs/BACKEND.md); runnable code is in
[`examples/server.mjs`](./examples/server.mjs).

---

## Theming & styling hooks

The modal injects one self-contained stylesheet (`#x402-styles`) scoped to
`.x402-*` classes, with full `prefers-color-scheme` light/dark support and a
`prefers-reduced-motion`-friendly entrance animation. To restyle, override those
classes after the script loads:

```css
.x402-modal     { border-radius: 8px; }          /* the card */
.x402-pay-btn   { background: #6d28d9; }          /* the primary CTA */
.x402-wallet-btn:hover:not(:disabled) { border-color: #6d28d9; }
.x402-price     { letter-spacing: -0.02em; }      /* the price line */
```

Key hooks: `.x402-overlay`, `.x402-modal`, `.x402-head`, `.x402-merchant`,
`.x402-price-row`, `.x402-network`, `.x402-step` (`.x402-active` / `.x402-done` /
`.x402-error`), `.x402-wallet-btn`, `.x402-pay-btn`, `.x402-close`. The two
header lines are set by `merchant` / `action`; the footer text/link by `brand`.

---

## Security

- **The modal never holds keys.** Signing happens in the user's wallet; the
  signed payload goes to your endpoint.
- **Client-side spending caps** are advisory guardrails enforced in
  `localStorage` — they stop *this browser* from overspending and survive
  reloads, but a determined user can clear storage. Treat them as a UX guardrail
  for agents and humans, and enforce authoritative limits server-side.
- **Idempotent retries.** A `429` from the merchant is retried with the *same*
  signed payment — safe, because x402 settles only after the work succeeds.
- **No leakage.** Upstream throttle/billing text is never relayed to the buyer
  verbatim; all endpoint-supplied strings are HTML-escaped before rendering.
- **CSP note.** On the Solana path the dynamic CDN import can be blocked by a
  strict Content-Security-Policy; either allow it, repoint it via `solanaWeb3Url`
  / `nobleHashesUrl`, or steer users to the dependency-free Base path.

---

## FAQ & troubleshooting

**The modal opens but immediately errors with "Endpoint returned … but no
`accepts`".** Your endpoint isn't returning a valid x402 `402`. The modal expects
a `402` with a JSON body containing a non-empty `accepts[]` array (or a `401`
with a base64-JSON `payment-required` header). Pointing the modal at a free `200`
endpoint is treated as an error on purpose.

**Do I need a wallet adapter / WalletConnect?** No. Solana uses the injected
Phantom provider; EVM uses the injected `window.ethereum`. If neither is present,
the modal tells the user to install a wallet.

**Does the payer pay gas?** No. On EVM, EIP-3009 is a gasless signed
authorization your facilitator submits. On Solana the facilitator is the
fee-payer.

**My Solana payment fails but Base works.** Base is fully client-side; Solana
needs the `prepare`/`encode` backend helper. Confirm `apiOrigin` resolves to a
host serving `/api/x402-checkout` (see [`docs/BACKEND.md`](./docs/BACKEND.md)),
and that a strict CSP isn't blocking the `@solana/web3.js` CDN import — repoint
it with `solanaWeb3Url` if so.

**`pay()` rejected — how do I tell a cancel from a real error?** A user-closed
modal rejects with `err.code === 'cancelled'`; everything else is a genuine
failure. The declarative path never fires `x402:error` on a cancel.

**A payment got rejected before the wallet even opened.** A spending cap was hit.
Caps are per-wallet in `localStorage`, bucketed by UTC hour/day. Raise the cap,
or clear the bucket by waiting out the window.

**Can I theme it / does it support dark mode?** Yes — see
[Theming](#theming--styling-hooks). It honors `prefers-color-scheme` out of the
box and exposes `.x402-*` classes for overrides.

**Does it work in React/Vue/Svelte?** Yes — it's framework-agnostic. Import
`pay()` and call it from a handler, or drop the `/global` script and use `data-*`
buttons. See [Framework guides](#framework-guides).

---

## Related packages

- **[`@three-ws/x402-payment-modal`](https://www.npmjs.com/package/@three-ws/x402-payment-modal)**
  — a sibling package. If you arrived looking for that one, note the difference:
  this package (`@three-ws/x402-modal`) is the **dependency-free, bundler-free
  drop-in** focused on the smallest possible client (one `