Getting started
Hall is a vault contract on Robinhood Chain that holds an owner's funds and lets an AI agent move them only within a policy the owner writes. The agent signs with its own key, and every move it asks for walks four doors in the contract: the lock, the guest list, the counter and the waiting room.
Three ways in:
- People open and run a vault from the vault desk: write the policy, lock it, release or cancel held moves, withdraw.
- Agents use the JSON API or the MCP server to ask whether a call would pass, then build the unsigned transaction and sign it with their own key.
- Anyone can read any vault: its policy, balances, waiting room and activity, straight from the chain.
Hall's server never holds a key and never sends a transaction. Everything here is free.
The four doors
The agent calls execute(target, value, data) on its vault. The vault checks the call at four doors in this order; the first that says no decides it.
- The lock (kill switch). If the owner locked the vault, every agent move and every release is refused. Withdrawals still work.
- The guest list (allowed calls). The target address and the call's 4-byte selector must be listed. A plain ETH send with no calldata is the selector
0x00000000. Unlimited approvals (approve or increaseAllowance for 2256−1, setApprovalForAll) and calls to the vault or its factory are always refused. - The counter (spend caps). The amount must fit the asset's per-move cap and what's left of its clock-hour and UTC-day caps. ETH counts the call's value; a token counts the amount in transfer, approve, increaseAllowance, or transferFrom out of the vault, on the token's own contract. An asset with no caps set has caps of zero.
- The waiting room (time-lock). Above the asset's hold threshold, the move is queued for the vault's delay (1 minute to 30 days). The owner or agent can cancel it; after the delay the agent or owner releases it, and it is checked again (without this door) and counted then. It expires 7 days after it becomes ready.
More on each door, with what it stops and lets through, on the doors page.
Answers and reasons
Every check gives one of three answers: pass (goes through now), hold (waits in the waiting room) or refuse (reverts). A refusal carries a reason code, the same one the contract's Refused(reason, asset, amount) error uses.
| Code | Key | Door | Meaning |
|---|---|---|---|
| 1 | frozen | lock | The owner locked the vault. |
| 2 | self_call | list | The call aims at the vault or its factory. |
| 3 | not_allowed | list | Target and selector aren't listed. |
| 4 | unlimited_approval | list | An unlimited approval, refused whatever the list says. |
| 5 | bad_calldata | list | Calldata too short for the function it names. |
| 6 | over_per_tx | counter | Over the per-move cap. |
| 7 | over_per_hour | counter | Over what's left of this hour's cap. |
| 8 | over_per_day | counter | Over what's left of today's cap (UTC). |
Agent quickstart
The owner gives the agent two things: the vault's address and an agent key (any address the agent controls, never the owner's). Then, for every move:
- Ask.
GET /api/check(or the MCP toolcheck_policy) returns the answer, the door and reason, and a simulation of the agent's ownexecuteagainst the live chain. - Build.
GET /api/build(orbuild_execute_tx) returns the unsigned transaction to the vault, with a gas estimate. - Sign and send it with the agent key. Hall never signs.
- If it was held,
GET /api/pending(orpending_timelocks) shows when it is ready, with the release transaction to send.
curl "https://hallofagents.xyz/api/check?vault=0xVAULT&target=0xCaf681a66D020601342297493863E78C959E5cb2&value=0.04&data=0x04e45aaf…"
curl "https://hallofagents.xyz/api/build?vault=0xVAULT&target=0xCaf681a66D020601342297493863E78C959E5cb2&value=0.04&data=0x04e45aaf…"API reference
Base URL https://hallofagents.xyz/api. JSON in and out, CORS open to any origin, no key. Addresses are checksummed in answers. Amounts come as { raw, text, asset, symbol }: raw in the asset's smallest unit, text for people. value is in ETH (0.05); pass value_wei instead for an exact amount.
/api/factoryThe factory: whether it's deployed, deposit caps, vault count, admin, and the rules (delays, sizes, doors, reason codes).
{ "deployed": true, "factory": "0x3A25…556c", "chainId": 4663, "audited": false,
"admin": "0xf39F…2266", "capsLifted": false, "vaultCount": 3,
"depositCaps": [ { "raw": "1000000000000000000", "text": "1 ETH", "symbol": "ETH", … },
{ "raw": "2500000000", "text": "2,500 USDG", "symbol": "USDG", … } ],
"rules": { "minDelay": 60, "maxDelay": 2592000, "grace": 604800, "maxAssets": 32, "maxAllowed": 128,
"doors": { … }, "reasons": [ { "code": 1, "key": "frozen", "door": "lock", "text": "…" }, … ] } }/api/vault?vault= · /api/vault?owner=A whole vault in one read: owner, agent, pending owner, lock, delay, policy revision, balances with deposit caps, caps with what was used this hour and today, the guest list, held moves and the check-up notes. Pass inspect=0 to skip the notes.
{ "vault": "0x9E27…6f6B", "factory": "0x3A25…556c", "fromFactory": true,
"owner": "0xE7f9…A7De", "pendingOwner": null, "agent": "0x1831…E881",
"frozen": false, "gateDelay": 7200, "gateDelayText": "2 h", "revision": 12, "heldCount": 1,
"balances": [ { "text": "0.38 ETH", "symbol": "ETH", "depositCap": "1 ETH", … } ],
"limits": [ { "symbol": "ETH", "perTx": { "text": "0.05 ETH", … }, "perHour": { … }, "perDay": { … },
"holdAbove": { … }, "spentThisHour": { "text": "0.08 ETH", … }, "spentToday": { … } } ],
"allowed": [ { "target": "0xCaf6…5cb2", "targetLabel": "Uniswap SwapRouter02",
"selector": "0x04e45aaf", "function": "exactInputSingle" }, … ],
"pending": [], "inspection": [ { "level": "info", "text": "ETH: nothing can be over the hold threshold …" } ] }/api/check?vault=&target=&value=&data= · POST the same as JSONWould this call pass? The vault answers with its own check function, then the agent's execute is simulated with eth_call. Without vault, the call is checked against the home page's sample policy instead.
{ "source": "vault", "vault": "0x9E27…6f6B",
"call": { "target": "0x5fc5…1168", "targetLabel": "USDG", "selector": "0x095ea7b3", "function": "approve", … },
"ruling": "refuse", "door": "list", "doorName": "The guest list (allowed calls)",
"reason": "unlimited_approval", "reasonCode": 4,
"message": "Unlimited approvals are refused, whatever the list says.",
"amount": { "text": "unlimited USDG", … }, "releaseAt": null, "simulation": null }/api/build?vault=&target=&value=&data= · ?vault=&action=release|cancel&move=The unsigned transaction the agent key sends: execute for a call (with the check as a preview), or release / cancel for held move number move. from defaults to the vault's agent.
{ "tx": { "chainId": 4663, "from": "0x1831…E881", "to": "0x9E27…6f6B",
"data": "0xb61d27f6…", "value": "0", "gas": "70828" },
"signer": "agent", "agent": "0x1831…E881", "owner": "0xE7f9…A7De",
"preview": { "ruling": "pass", … },
"note": "Unsigned. Sign and send it with the agent's own key. execute takes no ETH itself: the vault pays value from its balance." }/api/pending?vault=Held moves: what each would do, state (waiting, ready, expired), etaIso and expiresIso, and the unsigned releaseTx (only when ready and unlocked) and cancelTx.
/api/activity?vault=&n=The vault's own events, newest first (up to 200): agent moves, held, released and cancelled moves, policy changes with their revision, locks, deposits, withdrawals and handovers, each with a plain-words text.
/api/draftFor owners. Send { vault, changes: [ { op, … } ] } and get back what will change, a check-up of the policy after it, and one unsigned transaction (a multicall when there are several changes). Ops: allow / disallow (target, selectors), limits (asset, perTx, perHour, perDay, holdAbove), clearLimits, delay (gateDelayHours), agent (address), freeze, unfreeze, cancel, offer (to), cancelOffer. Selectors can be 0x12345678, a signature like transfer(address,uint256), or plain.
curl -X POST https://hallofagents.xyz/api/draft -H "content-type: application/json" \
-d '{"vault":"0xVAULT","changes":[{"op":"freeze"},{"op":"delay","gateDelayHours":12}]}'
{ "summary": [ "Lock the vault", "Waiting room: 12 h" ],
"inspection": [ { "level": "info", "text": "The vault is locked. The agent can't move anything until the owner unlocks it." } ],
"tx": { "chainId": 4663, "from": "0xE7f9…A7De", "to": "0x9E27…6f6B", "data": "0xac9650d8…", "value": "0" } }To open a vault, send { create: { owner, agent, gateDelayHours, deposit, limits: [ … ], allows: [ { target, selectors } ] } }. The answer adds predictedVault; an owner who already has one gets 409 has_vault with its address.
/api/inspect?vault= · /api/sample · /api/known · /api/tokeninspect: just the check-up notes (info, ok, warn, risk). sample: the home page's sample policy and seven example moves with their answers and live simulations. known: labelled Robinhood Chain contracts, common selectors and guest-list presets. token: the token's supply and burned amount from the chain, never a price.
MCP server
A remote MCP server at https://hallofagents.xyz/api/mcp: Streamable HTTP with plain JSON replies, protocol 2025-06-18, no sessions, no auth. Methods: initialize, notifications/initialized, tools/list, tools/call, ping. Tool errors come back as results with isError: true.
claude mcp add --transport http hall https://hallofagents.xyz/api/mcp{ "mcpServers": { "hall": { "url": "https://hallofagents.xyz/api/mcp" } } }| Tool | What it does | Arguments |
|---|---|---|
vault_status | The whole vault: who, lock, policy with what's used, balances, held moves, check-up. | vault or owner |
check_policy | Would this call pass, hold or be refused, at which door, plus a live simulation. | vault, target, value, data |
build_execute_tx | The unsigned transaction for the agent key: execute, or release / cancel a held move. | vault, action, move, call fields |
pending_timelocks | Held moves with times and their release and cancel transactions. | vault or owner |
vault_activity | The vault's events, newest first. | vault, n |
curl -s https://hallofagents.xyz/api/mcp -H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_policy","arguments":{"vault":"0xVAULT","target":"0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168","data":"0x095ea7b3…"}}}'Example agent
Ask first, then sign with the agent's own key. Uses viem in Node 18 or later.
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
const API = 'https://hallofagents.xyz/api';
const VAULT = '0xYourVault';
const chain = { id: 4663, name: 'Robinhood Chain', nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
rpcUrls: { default: { http: ['https://rpc.mainnet.chain.robinhood.com'] } } };
const wallet = createWalletClient({ account: privateKeyToAccount(process.env.AGENT_KEY), chain, transport: http() });
const call = new URLSearchParams({ vault: VAULT, target: '0x…', value: '0.01', data: '0x' });
const check = await (await fetch(`${API}/check?${call}`)).json();
if (check.ruling === 'refuse') throw new Error(`${check.doorName}: ${check.message}`);
const { tx } = await (await fetch(`${API}/build?${call}`)).json();
const hash = await wallet.sendTransaction({ to: tx.to, data: tx.data, gas: tx.gas ? BigInt(tx.gas) * 12n / 10n : undefined });
console.log(check.ruling === 'hold' ? 'queued, see /api/pending' : 'sent', hash);Errors and limits
Errors are JSON: { "error": "code", "message": "…" }.
- 400 bad input:
bad_address,bad_value,bad_data,bad_op,bad_move,bad_amount,bad_selectors,bad_delay,agent_is_owner,too_many. - 404
not_a_vaultorno_vault(that owner has none). 405 wrong method. 409has_vault. - 429 more than 120 requests a minute from one IP. 502 the Robinhood Chain RPC failed; try again. 503
not_launchedwhen the factory isn't deployed yet.
Free tier: everything, for everyone. Reads are cached for a few seconds at the edge (s-maxage 3 to 60 s; the factory 15 s). Nothing is stored about you.
Opening a vault
On the vault desk, connect the wallet that will own the vault and press Open a vault. Choose the agent key, the waiting room delay, caps for ETH (and USDG if you like) and what the agent may call. The desk asks the API to check it, shows a check-up, then your wallet sends one createVault transaction to the factory, with an optional ETH deposit.
- One vault per owner. The vault's address is predictable before you send.
- Deposits are capped per vault until an audit. ETH and USDG have caps; other tokens can't be deposited through the vault while caps apply.
- Give the agent only the agent key's private key, never the owner's.
Changing the policy
Only the owner can change anything. On the desk, add changes to a draft, press Check the draft to see exactly what one transaction will do and a check-up of the result, then sign. Each change bumps the vault's revision number, which is logged with the change.
The check-up flags things that won't do what they seem to: a hold threshold at or above the per-move cap (the waiting room never fills), an hour cap above the day cap, an unlimited-approval function on the list, a listed contract with no code, a vault without an agent key, and more.
The lock, withdrawals and handover are on the desk too. Withdrawals are never blocked, locked or not.
The contracts
- HallFactory opens vaults with CREATE2, one per owner, and holds the deposit caps. Its admin can lift the caps once, for all vaults, and renounce the role. Nothing else.
- HallVault holds the funds and the policy. Owner: withdraw, ownerExecute, freeze/unfreeze, setLimits, clearLimits, setAllowed, setGateDelay, setAgent, offerOwnership, cancelOffer, cancel, multicall. Agent: execute, release, cancel. Anyone: check, limits, assets, isAllowed, allowedList, pendingIds, heldMove, info.
- Solidity 0.8.24, OpenZeppelin 5 (ReentrancyGuard, SafeERC20, Multicall). 76 Foundry tests: 57 unit, 7 fuzz, 6 invariant, 6 on a fork of Robinhood Chain.
The factory's address appears in the bar at the top once it is deployed.
The token
$HALL is Hall's token on Pons. No vault uses it: creating a vault, writing its policy and every agent move cost only gas, and holding the token gives no access to any vault. /api/token shows supply and the burned amount read from the chain; there is no price anywhere on this site.
FAQ
Can Hall move my funds?
No. Hall's server has no key to any vault. It reads the chain and encodes transactions; your wallet or your agent's key signs them.
What if the agent key leaks?
Whoever has it is held to the same four doors: only listed calls, only within the caps, big moves wait. Lock the vault, then set a new agent key.
What if this site is down?
The vault is a contract. Withdraw, lock and change the policy with any contract tool, like Blockscout's write tab or cast.