What you will set

One spend limit on one agent, in about five minutes. Concretely, two numbers and a window: a per-transaction cap, a total allowance, and the period the allowance covers. The wallet checks both on every payment and refuses anything over the line before money moves. This is the short, do-it-now version. For the deeper treatment of the model, the trade-offs, and emergency controls, the companion how-to-set-up-agent-spending-limits goes further; this page is about getting a sane limit in place quickly.

Amounts are in USDC base units (6 decimals), so $20.00 is 20000000 and a $2.00 per-payment cap is 2000000. The spending controls product page is the broader reference.

The one number to set first

If you do nothing else, set the per-transaction cap. Here is why it carries the most weight.

An agent's spend goes wrong in two shapes. The first is a slow bleed: many small payments that add up faster than you expected. The second is a single bad payment: one large transfer to the wrong place, whether from a bug, a runaway loop, or a prompt injection that redirected a payment. The second shape is the one that empties a balance in a single call, and the per-transaction cap is the only control that stops it cold.

So set per_tx_wei close to your largest legitimate single payment, with a little headroom and no more. If your priciest real call is a five-cent bulk lookup, a twenty-cent cap is sane and a fifty-dollar cap is not. A tight per-transaction cap means that even in the worst case, a single wrong payment is small, and the period allowance then catches the slow-bleed shape on top. Set the one number first, add the allowance second.

Prerequisites

• A Blockchain0x account with the agent already created.
• A sk_test_ or sk_live_ API key for reading the limit back. The agent's own key is fine; it has read access.
• Two minutes to estimate your numbers: the largest normal single payment, and a normal day or week of total spend.

Set the limit in the dashboard

You set the limit in the dashboard, not from code. Open the agent, go to its spend permission, and enter the per-transaction cap, the allowance, and the period. Save, and the wallet starts enforcing it on the next payment.

This is deliberate. The agent's key cannot create or change a spend permission, because the write routes are not exposed on the API. If the agent could edit its own limit, a compromised agent would simply raise it, and the control would be theatre. Keeping the edit surface human-only is what makes the limit a real boundary rather than a setting the agent can talk its way past.

Confirm it from the API

After you save, confirm what is actually enforced. The agent's key can read the permission even though it cannot write it.

import { createClient } from "@blockchain0x/node";

const client = createClient({ apiKey: process.env.B0X_API_KEY! });

const res = await fetch(
  `https://api.blockchain0x.com/v1/agents/${agentId}/spend-permissions`,
  { headers: { Authorization: `Bearer ${process.env.B0X_API_KEY!}` } },
);
const permissions = await res.json();
// [{ per_tx_wei, allowance_wei, period_seconds, start_at, end_at, revoked_at }]

Read this on boot and log it. A one-line "agent X enforcing per_tx 200000, allowance 3000000 daily" in your startup logs means an on-call engineer can see the limit without opening the dashboard, and a missing or zeroed limit shows up immediately rather than during an incident.

A worked example

Make it concrete with a content-generation agent that calls a paid image API. Suppose each image costs you about $0.04, the agent generates around 50 images on a normal day so it spends roughly $2.00, and the most expensive single call is a $0.10 high-resolution render.

Set per_tx_wei to 200000 ($0.20), about double the largest real call, so one render can never balloon into a large transfer. Set allowance_wei to 6000000 ($6.00), three times a normal day, on a daily period_seconds of 86400. That gives the agent room for a heavy day, around 150 images, while capping a runaway loop at six dollars before the wallet stops it, and capping any single payment at twenty cents no matter what.

Now watch it for a week. If the agent regularly brushes the $6.00 ceiling on legitimate days, raise the allowance toward twice the observed median. If it never gets near it, tighten down so the limit means something. The per-transaction cap rarely needs changing once you have set it from a real largest-call number; it is the allowance you tune as you learn the agent's real shape.

Pick the right period

The period_seconds value sets how often the allowance resets: 86400 for daily, 604800 for weekly, 2592000 for a 30-day month. Match it to how the agent actually spends.

A daily window fits an interactive agent with steady, predictable traffic, where each day looks roughly like the last. A weekly or monthly window fits a batch agent whose spend is lumpy, heavy on the day a job runs and quiet otherwise, because a daily cap would either choke the busy day or be too loose on the quiet ones. When unsure, start daily; it gives you the tightest feedback loop and the smallest blast radius, and you can widen the period once you have seen real usage.

Change or lift the limit

Limits are not set once and forgotten. When real usage tells you the cap is too tight (the agent keeps brushing it on legitimate work) or too loose (it never comes close), change it in the dashboard. The change applies to the next payment; you do not redeploy anything.

To stop an agent's spending entirely and immediately, revoke the spend permission in the dashboard, which stamps its revoked_at and the wallet stops authorizing payments under it. For a harder stop that also cuts off the agent's other operations, revoke its API key with client.apiKeys.revoke(apiKeyId). Use the permission revoke for "stop spending", the key revoke for "stop everything".

When you raise a limit, do it in small steps rather than one large jump. Doubling an allowance you have watched for a week is a reasoned change; multiplying it tenfold because the agent hit the cap once is how a real limit quietly becomes no limit. Each change is reversible and takes effect on the next payment, so there is no cost to moving carefully and re-checking after a few days.

Common pitfalls

Three quick traps.

Setting a round number instead of a real one. A hundred-dollar cap because it sounds safe, on an agent that spends a dollar a day, is not a limit. Base both numbers on real usage.

Skipping the per-transaction cap. A period allowance alone still lets one payment consume the whole allowance at once. The per-transaction cap is what stops the single-bad-payment shape; do not leave it open.

Forgetting limits are per agent. Your test agent and your live agent are different agents with different permissions. Setting a limit on one does nothing for the other. Set it on the agent that actually transacts in production.

What to ship today

Set a per-transaction cap close to your largest real call, add a daily allowance at two to three times a normal day, and read it back over the API to confirm. That is a sane limit in five minutes. For the full model, emergency controls, and tuning over time, continue with how-to-set-up-agent-spending-limits. Pricing is on the pricing page.