> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axon402.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Bootstrap a hosted AXON runtime wallet with one command

## Two paths

AXON is a dual-sided platform. Pick the path that matches what you're building:

> **[I want my agent to spend safely](#bootstrap-with-one-command)**
>
> Buyer path — AXON governs your agent's x402 spending with mandates, approvals, and on-chain safety. Continue below.

> **[I want to monetize an endpoint or file](https://docs.axon402.com/docs/getting-started/seller-quickstart)**
>
> Seller path — paste an endpoint or upload a file, set a price, and get a paid AXON URL. See [Seller Quickstart](https://docs.axon402.com/docs/getting-started/seller-quickstart).

> [!NOTE]
>
> This page is the **hosted runtime bootstrap** path powered by `@axon402/init`.
> If you are bringing up your own Decision daemon, Supabase project, and Base
> RPC, use [Live Onboarding](https://docs.axon402.com/docs/getting-started/live-onboarding.md) instead.

## Bootstrap with one command

```bash theme={null}
npx @axon402/init
```

`@axon402/init` is the **one-shot onboarding helper**. It walks you through one prompt (your email), generates a fresh wallet locally, mints a wallet-scoped starter API key against the hosted Decision API at `https://api.axon402.com`, and merges a hosted HTTP MCP entry into `~/.claude.json` so Claude Code can call AXON immediately.

> [!NOTE]
>
> `@axon402/init` is a one-shot bootstrap, not an ongoing CLI. For day-to-day wallet, key, deposit, and allocation management, use [`@axon402/cli`](https://docs.axon402.com/docs/cli/installation#step-2-the-operator-cli) (bin: `axon-op`) after you finish this quickstart.

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

**1. Run the installer**

```bash theme={null}
npx @axon402/init
```

You'll be asked for an email address. The CLI then:

1. Generates a fresh BIP-39 mnemonic locally (never sent to the server).
2. Derives two addresses — a **vault** (HD index 0) and an **agent** (HD index 1).
3. Calls `POST https://api.axon402.com/v1/cli/init` with your email and the two addresses.
4. Gets back an organization, both wallets, a starter spending mandate (10 USDC/day, 0.50/tx, 300/mo, hard-stop), and a wallet-scoped API key bound to the agent wallet.
5. Writes everything to `~/.axon/config.json` (chmod 0600) and merges a hosted HTTP MCP entry into `~/.claude.json` (the original is backed up first).

**2. Confirm the email**

A confirmation email arrives from `noreply@mail.app.supabase.io`. Click the link — it grants you access to the [hosted dashboard](https://axon402.com) at `axon402.com` where you can edit mandates, view ledger entries, and manage approvals.

**3. Fund the wallet the runtime key will use**

The CLI currently prints a QR code for the **vault** address. That does fund the
organization treasury, but the runtime key issued by `@axon402/init` is bound to
the **agent wallet**.

For today's hosted path, use the dashboard after email confirmation to open the
agent wallet and choose **Deposit to Wallet**. That deposit address is the
copy-paste-safe way to fund the wallet your runtime key can actually spend from.

> [!WARNING]
>
> Hosted `@axon402/init` bootstraps a browser-signed org. Browser-signed orgs
> cannot allocate from vault to pocket server-side, so do not assume a vault
> deposit alone will make the issued runtime wallet spendable.

**4. Start Claude Code**

Open a new terminal and run `claude`. The MCP config is already wired — your agent has the AXON tools (`governed_fetch`, `read_spending_policy`, `get_balance`, etc.) available. Try:

> Use `governed_fetch` to retrieve `https://example.com` and tell me the title.

See the [CLI reference](https://docs.axon402.com/docs/cli/reference.md) for flags, exit modes, and troubleshooting.

## Develop locally (contributors)

If you want to run AXON from source — to modify the Decision API, write tests, or use the demo mode that ships zero secrets — start from an AXON source checkout:

```bash theme={null}
npm install
```

### Demo mode (zero secrets)

```bash theme={null}
npm run demo:smoke   # full SSAR pipeline test against deterministic wallets
npm run demo:up      # boots a Decision API on http://127.0.0.1:3030
```

Demo mode uses deterministic wallets and an in-memory provider catalog — no Supabase, no Base RPC, no mnemonic. Useful for understanding the pipeline without setting anything up.

### Live mode (self-hosted)

For a production self-hosted Decision API with real Supabase + real Base settlement, see [Live Onboarding](https://docs.axon402.com/docs/getting-started/live-onboarding.md).

## Manual MCP configuration

The CLI auto-configures Claude Code. If you need to wire MCP by hand, use the
hosted HTTP shape below for the hosted service. Use the stdio shape only when
you are running AXON yourself from source.

**Hosted (recommended)**

```json theme={null}
{
  "mcpServers": {
    "axon": {
      "url": "https://api.axon402.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer axon_sk_..."
      }
    }
  }
}
```

**Self-hosted (live mode)**

```json theme={null}
{
  "mcpServers": {
    "axon": {
      "command": "node",
      "args": ["/path/to/AXON/axon-402-mcp/dist/index.js"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-role-key",
        "BASE_RPC_URL": "https://base-mainnet.g.alchemy.com/v2/your-key",
        "MASTER_MNEMONIC": "your twelve or twenty-four word seed phrase",
        "AGENT_WALLET_ID": "wallet-id-emitted-by-bootstrap"
      }
    }
  }
}
```

> [!NOTE]
>
> `@axon402/init` does **not** install or launch a local MCP process. It writes
> the hosted HTTP entry shown above into `~/.claude.json`.

## Verify end-to-end

The minimum tool sequence to confirm a working agent flow:

1. `read_spending_policy` — see the active mandate
2. `get_financial_status` — confirm wallet balance
3. `governed_fetch` — make a governed x402 call, or receive the approval/browser-signing handoff required before settlement
4. `get_receipt` — fetch the receipt after settlement completes
5. `explain_denial` — if anything got rejected, see why


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.