Organizations, applications and wallets
Everything in Wallet for Agents hangs off a three-level hierarchy: an organization contains applications, and an application contains agent wallets. This page explains what each level owns, which people and which keys can act on a wallet, and what your Keyban subscription changes.
1 organization Organization
Members
Owner, Admin, Editor, Viewer
Keyban subscription
Your plan and its quotas
Display currency
Chosen once
Destination rules
Where every wallet of the organization may pay
Monthly budget
The hard cap for the whole organization. Optional, set by an Owner
Treasuries
Optional multisig, at most one per network, from the Growth plan
N per organization Application
Network
One blockchain per application, set once
Destination rules
Narrow the organization's, for every wallet of the application
Monthly budget
Optional, within the organization's
N per application, one per agent Agent wallet
Smart account
Holds the USDC, on one network
Key share
Stored where the agent runs
Operators
People who run this wallet
Destination rules
Narrow the application's
Monthly budget
Within the application's
Wallet controls
Per-payment cap, daily and weekly budgets, approval threshold, emergency stop
In short, one organization has one display currency and holds several applications; each application runs on one blockchain network and holds several agent wallets on it, so an organization can use several networks through several applications. At every level the policy is made of the same two things, destination rules and a monthly budget, with controls of its own added at the wallet.
The organization
The organization is the account. It holds:
- Members, each with one role: Owner, Admin, Editor or Viewer.
- Your Keyban subscription, the plan that sets the limits described below.
- The display currency (euro, US dollar or yen), chosen once for the whole organization and impossible to change afterwards. Balances are shown in it and spending policies are written in it.
- Destination rules, which apply to every wallet of the organization. See Destination rules.
- A monthly budget, optional: the most all the agent wallets of the organization spend together in a calendar month. It is the hard cap for the whole organization. Only an Owner sets it, and only an Owner decides a raise that reaches it. See Monthly budgets.
- Multisig treasuries, if you use them: pots of USDC that several signers control together and that refill your agents' wallets. An organization has at most one treasury per network. See Multisig treasury.
The application
An application groups agent wallets. Your account comes with one already created, and your subscription sets how many you can have.
An application runs on one blockchain network, chosen once and fixed afterwards: every agent wallet of the application lives on that network, and a wallet on another network is refused. To use two networks, for example Base mainnet and XDC mainnet, use two applications.
An application can have its own destination rules, which apply to every wallet it contains, and its own monthly budget, which Owner and Admin set inside the budget of the organization.
The agent wallet
An agent wallet is one agent's own wallet. It belongs to one application and runs on the network of that application. Its main parts are:
- A smart account on that network, which holds the USDC. Its address is known once the wallet leaves
deploying, before the agent runs anything, so you can fund it then. - A key share. The agent's key is split in two shares. Keyban keeps one, and the agent keeps the other, its client key share, in a file stored where the agent runs: on your machine, or on the hosted platform you gave it to. The same file holds the wallet's API key. Any agent that has access to that file can ask Keyban to pay from the wallet, within the policy, so keep it like a password. The agent cannot sign without being authenticated on Keyban, and Keyban co-signs only what the policy allows. See Where the agent's share lives.
- Operators: the people who run this wallet. They receive its MCP configuration, approve or decline payments that wait for a human, and can pause the wallet.
- A policy, created together with the wallet. It is made of the same two things as at the levels above, destination rules and a monthly budget, plus the controls of the wallet itself: a per-payment cap, daily and weekly budgets, the approval threshold and the emergency stop. See Spending policy.
If the wallet's file leaks, pause the wallet with the emergency stop and replace the agent's key: the wallet's address does not change. Replacing the agent's key goes through the API, and the steps are in What a leaked credential gives an attacker.
A wallet goes through these states:
| Status | Meaning |
|---|---|
deploying | Keyban is creating the smart account on the network. The address is not available yet. |
ready | The smart account exists and can receive funds, but the agent has not connected for the first time, so it cannot sign yet. |
active | The agent's key is registered. The wallet can pay. |
failed | Deployment failed and the wallet cannot be used. |
| Paused | The emergency stop is on, set by a person or by the end of the free trial. Every payment request is refused until someone resumes the wallet. A wallet can be paused in any of the states above. |
Paused is how the dashboard shows the emergency stop. In the API it is not a value of the wallet's status but a switch of its policy (emergencyStop), so a paused wallet keeps its status underneath. The end of the free trial pauses every wallet of the organization the same way. An upgrade resumes only the wallets that the trial end paused, not a wallet that a person paused. See The emergency stop.
Destination rules
A destination rule says where the payments of a level may go: which addresses for USDC transfers, and which domains for x402 payments. It guards against an agent that pays a service or an address you never meant it to.
- A rule is an allow-list (only these destinations) or a deny-list (anything but these). A level has one mode, never both.
- The levels combine: a destination must pass the rule of the organization, of the application and of the wallet, and the strictest wins. A lower level can only narrow what a higher one allows.
The detail, with who edits each level, is in Spending policy.
Who can do what
Three separate rights apply to an agent wallet. They are deliberately separate so that the person who decides the limits is not the one who runs the agent, and neither is the agent.
| Right | What it allows | Who has it |
|---|---|---|
update | Decide the limits: edit the policy, edit the destination rules of a wallet or an application, set the monthly budget of an application, assign operators. | Owner and Admin. |
operate | Run a wallet inside those limits: get its MCP configuration, register a new key for the agent, approve or decline held payments, pause and resume the wallet, and ask for a top-up. Revoking the old key needs Owner or Admin. | Owner and Admin on every wallet. Editor (shown as "Operator" in the dashboard) only on the wallets they are assigned to as an operator. |
spend | Ask Keyban to evaluate and sign a payment. | The agent's API key, and nothing else. |
Two consequences matter in practice:
- An agent cannot change its own limits or approve its own payment. Its key carries
spendand read access, but notupdateoroperate. - A person is involved only when a payment triggers a policy rule that asks for one. Under the approval threshold set by the person responsible for the wallet, the agent pays on its own. A person steps in when a payment is above the threshold, or when its price drifted beyond the margin after an approval. When a person does approve, the approval comes from a signed-in session or from a person's OAuth sign-in, never from an API key, so that every approval can be attributed to someone. See The approval threshold.
Viewers can read wallets but not act on them. The organization-wide destination rules are edited with the organization settings right, which only Owner and Admin have.
One decision is reserved to the Owner role, above the three rights: the monthly budget of the organization. An Admin has the organization settings right but cannot set or remove that budget, and cannot approve a raise request that makes it rise, even their own request. An Owner also sets the time zone of the months. See Control spending.
A wallet always has at least one operator. When you create it, you are its operator unless you name others. When a wallet has operators, they are the ones notified of the payments waiting for approval; Owner and Admin can still approve as a fallback.
What your subscription decides
Your Keyban subscription, the plan, sets limits on the organization, shown in the dashboard under Billing, then Usage:
- the number of applications and of agent wallets;
- a monthly transaction quota, shared by every wallet of the organization;
- the networks you may create wallets on;
- which features are open: the multisig treasury comes with the Growth plan and above, or by a grant from Keyban.
A new organization starts on the free plan, a 90-day trial. It needs no verified e-mail address and no accepted terms to be created. A verified e-mail address is needed before any payment to Keyban, and accepted terms before money moves: see Plans and quotas.
Related
- Funding sources: how money reaches a wallet.
- Multisig treasury: the shared pot that refills the wallets of a fleet.
- Spending policy: the destination rules, the budgets and the controls of a wallet.
- Security model: how these rights fit in the overall threat model.