Docs · For builders
Agent vault
Why a vault
An agent that trades needs a key it can sign with. Handing it the key of your own wallet means handing it everything in that wallet. A vault splits the two: your wallet owns the vault, and the agent's key only trades inside it. If the agent's key leaks, the most anyone can do with it is trade inside your limits until you remove it.
What the agent can and cannot do
| The agent | You, the owner | |
|---|---|---|
| Buy and sell through the router | Yes, inside the limits | Yes, without limits |
| Where bought tokens go | The vault, always | The vault, always |
| Where the ZRO from a sale goes | The vault, always | The vault, always |
| Take ZRO or tokens out | Never | Any time, to any address |
| Change the limits or the token list | Never | Any time |
| Change or remove the agent | Never | Any time |
| Change the owner | Nobody can | Nobody can |
The owner is fixed when the vault is made. There is no call that hands the vault to someone else, so there is none for an agent to trick you into.
The limits
| Limit | What it does |
|---|---|
perTrade | The most ZRO one buy may spend |
perDay | The most ZRO the agent's buys may spend in a UTC day. What a curve hands back on the buy that fills it is not counted |
slippageBps | Every trade's minimum must be at least the router's quote at that moment, less this. 500 is 5%. At most 5,000 |
listedOnly | When on, the agent may buy only tokens you have listed with setListed |
Sales are not counted against the day: they bring ZRO back. They still have to meet the slippage floor.
Making one
Call create on AgentVaultFactory from the wallet that should own the vault, with the agent's address, the limits, and any ZRO to put in. The factory keeps a list of every owner's vaults, vaultsOf(owner). The address is on Contract addresses once it is deployed.
const limits = { perTrade: parseEther('50'), perDay: parseEther('200'), slippageBps: 500, listedOnly: false };
await owner.writeContract({
address: agentVaultFactory,
abi: parseAbi(['function create(address agent, (uint128 perTrade, uint128 perDay, uint16 slippageBps, bool listedOnly) limits) payable returns (address)']),
functionName: 'create',
args: [agentAddress, limits],
value: parseEther('500'),
});Make the agent's key a fresh one, not one that holds anything else. It needs a little ZRO of its own for gas: the vault pays for trades, not for the agent's transactions.
Trading from the MCP server
Give the MCP server the vault's address and the agent's key, and it offers three more tools: vault_status, vault_buy and vault_sell. They quote first, set the minimum from the quote, and never ask for a looser one than the vault allows.
"env": {
"TERMINAL_API": "...",
"RPC_URL": "...",
"AGENT_VAULT": "0xYourVault",
"AGENT_KEY": "0xTheAgentsOwnKey"
}Trading from code
| Call | Who | What |
|---|---|---|
buy(token, zroIn, minOut, deadline) | agent or owner | Buys with the vault's ZRO. The tokens stay in the vault |
sell(token, tokensIn, minOut, deadline) | agent or owner | Sells the vault's tokens. The ZRO comes back to the vault |
leftToday() | anyone | What the agent may still spend today, given the vault's balance |
setAgent(agent) | owner | Changes the agent. The zero address removes it |
setLimits(limits) | owner | New limits, from the next trade on |
setListed(tokens, on) | owner | Adds tokens to the list, or takes them off |
withdraw(amount, to) | owner | Sends ZRO out |
withdrawTokens(token, amount, to) | owner | Sends tokens out |
A vault that holds a token which pays its holders earns like any holder. Anyone can call claimFor(vault) on the token, and the ZRO lands in the vault.
What the limits do not cover
- The limits cap how much the agent can spend, not how well it trades. Inside them it can still buy a token that goes to zero.
- A leaked agent key can trade until you remove it with setAgent. It can never take anything out.
- For larger amounts, turn on listedOnly and list only tokens you are willing to hold.
Source: contracts/src/periphery/AgentVault.sol, tests in contracts/test/AgentVault.t.sol.