Integration guide
An assistant that pays when you ask it, such as Claude or ChatGPT connected from the dashboard, may be all you need, every day. This page is for the other use: agents you build and run yourself, on a platform such as Claude Platform, LangChain or CrewAI, that work with no person in the conversation. There can be one or many. Each needs a wallet and limits, and no one pastes a setup line to them. Your coding agent can do the integration for you, in your repository.
Your coding agent
In your repository, signed in to Keyban as you.
Wallet files
Created by the Keyban CLI, one per wallet, kept in your secret store.
Your agents
Each receives its wallet through its runtime and pays within its limits.
In short, your coding agent creates the wallets with the Keyban CLI, the wallet files go to your secret store, and each of your agents receives its own.
1. Check that it fits
Before creating anything, check four things:
- The runtime. The agent must either start an MCP server over stdio (
npx -y @keyban/cli@latest mcp) or run shell commands (keyban wallet …). Either way it needs Node.js 20 or later and network access to the Keyban API. - The services. For each paid API your agents use today, through a subscription or a key, look for an x402 service that sells the same thing.
keyban wallet discover-x402-servicessearches the catalog andkeyban wallet x402-infoshows a service's price and parameters; the dashboard's Services page lists the same catalog. A provider marked as not payable cannot be settled by a Keyban wallet. - The cost. x402 charges per call. Compare it with the subscription at your volume. A mission trial gives you a measured cost per unit, see Missions.
- The network. x402 payments work on Base mainnet and XDC mainnet, and each application runs on one network, set once. See Networks.
2. Choose what a wallet stands for
A wallet carries its own limits, its own emergency stop and its own line in the spending. You decide what it stands for:
| One wallet per | Fits when | What follows |
|---|---|---|
| Agent | Each agent you define has its own job and budget: an agent on Claude Platform, an agent class in your LangChain or CrewAI code. | Every session or instance of the agent shares its wallet and its budget, even when they run in parallel. You can pause and follow each agent. |
| Team or cost centre | Several agents spend from one budget, such as a department's. | Few wallets, one budget per team. Pausing the wallet stops every agent of the team, and the spending does not tell the agents apart. |
| End customer | Your agents work for your own customers. | Spending and limits per customer, so you can bill each one back. As many wallets as customers. |
Never create one wallet per session or per run: a session is short-lived, while a wallet keeps its key share and counts against your plan. Each plan includes a number of wallets, and beyond it extra wallets are billed or refused, see Plans and quotas.
3. Lay out your environments
Create one application per environment, for example dev, staging and prod:
- each application has its own monthly budget, its own destination rules and its own wallets, so a test never spends from another environment's budget;
- the Expenses list is per application, so each environment's spending stays apart;
- give the test environments a small budget, and keep
prodto the services you validated with destination rules; - the organization's monthly budget caps the total, across every environment.
Keyban production offers only mainnet networks for a new agent wallet, so every environment, test included, pays real services with real money: that is what tells you it works. Your plan caps the number of applications, see Plans and quotas. Budgets and destination rules are explained in Spending policy.
4. Create the wallets
This runs on a developer's machine, signed in to Keyban as a person who can create wallets (an Owner or an Admin). Your coding agent can run it: it acts with your rights, and its harness asks you before the sensitive commands.
# Sign in once, in the browser
npx -y @keyban/cli@latest admin login
# One application per environment
npx -y @keyban/cli@latest admin create-application --name prod
# One wallet per agent: the wallet, its policy and its key share, in one file
KEYBAN_WALLET_PATH=./secrets/prod/enrich-01.json \
npx -y @keyban/cli@latest admin new-wallet \
--application-name prod --label enrich-01 --network BaseMainnet \
--policy "$POLICY" --share
admin new-walletcreates the wallet, keeps its configuration in the fileKEYBAN_WALLET_PATHnames, and with--sharegenerates the wallet's key share and adds it to that file. The file is then the whole wallet, ready to hand to a runtime that keeps nothing of its own.--policysets the wallet's limits in the same step, so a wallet never exists without them.npx -y @keyban/cli@latest admin new-wallet --helplists the fields.- An application runs on one network, fixed by its first wallet: a wallet on another network is refused.
- Every admin tool is a
keyban admincommand: set an application's budget or destination rules, change a wallet's policy, list the wallets.npx -y @keyban/cli@latest admin --helplists them, and Admin tools describes each one.
5. Hand each wallet to its runtime
| Runtime | How the agent gets its wallet |
|---|---|
| A Claude managed agent (Claude Platform) | Mount the wallet file in the agent, at /uploads/wallet.json. The agent drives the wallet through the keyban CLI in its bash tool: its environment needs the npm package @keyban/cli and network access to the Keyban API, and its system prompt starts with You hold a wallet through the keyban CLI: export KEYBAN_WALLET_PATH=/mnt/session/uploads/wallet.json before each keyban command, then read keyban wallet get-wallet-instructions and follow it. |
| LangChain, CrewAI or any framework that speaks MCP | Start the stdio server npx -y @keyban/cli@latest mcp for each agent, with KEYBAN_WALLET_PATH pointing to the wallet file mounted from your secret store, or KEYBAN_CONFIG holding the file encoded in base64. |
| A runtime that only has environment variables (Amazon Bedrock AgentCore, a serverless container) | KEYBAN_CONFIG, the wallet file encoded in base64. |
| An agent with a shell and no MCP | The same variables, with the keyban wallet <tool> commands. |
The agent then learns the wallet from its skill, through the get_wallet_instructions tool or keyban wallet get-wallet-instructions.
6. Keep the wallet files secret
A wallet file holds the wallet's API key and its key share: whoever holds it can ask Keyban to pay, within the wallet's limits.
- Keep each file in your secret store and mount it at runtime. Never commit it, bake it into an image, paste it in a prompt or write it to a log.
- A key share is generated once and cannot be exported again. If you lose a file, create a new wallet.
- If a file leaks, pause the wallet with the emergency stop, then replace it. See Security.
7. Run missions
A mission turns a task you tried into one your agents repeat at a known cost. You tune it with one wallet: a trial pays the services for real and measures the cost. Then you publish it and share it with the application or the whole organization. Every wallet inside its sharing can then start runs, each within the mission's envelope. To keep an agent's wallet to the tasks you validated, require a mission in its policy: it can then pay only inside a run. See Run missions.
8. Watch and operate
- Spending. Expenses shows each payment by wallet, operator, destination and mission, per application, with a CSV export. For a supervision tool, mint a read-only follower key for a wallet. See Track spending.
- People in the loop. A payment above a wallet's approval threshold waits in the Inbox. Set thresholds so that routine payments pass on their own. See Approve payments.
- Alerts. Keyban e-mails people when a monthly budget is on pace to run out, and when it is used up.
- Stop. The emergency stop pauses one wallet at once. To retire a wallet, delete it.
Before you go live
- Each paid API your agents use has an x402 equivalent, checked with its price.
- One application per environment, each with its monthly budget and destination rules.
- Each wallet created with its policy, and its file in your secret store only.
- Each runtime starts the Keyban MCP server or runs the
keybanCLI, and reaches the Keyban API. - The missions you rely on are published and shared with your agents' wallets.
- Someone watches the Inbox and the budget e-mails.
Related
- How it works: who pilots, who operates.
- Organizations, applications and wallets: who can do what.
- Compatible agents: the assistants the dashboard's wizard connects one by one.