Test keys & funds
Create a test publishable key and send test funds with the @capxul/sandbox CLI — and know what must never ship to production.
@capxul/sandbox is the self-serve CLI for local development against the
Capxul test environment. It does two things: mint a test publishable key
and send test funds. Everything it produces is test-only — live keys are
provisioned by Capxul through a secure handoff, not this CLI.
Create a test publishable key
npx @capxul/sandbox key createThe CLI is interactive. It asks for three things:
- Application name — how your app is labeled in Capxul.
- Allowed local origin — the exact origin your dev server runs on.
Defaults to
http://localhost:3000(Next.js); usehttp://localhost:5173for Vite. Keys are origin-locked, so this must match exactly. - Secure handoff file path — where the results are written. Defaults to
~/.config/capxul/quickstart-handoffs/customer-nextjs-quickstart.md.
It then creates a developer application and a test publishable key against the already-deployed Capxul sandbox backend. It does not deploy anything of yours, and it never prints the raw key to the terminal — the key is written to the handoff file, and the terminal shows only the application id, key id, allowed origin, and Capxul site URL.
What the handoff file contains
Open the handoff file and you have everything the quickstarts ask for:
- Publishable key — browser-safe, origin-locked. This is the only value that belongs in a browser env var.
- Capxul site URL — the backend your dev proxy or rewrites point at.
- Package versions — the validated
@capxul/sdk/@capxul/sdk-reactversions to pin.
Treat the file like a credential anyway: don't commit it, and don't paste backend secrets, private keys, or operator credentials into your frontend app alongside it.
Origins are gated twice
The key's origin allowlist covers bootstrap only. The Capxul backend keeps separate trusted-origin and CORS allowlists that must also include your origin — the CLI reminds you of this when it finishes. If bootstrap succeeds but sign-in calls fail, this split is the usual suspect. Before deploying anywhere, get the production origin added to both gates — see the Next.js validation checklist.
Send test funds
You do not need test money to prove sign-in. Reach for the faucet only when
your product exercises balance or money-movement flows and you have set an
account requirement.
npx @capxul/sandbox faucet sendThe CLI asks for a recipient address and an amount (default 10 test USDX),
confirms, and mints the funds on a public test network — it prints the
transaction hash when done. It cannot select a live environment; test funds
never touch real money.
The current release asks for a raw EVM address because it sends funds directly to that address. Treat that as a temporary developer-tool detail — a future release is expected to be account-based (pick or create a Capxul account, then fund it). Do not design customer onboarding around collecting addresses by hand.
Faucet funding never ships in a production frontend
The faucet exists for developer validation in test environments, full stop.
The same rule covers useCapxulAccountFund — it is a dev/test funding proof,
not a product feature. If your product needs users to bring real money in,
that is a platform capability question: check
Capability status for what is live before you
design the flow.
Next
- Quickstart — use the key in a fresh React app.
- Next.js — use the key in a Next.js app.
- Requirements & signers — when your app needs an account, not just a session.
Next.js
Wire Capxul email OTP sign-in into a Next.js App Router app — environment variables, route rewrites, provider mounting, and a login page.
Requirements & signers
The requirement prop declares how much account readiness your app needs at start-up — none, counterfactual, or deployed — and the signer rules that go with it.