@three-ws/x402-payment-modal 1.1.0 → 1.2.0

package/docs/EXAMPLES.md

@@ -0,0 +1,137 @@
+# Examples
+
+Every example in [`../examples`](../examples) is runnable. They point at
+placeholder endpoints (`https://api.example.com/…`) — swap in a real x402 endpoint
+to take an actual payment. This page indexes them and shows the smallest snippet
+for each integration style.
+
+| Example | Shows | Run it |
+| --- | --- | --- |
+| [`plain-html/`](../examples/plain-html) | No build step. Declarative `data-x402-*` buttons, a programmatic `pay()` call, and `x402:result`/`x402:error` handling from one CDN `<script>`. | Open `index.html`, or `npx serve examples/plain-html`. |
+| [`react/`](../examples/react) | Using the shipped `./react` wrapper (`X402Button`). | Copy `App.jsx` into your app — see [`react/README.md`](../examples/react/README.md). |
+| [`server-express/`](../examples/server-express) | A full Express server mounting the Solana checkout router + a demo paid route that returns a real x402 v2 challenge. | `cd examples/server-express && npm install && npm start`, open http://localhost:3000. |
+| [`solana-crypto-paywall/`](../examples/solana-crypto-paywall) | An end-to-end Solana paywall: a paid endpoint, the checkout server, and a local facilitator. | See its [`README.md`](../examples/solana-crypto-paywall/README.md). |
+
+## Which do I need?
+
+- **EVM payments** sign in the browser (EIP-3009) — the **plain-html** or
+  **react** client is all you need, no server.
+- **Solana payments** also need the checkout endpoint (**server-express** or
+  **solana-crypto-paywall**) to build and wrap the transfer. See
+  [server setup](./server-setup.md).
+
+---
+
+## 1. Plain HTML — declarative
+
+The leanest integration: load the module and annotate a button. No JavaScript.
+
+```html
+<script type="module" src="https://unpkg.com/@three-ws/x402-payment-modal"></script>
+
+<button
+  data-x402-endpoint="https://api.example.com/paid/summarize"
+  data-x402-method="POST"
+  data-x402-body='{"url":"https://en.wikipedia.org/wiki/x402"}'
+  data-x402-merchant="Acme"
+  data-x402-action="Summarize">
+  Summarize for $0.01
+</button>
+
+<script>
+  document.addEventListener('x402:result', (e) => console.log('paid:', e.detail.result));
+  document.addEventListener('x402:error',  (e) => console.error(e.detail.error));
+</script>
+```
+
+## 2. Plain HTML — programmatic
+
+```html
+<script type="module">
+  import { pay } from 'https://unpkg.com/@three-ws/x402-payment-modal';
+
+  document.getElementById('go').addEventListener('click', async () => {
+    try {
+      const { result, payment } = await pay({
+        endpoint: 'https://api.example.com/paid/translate',
+        method: 'POST',
+        body: { text: 'Hello', to: 'es' },
+        merchant: 'Acme Translate',
+        action: 'Translate',
+      });
+      console.log(result, 'tx:', payment?.transaction);
+    } catch (err) {
+      if (err.code !== 'cancelled') console.error(err);
+    }
+  });
+</script>
+```
+
+## 3. React
+
+```jsx
+import { X402Button } from '@three-ws/x402-payment-modal/react';
+
+export default function Demo() {
+  return (
+    <X402Button
+      endpoint="/api/paid/summarize"
+      method="POST"
+      body={{ url: 'https://en.wikipedia.org/wiki/x402' }}
+      merchant="Acme"
+      action="Summarize"
+      label="Summarize for $0.01"
+      onResult={(r) => console.log('paid', r.payment)}
+    />
+  );
+}
+```
+
+See the [React reference](./react.md) for the `useX402` hook and all props.
+
+## 4. Express checkout server (Solana)
+
+```js
+import express from 'express';
+import { x402CheckoutRouter } from '@three-ws/x402-payment-modal/server/express';
+
+const app = express();
+app.use(express.json());
+app.use('/api/x402-checkout', x402CheckoutRouter({
+  rpcUrls: [process.env.SOLANA_RPC_URL],   // dedicated RPC for production
+}));
+app.listen(3000);
+```
+
+Then point the client at it:
+
+```js
+import { configure } from '@three-ws/x402-payment-modal';
+configure({ checkoutOrigin: 'https://your-server.com' });
+```
+
+Full server guide: [server setup](./server-setup.md).
+
+## 5. Building a 402 challenge with `solanaAccept`
+
+On the merchant side, build spec-shaped accepts (USDC default, optional second
+token for a picker):
+
+```js
+import { solanaAccept } from '@three-ws/x402-payment-modal/server';
+
+const common = { payTo, feePayer, maxTimeoutSeconds: 60 };
+const accepts = [
+  solanaAccept({ token: 'usdc', uiAmount: 0.01, ...common }), // $0.01 USDC
+  // Optional: offer a second SPL token → the modal shows a picker.
+  // solanaAccept({ token: 'three', uiAmount: 1000, ...common }),
+];
+
+res.status(402).json({ x402Version: 2, accepts });
+```
+
+## See also
+
+- [Tutorial](../TUTORIAL.md) — build a paid endpoint end-to-end.
+- [API reference](./api-reference.md) · [Server setup](./server-setup.md) ·
+  [React reference](./react.md) · [Architecture](./architecture.md)

