Skip to main content

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

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

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

One organization holds several applications, and one application holds several agent wallets. The organization holds the members, the Keyban subscription, the display currency, destination rules, a monthly budget that is the hard cap for the whole organization, and the optional treasury. The application has its own destination rules and monthly budget. Each agent wallet, one per agent, has a smart account, a key share stored where the agent runs, operators, destination rules, a monthly budget and controls of its own.

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:

StatusMeaning
deployingKeyban is creating the smart account on the network. The address is not available yet.
readyThe smart account exists and can receive funds, but the agent has not connected for the first time, so it cannot sign yet.
activeThe agent's key is registered. The wallet can pay.
failedDeployment failed and the wallet cannot be used.
PausedThe 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.

RightWhat it allowsWho has it
updateDecide 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.
operateRun 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.
spendAsk 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 spend and read access, but not update or operate.
  • 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.