Test keys & funds

@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 create

It needs nothing but npx — no secrets, no login. It asks for one thing:

• Allowed local origin — the exact origin your dev server runs on. Defaults to http://localhost:3000. Keys are origin-locked, so this must match exactly. For the shared sandbox, use one of the origins it pre-trusts for email/OTP sign-in — http://localhost:3000 or http://localhost:3100. Any other origin still mints a key and bootstraps, but sign-in requests are rejected until Capxul adds it (the CLI warns you when you pick one).

It POSTs that origin to Capxul's public quickstart endpoint (against the already-deployed sandbox backend — it does not deploy anything of yours) and upserts two variables into .env.local in the directory you ran it from:

NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY=<test publishable key>
CAPXUL_SITE_URL=https://api.staging.capxul.com

Only those two keys are written — any other lines already in your .env.local are preserved. The NEXT_PUBLIC_ publishable key is browser-safe and origin-locked; the site URL is the backend your dev proxy or rewrites point at. The command then prints the next.config.ts rewrite snippet.

Treat .env.local 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 send

The 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.

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 Next.js App Router app.
• Requirements & signers — when your app needs an account, not just a session.