@three-ws/x402-modal 0.2.0

package/LICENSE

@@ -0,0 +1,180 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Derivative Works, and to permit persons to whom the Derivative Works
+      are furnished to do so.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer only
+      conditions consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 nirholas
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,306 @@
+<div align="center">
+
+# @three-ws/x402-modal
+
+**A drop-in payment modal for any [x402](https://x402.org) paid endpoint.**
+
+One script tag turns an HTTP `402 Payment Required` into a polished checkout:
+wallet connect (Phantom on Solana, MetaMask/EVM via EIP-3009), the
+`402 → sign → settle` flow, SIWX re-entry, spending caps, and a receipt — all
+in **vanilla JS, with no bundler and no framework**.
+
+[![npm](https://img.shields.io/npm/v/@three-ws/x402-modal?logo=npm&color=cb3837)](https://www.npmjs.com/package/@three-ws/x402-modal)
+[![downloads](https://img.shields.io/npm/dm/@three-ws/x402-modal?color=cb3837)](https://www.npmjs.com/package/@three-ws/x402-modal)
+![license](https://img.shields.io/npm/l/@three-ws/x402-modal?color=3b82f6)
+![node](https://img.shields.io/node/v/@three-ws/x402-modal?color=339933&logo=node.js)
+
+[Quick start](#quick-start) · [How it works](#how-it-works) · [API](#api) · [Configuration](#configuration) · [Backend](#the-backend) · [Tutorials](./TUTORIAL.md) · [FAQ](#faq)
+
+</div>
+
+---
+
+## Why
+
+[x402](https://x402.org) revives HTTP `402 Payment Required` as a real payment
+rail: a server answers a request with a `402` whose body lists what it
+`accepts` (asset, amount, network, pay-to), the client pays, and re-sends the
+request with an `X-PAYMENT` header. It's perfect for pay-per-call APIs, agent
+economies, and content paywalls — but every merchant ends up rebuilding the same
+fiddly client: parse the challenge, connect a wallet, sign the right thing for
+the right chain, retry, settle, show a receipt.
+
+**This package is that client, done once and done well.** Point it at a `402`
+endpoint and it renders the entire flow. The EVM/Base path is 100%
+client-side. The Solana path needs one small backend helper (see
+[The backend](#the-backend)).
+
+## Quick start
+
+### 1 — One script tag (zero JS)
+
+```html
+<script type="module" src="https://unpkg.com/@three-ws/x402-modal/global"></script>
+
+<button
+  data-x402-endpoint="https://api.example.com/paid/summarize"
+  data-x402-method="POST"
+  data-x402-body='{"text":"hello world"}'
+  data-x402-merchant="Acme"
+  data-x402-action="Summarize">
+  Pay &amp; summarize
+</button>
+```
+
+Clicking the button opens the modal, runs the payment, calls the endpoint, and
+fires an `x402:result` event on the button with `{ ok, result, payment, response }`:
+
+```js
+document.querySelector('button').addEventListener('x402:result', (e) => {
+  console.log('paid + got result:', e.detail.result);
+});
+```
+
+### 2 — Programmatic (full control)
+
+```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.
+
+### 3 — Self-hosted, fully branded
+
+```html
+<script
+  type="module"
+  src="https://your.cdn/x402.global.js"
+  data-x402-api-origin="https://pay.your-company.com"
+  data-x402-brand-label="Powered by Acme"
+  data-x402-brand-href="https://acme.com"></script>
+```
+
+or from JS, before the first `pay()`:
+
+```js
+import { configure } from '@three-ws/x402-modal';
+
+configure({
+  apiOrigin: 'https://pay.your-company.com',     // Solana checkout backend
+  brand: { label: 'Powered by Acme', href: 'https://acme.com' },
+});
+```
+
+> **No dependencies to install.** The ESM build leaves the two optional wallet
+> libraries (`@solana/web3.js` for Solana, a keccak for EVM sign-in) as runtime
+> CDN imports, fetched only when that wallet path actually runs. The `/global`
+> build is a single self-contained file.
+
+## How it works
+
+```
+pay({ endpoint })
+   │
+   ├─ 1. discover   GET/POST endpoint → 402 (or 401 + payment-required header)
+   │                parse `accepts[]` (asset · amount · network · payTo)
+   │
+   ├─ 2. connect    pick a wallet that can satisfy an accept:
+   │                  Solana → Phantom          EVM → MetaMask / window.ethereum
+   │
+   ├─ 3. authorize  Solana: backend builds the tx → Phantom signs it
+   │                  EVM:   wallet signs an EIP-3009 transferWithAuthorization
+   │                  (no on-chain tx, no gas for the payer)
+   │
+   └─ 4. verify     re-send the request with `X-PAYMENT` → endpoint runs the work,
+                    settles on-chain, returns 200 + `x-payment-response` receipt
+```
+
+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.
+
+### Networks
+
+| Network | Wallet | Scheme | Needs a 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 |
+
+When a `402` advertises more than one network the modal shows a wallet picker;
+when it advertises exactly one, it goes straight there.
+
+## API
+
+### `pay(options): Promise<PayResult>`
+
+| option        | type                          | default            | notes |
+|---------------|-------------------------------|--------------------|-------|
+| `endpoint`    | `string`                      | — (**required**)   | the x402-protected URL to pay for and call |
+| `method`      | `string`                      | `GET` / `POST`*    | *POST when a `body` is set |
+| `body`        | `object \| string`            | —                  | forwarded to the endpoint (object → JSON) |
+| `headers`     | `Record<string,string>`       | —                  | merged into discovery + paid calls |
+| `merchant`    | `string`                      | `Payment`          | shown in the modal header |
+| `action`      | `string`                      | `Pay-per-call`     | shown in the modal header |
+| `caps`        | `{ maxPerCall, maxPerHour, maxPerDay }` | —      | µUSD spending caps (see [Configuration](#configuration)) |
+| `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 `{ ok: true, result, payment?, siwx?, response }`. `payment` is present
+on a fresh payment (`{ network, payer, transaction }`); `siwx` is present when
+the user re-entered via sign-in instead of paying.
+
+### `configure(config): config` · `getConfig(): config`
+
+Set global defaults once at startup. See [Configuration](#configuration).
+
+### `init(): void`
+
+Scan the document and bind every `[data-x402-endpoint]` element. The `/global`
+build calls this automatically (and re-scans on DOM mutation); call it yourself
+only when using the ESM build with declarative buttons.
+
+### DOM events (declarative usage)
+
+Bound elements dispatch bubbling `CustomEvent`s:
+
+- `x402:result` — `detail` is the full `PayResult`.
+- `x402:error` — `detail` is `{ error: string }`. (Cancellation does **not** fire this.)
+- `x402:siwx-signed` — `detail` is `{ address, network }`, when re-entry was via SIWX.
+
+### `data-*` attributes (declarative usage)
+
+`data-x402-endpoint` (required), `data-x402-method`, `data-x402-body` (JSON),
+`data-x402-headers` (JSON), `data-x402-caps` (JSON), `data-x402-api-origin`,
+`data-x402-merchant`, `data-x402-action`.
+
+## Configuration
+
+All fields are optional; the defaults reproduce the hosted three.ws modal.
+
+```js
+configure({
+  // Origin serving the Solana prepare/encode checkout helpers. Only the Solana
+  // path uses it; the EVM path needs no backend. null → resolve from the
+  // script's own origin; '' → same-origin.
+  apiOrigin: 'https://pay.example.com',
+
+  // Footer attribution.
+  brand: { label: 'Powered by Acme', href: 'https://acme.com' },
+
+  // ERC-8021 builder-code self-attribution, echoed back only when the 402
+  // challenge declares a builder code. null disables the echo.
+  builderCode: { wallet: 'acme', service: 'acme_checkout' },
+
+  // Override the on-demand CDN modules (e.g. to self-host under a strict CSP).
+  solanaWeb3Url: 'https://esm.sh/@solana/web3.js@1.95.3?bundle',
+  nobleHashesUrl: 'https://esm.sh/@noble/hashes@1.4.0/sha3?bundle',
+});
+```
+
+### Spending caps
+
+Caps are enforced in `localStorage`, bucketed by rolling UTC hour and day, and
+survive reloads. Amounts are **micro-USD** (`1_000_000` = `$1`). A failed payment
+rolls its reservation back.
+
+```js
+await pay({
+  endpoint: '/api/paid/x',
+  caps: {
+    maxPerCall: 1_000_000,    // $1.00 per call
+    maxPerHour: 10_000_000,   // $10/hour
+    maxPerDay:  50_000_000,   // $50/day
+  },
+});
+```
+
+Stablecoins (USDC, USDT, DAI) are converted to µUSD exactly. Non-stable assets
+pass through atomic in the browser (no price feed is fetched to keep the script
+dependency-free) — enforce those server-side.
+
+## The backend
+
+**EVM / Base needs no backend.** The payer signs an EIP-3009
+`transferWithAuthorization` in their wallet and the modal sends the signed
+authorization straight to your merchant endpoint as `X-PAYMENT`. Your x402
+server (and its facilitator) verify and settle it.
+
+**Solana needs one tiny helper**, because building a Solana transfer transaction
+requires RPC access and the facilitator's fee-payer. The modal expects 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. See
+[`docs/BACKEND.md`](./docs/BACKEND.md) for the full contract and a reference
+implementation, and [`examples/`](./examples) for runnable code.
+
+## Install
+
+```sh
+npm i @three-ws/x402-modal
+```
+
+```js
+import { pay, configure } from '@three-ws/x402-modal';   // ESM, no side effects
+```
+
+or skip the install entirely and use the CDN `/global` build (auto-binds
+`[data-x402-endpoint]`, exposes `window.X402`).
+
+## Security notes
+
+- The modal **never holds keys**. Signing happens in the user's wallet; the
+  signed payload goes to your endpoint.
+- A `429` from the merchant is retried with the *same* signed payment — safe,
+  because x402 settles only after the work succeeds.
+- Upstream throttle/billing text is never relayed to the buyer verbatim.
+- All endpoint-supplied strings are HTML-escaped before rendering.
+- For the Solana path, the dynamic CDN import can be blocked by a strict
+  Content-Security-Policy; either allow it, repoint it via `solanaWeb3Url`, or
+  steer users to the dependency-free Base path.
+
+## FAQ
+
+**Do I need a wallet adapter / WalletConnect?** No. Solana uses the injected
+Phantom provider; EVM uses the injected `window.ethereum`.
+
+**Does the payer pay gas?** On EVM, no — EIP-3009 is a gasless signed
+authorization your facilitator submits. On Solana the facilitator is the
+fee-payer.
+
+**Can I theme it?** It ships a self-contained stylesheet with light/dark
+(`prefers-color-scheme`) support. Override the `.x402-*` classes, or set
+`brand` for the footer. The header reflects `merchant` / `action`.
+
+**Framework support?** It's framework-agnostic. Import `pay()` and call it from
+a React/Vue/Svelte handler, or drop the `/global` script and use `data-*`
+buttons.
+
+**Where does this run in production?** This is the same modal that powers
+payments on [three.ws](https://three.ws); the package is its standalone,
+configurable home.
+
+## License
+
+[Apache-2.0](./LICENSE) © three.ws. Part of the [three.ws](https://three.ws)
+platform for building, animating, rigging, and monetizing 3D AI agents.