Security
What's enforced on-chain
- An agent key can only call
AgentVault.execute. executeonly reaches an allowlisted Hartii contract (see Contracts).transfer/transferFromare forbidden on every token — an agent key cannot move assets out of the vault through any call it's allowed to make.approveis only allowed against a token this vault can actually trade, must carry zero QUAI value, and its spender must be the router or that token's own registered curve — an agent cannot disguise a payment as an approval.- Per-transaction and daily QUAI caps are enforced by the contract, not by the API, the MCP server, or the page. The daily cap is counted in hourly buckets (see What the caps measure).
- The owner can
pause,revoke, or withdraw everything at any time, independent of the agent.
What the caps measure
- The caps meter native QUAI only.
maxPerTxandmaxPerDaycount the QUAI value attached to an agent call. Launch tokens, WQUAI and other tokens held in a vault are not covered by the caps: the agent can trade them (for example sell a launch token on its curve, or swap tokens through the router) without a limit, because what it receives stays in the vault. The agent still cannot send anything out of the vault, since recipients are pinned to the vault andtransfer/transferFromare forbidden. This is a question of how much a bad trade can lose, not of theft. - Keep a vault to QUAI, or sweep tokens out. If you do not want token or WQUAI holdings exposed to the agent, hold only QUAI in the vault, or move tokens out with the owner function
withdrawToken(see Contracts).pause,revokeand withdrawing remain available to you at any time. - The daily cap is counted in hourly buckets, not a strictly rolling window. The contract adds up the last 24 hourly buckets. A spend late in one hour and another a little over 23 hours later can fall in different windows, so inside a real 24-hour span an agent can spend close to twice
maxPerDay. The per-transaction cap, your pause and revoke, and the pinned recipients still apply. This is a known property of the deployed vault generation and is not changed for existing vaults.
What isn't guaranteed
- Caps limit blast radius, not loss. An agent can still lose everything within its caps — a bad trade, a buggy strategy, a launched token going to zero.
- The Agent API's builders and the MCP server's simulation reduce the chance of a failed or unintended transaction, but a simulation can still miss a revert that only happens under different chain state a block later.
- Start with low caps, and fund a vault with only what you can afford to lose.
Hartii never handles a private key
The Agent page at hartiilabs.com/agent only ever accepts an agent's public
address. It has no way to generate, accept or display a private key, and never has. Your agent generates its own
key on its own machine (npx -y https://hartiilabs.com/downloads/hartii-agent-mcp.tgz keygen, see
MCP setup) and hands you only the address. The key itself never touches a browser or a Hartii server.
The agent key must be ground in-zone
Quai Network is sharded into zones; a vault's agent address must resolve to a Cyprus-1
address, the zone AgentVault deploys in. A plain random private key lands in Cyprus-1 only about
1 in 512 tries. npx -y https://hartiilabs.com/downloads/hartii-agent-mcp.tgz keygen grinds a fresh key locally until
quais.isQuaiAddress(address) and quais.getZoneForAddress(address) === quais.Zone.Cyprus1 are
both true, and prints only its address — the key is written straight to a local file and never
transmitted anywhere. See MCP setup for the same requirement from the agent runtime's side.
MCP profiles
@hartii/agent-mcp starts in the read-only profile. In it the server never reads an agent key, never opens a key
file and never creates a wallet, even when an old config supplies one. It can only read. Signing needs an explicit
HARTII_MCP_PROFILE=legacy-delegated and an existing vault. In that profile a write runs right after the
server's simulation and the vault checks, with no review-token step. The on-chain caps still apply.
hartii mcp, the server inside the Hartii CLI, is separate. Its writes are
off unless you start it with --allow-writes and both caps. Each write is a dry run until a one-use review token
confirms it. See MCP setup.
The personal holder trader is different
The personal holder trader does not use an AgentVault. It runs in Observe and Paper only, and Live trading is not available. If Live ever ships, its limits will be software on your own machine, not a contract. Anyone who holds the trading wallet's key can bypass them.
| AgentVault | Personal holder trader | |
|---|---|---|
| Where limits are enforced | On-chain, by the vault contract | In software on your computer |
| The key | An agent key the contract limits | A dedicated trading wallet, encrypted on your computer |
| What a stolen key can do | Only what the vault allows, inside its caps | Anything that wallet's balance allows |
| Remote control | The owner can pause, revoke and withdraw on-chain at any time | The dashboard can only pause. It cannot start, unlock, raise a limit or withdraw. The dashboard is not available in this release |
| Status | Live (beta) | Observe and Paper only |
Observe and Paper never create a signer and never send a transaction. Use a trading wallet that is separate from your owner wallet. The CLI refuses the same address for both. Do not put funds in a trading wallet you do not need to fund.
Revoking access
From hartiilabs.com/agent, "Revoke" clears the vault's agent address and pauses it in one on-chain transaction — the agent loses all ability to act immediately, independent of whatever MCP server or key it was using.
Reporting an issue
Treat a suspected vulnerability the same as any other Hartii contract issue — see the main FAQ for the current contact channel.