package/docs/api-reference.md

@@ -3,7 +3,8 @@
 The browser entry point. Import it as an ES module, or drop the bundle on a page
 and use `window.X402`. For how these pieces fit together see
 [architecture](./architecture.md); for the Solana backend see
-[server setup](./server-setup.md).
+[server setup](./server-setup.md); for the React bindings see the
+[React reference](./react.md).
 
 ```js
 import { pay, configure, init, version } from '@three-ws/x402-payment-modal';
@@ -92,8 +93,10 @@ import { configure } from '@three-ws/x402-payment-modal';
 configure({
   checkoutOrigin: 'https://pay.example.com',
   checkoutPath: '/api/x402-checkout',
-  brand: { name: 'Example', url: 'https://example.com' },
+  brand: { name: 'Example', url: 'https://example.com', logo: '/logo.svg' },
   footerNote: 'Secured by x402',
+  theme: 'auto',                                  // 'auto' | 'light' | 'dark'
+  cssVars: { '--x402-accent': '#ff5c00' },        // runtime brand-match
   builderCode: { wallet: 'examplewallet', service: 'example_api' },
   esm: {
     solanaWeb3: 'https://esm.sh/@solana/web3.js@1.95.0',
@@ -106,11 +109,16 @@ configure({
 |------------------|---------------------------------------|-----------------------------------------------------------------------------------------------|
 | `checkoutOrigin` | `string \| null`                      | Origin serving the Solana checkout endpoint. `null` resolves it from the script `src` or page origin. |
 | `checkoutPath`   | `string`                              | Checkout path. Default `'/api/x402-checkout'`.                                                |
-| `brand`          | `{ name, url }`                       | Footer attribution.                                                                            |
-| `footerNote`     | `string`                              | Text on the left side of the footer.                                                           |
+| `brand`          | `{ name?, url?, logo? }`              | Footer attribution (`name`/`url`) and an optional header `logo` (URL).                         |
+| `footerNote`     | `string`                              | Text on the left side of the footer. Default `'x402 · onchain settled'`.                       |
+| `theme`          | `'auto' \| 'light' \| 'dark'`         | Force the color scheme. Default `'auto'` (follow the OS). See [theming](./theming.md).        |
+| `cssVars`        | `Record<string,string> \| null`       | Flat map of `--x402-*` design tokens to brand-match at runtime, e.g. `{ '--x402-radius': '8px' }`. |
 | `builderCode`    | `{ wallet, service }`                 | ERC-8021 builder-code echo. Each value lowercase `[a-z0-9_]{1,32}`.                            |
 | `esm`            | `{ solanaWeb3, nobleHashesSha3 }`     | CDN URLs for crypto helpers loaded on demand. Repoint for strict CSP / self-hosting.          |
 
+Nested objects (`brand`, `builderCode`, `esm`, `cssVars`) are **shallow-merged**,
+so you can set a single field without clearing the others.
+
 > The `checkoutOrigin` / `checkoutPath` settings only matter for the Solana rail.
 > EVM-only sites can ignore them.
 
@@ -136,11 +144,30 @@ The package version string.
 
 ```js
 import { version } from '@three-ws/x402-payment-modal';
