Skip to main content
AXON is easiest to reason about if you separate four ideas:
  1. An organization is the tenant boundary.
  2. A vault wallet is the treasury wallet for that organization.
  3. An agent pocket wallet is the wallet a worker agent actually spends from.
  4. A runtime key is bound to one agent pocket wallet, not to the whole org.

​
Organization

An organization owns the wallets, mandates, offers, approvals, and ledger entries for one team or company. API keys are always scoped to exactly one organization.
  • Org-wide operator keys live on the control plane.
  • Wallet-scoped runtime keys live on the runtime plane.
If you ever need to answer “which org am I operating on?” or “is this key runtime or operator?”, start with GET /v1/me.

​
Vault wallet

The vault is the organization’s treasury wallet. What it does:
  • receives treasury deposits
  • acts as the source for vault -> pocket allocations in server-signed orgs
  • anchors the org’s signing mode (full vs browser)
What it does not do:
  • it is not the wallet your worker agent spends from
  • it does not carry the runtime mandate that governs agent spend

​
Agent pocket wallets

An agent pocket wallet is the wallet a specific agent uses for governed spend. It can also receive earnings when you attach an offer to it. Operationally, this is the wallet that matters most:
  • the runtime key from @axon402/init is bound to one agent pocket
  • governed_fetch spends from that pocket
  • seller offers pay into that pocket
  • spend-side and earn-side governance both attach to that pocket’s mandate row
Best practice is still one wallet per agent. It keeps limits, audit trails, receipts, and earnings attribution clean.

​
Signing mode changes funding

The most important wallet behavior difference is the org’s signing mode. This distinction is load-bearing:
  • full / server-signed orgs can use treasury allocation as an internal move
  • browser-signed orgs must use Deposit to Wallet for each target wallet because the server has no vault signer
If a funding action fails with VAULT_ALLOCATION_UNAVAILABLE, that is not a generic treasury error. It means the org is browser-signed and the correct next step is direct wallet funding.

​
Departments are optional

AXON still supports departments as an optional grouping for wallets, but they are not required for first launch and most new teams can ignore them initially. Use departments only when you actually need:
  • wallet grouping by team or business unit
  • scoped emergency stops
  • reporting or ownership boundaries inside one organization

​
Practical mental model

For most launches, think in this order:
  1. Operator creates or boots the organization.
  2. Operator creates or confirms the vault wallet.
  3. Operator creates one agent pocket wallet per worker.
  4. Operator funds the pocket that should spend.
  5. Operator hands the runtime key for that pocket to the agent host.

​
Where to inspect the current state