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.
Autonomous agent-to-agent payments
One three.ws agent can pay another agent's paid endpoint without a human approving each payment. This is the developer reference for that path: how the authorization is issued, which gates every payment passes, what the payment leaves behind, and how to stop an agent that has gone wrong.
Source: issue a mandate
api/agents/a2a-mandate.js, pay a peerapi/agents/a2a-call.js, the shared spend policyapi/_lib/agent-trade-guards.js, the owner surfaces (limits, custody ledger) inapi/agents/solana-wallet.js, the economy statementapi/agents/[id]/economy.js. The whole chain is proven end to end byscripts/a2a-spend-hardening-proof.mjs.
Related: the agent wallet control API for the other owner-only wallet surfaces, financial controls for the platform-wide picture, and agent economy volume for what settled A2A payments add up to.
The shape of the problem
An Intent Mandate is a signed, offline-verifiable bearer credential: the
user's recorded consent that a named agent may spend up to a total budget, with
a per-call cap, on named networks, for up to 90 days. Issuing one is itself a
spend: a signed-in session may do it, but an API key or OAuth token needs the
wallet:write scope (assertBearerMaySpend), as it does on a2a-call. That is what makes
autonomy possible, and it is also why the mandate cannot be the whole safety
story. A bearer credential has no revocation of its own: whoever holds it can
spend its remaining budget until it expires.
So every autonomous payment also runs through the agent's own server-side spend policy, the same one the trade, snipe, x402 and withdraw paths already use. That policy is stored on the agent, read fresh on every payment, and editable at any moment by the owner. It is what makes an outstanding mandate stoppable.
The gates, in order
POST /api/agents/a2a-call refuses at the first gate that says no, and nothing
downstream of a refusal happens: no peer is contacted, no key is touched, no
token moves.
| # | Gate | What it decides | Refusal code |
|---|---|---|---|
| 1 | Mandate signature + ownership | Is this a real mandate, issued to this user, still unexpired? | invalid_mandate, mandate_expired, mandate_not_yours |
| 2 | Subject agent | Does the agent the mandate names still exist, and is it still this user's? | agent_not_found, agent_not_yours |
| 3 | Kill switch | Is the agent halted? Checked before the peer is even quoted | wallet_frozen |
| 4 | Mandate per-call policy | Is this amount, network, currency and resource inside what was authorized? | amount_over_per_call, currency_mismatch, network_not_allowed, resource_not_allowed |
| 5 | Peer reputation (opt-in) | Does the peer clear the caller's ERC-8004 trust bar? | reputation_too_low, reputation_too_few_reviews, reputation_unavailable |
| 6 | Mandate cumulative budget | Would lifetime spend under this mandate exceed its total cap? | budget_exceeded |
| 6b | Platform ceilings | Is this inside the limits the platform sets and no mandate can widen? Per call $25, per user per day $50, whole payer wallet per day $500 (overridable by A2A_PLATFORM_PER_CALL_ATOMICS, A2A_PLATFORM_USER_DAILY_ATOMICS, A2A_PLATFORM_DAILY_ATOMICS) |
platform_per_call_exceeded, platform_user_daily_exceeded, platform_daily_exceeded (all 403) |
| 7 | The agent's own spend policy | Per-transaction, rolling-daily and per-counterparty ceilings, the owner's plain-English rules, the anomaly guard, any scoped capability | per_tx_exceeded, daily_exceeded, counterparty_daily_exceeded, policy_blocked, policy_step_up, policy_freeze, wallet_anomaly_frozen, capability_required |
The payer key is platform-held and the mandate is self-issued, so gate 6b is the
last line of defence when the mandate is huge and the agent's own limits are
unset. The same platform caps apply when the mandate is issued: a total budget
above $100 (A2A_PLATFORM_MAX_MANDATE_ATOMICS) or a per-call allowance above
the per-call ceiling is refused with amount_exceeds_platform_cap. A payment
that fails after gate 6b releases both the mandate and the platform
reservations.
Gate 7 is atomic: it enforces the ceilings and writes the payment's pending receipt row in one statement under a per-agent advisory lock, so concurrent calls cannot all pass on the same stale daily total. If the payment then fails to settle, the row is released and stops counting toward the day.
The policy is resolved fail-closed
The guards take the policy as limits (already read), as meta (the agent's
blob), or as neither. With neither, they read the agent's real policy from its
row. There is no argument shape that silently yields an unrestricted wallet, and
a spend for an agent that no longer exists is refused with agent_not_found
rather than falling through to empty defaults. This matters because autonomous
callers are background code with an agent id and an amount, not request handlers
holding a freshly-loaded row.
The per-agent spend policy
Owner-only, on the agent's wallet:
GET /api/agents/:id/solana/limits
PUT /api/agents/:id/solana/limits (CSRF-gated for cookie callers)
| Field | Meaning | Default |
|---|---|---|
per_tx_usd |
Ceiling on any single payment | null (uncapped) |
daily_usd |
Rolling 24h ceiling on total outflow | null (uncapped) |
per_counterparty_daily_usd |
Rolling 24h ceiling per payee | null (uncapped) |
approval_threshold_usd |
Above this amount an autonomous x402 payment (/api/pay/execute) or agent hire (/api/agents/a2a-hire) is parked in the Approval Inbox and answers 202 with a poll link instead of executing; it resumes when the owner approves. The mandate path above does not park, it keeps its hard gates |
null (no threshold) |
withdraw_allowlist |
Read-only view of the active destination whitelist. Edit it there: new addresses serve a cooldown and need step-up | [] |
frozen |
The kill switch. Halts every autonomous path | false |
require_capabilities |
Autonomous spends must present a covering scoped capability | false |
per_counterparty_daily_usd exists because a wallet-wide daily cap bounds total
damage but not concentrated damage. A peer that reprices upward every call, or a
compromised endpoint the agent keeps paying, can drain the entire daily budget
into one address while every individual payment stays under per_tx_usd.
curl -X PUT https://three.ws/api/agents/$AGENT_ID/solana/limits \
-H 'content-type: application/json' -H "x-csrf-token: $CSRF" -b "$COOKIES" \
-d '{"per_tx_usd":5,"daily_usd":25,"per_counterparty_daily_usd":10}'
The response returns the normalized policy plus spent_today_usd, so a UI can
show remaining headroom without a second call.
Ceilings are metered per (agent, network), and every mainnet rail (Solana
mainnet and every EVM mainnet) folds into one mainnet budget on purpose: an
agent cannot double its real daily cap by alternating rails. Solana devnet keeps
its own budget.
The kill switch
curl -X PUT https://three.ws/api/agents/$AGENT_ID/solana/limits \
-H 'content-type: application/json' -H "x-csrf-token: $CSRF" -b "$COOKIES" \
-d '{"frozen":true}'
The very next spend attempt fails, with no lock wait and no reservation written. Precisely what it halts:
- Halted: every autonomous category. A2A payments, x402 payments, trades,
snipes, scheduled orders, armed intents, autopilot rules.
a2a-callrefuses at gate 3, before the peer is contacted, so a halted agent does not even leak that it is alive or keep the peer's meter running. - Still open: the owner's own withdraw. A freeze must never trap the owner's funds, so the safe direction (sweeping the balance out) stays available while the agent is locked down.
The anomaly guard (api/_lib/wallet-anomaly.js)
can set the same flag automatically when an outbound movement scores far enough
outside the wallet's learned normal. Unfreezing is the same call with
{"frozen": false}.
Receipts
Every agent-initiated payment writes one row to the agent's custody ledger: pending at reservation, confirmed with the settlement signature once the peer's task completes, released if it never settles. Nothing an agent pays for is invisible to its owner afterwards.
GET /api/agents/:id/solana/custody?category=x402&limit=50
Owner-only (a stranger gets 403). Each item carries usd, destination (the
counterparty), signature and explorer (the settlement transaction),
status, created_at, and a meta blob that for an A2A payment holds
kind: "a2a", the mandate id, the peer endpoint, the task id, the settlement
network, the atomic amount, the payer address, the signed AP2 cart mandate, and
the peer's own receipts. The response paginates with next_cursor.
The a2a-call response returns that row's id as receipt_id, alongside the
portable half of the receipt: cart_mandate, a signed proof of the exact
transaction that anyone can verify with
POST /api/agents/a2a-cart-verify.
For a rolled-up view, GET /api/agents/:id/economy returns the same payments as
a statement: spending.x402 windowed in USD, and receipts[] entries with
direction: "out", kind: "x402", the counterparty, the resource, and the
signature, interleaved with the agent's inbound earnings.
End to end
# 1. The human authorizes a class of spend: $10 total, $0.50 per call, 24h.
curl -X POST https://three.ws/api/agents/a2a-mandate \
-H 'content-type: application/json' -b "$COOKIES" \
-d '{"subjectAgentId":"'$AGENT_ID'","maxAtomics":"10000000","perCallAtomics":"500000","ttlSec":86400}'
# → 201 { "mandate": "<JWS>", "details": { … } }
# 2. The agent pays a peer, no human in the loop.
curl -X POST https://three.ws/api/agents/a2a-call \
-H 'content-type: application/json' -b "$COOKIES" \
-d '{"mandate":"<JWS>","endpoint":"https://peer.example/a2a","text":"Summarize this market."}'
# → 200 { "ok": true, "receipt_id": "8421", "usd": 0.25, "payer": "…",
# "cart_mandate": "<JWS>", "artifacts": [ … ] }
# 3. The owner reads the receipt back.
curl -s "https://three.ws/api/agents/$AGENT_ID/solana/custody?category=x402&limit=5" -b "$COOKIES"
Amounts are USDC atomics (six decimals), so 500000 is $0.50. USDC is the only
currency the A2A rails settle in; any other asset is recorded unpriced rather
than guessed, and the unpriceable spend is governed by the allowlist and the
mandate rather than by a USD ceiling the guard cannot compute.
Proving it still holds
Two layers, both runnable:
npx vitest run tests/a2a-payment-hardening.test.js # deterministic, mocked DB
npm run prove:a2a-spend # real Postgres + live HTTP
npm run prove:a2a-spend starts a throwaway Postgres container, applies the real
schema, drives the real guard module and the real server, and asserts that each
ceiling blocks its over-limit attempt, that eight concurrent reserves for the
last dollar of headroom produce exactly one winner, that the kill switch halts
every autonomous category while the owner's withdraw stays open, and that the
receipts come back from the live owner surfaces. No funds move: every spend stops
at the reservation layer, which is the same layer that runs before any key is
touched in production. It needs docker and ports 5817, 5818 and 3817.
Runnable example
agent-payments-sdk/ The @three-ws/agent-payments package: agent-to-agent payments over x402 and a2a, with its quickstart in the README.
It is part of the curated set npm run export:satellites publishes as the public
three.ws examples repo, so it is installed, run, and link-checked before every release.