-console.log(version); // "1.1.0"
+console.log(version); // e.g. "1.2.0"
 ```
 
 ---
 
+## Token constants
+
+For inline merchants composing a 402 challenge in the browser, the client also
+exports the well-known Solana mints (also at `window.X402.tokens`):
+
+```js
+import { USDC_MINT_SOLANA, THREE_MINT, KNOWN_SOLANA_TOKENS }
+  from '@three-ws/x402-payment-modal';
+```
+
+| Export | Type | Notes |
+|--------|------|-------|
+| `USDC_MINT_SOLANA` | `string` | Solana USDC mint (mainnet) — the always-on default settlement asset. |
+| `THREE_MINT` | `string` | An optional opt-in SPL token recognized by the modal; used only when an endpoint chooses to accept it alongside USDC. |
+| `KNOWN_SOLANA_TOKENS` | `Readonly<Record<string, { symbol, name, decimals, stable?, accent?, glyph? }>>` | Mints the modal renders with the correct symbol/decimals even when the `accept` omits `extra.name`/`extra.decimals`. |
+
+The server side builds accepts with the higher-level `solanaAccept()` helper — see
+[server setup](./server-setup.md).
+
 ## HTML data attributes
 
 You can drive the modal declaratively without writing JavaScript. Add attributes

package/docs/architecture.md

@@ -168,4 +168,10 @@ rolled back. Callers should treat `cancelled` as a no-op, not a failure.
   noble hashes) are loaded on demand from CDN ESM and can be repointed for
   strict CSP via [`configure`](./api-reference.md#configure).
 - **Server:** optional, only for the Solana rail. Exposed at
-  `@three-ws/x402-payment-modal/server` with Express and Vercel adapters.
+  `@three-ws/x402-payment-modal/server` (framework-agnostic) with Express
+  (`./server/express`) and Vercel (`./server/vercel`) adapters. Peer deps
+  `@solana/web3.js` + `@solana/spl-token` (and `express` for that adapter) are
+  optional — install only when you mount the checkout.
+- **React:** optional bindings at `@three-ws/x402-payment-modal/react`
+  (`X402Button`, `useX402`) that dynamically import the browser core on first use,
+  so they are SSR-safe. See the [React reference](./react.md).

package/docs/react.md

@@ -0,0 +1,163 @@
+# React reference
+
+The `./react` subpath ships first-class React bindings for the modal:
+
+```js
+import { X402Button, useX402, configure } from '@three-ws/x402-payment-modal/react';
+```
+
+`react` is an **optional peer dependency** — you already have it in a React app.
+The browser-only core (`@three-ws/x402-payment-modal`) is **dynamically imported
+on first use**, so nothing from it runs during render or on the server. That makes
+both exports **SSR-safe** in Next.js, Remix, Astro, etc. — no `dynamic`/`ssr:false`
+wrapper needed.
+
+For the underlying `pay()` contract and `PayResult` shape, see the
+[API reference](./api-reference.md). For the payment lifecycle, see
+[architecture](./architecture.md).
+
+---
+
+## `<X402Button>`
+
+A drop-in pay button. It renders a `<button>`, runs the modal on click, and calls
+`onResult` / `onError`. While a payment is in flight it is `disabled`, shows
+`Processing…`, and sets `aria-busy`. User cancellation is silent (no `onError`).
+
+```jsx
+import { X402Button } from '@three-ws/x402-payment-modal/react';
+
+export default function Buy() {
+  return (
+    <X402Button
+      endpoint="/api/paid/summarize"
+      method="POST"
+      body={{ url: 'https://en.wikipedia.org/wiki/x402' }}
+      merchant="Acme Summaries"
+      action="Summarize article"
+      label="Summarize for $0.01"
+      caps={{ maxPerCall: 100_000 }}     // 0.10 USDC (atomic micro-USD)
+      onResult={(r) => console.log('paid', r.payment)}
+      onError={(e) => console.error('payment failed', e)}
+      className="my-pay-btn"             // extra props spread onto the <button>
+    />
+  );
+}
+```
+
+### Props
+
+| Prop          | Type                          | Notes                                                                       |
+|---------------|-------------------------------|-----------------------------------------------------------------------------|
+| `endpoint`    | `string`                      | **Required.** The x402-protected URL.                                       |
+| `method`      | `string`                      | HTTP method. Defaults to `GET` (or `POST` when `body` is set).              |
+| `body`        | `unknown`                     | Request body. Objects are JSON-stringified.                                 |
+| `headers`     | `Record<string,string>`       | Extra request headers.                                                      |
+| `merchant`    | `string`                      | Shown in the modal header.                                                  |
+| `action`      | `string`                      | Shown in the modal header.                                                  |
+| `caps`        | `SpendingCaps`                | Client-side caps (stablecoin only). See [spending caps](./spending-caps.md).|
+| `autoConnect` | `boolean`                     | Skip the picker when exactly one wallet is detected.                        |
+| `label`       | `string`                      | Button text. Default `"Pay"`. `children` overrides it.                      |
+| `onResult`    | `(result: PayResult) => void` | Called on success.                                                          |
+| `onError`     | `(error: Error) => void`      | Called on failure. **Not** called when the user cancels.                    |
+| `children`    | `ReactNode`                   | Custom button content (overrides `label`).                                  |
+| …`rest`       | `button` attributes           | Any other `<button>` prop (`className`, `style`, `id`, …) is spread through.|
+
+`onResult` receives the full [`PayResult`](./api-reference.md#payresult):
+`{ ok, result, payment?, siwx?, response }`.
+
+---
+
+## `useX402(defaults?)`
+
+A headless payment hook with a small state machine. Use it when you want full
+control over the trigger UI (your own button, a menu item, an effect) instead of
+`<X402Button>`.
+
+```jsx
+import { useX402 } from '@three-ws/x402-payment-modal/react';
+
+function PremiumGate() {
+  const { pay, status, result, error, reset, isPaying } = useX402({
+    merchant: 'Acme',          // defaults merged under every pay() call
+    action: 'Unlock premium',
+  });
+
+  if (status === 'done') {
+    return <pre>{JSON.stringify(result.result, null, 2)}</pre>;
+  }
+
+  return (
+    <>
+      <button disabled={isPaying} onClick={() => pay({ endpoint: '/api/paid/premium' })}>
+        {isPaying ? 'Processing…' : 'Unlock for $0.05'}
+      </button>
+      {status === 'error' && (
+        <p role="alert">
+          {error?.message} <button onClick={reset}>Try again</button>
+        </p>
+      )}
+    </>
+  );
+}
+```
+
+### Return value
+
+| Field      | Type                                              | Notes                                                            |
+|------------|---------------------------------------------------|------------------------------------------------------------------|
+| `pay`      | `(opts?: Partial<PayOptions>) => Promise<PayResult \| undefined>` | Opens the modal; `opts` are merged over `defaults`. Resolves to the result, or `undefined` if cancelled. Re-entrancy is guarded — a second call while one is in flight is a no-op. |
+| `status`   | `'idle' \| 'paying' \| 'done' \| 'error'`         | Current state. Cancellation returns to `idle`.                  |
+| `result`   | `PayResult \| null`                               | The last successful result.                                     |
+| `error`    | `Error \| null`                                   | The last non-cancellation error.                                |
+| `reset`    | `() => void`                                       | Clear `result`/`error` back to `idle`.                          |
+| `isPaying` | `boolean`                                          | `status === 'paying'`.                                          |
+
+`pay` re-throws non-cancellation errors so you can `try/catch` at the call site as
+well as read `error`.
+
+---
+
+## `configure(opts?)`
+
+Set modal-wide config (checkout origin, theme, branding, builder-code, CDN URLs)
+before the first payment. The React wrapper's `configure` is **async** — it
+resolves once the core module has loaded and applied the config — so call it once
+at app startup:
+
+```jsx
+import { useEffect } from 'react';
+import { configure } from '@three-ws/x402-payment-modal/react';
+
+export default function App({ children }) {
+  useEffect(() => {
+    configure({
+      checkoutOrigin: 'https://pay.acme.com',
+      theme: 'dark',
+      brand: { name: 'Acme', url: 'https://acme.com', logo: '/logo.svg' },
+    });
+  }, []);
+  return children;
+}
+```
+
+The accepted options are identical to the core
+[`configure()`](./api-reference.md#configure).
+
+---
+
+## SSR notes
+
+- Import from `@three-ws/x402-payment-modal/react` anywhere — the heavy core is
+  only loaded inside `pay()` / the button's click handler.
+- The first payment pays a one-time dynamic-import cost; subsequent ones reuse the
+  loaded module.
+- `configure()` here returns a `Promise`; awaiting it (or firing it in an effect)
+  guarantees the config is applied before the first modal opens.
+
+## Solana payments still need a server
+
+EVM signs in the browser; **Solana needs the checkout endpoint** that builds and
+wraps the transfer. Stand one up before going live — see
+[server setup](./server-setup.md) and the runnable
+[`examples/server-express`](../examples/server-express).

package/docs/server-setup.md

@@ -44,14 +44,38 @@ npm install @solana/web3.js@^1.95 @solana/spl-token@^0.4
 
 EVM-only sites can skip this entirely.
 
+## Adapter options
+
+Every adapter (`x402CheckoutRouter`, `createVercelCheckoutHandler`) and the core
+`handleCheckout` take the same options:
+
+| Option           | Type        | Default | Purpose                                                                 |
+|------------------|-------------|---------|-------------------------------------------------------------------------|
+| `rpcUrl`         | `string`    | public RPC | Single Solana **mainnet** RPC URL.                                    |
+| `rpcUrls`        | `string[]`  | —       | Ordered mainnet RPCs tried with **failover** on a transient RPC error. **Preferred for production.** |
+| `devnetRpcUrl`   | `string`    | public devnet | Single Solana **devnet** RPC URL.                                |
+| `devnetRpcUrls`  | `string[]`  | —       | Ordered devnet RPCs with failover.                                      |
+| `origin`         | `string`    | `'*'`   | `Access-Control-Allow-Origin` for the adapter.                          |
+| `logger`         | `Function`  | `console.error` | Called with the root cause of an unexpected (non-`CheckoutError`) failure before the generic `502`. |
+
+> **Use a dedicated RPC.** With no `rpcUrl`/`rpcUrls` the helpers fall back to the
+> public Solana RPC, which is heavily rate-limited and **warns once** at startup —
+> it will fail under real load. Pass a list (Helius / Triton / QuickNode) via
+> `rpcUrls` so the adapter can rotate on a transient error:
+>
+> ```js
+> x402CheckoutRouter({ rpcUrls: [process.env.SOLANA_RPC_PRIMARY, process.env.SOLANA_RPC_BACKUP] });
+> ```
+
 ## Environment variables
 
 | Variable          | Purpose                                                        |
 |-------------------|---------------------------------------------------------------|
 | `SOLANA_RPC_URL`  | Mainnet RPC endpoint used to build/serialize the transaction. |
 
-You may also pass `rpcUrl` (and `devnetRpcUrl`) explicitly to the adapters or to
-`prepareSolanaCheckout`; explicit options take precedence over the env var.
+These are your wiring convention — the package reads no env var itself. Pass the
+value into the option (`rpcUrl: process.env.SOLANA_RPC_URL`). Explicit options
+always take precedence.
 
 ## Mounting with Express
 
@@ -74,9 +98,10 @@ app.use(
 app.listen(3000);
 ```
 
