Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Approvals: the inbox for actions your agents pause to ask about
Some actions are yours to decide. When you set an agent's spend policy to
Ask me (the Policy tab at /agent/<id>/wallet), the agent no longer moves
funds on its own for that rule: it writes an approval request, tells you
on every channel you have connected, and waits. You answer from a push
notification's Approve or Deny button, from the email, or from the inbox at
/approvals. Approving runs exactly the action you
were shown, once. Denying, ignoring it, or letting it expire runs nothing.
| Piece | Where | Source |
|---|---|---|
| Inbox page | /approvals, deep links /approvals/<id>?t=<token> |
pages/approvals.html, src/approvals-page.js |
| Library (lifecycle, hashing, links, policies) | server | api/_lib/approvals.js |
| Inbox API | GET/POST /api/approvals, GET/POST /api/approvals/:id, GET/POST/DELETE /api/approvals/policies |
api/approvals/ |
| Wallet intent wiring | where a gated transfer or swap becomes a request, and where an approved one executes | api/_lib/wallet-intents.js, api/_lib/agent-trade-guards.js |
| Push Approve/Deny buttons | the browser service worker | public/push-sw.js |
| Schema | approval_requests, approval_auto_policies |
api/_lib/migrations/20261010120000_approval_requests.sql |
| Tests | tamper, expiry, idempotency, policy matching | tests/approvals.test.js |
What triggers a request
A spend rule set to Ask me makes the spend-limit check raise
policy_step_up instead of letting the action through. The wallet intent
engine catches that and calls createApprovalRequest() with the exact action
it was about to take. Approving lifts only that step-up rule. Your numeric
caps, block rules, and any wallet freeze still apply when the approved action
runs, so an approval can never push an action past a limit you set elsewhere.
Each request stores:
- the payload: the exact action the executor will run, nothing more;
- a confirmation table built from it: action, amount, asset and chain, recipient (with a label when the address is known), the USD value when it can be priced, the venue, and the expiry;
- risk notes, such as "first transfer to this address";
- the gate reason: which rule asked you;
- an idempotency key (and a
source_ref), so an agent retrying the same action never stacks duplicate requests.
Lifecycle
pending ──approve──> approved ──> executing ──> executed
│ └────> failed
├──deny──────────> denied
└──deadline──────> expired
- pending: waiting on you. A swap waits 15 minutes, because prices move; a transfer of a fixed amount waits 6 hours.
- approved / executing: claimed by your decision. The move from
approvedtoexecutingis a conditional update, so even two decisions arriving at the same instant (push on your phone, click on your laptop) run the action once. The second caller gets the request's current state back withidempotent: true. - executed: done, with the transaction signature and an explorer link.
- failed: the executor ran and refused or errored (for example, a cap you set later now blocks it). A failed request is never retried automatically; the agent asks again if the action is still wanted.
- denied / expired: terminal, nothing ran. Expiry is lazy: a request
past its deadline is written as
expiredthe next time anything reads or decides it, so no cron is involved, and an expired request can never be approved.
Why approving is safe
The payload hash. Every request carries the SHA-256 of its payload in
canonical JSON (keys sorted). The inbox shows the action and sends that hash
back with your approval. If the stored action differs from the one you were
shown, the approval answers 409 payload_mismatch and nothing runs. The
executor re-hashes the stored payload once more right before it runs, so an
edit to the row after approval also fails closed.
Signed deep links. Every delivery carries a link of the form
/approvals/<id>?t=a1.<claims>.<hmac>. The claims bind the request id, its
owner, its payload hash, and its expiry, signed with the server secret. The
page shows "This link matches the request on file" when it verifies, or says
why it does not (payload_changed, wrong_request, bad_signature,
malformed). A decision made through a link that does not match is refused
with 409 link_mismatch.
Your session, not a key. Reading the inbox works with a session or a read-only bearer. Deciding needs a signed-in browser session plus a CSRF token. A machine credential, which an agent could hold, can never approve its own request. A paired chat is the one other place a decision can come from, and only from the person the chat is paired to (below).
Delivery
A new request goes out through the same fan-out as every notification, in the Approvals category (on by default for every channel):
| Channel | What you get |
|---|---|
| Bell and /notifications | A row that opens the request's deep link. |
| Web push | A notification with Approve and Deny buttons. Each request has its own tag, so two pending approvals never replace each other. The Approve button sends the request's payload hash, so it executes exactly what the notification described. |
| iOS app | An APNs alert that opens the deep link. |
| Telegram and Discord | A message in every paired chat with the full confirmation table, the risk notes, the payload fingerprint, the deadline, the deep link, and signed Approve and Deny buttons. See Approving from Telegram and Discord. |
The fallback. Sent only when no push device or chat received the request, and only if email is on for Approvals in /dashboard/settings. It carries the full confirmation table, the risk notes, and the deep link. |
Turn browser push on from the Turn on push button in the inbox header.
Change channels from Delivery settings, which opens /dashboard/settings.
The inbox
/approvals has:
- Status tabs: Pending, Done, Denied, Expired, All, each with a live count.
- An agent filter listing only the agents that have asked you something.
- Cards with the confirmation table, copy buttons for the recipient and amounts, risk notes, and a countdown to the deadline. Approve is two steps (click, then Confirm approve; Escape cancels) so a stray click never moves money.
- Bulk deny: select pending requests, or select all, and deny them in one action.
- Auto-approve rules (below).
- An activity log of every request, approval, denial, execution, failure, and rule change, read from the account audit log.
Opening a deep link pins that request on top of the list with its payload fingerprint and the link check result.
Approving from Telegram and Discord
Pair a chat once from /settings/connections (or send /start to the bot),
and every new request lands there as a message like this one (a real render,
from the gateway test suite). When the recipient is shown shortened, a
Full address: line follows with the whole address.
Approval needed from Treasury Bot
Send 0.5 SOL to the treasury wallet
Recipient: THREEsynthetic11111111111111111111111111111
Amount: 0.5 SOL (~$75.00)
Asset: SOL
Chain: Solana devnet
Venue: Transfers to addresses this wallet has paid before
Held because: Above your per-transfer approval threshold
Risk notes:
- First transfer to this address
Payload hash: 60c9369d86304139...
Expires in 15 min. Nothing runs unless you press Approve.
Review on the web: https://three.ws/approvals/<id>?t=...
[ Approve ] [ Deny ]
Pressing a button decides the request through the same path as the inbox, so everything in Why approving is safe still holds, and the message is edited in place to the outcome ("Approved and executed." with the signature, "Denied. Nothing was sent.", "Expired before a decision", or why it did not execute). The buttons are removed once a request is decided.
What makes a button safe to press. Each button's callback data
(ar1<verb><id><expiry><mac>, at most 64 bytes, the Telegram limit) carries
an HMAC under the server secret over the platform, the verb, the request id,
the paired link, the presser's platform account, the request's payload hash,
and its deadline. A press is refused, and nothing runs, when:
| Case | What the owner sees |
|---|---|
| The request's payload or hash changed after the message was sent | "This button does not match the request on file, so nothing ran." The request stays pending for review on the web. |
| The stored payload was edited under an unchanged hash | The executor's re-hash fails, the request is marked failed with integrity: false, and the message says it did not execute. |
| The button was altered, or pasted into another chat of the same account | "does not match", nothing ran. |
| Someone other than the paired owner presses it (a group chat) | "Only the account owner paired to this chat can approve or deny." |
| The chat is not paired | "This chat is not paired to a three.ws account, so these buttons do nothing here." |
| The deadline passed | "Expired before a decision. Nothing was sent." |
| The button is pressed again after a decision | The outcome is redrawn ("Already executed."); the action never runs twice. |
A chat decision is recorded with decided_via set to telegram or
discord, and shows in the activity log like any other.
Chat commands
| Command | What it does |
|---|---|
/approvals |
Sends every pending request (up to five, soonest deadline first), each with its own signed buttons. |
/agents |
Lists your agents; /use <number or name> picks the one this chat talks to. |
/positions [agent] |
Open Solana positions for the chat's agent (or the named one): entry, live value, and P&L. |
/pause [agent] |
Freezes one agent: outbound spending frozen (withdrawals still work), discretionary trading off, its sniper off. |
/kill |
Does the same for every agent on the account, engages the account-wide strategy kill switch, and denies every pending request. |
Anything that is not a command is a message to the chat's agent. Chat
control only moves in the safe direction: a chat can stop agents and deny
requests, but lifting a freeze is done on the web (the agent's wallet,
Withdraw, then Limits & Safety), so a lost or hijacked chat account can
halt your agents and never unfreeze them. Every /pause and /kill is
written to the audit log as gateway.pause_agent or gateway.kill_all.
What a chat ignores
- Unpaired chats. A command from a chat that is not paired gets only the pairing prompt. Nothing reaches an agent or a wallet.
- Other people in a paired group. They are told the chat belongs to someone else, and their buttons are refused.
- Forwarded messages. Anything forwarded (from a person, a channel, or
posted through another bot) is someone else's words, so it is never run as a
command or passed to the agent, even when it reads as
/killor "send my SOL to ...". The owner is told it was ignored; an unpaired chat gets no reply, and a forwarded/linkpairs nothing.
Telegram delivery runs on the agent-gateway worker.
Auto-approve rules
The default is that every gated action asks you. An auto-approve rule is an explicit exception you create:
- venues: which kinds of action it covers.
jupiter(token swaps) andwallet_transfer(transfers). A rule for swaps never covers transfers. Payout wallet changes are also gated by an approval but can never be auto-approved: the request shows the old and new address, and the new wallet takes effect 24 hours after approval. - max_usd: the largest single action it covers, capped at $1,000 per action. Anything larger always asks.
- agent_id (optional): limit it to one agent. team_id (optional): limit it to one team.
- expires_at (optional): the inbox offers 1 day, 7 days, 30 days, or no expiry.
Three kinds of request are never auto-approved, whatever rules exist: a
transfer to an address this wallet has never paid before, an action whose
USD value cannot be priced, and anything outside the rule's venues or size.
When several rules match, the one with the smallest cap wins. An
auto-approved request is recorded as approved via auto_policy with the
rule id, and shows up in the inbox and the activity log like any other.
Revoking a rule stops it immediately; the row stays for the audit trail.
API
All endpoints answer { error, error_description } on failure. Reads accept
a session or bearer; writes need a session plus x-csrf-token.
GET /api/approvals?status=pending|done|denied|expired|all&agent=<uuid>&limit=&cursor=
POST /api/approvals { action: "bulk_deny", ids: [uuid, ...] }
GET /api/approvals/:id?t=<link token>
POST /api/approvals/:id { decision: "approve"|"deny", payload_hash, token?, via? }
GET /api/approvals/policies
POST /api/approvals/policies { venues, max_usd, agent_id?, team_id?, expires_at?, label? }
DELETE /api/approvals/policies?id=<uuid>
GET /api/approvals returns { items, counts, agents, next_cursor }.
POST /api/approvals/:id returns { request, idempotent }. Errors worth
handling:
| Status | Code | Meaning |
|---|---|---|
| 400 | payload_hash_required |
Approve was sent without the hash of the action shown. |
| 404 | not_found |
No such request on your account. |
| 409 | payload_mismatch |
The stored action differs from the one you approved. Nothing ran. |
| 409 | link_mismatch |
The deep link does not match the request on file. Nothing ran. |
| 409 | already_denied / already_decided |
The request is already terminal. |
| 410 | expired |
The deadline passed. Nothing ran. |
Example: approve the request you just read.
const { request } = await fetch(`/api/approvals/${id}`, { credentials: 'include' }).then((r) => r.json());
const csrf = await fetch('/api/csrf-token', { credentials: 'include' }).then((r) => r.json());
const res = await fetch(`/api/approvals/${id}`, {
method: 'POST',
credentials: 'include',
headers: { 'content-type': 'application/json', 'x-csrf-token': csrf.token },
body: JSON.stringify({ decision: 'approve', payload_hash: request.payload_hash }),
});
The capped burner
An owner can tell an agent how much it may spend on its own and what must come
back to them. The policy lives on the agent (meta.burner_policy) and is edited
in the agent wallet hub's Burner cap tab, or with
PUT /api/agents/:id/solana/limits and a burner_policy object:
| Field | Meaning |
|---|---|
autoMaxUsd |
Largest single spend the agent signs alone. Empty turns the cap off. |
dailyAutoMaxUsd |
Rolling 24h ceiling on what it signs alone. Once reached, later spends wait for you. |
confirmAboveUsd |
Above this a tap is not enough: you sign the approval with a Solana wallet linked to your account. |
expiryMinutes |
How long a confirmation request stays answerable (2 to 60, default 10). |
Above the cap nothing fails. The spend becomes a pending approval carrying the recipient, amount, token and chain, delivered on every linked channel and the web inbox. The classifier (api/_lib/burner-tier.js) is pure and shared: the server guard and the tab's live preview ("a $X spend would be: auto / needs your confirmation / needs your wallet signature") run the same code. An unpriced spend always asks.
Above confirmAboveUsd the approvals page asks your wallet to sign the request
text (three.ws approval, request id, recipient, amount, chain, payload hash).
The server verifies the ed25519 signature against your linked wallets
(api/_lib/owner-sign.js); a signature for another
request, an unlinked wallet or a missing one runs nothing. The requirement is
stored in the hashed payload, so it cannot be edited out of the row. An expired
request cannot execute, even with a valid signature.
Every burner-gated request, approval (with the signing wallet), denial and expiry
is appended to the agent's tamper-evident decision trail as a burner_gate
decision. Tests: tests/burner-tier.test.js,
tests/burner-approvals.test.js.
Adding a new kind of request
A source registers an executor in the EXECUTORS map in
api/_lib/approvals.js. The contract:
executor(row) receives the stored row, executes only row.payload, and
returns { status: 'ok'|'error'|'paused'|'skipped', signature?, note?, usd? }.
Registered sources include wallet_intent (agent transfers and swaps from
wallet intents), mail_rule (an agent mail rule in
approve mode: approving starts a read-only, zero-budget run on the email that
matched, and its table names the agent, the email and the instruction with
Spend: None), payment_session_execute (an agent payment session call
priced above its approval_threshold_usd: api/pay/execute.js
parks the call instead of failing it, and the caller polls the same endpoint
with GET until it resumes), and a2a_hire (an agent-to-agent hire priced
above the hiring agent's approval_threshold_usd: api/agents/a2a-hire.js
parks the hire and the caller's retry with the same idempotency key re-polls
it). Then call createApprovalRequest() where the source hits
its step-up gate, with an idempotency key derived from the action. Engines
that execute inline (an auto-approved request) call runApproved(row, run),
which provides the same once-only and integrity guarantees.
Related: Notifications for the delivery fan-out and the preference matrix, STRUCTURE.md for where everything lives.