Skip to content

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.

9.7 KB
Raw Blame

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:

  1. Tutorial 1 — Sell an API call in 5 minutes (Base, no backend)
  2. Tutorial 2 — Programmatic checkout in a SPA
  3. Tutorial 3 — A content paywall
  4. Tutorial 4 — Self-hosting & full branding
  5. Tutorial 5 — Adding the Solana path (the backend helper)
  6. Tutorial 6 — Spending caps for autonomous agents
  7. 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.