-`x402CheckoutRouter({ rpcUrl?, devnetRpcUrl?, origin? })` returns an Express
-`RequestHandler`. It sets permissive CORS by default (`origin: '*'`), answers
-`OPTIONS` preflight, and requires `POST` for the actual calls.
+`x402CheckoutRouter({ rpcUrl?, rpcUrls?, devnetRpcUrl?, devnetRpcUrls?, origin?, logger? })`
+returns an Express `RequestHandler` (see [Adapter options](#adapter-options)). It
+sets permissive CORS by default (`origin: '*'`), answers `OPTIONS` preflight, and
+requires `POST` for the actual calls.
 
 ## Mounting with Vercel / Next.js (pages API)
 
@@ -228,12 +253,44 @@ Response:
 The client puts `x_payment` into the `X-PAYMENT` header and retries the original
 request.
 
+## Building the 402 challenge: `solanaAccept`
+
+On the merchant side, build spec-shaped `accept` entries for your 402 body with
+`solanaAccept` — no hardcoded mints, USDC by default, an optional second token for
+a picker:
+
+```js
+import { solanaAccept } from '@three-ws/x402-payment-modal/server';
+
+const common = { payTo, feePayer, maxTimeoutSeconds: 60 };
+const accepts = [
+  solanaAccept({ token: 'usdc',  uiAmount: 0.25, ...common }), // $0.25 USDC
+  // Optional second token → the modal renders a token picker:
+  // solanaAccept({ token: 'three', uiAmount: 1000, ...common }),
+  // …or any SPL mint:
+  // solanaAccept({ mint: 'So111…', decimals: 9, name: 'MyToken', uiAmount: 5, ...common }),
+];
+
+res.status(402).json({ x402Version: 2, accepts });
+```
+
+`solanaAccept({ token?, mint?, payTo, feePayer, amount?, uiAmount?, decimals?, name?, network?, maxTimeoutSeconds? })`
+needs a `token: 'usdc' | 'three'` **or** an explicit `mint`, plus the price as
+`amount` (atomic integer string) **or** `uiAmount` (human units, converted via
+decimals). `feePayer` is the facilitator sponsor that pays the SOL network fee.
+
 ## Helpers
 
 | Export                     | Description                                                            |
 |----------------------------|------------------------------------------------------------------------|
+| `solanaAccept(args)`       | Build one Solana `accept` entry for a 402 challenge (see above).        |
+| `prepareSolanaCheckout(args)` | Build the partially-signed v0 transaction the buyer signs.          |
+| `encodeX402Payment(args)`  | Wrap the buyer-signed tx into the base64 `X-PAYMENT` envelope.         |
+| `handleCheckout(args)`     | Route `prepare`/`encode`; returns `{ status, body }`.                  |
 | `CheckoutError`            | `Error` subclass with `.status` and `.code`; mapped to HTTP by router. |
 | `isSolanaNetwork(network)` | `true` for Solana mainnet/devnet network identifiers.                  |
 | `X402_VERSION`             | `2` — the x402 envelope version produced by `encode`.                  |
 | `NETWORK_SOLANA_MAINNET`   | Canonical Solana mainnet network id.                                   |
-| `NETWORK_SOLANA_DEVNET`    | Canonical Solana devnet network id.                                    |
+| `NETWORK_SOLANA_DEVNET`    | Canonical Solana devnet network id.                                   |
+| `USDC_MINT_SOLANA`, `THREE_MINT` | Well-known mint constants.                                        |
+| `WELL_KNOWN_SOLANA_TOKENS` | `{ usdc, three }` token metadata keyed by lowercase shortcut.          |

package/examples/README.md

@@ -6,8 +6,9 @@ Runnable examples for [`@three-ws/x402-payment-modal`](https://www.npmjs.com/pac
 | Example | What it shows | Fastest way to try it |
 | --- | --- | --- |
 | [`plain-html/`](./plain-html) | No build step. Declarative `data-x402-*` buttons, a programmatic `pay()` call, and `x402:result` / `x402:error` event handling — all from a single CDN `<script>`. | Open `plain-html/index.html` in a browser (or serve the folder, e.g. `npx serve plain-html`). |
-| [`react/`](./react) | A reusable `<X402Button>` component that wraps `pay()` with a dynamic import, so it is SSR-safe. | Copy `react/X402Button.jsx` into your app — see [`react/README.md`](./react/README.md). |
+| [`react/`](./react) | The shipped `./react` wrapper — `<X402Button>` and the `useX402()` hook, both SSR-safe. | Copy `react/App.jsx` into your app — see [`react/README.md`](./react/README.md). |
 | [`server-express/`](./server-express) | A complete Express server that mounts the Solana checkout router and serves a demo paid endpoint returning a real x402 v2 challenge. | `cd server-express && npm install && npm start`, then open http://localhost:3000 |
+| [`solana-crypto-paywall/`](./solana-crypto-paywall) | End-to-end Solana paywall: a paid endpoint, the checkout server, and a local facilitator. | See [`solana-crypto-paywall/README.md`](./solana-crypto-paywall/README.md). |
 
 ## Which do I need?
 

package/examples/react/App.jsx

@@ -0,0 +1,95 @@
+/**
+ * React example for @three-ws/x402-payment-modal.
+ *
+ * This uses the package's SHIPPED React wrapper — `@three-ws/x402-payment-modal/react`
+ * — not a hand-rolled component. The wrapper exports:
+ *
+ *   - <X402Button>  a drop-in pay button
+ *   - useX402()     a headless { pay, status, result, error, reset, isPaying } hook
+ *
+ * Both dynamically import the browser-only core on first use, so they are
+ * SSR-safe (nothing runs during render or on the server) in Next.js, Remix, etc.
+ *
+ * For Solana payments your app must also run the checkout endpoint
+ * (see ../../docs/server-setup.md and ../server-express). EVM payments sign
+ * in-browser and need no server.
+ *
+ * The endpoints below are PLACEHOLDERS — swap in a real x402 endpoint.
+ */
+
+import { useState } from 'react';
+import { X402Button, useX402 } from '@three-ws/x402-payment-modal/react';
+
+export default function App() {
+  return (
+    <main style={{ maxWidth: 520, margin: '40px auto', fontFamily: 'system-ui' }}>
+      <h1>x402 Payment Modal — React</h1>
+
+      <h2>1. Drop-in button</h2>
+      <ButtonDemo />
+
+      <h2>2. Headless hook</h2>
+      <HookDemo />
+    </main>
+  );
+}
+
+/** The simplest integration: render <X402Button> and handle the result. */
+function ButtonDemo() {
+  const [last, setLast] = useState(null);
+
+  return (
+    <>
+      <X402Button
+        endpoint="https://api.example.com/paid/summarize"
+        method="POST"
+        body={{ url: 'https://en.wikipedia.org/wiki/x402' }}
+        merchant="Acme Summaries"
+        action="Summarize article"
+        label="Summarize for $0.01"
+        // Client-side cap (stablecoin only): 0.10 USDC per call.
+        caps={{ maxPerCall: 100_000 }}
+        onResult={(r) => setLast(r)}
+        onError={(e) => console.error('payment failed', e)}
+      />
+      {last && (
+        <pre style={{ marginTop: 12 }}>
+          {JSON.stringify({ payment: last.payment, result: last.result }, null, 2)}
+        </pre>
+      )}
+    </>
+  );
+}
+
+/** Full control over the trigger UI via the useX402 state machine. */
+function HookDemo() {
+  const { pay, status, result, error, reset, isPaying } = useX402({
+    merchant: 'Acme',
+    action: 'Unlock premium',
+  });
+
+  if (status === 'done') {
+    return (
+      <>
+        <pre>{JSON.stringify(result.result, null, 2)}</pre>
+        <button onClick={reset}>Reset</button>
+      </>
+    );
+  }
+
+  return (
+    <>
+      <button
+        disabled={isPaying}
+        onClick={() => pay({ endpoint: 'https://api.example.com/paid/premium' })}
+      >
+        {isPaying ? 'Processing…' : 'Unlock for $0.05'}
+      </button>
+      {status === 'error' && (
+        <p role="alert" style={{ color: 'crimson' }}>
+          {error?.message} <button onClick={reset}>Try again</button>
+        </p>
+      )}
+    </>
+  );
+}