@axon402/init

One-shot runtime bootstrap for an AXON worker-agent wallet. Under 15 seconds, no clone, no config file.

AXON is a governed-payment runtime for AI agents that need to spend money. @axon402/init is the one-shot runtime bootstrap helper: it creates your first wallet, mints a wallet-scoped runtime key for that wallet, and wires Claude Code's MCP config so a worker agent can start making governed x402 payments immediately. The runtime key it issues is intended for an agent to use the prepared wallet — it is not an operator or org-admin credential.

@axon402/init lives on the runtime plane. For day-to-day control-plane work — additional wallets, key rotation, deposits, vault allocations — use @axon402/cli (bin name: axon-op), the durable control-plane operator CLI that authenticates with an org-wide operator key. One key = one surface: the runtime key this CLI issues is never an operator key, and vice versa.

What it's for

Run it once, when you first want to try AXON from Claude Code:

npx @axon402/init

That's the whole thing. No global install, no clone, no .env. The installer walks you through one prompt (your email), generates a fresh BIP-39 wallet locally, calls AXON's hosted Decision API at https://api.axon402.com, and writes everything to disk.

Requirements: Node.js ≥ 18 on macOS, Linux, or WSL.

What it does (once)

When you run npx @axon402/init, the following happens — all on your machine, in one round-trip to the AXON hosted Decision API:

1. Generate a fresh wallet locally — BIP-39 mnemonic, BIP-44 derivation. Two addresses: a vault (HD index 0, the deposit target) and an agent (HD index 1, the spend source). The mnemonic never leaves your machine.
2. Bootstrap the org + agent + mandate — POST /v1/cli/init sends your email and the two derived addresses. The server creates a Supabase auth user (and emails you a confirmation link), an organization, both wallets, and a starter spending mandate (10 USDC/day, 0.50/tx, 300/mo, hard-stop enforcement).
3. Mint a wallet-scoped API key — bound to the agent wallet (not the vault — the vault has no mandate by design). Returned to the CLI exactly once and persisted to ~/.axon/config.json at chmod 0600.
4. Wire Claude Code's MCP config — merges an entry for the AXON MCP server into ~/.claude.json, backing the existing file up to ~/.claude.json.bak-<timestamp> first.
5. Print a deposit QR code — scan with Coinbase Wallet, Rainbow, or any Base-compatible wallet to deposit USDC to the vault on Base mainnet. Once the vault holds USDC, allocate some to the agent pocket from the dashboard or @axon402/cli, and your agent can start making governed payments.

You're now ready to run claude in the same terminal and ask your agent to call any x402-compatible endpoint.

Scope (what this package is NOT)

@axon402/init intentionally stops after the first wallet and the first MCP handshake. Everything below is a control-plane operation and belongs to the dashboard or @axon402/cli (axon-op) — never to a runtime-key holder:

| Task | Where it lives | | --- | --- | | Create additional wallets | AXON dashboard (the operator CLI does not expose wallets create yet) | | Rotate or list API keys | @axon402/cli (keys create / keys list / keys revoke) | | Show wallet inventory / deposit addresses | @axon402/cli (wallets list / wallets show / wallets deposit) | | Deposit USDC to a wallet | External wallet app — scan the QR shown by wallets deposit | | Allocate from vault to agent pocket (server-signed orgs only) | @axon402/cli (wallets allocate) | | Inspect the active org, signing mode, scopes, and surface | @axon402/cli (auth whoami) | | Sign in with an operator API key | @axon402/cli (auth login) |

If you try to re-run npx @axon402/init to "add another wallet", it will fail with 409 CONFLICT — the endpoint is intentionally one-shot per email. Use @axon402/cli instead.

Flags

| Flag | Description | | --- | --- | | --version | Print version and exit | | --help, -h | Print help and exit | | --json | Machine-readable JSON output (no prompts). Suitable for scripting. The API key is intentionally NOT included in the JSON output — it's only persisted to disk. | | --email <email> | Email address for headless / --json mode. | | --endpoint <url> | Override the Decision API endpoint. Default: https://api.axon402.com | | --raw-qr | Encode the bare 0x… address in the QR instead of an EIP-681 URI | | --no-open | Do not open the dashboard URL in a browser after success | | --force | Overwrite an existing ~/.axon/config.json. The previous file is copied to ~/.axon/config.json.bak-<ISO8601> before being replaced. Without this flag, the CLI refuses to overwrite and exits non-zero so the existing wallet-bound api_key is never silently destroyed. |

Environment variables

| Var | Description | | --- | --- | | AXON_ENDPOINT | Equivalent to --endpoint. Overridden by the flag. | | AXON_CLI_DEFAULT_ENDPOINT | Same as AXON_ENDPOINT, kept for legacy reasons. | | AXON_EMAIL | Email address for headless / --json mode. Overridden by --email. |

Files written

| Path | Permissions | Contents | | --- | --- | --- | | ~/.axon/config.json | 0600 | { organization_id, wallet_id, api_key, funding_address, dashboard_url, created_at }. Never overwritten silently — the CLI refuses to proceed if the file already exists, unless --force is passed, in which case the old file is copied to ~/.axon/config.json.bak-<ISO8601> first. | | ~/.claude.json | unchanged | New mcpServers.axon entry merged in with url: <endpoint>/v1/mcp plus Authorization: Bearer <runtime-key>. The original is backed up to ~/.claude.json.bak-<unix-timestamp> before modification. |

The api_key written by @axon402/init is a wallet-scoped runtime key (bound to the single agent wallet this tool created). It is NOT an organization-wide operator key — for that, create one from the dashboard or via POST /v1/api-keys and pass it to axon-op auth login. One key = one surface.

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Unexpected error (network failure, server 5xx, validation crash) | | 130 | SIGINT (Ctrl+C aborted the prompt) |

Bin name and global install

If you global-install this package:

npm install -g @axon402/init
axon

The bin name is axon. This is deliberately different from @axon402/cli's axon-op bin, so the two packages can coexist on the same machine without colliding. Most users never need the global install — npx @axon402/init is the supported entry point.

Troubleshooting

• Mandate missing for wallet: you're on a build older than v0.1.0 where the API key was bound to the vault wallet by mistake. Upgrade to ≥ v0.1.0 (npm install -g @axon402/init@latest) and re-run.
• 409 CONFLICT: there's already an account with that email. The CLI prints a dashboard_url you can sign in at to retrieve your existing API key. To manage that existing account from the terminal, install @axon402/cli and run axon-op auth login.
• 429 RATE_LIMITED: 10-per-hour-per-IP limit. Wait the printed number of seconds and retry.
• NETWORK_ERROR: the Decision API is unreachable. For local dev, set --endpoint http://localhost:3030.

Links

• Control-plane operator CLI: @axon402/cli — the durable control-plane operator CLI for wallet lifecycle, keys, deposits, and vault allocations
• Docs: https://axon402.com/docs/cli
• Dashboard: https://axon402.com

License

Apache-2.0.