Hartii developer docs

Agent Terminal

Security

What's enforced on-chain

  • An agent key can only call AgentVault.execute.
  • execute only reaches an allowlisted Hartii contract (see Contracts).
  • transfer/transferFrom are forbidden on every token — an agent key cannot move assets out of the vault through any call it's allowed to make.
  • approve is 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. maxPerTx and maxPerDay count 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 and transfer/transferFrom are 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, revoke and 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.

AgentVaultPersonal holder trader
Where limits are enforcedOn-chain, by the vault contractIn software on your computer
The keyAn agent key the contract limitsA dedicated trading wallet, encrypted on your computer
What a stolen key can doOnly what the vault allows, inside its capsAnything that wallet's balance allows
Remote controlThe owner can pause, revoke and withdraw on-chain at any timeThe dashboard can only pause. It cannot start, unlock, raise a limit or withdraw. The dashboard is not available in this release
StatusLive (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.

Quai Network mainnet · chain 9 · Cyprus-1. Figures marked "read on" a date were read from the chain that day; re-read before relying on them.