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.
Tutorials — @three-ws/x402-modal
Hands-on, copy-paste walkthroughs. Each one is self-contained and ends with something running. Pick the path that matches your stack:
- Tutorial 1 — Sell an API call in 5 minutes (Base, no backend)
- Tutorial 2 — Programmatic checkout in a SPA
- Tutorial 3 — A content paywall
- Tutorial 4 — Self-hosting & full branding
- Tutorial 5 — Adding the Solana path (the backend helper)
- Tutorial 6 — Spending caps for autonomous agents
- Troubleshooting
Every tutorial assumes you already have — or are about to build — an x402 server
that answers a protected route with 402 Payment Required. If you don't, skim
the backend doc first; it shows the minimal server side.
Tutorial 1 — Sell an API call in 5 minutes (Base, no backend)
Goal: charge USDC on Base for one API call, with zero backend beyond your existing x402 server. The Base path is fully client-side.
1. Have an endpoint that returns 402
Your server should respond to an unpaid request with 402 and an accepts
array describing a Base USDC payment. A minimal challenge body looks like:
{
"x402Version": 2,
"accepts": [{
"scheme": "exact",
"network": "eip155:8453",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"payTo": "0xYourMerchantWallet",
"amount": "10000",
"maxTimeoutSeconds": 600,
"extra": { "name": "USDC", "version": "2", "decimals": 6 }
}]
}
(amount is atomic — 10000 = $0.01 at 6 decimals.)
2. Add the modal to your page
<script type="module" src="https://unpkg.com/@three-ws/x402-modal/global"></script>
<button
data-x402-endpoint="https://api.acme.com/paid/summarize"
data-x402-method="POST"
data-x402-body='{"text":"Long article text here..."}'
data-x402-merchant="Acme AI"
data-x402-action="Summarize article">
Summarize for $0.01
</button>
3. Handle the result
<script>
document.querySelector('button').addEventListener('x402:result', (e) => {
const { result, payment } = e.detail;
document.querySelector('#out').textContent = JSON.stringify(result, null, 2);
console.log('settled tx:', payment.transaction);
});
document.querySelector('button').addEventListener('x402:error', (e) => {
alert('Payment failed: ' + e.detail.error);
});
</script>
<pre id="out"></pre>
That's the whole integration. Click → MetaMask signs an EIP-3009 authorization (no gas, no on-chain tx for the user) → your endpoint runs and settles → the result renders.
Tutorial 2 — Programmatic checkout in a SPA
Goal: trigger checkout from your own button in React/Vue/Svelte/vanilla and get the result back as a promise.
npm i @three-ws/x402-modal
// React example
import { pay } from '@three-ws/x402-modal';
function BuyButton({ text }) {
const [out, setOut] = useState(null);
const [err, setErr] = useState(null);
async function onClick() {
setErr(null);
try {
const res = await pay({
endpoint: '/api/paid/summarize',
method: 'POST',
body: { text },
merchant: 'Acme AI',
action: 'Summarize',
});
setOut(res.result);
} catch (e) {
if (e.code === 'cancelled') return; // user closed the modal — not an error
setErr(e.message);
}
}
return (
<>
<button onClick={onClick}>Summarize for $0.01</button>
{err && <p className="error">{err}</p>}
{out && <pre>{JSON.stringify(out, null, 2)}</pre>}
</>
);
}
The ESM import has no side effects — it won't scan the DOM or touch
window. You control exactly when the modal opens.
Tutorial 3 — A content paywall
Goal: blur premium content until the visitor pays, then reveal it.
<script type="module" src="https://unpkg.com/@three-ws/x402-modal/global"></script>
<article id="premium" class="locked">
<div class="blurred">…premium article body…</div>
<button
data-x402-endpoint="https://api.acme.com/paid/article/42"
data-x402-merchant="Acme Times"
data-x402-action="Unlock this article">
Unlock — $0.25
</button>
</article>
<style>
.locked .blurred { filter: blur(8px); pointer-events: none; user-select: none; }
.unlocked .blurred { filter: none; }
</style>
<script>
const article = document.getElementById('premium');
article.querySelector('button').addEventListener('x402:result', (e) => {
// Put the unlocked content from the endpoint into the page, then reveal.
article.querySelector('.blurred').innerHTML = e.detail.result.html;
article.classList.replace('locked', 'unlocked');
// Remember it so a refresh doesn't re-lock (optional).
localStorage.setItem('unlocked:article:42', '1');
});
</script>
To skip the paywall for returning buyers, check your flag on load — and if your server supports SIWX (sign-in-with-x), the modal will automatically offer "Already paid? Sign in" so they re-enter by signing instead of paying again.
Tutorial 4 — Self-hosting & full branding
Goal: serve the script yourself, point the Solana backend at your own domain, and replace the footer attribution — without writing JS.
<script
type="module"
src="https://cdn.acme.com/x402.global.js"
data-x402-api-origin="https://pay.acme.com"
data-x402-brand-label="Powered by Acme Pay"
data-x402-brand-href="https://acme.com/pay"
data-x402-builder-wallet="acme"
data-x402-builder-service="acme_checkout"></script>
Grab x402.global.js from the package's dist/ (or build it with
npm run build) and host it anywhere static.
Prefer JS? Configure before the first payment:
import { configure } from '@three-ws/x402-modal';
configure({
apiOrigin: 'https://pay.acme.com',
brand: { label: 'Powered by Acme Pay', href: 'https://acme.com/pay' },
builderCode: { wallet: 'acme', service: 'acme_checkout' },
});
To drop the footer link entirely, set data-x402-builder-disable and a
brand with no href.
Tutorial 5 — Adding the Solana path (the backend helper)
Goal: accept USDC on Solana too. This is the only path that needs a backend, because building a Solana transfer needs RPC + the facilitator fee-payer.
The modal calls two actions on {apiOrigin}/api/x402-checkout:
POST /api/x402-checkout?action=prepare
body: { accept, buyer }
→ { tx_base64 } # a VersionedTransaction the buyer will sign
POST /api/x402-checkout?action=encode
body: { accept, signed_tx_base64, resource_url, builder_code? }
→ { x_payment } # the base64 X-PAYMENT value to send to the merchant
A reference Express handler that delegates to an x402 facilitator SDK lives in
examples/server.mjs, and the exact field contract is
in docs/BACKEND.md.
Once the helper is live, no client change is needed beyond pointing apiOrigin
at it (Tutorial 4). When your 402 advertises both a Solana and a Base
accept, the modal shows a wallet picker; when it advertises one, it goes
straight there.
Tutorial 6 — Spending caps for autonomous agents
Goal: let an agent (or a kiosk, or a shared browser) pay automatically, but cap how much it can spend per call / hour / day.
import { pay } from '@three-ws/x402-modal';
await pay({
endpoint: '/api/paid/inference',
body: { prompt },
autoConnect: true, // skip the picker when one wallet is present
caps: {
maxPerCall: 500_000, // $0.50 max for any single call
maxPerHour: 5_000_000, // $5.00/hour
maxPerDay: 20_000_000, // $20.00/day
},
});
Amounts are micro-USD (1_000_000 = $1). Caps are tracked per wallet
address in localStorage, bucketed by rolling UTC hour and day, and survive
page reloads. A call that would breach a cap is rejected before the wallet
prompt with a clear reason; a payment that fails downstream rolls its
reservation back so it doesn't count against the budget.
Caps are a client-side guardrail, not a trust boundary. For hard limits an agent can't bypass, also enforce server-side.
Troubleshooting
| Symptom | Cause / fix |
|---|---|
| "Endpoint did not return 402 (got 200)" | The modal was pointed at a free/unprotected URL, or your server didn't send a 402. Confirm the route is actually gated. |
"no accepts array could be found" |
Your 402 body (or payment-required header) is missing the accepts array. See the challenge shape in Tutorial 1. |
| "NaN USDC" in the price | Your accept used a field other than amount/maxAmountRequired. The modal normalizes both; anything else needs mapping. |
| Solana payment errors with "component … was blocked" | A strict Content-Security-Policy blocked the dynamic @solana/web3.js import. Allow the CDN, set solanaWeb3Url to a self-hosted copy, or use the Base path (no third-party code). |
| EVM signature rejected by the facilitator | Check the USDC extra.version in your accept matches the deployed contract (Base USDC is "2"), and that payTo/asset are correct. |
| Modal opens then immediately shows the picker disabled | No supported wallet detected. Install Phantom (Solana) or MetaMask (EVM), or advertise an accept for a chain the visitor's wallet supports. |
pay() rejected but nothing went wrong |
The user closed the modal: the rejection's .code === 'cancelled'. Treat it as a no-op, not an error. |
Still stuck? Open an issue at https://github.com/nirholas/three.ws/issues.