What you will configure

A spend permission with three real controls: a per-transaction cap (per_tx_wei), a per-period allowance (allowance_wei measured over period_seconds), and a validity window (start_at, end_at). Together they bound how much an autonomous agent can move and how fast. The permission lives on the agent's Blockchain0x wallet and is checked on every payment before settlement. This is the way to put real guardrails on an agent in 2026. See the spending controls product page for the wider framing.

Amounts are in USDC base units (6 decimals), so $20.00 is 20000000 and a $2.00 per-payment cap is 2000000. Set this once per agent, and the wallet does the rest.

Why limits belong in the wallet, not the prompt

The most important decision in agent safety is where the limit lives. Three options, and only one works.

In the system prompt. "Do not spend more than fifty dollars a day." Common first attempt. It fails because an attacker who can get text into the agent's context can also remove the budget line. The prompt is not a security boundary.

In the agent's code. A check before each tool call. Better, but still inside the agent's manipulable scope. On frameworks where prompt content can shape function arguments, a crafted input can sometimes coax the code-level check into letting a payment through.

In the wallet. Server-side enforcement the agent cannot reach. The agent submits a payment, the wallet evaluates the permission, the wallet settles or refuses. This is the only design that survives a well-built prompt injection, and it is what Blockchain0x does.

Where you set limits

You create and edit spend permissions in the dashboard, not from code. The write routes (create, delete) are intentionally not exposed on the API. That is deliberate: if the agent's key could rewrite the permission, a compromised agent could lift its own ceiling, and the whole control would be theatre.

So the flow is: a human (or your internal admin tool) sets the per-transaction cap, the allowance, and the period in the dashboard. The agent runtime gets a sk_test_ or sk_live_ key that can transact and read, but cannot touch the permission. Clean separation, and one fewer thing an attacker can reach.

Read the active limits from the API

Your agent's key can read what is enforced, which is what you want for health checks and audits. The route is read-only.

const agentId = "agt_...";
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();
// Each permission carries:
//   allowance_wei    -> total spend allowed in one period (USDC base units, 6 dp)
//   per_tx_wei       -> max single payment
//   period_seconds   -> 86400 (daily), 604800 (weekly), or 2592000 (monthly)
//   start_at, end_at -> the window the permission is valid for
//   revoked_at       -> set when a permission has been revoked

The same call works as a plain curl with a Bearer header if you are scripting a health check outside Node. Read it on boot and log the active limits so an on-call engineer can see them without opening the dashboard.

Pick the right baseline numbers

Before you open the dashboard, write down two numbers and one period.

The common mistake is leaving it unset and discovering the limit only when the agent trips it mid-task. Spend ten minutes on the numbers. If the agent is brand new and you have no history, pick a busy-but-not-runaway figure and run a week. The first week of data tells you whether to tighten or loosen. Refusing to set any limit because you do not know the right number is the worst choice: an agent with no ceiling is one prompt injection away from draining the workspace balance overnight.

A worked example. Say your research agent makes about 200 paid calls a day at roughly $0.005 each, so it spends near $1.00 on a normal day, and the priciest single call is a $0.05 bulk lookup. A sane starting point is per_tx_wei at 200000 ($0.20, about 4x the largest call) and allowance_wei at 3000000 ($3.00, about 3x a normal day) on a daily period_seconds of 86400. That leaves room for a busy day while capping a runaway loop at three dollars before the wallet stops it. After a week of real numbers, nudge the allowance toward 2x your observed median and watch how often the agent brushes the ceiling.

What happens when a limit is hit

When a payment would break per_tx_wei or push the period total past allowance_wei, the wallet refuses it before anything settles. No USDC moves. The agent's paid request returns a non-2xx, and the planner sees a failure it can handle. Tell the planner in its system prompt what to do with a refused payment, something like "if a paid call fails, do not retry it with the same arguments", so a blocked agent does not loop on the same wall.

This is the behavior that makes a tight per_tx_wei so useful even without a payee allowlist: a redirected or runaway payment is capped at one small transaction, and the period allowance caps the bleed even if many small ones slip through.

Freeze an agent in an emergency

Two levers, fast to slow.

Fastest: revoke the agent's API key. This cuts off every operation immediately, not just spend.

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

const client = createClient({ apiKey: process.env.B0X_API_KEY! });
await client.apiKeys.revoke("ak_..."); // the agent's key stops working at once

More surgical: revoke the spend permission in the dashboard. The permission's revoked_at gets stamped and the wallet stops authorizing payments under it, while the rest of the agent's read operations keep working. Use the key revoke for "stop everything now" and the permission revoke for "stop spending, keep running".

Common mistakes

Four mistakes that quietly defeat the limit you configured.

Treating the system prompt as a backup limit. It is not defense in depth, it is false confidence. Only the wallet-side permission counts. You can mention the budget in the prompt for behavior, never as a line of defense.

Setting the allowance from a vanity number. The right allowance is 2 to 3x real usage, not a round number that sounds safe. A two-hundred-dollar daily allowance on an agent that spends five is no real limit at all.

Leaving per_tx_wei wide open. With no payee allowlist in the model, the per-transaction cap is your structural control. Keep it close to your real largest call so one bad payment stays small.

Handing the agent runtime a key you also use to administer. The runtime needs a transact-and-read key. Dashboard access that changes permissions belongs with a human and your secret manager, nowhere the agent's context can reach. The secure-your-agent-wallet guide covers the rest of the hardening.

The fuller safety story includes verification badges on the agent's public profile and a weekly audit-log review. See the pricing page for the per-agent tiers, the best wallet for AI agents page for wallet-level choices that complement these limits, and how to add payments to an MCP server for a place where tight limits earn their keep.