# Tillwarden

> Pocket money for AI agents. Rules it can't break. Tillwarden gives an AI agent its own spending account on Robinhood Chain (chain id 4663): the money stays in the owner's Safe, the owner sets rules on chain, a firewall checks and simulates every payment before it is signed, and every payment in or out gets a signed, hash-chained receipt.

Not audited. Use small amounts. All times are UTC.

## How it works
- Account: a Safe 1.4.1 (L2) with the Tillwarden module enabled. Open one through the factory, or attach the module to an existing Safe.
- Rules per token: enabled, max per payment, daily budget, weekly budget (fee included), "ask above" amount. Account-wide: payee list (on/off), contract-call list of (contract, function selector) pairs, allowed UTC hours, per-minute limit.
- Agent key: signs EIP-712 Pay/Call intents (domain "Tillwarden", version "1"). It cannot change rules or move money outside them.
- Firewall: eight checks (hidden instructions, account rules, hours, allowlist, balance and drain, approvals in calldata, contract check, simulation). Verdict: allow, needs_approval or block.
- Approvals: payments above the "ask above" amount are parked on chain until an owner approves or rejects.
- Watchdog: freezes an account on spikes (a payment > 5x the usual, > 3x the usual hourly rate, a burst to new payees). Only owners unfreeze.
- Fee: 0.1% on agent ETH/USDG payments, paid to the TillJar contract. Anyone calls poke() (reference price), then buyAndBurn() 1-30 min later: it buys $TILL and burns it. Incoming payments pay no fee.

## For agents and developers
- npm package `tillwarden`: SDK (`new Tillwarden({ baseUrl, apiKey, agentKey })` → check, pay, me, receipts, verifyReceipt), CLI (`npx tillwarden check|pay|me|receipts|verify|examples|keygen`), MCP server (`tillwarden-mcp`, tools: tillwarden_pay, tillwarden_check, tillwarden_balance, tillwarden_rules, tillwarden_receipts).
- Env: TILLWARDEN_URL, TILLWARDEN_API_KEY (issued by the owner in /app), TILLWARDEN_AGENT_KEY (signs locally, never sent).
- Always pass `context` (the text that made the agent decide to pay) so the firewall can scan it. Do not retry a blocked payment with changed wording.

## HTTP API (base https://tillwarden.fun/api)
- POST /api/firewall/check {to, amount, token?, memo?, context?, data?, safe?} — no key needed, rate limited
- GET /api/firewall/examples, /api/config, /api/health, /api/network
- GET /api/accounts/:safe, /receipts, /receipts.csv, /pending, /stats, /alerts
- POST /api/agent/pay, POST /api/agent/submit, GET /api/agent/me, GET /api/agent/receipts (Authorization: Bearer <agent API key>)
- GET /api/receipts/:id/verify, GET /api/pay/:safe/intent?amount&token, GET /pay.js

## Pages
- https://tillwarden.fun/ — overview and firewall playground
- https://tillwarden.fun/firewall/ — the firewall and its checks
- https://tillwarden.fun/pay/ — pay button generator
- https://tillwarden.fun/token/ — $TILL, fees and the TillJar (no promise of returns)
- https://tillwarden.fun/docs/ — docs, API, limits
- https://tillwarden.fun/developers/ — SDK, CLI, MCP
- https://tillwarden.fun/own-risk/ — what is not audited
- https://x.com/tillwardenfun