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.

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