How do I get an alert when an AI agent approaches its spend cap, before the hard deny?

What should I check, step by step?

1. Set the hard cap first with set_spend_policy: currency, per_tx_max_minor, daily_max_minor, allowed_domains/categories, optional expires_at. Soft alerts without a hard deny behind them are only noise.

2. Define soft thresholds as fractions of that hard cap (for example 0.50, 0.80, 0.90 of daily_max_minor, and the same for a per-task budget if you track one). Store them outside the agent's editable session.
3. After every authorize_spend allow (or on a short poll of GET /v1/spend/policies/{credential_id}), compare spent_today_minor to each soft line. Fire once per threshold per UTC day (or per task), not on every subsequent purchase.
4. On a soft hit: notify owners (pager, chat, email) with credential id, spent vs cap, merchant and reference. Do not auto-raise the cap from the agent.
5. Offer a raise path only through a human: request_human_approval bound to the new proposed daily_max_minor / per_tx_max_minor and policy version; after approve, call set_spend_policy again. Until then the hard cap still denies.
6. Keep authorize_spend as the execution boundary: over_per_transaction_cap and over_daily_cap must still return signed denies even if soft alerts failed or were ignored.
7. Record soft-threshold events and hard denies on an append-only ledger the agent cannot rewrite, with policy_id, policy_version, spent, cap and threshold.
8. Drill it: run spend to 80% and confirm one alert; push past the hard cap and confirm deny; approve a raise and confirm the new policy version is what authorize_spend uses.

What is the difference between a soft spend threshold and a hard spend cap for an AI agent?

A soft threshold is a notification and an optional re-approval path, not a second allow. At 80% of a $100 daily cap you want a page or a human looking at the run; at 101% authorize_spend must still return over_daily_cap.

• Provider consoles (OpenAI project monthly limits, Claude workspace limits, OpenRouter key limits) are hard ceilings with little or no soft warning you control. Put soft lines in your own monitor that reads Rightshold's running total so you are not surprised by a hard deny mid-task.
• How to set per-request and per-run spend caps, how to give each AI agent a task-scoped spend policy, and how to gate an agent wallet with per-task caps cover the hard limits. This page is the early-warning layer in front of them.

How do I wire soft spend alerts off the same totals authorize_spend uses?

set_spend_policy stores per_tx_max_minor and daily_max_minor on the credential. authorize_spend checks the proposed amount against those caps and the running daily total (UTC day) and returns a signed allow or deny with reasons.

• GET /v1/spend/policies/{credential_id} (owner key) shows the policy and spent_today_minor. Your alerter should use that same spent figure (or the sum of allows you already recorded for the task) so soft lines and hard denies cannot disagree.
• Debounce: emit one event per threshold crossing per window. Pair the alert with the purchase reference and merchant_domain from the last allow so on-call can see what is burning the budget.

How do I raise an AI agent's spend cap after a soft threshold alert?

When a soft threshold means "consider raising," do not let the agent rewrite its own cap. request_human_approval with an action that names the credential, current cap, proposed cap and policy_version; after decide_human_approval, call set_spend_policy with the new numbers.

• Until that approval lands, authorize_spend keeps denying over the old hard cap. That is the point: soft alerts buy time for a person; they do not punch a hole in the ceiling.
• ledger_verify is free and keyless for the chain of policy changes, soft-threshold records and hard denies. EU AI Act Article 14 expects human oversight that can intervene; a soft alert plus a bound raise approval is that oversight for spend.