Arc Onboard

A guided wizard that takes a brand-new developer from "I have a Circle API key" to a funded dev-controlled wallet on Arc Testnet, ready to send transfers in one tab, with no copy-paste from the docs.

Open source under MIT. Issues, suggestions, and pull requests are welcome — see CONTRIBUTING.md.

┌─────────────────────────────────────────────────┐
│  1. Disclaimer       6. Create wallet           │
│  2. API key          7. Fund + verify           │
│  3. Entity secret    8. First transfer          │
│  4. Register         9. Export .env             │
│  5. Wallet set                                  │
└─────────────────────────────────────────────────┘

Why

The Circle dev-controlled wallets quickstart asks a first-time dev to juggle:

• generating + encrypting an entity secret,
• registering the ciphertext,
• saving a recovery file (which is the only path back if they lose the secret),
• creating a wallet set,
• creating a wallet,
• funding it from the faucet,
• and finally sending a transfer.

That is too many context switches between docs, a terminal, and Circle Console. This wizard collapses all of it into a single guided flow with a Swagger-style request inspector so you see exactly what is sent to Circle.

Quickstart

Two ways to run it. Both keep your credentials entirely on your machine — they only travel from your browser to your own localhost server, which then talks to Circle. No third-party server ever sees them. Same security posture as prisma studio or vercel dev.

Option A — npx (no install)

npx @signordev/arc-onboard

Spawns a local server on a random 127.0.0.1 port and opens your browser. Requires Node.js 20+.

Option B — clone and run

git clone https://github.com/Signor1/arc-onboard.git
cd arc-onboard
pnpm install
pnpm dev

Open http://localhost:3000. Use this if you want hot-reload, want to read the code, or want to fork it.

Optional: hosted "deep-link checklist" mode

If you ever deploy this app behind NEXT_PUBLIC_ARC_ONBOARD_MODE=hosted, the wizard switches to a smart checklist that never proxies your credentials. Sensitive operations are handed off to console.circle.com via deep-links; the wizard generates your entity secret in the browser and walks you through pasting it into Circle's own UI. This is opt-in only — the default cloned setup is the local-server flow above.

NEXT_PUBLIC_ARC_ONBOARD_MODE=hosted pnpm dev

Step	Local mode (default)	Hosted mode
Generate entity secret	Browser (crypto.getRandomValues)	Browser (crypto.getRandomValues)
Register entity secret	Localhost API → Circle	User pastes into Circle Console
Create wallet set/wallet	Localhost API → Circle	User creates in Circle Console
Recovery file	Auto-downloaded	Saved from Circle Console
Trust required	Your own machine	Just Circle (we never see your key)

Security model

• The app never writes credentials to disk.
• API key + entity secret live in React state only, closing the tab clears them.
• The request inspector redacts apiKey (first 12 chars only) and entitySecret ([redacted]) in its log, so screenshots don't leak.
• Recovery file is generated by Circle and forced as a browser download you save yourself.
• The .env export is a download; it is never POSTed back to the server.

If you are evaluating whether to trust this code, the request flow is small enough to read end-to-end:

• src/app/api/*/route.ts — every server entry point. They construct a fresh SDK client per request and discard credentials when the response is sent.
• src/lib/circle.ts — the only place credentials touch the SDK.
• src/lib/api-client.ts — the only place the browser calls our server.

Scripts

Script	What it does
pnpm dev	Dev server with hot reload (port 3000) — primary path
pnpm build	Production build
pnpm start	Start a built app on port 3000 (requires prior pnpm build)
pnpm typecheck	Strict tsc --noEmit

Stack

• Next.js 15 (App Router) + React 19
• Tailwind CSS + shadcn-style primitives
• TanStack Query for server state
• Zustand for wizard state
• @circle-fin/developer-controlled-wallets SDK on the server

Status

Initial release covers Arc Testnet and the EVM testnets supported by Circle's faucet, plus Solana Devnet. Mainnet is not exposed by the wizard on purpose — onboard there once you've validated your flow on testnet.

Looking for user-controlled wallets?

Arc Onboard focuses on dev-controlled wallets — you (the developer) hold the keys and operate wallets on behalf of users. If you're building a consumer app where end users own and approve their own transactions with PIN / email / social login, that's a different Circle product (user-controlled wallets). Start with Circle's official reference implementation:

• circlefin/w3s-sample-user-controlled-client-web — Next.js sample app demonstrating the full flow: authentication, PIN setup, wallet creation, transactions, and gasless support via the @circle-fin/w3s-pw-web-sdk.
• Circle's user-controlled quickstart — concept docs and integration guide.

You can mix the two: use dev-controlled wallets for treasury/payouts and user-controlled wallets for consumer accounts in the same app.

Contributing

Arc Onboard is community-maintained. Anyone can:

• File a bug or feature request → open an issue.
• Improve the code → fork, branch off main, open a pull request.
• Improve the docs → same flow; small docs PRs are very welcome.

Read CONTRIBUTING.md for development setup, project layout, PR conventions, and the security-disclosure flow. The main branch is protected — every change lands via PR review, including from the maintainer.

License

MIT · Built by SignorDev