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.
title: "Give your AI agent a budget, not a private key" venue: AWS Builder Center account: three.ws (official) status: draft description: "An autonomous agent that pays for tools needs spending power, and every shortcut for granting it ends with a private key inside a prompt-injectable loop. Here is the pattern we shipped instead: a Payment Session that separates custody from authority from execution, enforced atomically in Postgres, with the real code, the race condition, and the failure mode nobody writes about." tags: [agentic-ai, ai-agents, security, serverless, api] index: docs/aws-builder-center.md
Give your AI agent a budget, not a private key
There is a moment in every agentic build where the agent needs to buy something.
Maybe it is a paid data feed mid-reasoning. Maybe it is another agent's tool. Maybe it is a rendering job it decided to queue. Whatever it is, the agent has hit a 402 Payment Required and the loop stops, because the one thing your agent does not have is spending power.
So you give it some. And this is where most designs quietly go wrong.
The obvious move is to put a wallet key in the agent's environment. It works immediately, which is the problem: you have now placed an unbounded bearer credential inside a system whose entire job is to read untrusted text and decide what to do next. Prompt injection is not a hypothetical against that design. It is the design's specification.
This is a walk through the pattern we shipped instead, in production, at three.ws. It is called a Payment Session, and the one-line version is:
The agent does not hold a wallet. It proposes spend. Governance enforces policy.
Everything below is real code from our open source (Apache-2.0) repository, including the concurrency bug we had to design around and the failure mode that has no clean answer.
The three bad options, and what each one actually costs
Before the pattern, the alternatives, because the pattern only looks good next to them.
| Approach | What the agent holds | What a compromise costs you | Why teams pick it |
|---|---|---|---|
| Hand the agent a wallet key | Full signing authority, forever | Everything in the wallet, plus everything the key can authorize later | It takes four minutes |
| Give the agent a funded burner wallet | Full authority over a smaller pot | The burner's balance, plus a refill treadmill and dust stranded across dozens of addresses | It feels bounded |
| Human-in-the-loop on every payment | Nothing | Nothing, but the agent is no longer autonomous | It is defensible in a review |
The burner wallet is the interesting failure, because it looks like the right answer. It is bounded, so a compromise is capped. But you have replaced a security problem with an operations problem: every agent now needs funding, refunding, and sweeping, and capital disperses one way into wallets that never send it back. We ran a fleet like this. The dispersion, not the theft, is what hurt.
What all three share is a category error. They conflate three separate concerns that only look like one:
- Custody: who holds the key that signs.
- Authority: who decides how much may be spent, on what, and until when.
- Execution: who initiates a given payment.
A private key fuses all three into one secret. Split them apart and the design gets much better very quickly.
The pattern
Developer Platform Agent
───────── ──────── ─────
funds a budget ──────> holds the keys <────── proposes a payment
sets the policy ──────> enforces the policy ──────> gets the result
signs the tx
logs everything
The developer creates a session: a budget envelope with a total, a per-transaction ceiling, a host allowlist and denylist, an optional approval threshold, an optional rolling daily cap per rail, a network, and an expiry. In return they get a bearer token, once.
They hand that token to the agent. The agent can now call paid endpoints. It cannot exceed the budget, cannot pay a host outside the allowlist (or on the denylist), cannot spend after the expiry, cannot push a single payment over the approval threshold without the owner saying yes, and cannot sign anything itself, because the platform's wallet does the signing and the agent never sees a key.
Custody sits with the platform. Authority sits with the developer. Execution sits with the agent. Compromising the agent gets an attacker exactly one thing: the remaining budget, spendable only at hosts you already approved, only until the session expires.
That is not zero. It is a number you chose in advance, which is the entire point.
The data model
Two core tables (plus a small reservation table that backs the rolling per-rail cap). The session is the policy plus the counter, and the execution log is the immutable audit trail. The CREATE TABLE below is abridged to the policy columns.
create table if not exists payment_sessions (
id uuid primary key default gen_random_uuid(),
user_id uuid not null references users(id) on delete cascade,
agent_id uuid references agent_identities(id) on delete set null,
label text not null default '',
budget_usdc bigint not null check (budget_usdc > 0),
spent_usdc bigint not null default 0 check (spent_usdc >= 0),
max_per_tx_usdc bigint check (max_per_tx_usdc > 0),
allowed_hosts text[] not null default '{}',
blocked_hosts text[] not null default '{}',
approval_threshold_usdc bigint check (approval_threshold_usdc > 0),
per_rail_daily_usdc jsonb not null default '{}'::jsonb,
network text not null default 'solana' check (network in ('solana', 'base')),
connector_ref text,
status text not null default 'active'
check (status in ('active', 'exhausted', 'expired', 'cancelled')),
expires_at timestamptz not null,
token_hash text not null,
session_metadata jsonb not null default '{}'::jsonb,
created_at timestamptz not null default now(),
updated_at timestamptz not null default now()
);
Three details in there are load-bearing.
Money is bigint, never float. USDC has six decimals, so every amount is stored in atomic units and converted at the edges. A rounding error in a budget check is a security bug, not a display bug.
// USDC has 6 decimals everywhere we settle (Solana mainnet and Base mainnet).
export const USDC_DECIMALS = 6;
const USDC_SCALE = 10 ** USDC_DECIMALS;
export function usdToAtomics(usd) {
return BigInt(Math.round(Number(usd) * USDC_SCALE));
}
export function atomicsToUsd(atomics) {
return Number(atomics) / USDC_SCALE;
}
spent_usdc lives on the session row, not derived from the log. It is tempting to compute spend with SELECT sum(amount) FROM executions. Do not. That number has to be checked and incremented in the same atomic operation as the authorization decision, and a sum over a second table cannot give you that without a lock you will regret. The log reconciles the counter; it does not replace it.
The token is never stored. Only its HMAC is:
const TOKEN_PREFIX = 'pss_';
export function generateSessionToken(sessionId) {
const rand = randomBytes(16).toString('hex');
return `${TOKEN_PREFIX}${sessionId}_${rand}`;
}
export function hashToken(token) {
return createHmac('sha256', hmacKey()).update(String(token)).digest('hex');
}
The session id is embedded in the token so lookup is a primary-key hit rather than a table scan over hashes, and verification is WHERE id = $1 AND token_hash = $2. A dumped database row is inert without the HMAC key; a leaked token is bounded by the policy on the row it points at.
The request path
The agent makes one call: POST /api/pay/execute with a session token and a URL. Six phases run behind it.
Phase 0: verify the token before touching the network
try {
await verifySessionToken(sessionToken);
} catch (err) {
if (err instanceof SpendGovernorError) {
return error(res, err.status, err.code, err.message, err.detail);
}
throw err;
}
Cheap check first. There is no reason to make an outbound request on behalf of a token that does not exist.
Phase 1: probe for the payment challenge
x402 works over ordinary HTTP. You request the resource, and a paid endpoint answers 402 with a JSON body describing what it will accept: network, asset, amount, and where to send it. So we ask before we authorize, because until the endpoint tells us the price, there is no amount to check the policy against.
let accept = challenge.accepts.find(
(a) => typeof a?.network === 'string' &&
a.network.startsWith('solana') &&
a.asset === USDC_SOLANA_MINT,
);
If the endpoint answers with something other than a 402, it was free, and we return the response without ever touching the session:
if (probeResult.free) {
return json(res, 200, {
ok: true,
paid: false,
note: 'Endpoint served response without a 402. No payment needed.',
status: probeResult.status,
result: probeResult.result,
});
}
Small thing, easy to skip, and it matters: an agent should not burn budget discovering that something was free.
Phase 2: the governor
Now the policy runs, in order, cheapest and most decisive first: status, then expiry, then the allowlist, then the denylist (an explicit block always beats a broad allow), then the per-transaction ceiling, then the rolling per-rail daily cap, then the budget, and last the approval threshold. A call over the threshold is not rejected: it is parked in the owner's approval inbox and the agent gets a 202 with a poll link, then the exact same reserve-and-settle path resumes if the owner approves.
The allowlist check is the one worth showing, because the subdomain rule is where these go wrong:
export function canonicalizeAllowlist(allowedHosts) {
if (!Array.isArray(allowedHosts)) return [];
return allowedHosts.map(normalizeHost).filter(Boolean);
}
export function hostMatches(targetHost, entry) {
if (!targetHost || !entry) return false;
return targetHost === entry || targetHost.endsWith(`.${entry}`);
}
The verdict is then canonical.some((entry) => hostMatches(targetHost, entry)).
targetHost.endsWith('.' + entry) and not targetHost.endsWith(entry). Without the dot, an allowlist entry of example.com also authorizes evil-example.com, and an attacker who can steer your agent to a URL just needs to register the right domain. That is exactly why this is a named function with a test behind it rather than an inline endsWith. Hosts are normalized through the URL parser first, so HTTPS://Example.COM:443/x and example.com compare equal.
These predicates live in api/_lib/pay/policy.js and are chained by one evaluateCall() that the dry-run simulator calls too, so a simulated verdict and an enforced one can never disagree. Every verdict, allow or deny, also carries a policy digest and an HMAC signature (keyed by PAY_VERDICT_HMAC_KEY, separate from the token secret) stored with its execution row, so a verdict cannot be edited after the fact without breaking the signature.
Phase 3: the atomic reservation
Here is the concurrency bug, and it is not a theoretical one. Agents are concurrent by nature. A single agent run can have three tool calls in flight, and a multi-agent orchestrator can have thirty.
Read-then-write does not work:
Session budget: $1.00 remaining
Request A: SELECT remaining -> $1.00. Enough for $0.80? Yes.
Request B: SELECT remaining -> $1.00. Enough for $0.80? Yes.
Request A: UPDATE spent = spent + 0.80
Request B: UPDATE spent = spent + 0.80
Spent: $1.60 against a $1.00 budget.
The fix is to make the check and the increment the same statement, and let the database resolve the race:
const [updated] = await sql`
UPDATE payment_sessions
SET spent_usdc = spent_usdc + ${amount.toString()},
updated_at = now()
WHERE id = ${session.id}
AND status = 'active'
AND (budget_usdc - spent_usdc) >= ${amount.toString()}
RETURNING id, spent_usdc, budget_usdc
`;
Row-level locking means the second UPDATE re-evaluates its WHERE clause against the first one's committed result. It matches zero rows, updated is undefined, and the caller gets a precise error rather than an overdraft:
if (!updated) {
// Could be exhausted mid-race; check to give a precise error
const [fresh] = await sql`
SELECT budget_usdc, spent_usdc FROM payment_sessions WHERE id = ${session.id}
`;
const remaining = fresh ? BigInt(fresh.budget_usdc) - BigInt(fresh.spent_usdc) : 0n;
// The SQL predicate already decided; budgetVerdict only phrases the failure,
// using the same wording the simulator shows for a predicted shortfall.
throwSigned(
budgetVerdict(amount, remaining) ?? {
code: 'insufficient_budget',
message: 'Session was not active when the payment was reserved',
detail: { need_usd: atomicsToUsd(amount), remaining_usd: atomicsToUsd(remaining) },
},
{ policyDigest, requestHash, timestamp },
);
}
throwSigned raises a SpendGovernorError carrying the machine-readable code the API layer maps to a status (insufficient_budget becomes a 402) plus the signed verdict. When a per-rail daily cap is set, a rolling-window reservation is taken first in its own advisory-locked statement and released if this UPDATE then loses the race.
No advisory locks, no transaction retry loop, no distributed lock service. One statement whose WHERE clause is the invariant. If you take one thing from this article, take this: write the budget check as a predicate in the UPDATE, not as a SELECT before it.
Note that this is a reservation, taken before the payment is attempted. Optimistic ordering, because the alternative is holding budget open across a network call to a third party.
Phase 4: sign and present
The platform payer signs a Solana USDC transfer, serializes it, and presents it in the X-PAYMENT header on a retry of the original request. The agent's token never enters this path, and the keypair never leaves the server.
const xPayment = Buffer.from(JSON.stringify(paymentPayload)).toString('base64');
paid = await guardedFetch(targetUrl, {
method,
body: requestBody,
headers: { 'X-PAYMENT': xPayment },
});
guardedFetch is not fetch. More on that below.
Phase 5: settle, or fail honestly
This is the section most write-ups skip, and it is the one that decides whether you can run this in production.
A payment has three possible outcomes, not two, and the third is the interesting one.
Rejected after signing. The service answers 402 again. It is tempting to read that as "no funds moved" and release the reservation. We used to, and it was wrong: the signed transfer was already handed to the host, and a host that is also the fee payer can co-sign and broadcast it, then answer 402. So the reservation stays spent and the failed execution is recorded:
if (paid.status === 402) {
// The signed transfer was already handed to the host. A host that is also
// the fee payer can co-sign and broadcast it, then answer 402, so a 402
// is not proof nothing landed: the reservation stays spent.
// ... record the failed execution ...
return { ok: false, status: 402, code: 'payment_rejected',
message: 'Service answered 402 after the signed payment was submitted. The budget stays reserved because the transfer may still land.' };
}
The release path (rollbackReservation, which also frees the rail-daily reservation) is reserved for failures that happen before anything is signed.
Settled. Log the tx hash, return the result, done.
Unknown. The request was submitted and the connection died before an answer came back. The transaction may have landed on-chain. It may not have. We cannot know from here.
} catch (err) {
// Network failure AFTER signing: chain state unknown, do NOT roll back.
await recordExecution({
/* ... */
status: 'failed',
errorCode: 'settle_uncertain',
errorMessage: err?.message,
}).catch(() => {});
return error(res, 502, 'settle_uncertain',
'Payment was submitted but confirmation was not received. Do not retry immediately.');
}
The comment carries the whole decision: do not roll back. Restoring the budget after a payment that may have settled means the next call can spend money that is already gone. So the session stays debited, the execution is logged as settle_uncertain, and the error message tells the caller not to retry blindly.
This is worse for the user than an automatic refund and better than a silent double-spend. When you cannot know the truth, bias the accounting toward the conservative answer and make the uncertainty legible instead of hiding it. Every payment system reaches this fork. Most of them pretend they do not.
Idempotency is the companion control. Every execution can carry a caller-supplied key with a unique constraint behind it, so a retried run cannot bill twice:
idempotency_key text unique,
The target URL is attacker-influenced. Treat it that way.
Step back and look at what this endpoint does: it takes a URL chosen (at least partly) by an LLM and makes a server-side request to it, from inside your infrastructure. That is a server-side request forgery primitive with a payment attached.
So the fetch is guarded, and the guard runs before the payment is signed:
async function guardedFetch(rawUrl, { method = 'GET', headers = {}, body } = {}) {
const url = validatePublicUrl(rawUrl);
const addrs = await resolvePublicHost(url.hostname);
const agent = pinnedAgent(url.hostname, addrs);
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
try {
const res = await fetch(url, {
method,
redirect: 'manual',
signal: controller.signal,
dispatcher: agent,
/* ... */
});
Four controls, each closing a specific hole:
validatePublicUrlrejects non-public schemes and address ranges: link-local, loopback, private space, and the cloud metadata endpoint at169.254.169.254that turns SSRF into credential theft on every major cloud.resolvePublicHostresolves DNS and validates the answers, so a hostname that resolves into private space is caught.pinnedAgentpins the connection to the addresses that were validated. Without this you have a DNS rebinding window between the check and the connect.redirect: 'manual'stops a public URL from bouncing you to an internal one after validation has already passed.
The allowlist is policy. This is the floor underneath it, and it applies even when a session sets no allowlist at all.
Wiring it into an agent
The interface is an MCP server, so any client that speaks the Model Context Protocol gets these as ordinary tools. Nothing here is specific to a particular agent framework: it is an npm bridge to an HTTP API, so it drops into a Bedrock AgentCore agent, a Strands agent, a Claude Code session, or your own loop, without caring where the agent runs.
{
"mcpServers": {
"three-ws-payments": {
"command": "npx",
"args": ["-y", "@three-ws/agentcore-payments-mcp"],
"env": {
"THREE_WS_SESSION": "__Host-sid=...",
"PAYMENT_SESSION_TOKEN": "pss_..."
}
}
}
}
Create a session with the policy you are willing to live with:
{
"budget_usd": 10.00,
"label": "Research agent, June sprint",
"expiry_seconds": 86400,
"max_per_tx_usd": 0.50,
"allowed_hosts": ["api.example.com", "data.provider.io"],
"approval_threshold_usd": 0.25,
"network": "solana"
}
Then the agent pays:
{
"url": "https://api.example.com/data",
"method": "GET",
"session_token": "pss_...",
"idempotency_key": "run-42-fetch-data"
}
It gets back the result it wanted plus the receipt it did not ask for: amount, network, payer, payee, transaction hash, explorer link, and the updated budget. The audit trail is a side effect of the design rather than an integration you have to remember to add.
{
"ok": true,
"paid": true,
"result": { "...": "the endpoint's response" },
"payment": {
"amount_usd": 0.05,
"network": "solana",
"tx_hash": "...",
"explorer": "https://solscan.io/tx/...",
"pay_to": "..."
},
"session": { "spent_usd": 1.35, "remaining_usd": 8.65 }
}
Budgets that expire have to give the money back
A budget is debited from the developer's credit balance the moment the session is created, which means an expiry that just marks a row expired quietly keeps their money. A sweep runs every five minutes and refunds the difference:
const expiredRows = await sql`
WITH due AS (
SELECT id FROM payment_sessions
WHERE status = 'active'
AND expires_at < now()
ORDER BY expires_at ASC
LIMIT ${BATCH_LIMIT}
FOR UPDATE SKIP LOCKED
)
UPDATE payment_sessions s
SET status = 'expired', updated_at = now()
FROM due
WHERE s.id = due.id
RETURNING s.id, s.user_id, s.budget_usdc, s.spent_usdc
`;
The batch limit lives inside the UPDATE rather than in a JS slice of the result, and that is not a detail. An unbounded UPDATE flips every due session to expired while only the sliced head is ever refunded, and the remainder is then invisible to the next tick, which only looks at status = 'active'. Whatever this tick does not claim stays active and is swept next time. FOR UPDATE SKIP LOCKED keeps concurrent ticks on disjoint rows.
Then, per row, with an idempotency key derived from the session id so overlapping ticks cannot double-refund:
await creditAccount({
userId: row.user_id,
amountUsd: atomicsToUsd(refundAtomics),
kind: 'refund',
action: 'payment_session_expire',
refType: 'payment_session',
refId: row.id,
idempotencyKey: `paysess_expire_${row.id}`,
});
The same refund path runs on manual cancellation. Short-lived sessions are the security posture we want people to adopt, so expiring one has to be free. If it costs the user money, they will set the TTL to a year and the control is gone.
What we would tell you to copy
The specifics here are Solana, USDC, Postgres, and x402, and none of that is the transferable part. The pattern is:
- Separate custody, authority, and execution. Whatever your rail (a card token, an internal ledger, a cloud budget), do not let one credential carry all three. Everything else follows from this.
- Give the agent a grant, not a key. Bounded by amount, by destination, and by time. Then a compromise costs a number you picked instead of a number an attacker picks.
- Enforce the budget as a predicate in the write.
UPDATE ... WHERE remaining >= amount RETURNINGis the whole concurrency story. Read-then-write is an overdraft waiting for enough traffic. - Design the uncertain outcome first. Success and rejection are easy. The submitted-but-unconfirmed case is the one that decides whether your accounting can be trusted, and it deserves an explicit state rather than a
catchthat guesses. - Assume the URL is hostile. Any agent-driven outbound request is an SSRF primitive. Validate, resolve, pin, and refuse redirects, before anything is signed.
- Make expiry cheap. Refund on expiry and on cancel, idempotently, or nobody will use short sessions.
An autonomous agent with a private key is a liability you cannot bound. An autonomous agent with a budget is a line item. The difference is about four hundred lines of code, and most of them are the boring ones.
Resources
- Source:
api/pay/execute.jsis the request path,api/_lib/pay/spend-governor.jsis the governor,api/_lib/pay/policy.jsholds the shared policy predicates,api/_lib/pay/payment-session.jsis the lifecycle, andapi/cron/payment-session-sweep.jsis the expiry-and-refund sweep - MCP server:
@three-ws/agentcore-payments-mcp - x402: x402.org, the HTTP-native pay-per-call standard the payments settle over
- Model Context Protocol: modelcontextprotocol.io
- Our previous Builder Center article: How we metered a SaaS product through AWS Marketplace with the AWS SDK for JavaScript v3, which covers the other half of this: how an AWS Marketplace subscription resolves into the same access check that grants a session
three.ws is a verified AWS Partner and an open-source platform for 3D AI agents and on-chain communities, with an AWS Marketplace listing built and awaiting publication. Live at three.ws.