> ## 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.

# Organizations & Wallets

> The tenant boundary, treasury wallet, agent wallets, and how signing mode changes funding

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](https://docs.axon402.com/docs/api-reference/organizations/me.md).

## 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.

| Signing mode | Who holds the vault key | Can AXON allocate vault -> pocket? | Safe funding path |
| :- | :- | :- | :- |
| `full` | The AXON server | Yes | Deposit to vault, then allocate to the pocket |
| `browser` | The user's browser | No | Deposit directly to the target wallet |

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

* [GET /v1/me](https://docs.axon402.com/docs/api-reference/organizations/me.md) — org, surface, wallet binding, signing mode
* [GET /v1/wallets/{wallet_id}](https://docs.axon402.com/docs/api-reference/treasury/get-wallet.md) — deposit address and whether vault allocation is available
* [GET /v1/orgs/{organization_id}/vault](https://docs.axon402.com/docs/api-reference/treasury/get-vault.md) — treasury view
* [GET /v1/orgs/{organization_id}/workforce](https://docs.axon402.com/docs/api-reference/organizations/get-workforce.md) — org wallet/workforce view


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