Testnet on Base Sepolia: 1 ZRO here is 0.0001 test ETH.
Docs · Agent vault

Docs · For builders

Agent vault

A vault you make for an AI agent or a bot of your own. You own it and put ZRO in. The agent gets a key of its own that can only buy and sell through Submarine's router, inside limits only you set. Only you can take anything out.

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 agentYou, the owner
Buy and sell through the routerYes, inside the limitsYes, without limits
Where bought tokens goThe vault, alwaysThe vault, always
Where the ZRO from a sale goesThe vault, alwaysThe vault, always
Take ZRO or tokens outNeverAny time, to any address
Change the limits or the token listNeverAny time
Change or remove the agentNeverAny time
Change the ownerNobody canNobody 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

LimitWhat it does
perTradeThe most ZRO one buy may spend
perDayThe 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
slippageBpsEvery trade's minimum must be at least the router's quote at that moment, less this. 500 is 5%. At most 5,000
listedOnlyWhen 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.

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

json
"env": {
  "TERMINAL_API": "...",
  "RPC_URL": "...",
  "AGENT_VAULT": "0xYourVault",
  "AGENT_KEY": "0xTheAgentsOwnKey"
}

Trading from code

CallWhoWhat
buy(token, zroIn, minOut, deadline)agent or ownerBuys with the vault's ZRO. The tokens stay in the vault
sell(token, tokensIn, minOut, deadline)agent or ownerSells the vault's tokens. The ZRO comes back to the vault
leftToday()anyoneWhat the agent may still spend today, given the vault's balance
setAgent(agent)ownerChanges the agent. The zero address removes it
setLimits(limits)ownerNew limits, from the next trade on
setListed(tokens, on)ownerAdds tokens to the list, or takes them off
withdraw(amount, to)ownerSends ZRO out
withdrawTokens(token, amount, to)ownerSends 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.
Keep in it only what the agent may lose. The vault makes a bad agent cheap, not harmless. Start small, watch it trade, then raise the limits.

Source: contracts/src/periphery/AgentVault.sol, tests in contracts/test/AgentVault.t.sol.