Budgets stop an agent at its daily or monthly cap.

Each agent can carry a cap per day and a cap per month, in US dollars. Paidwen counts what the agent spends, and blocks its next action once a cap is reached.

The caps belong to the agent.

HTTP

PATCH /v1/agents/{agent_id}
Content-Type: application/json

{"budget": {"daily_usd": 100, "monthly_usd": 2000}}

Both caps are optional, and an agent without a cap has no budget. A cap goes from 0.000000001 to 1,000,000,000 dollars, and null removes it. The agent's Settings tab in the dashboard sets the same caps.

The day and the month follow the calendar in UTC.

The daily counter runs from midnight to midnight UTC, and the monthly counter from the first to the last day of the month, in UTC. A new window starts at zero.

The counter moves at three moments, once per cost.

At the decision, by the estimated cost of an allowed action.
At the answer of a person, by the estimated cost of an action that is going to run: an approved action, or an expired one whose group allows it.
When a model call reaches the journal, by its real cost.

A request sent again with the same action id moves nothing.

The agent estimates the cost of its tools.

Only the agent knows what a tool costs. A wrapped function gives its estimate, fixed or computed from its parameters.

const search = paidwen.tool("search.web", searchWeb, { cost: { estimated_usd: 0.001 } });

const sendSms = paidwen.tool("sms.send", sendMessages, {
  cost: (params) => ({ estimated_usd: 0.0075 * params.to.length }),
});

@paidwen.tool("search.web", cost={"estimated_usd": 0.001})
def search(query: str) -> list[str]:
    return search_web(query)


@paidwen.tool("sms.send", cost=lambda params: {"estimated_usd": 0.0075 * len(params["to"])})
def send_sms(to: list[str], text: str) -> None:
    send_messages(to, text)

Rules read the estimate in cost.estimated_usd.

Paidwen prices each model call from its tokens.

The SDK sends the model calls that your OpenTelemetry instrumentation describes, once you add its span processor, as the quickstart shows. Paidwen reads gen_ai.usage.input_tokens, gen_ai.usage.output_tokens and the cache tokens, finds the model in LiteLLM's price table, and adds the cost to the agent's counters.

A cost that the agent writes itself in paidwen.cost.usd comes first.
A model absent from the table keeps its tokens but gets no cost, and does not count in the budget.
The SDK sends each model call as soon as it ends, and the agent's next question waits for it, one second at most, so that the budget sees its cost.

At the cap, the verdict is block.

Paidwen refuses the action when the counter has reached the cap, or when the counter plus the estimated cost would pass it. The decision carries the budget field:

JSON

{"exceeded": "daily", "spent_usd": 100.02, "limit_usd": 100}

The message of DeniedError says that the agent's budget is spent. The agent stays blocked until the next window, or until you raise the cap. A stricter active rule still wins: a quarantine stays a quarantine.

Rules read what the agent already spent.

cost.spent_today_usd and cost.spent_month_usd carry the counters read before the decision, so a rule can act before the cap:

CEL

cost.spent_today_usd > 80.0

With escalate, this rule sends each action of an agent that spent more than $80 today to a manager.

The overshoot was measured on October 5, 2026.

A looping agent with a daily cap of $0.05 stopped after 16 turns, at $0.0517. The overshoot of $0.0017 is the seventeenth model call, which had left before the question that the budget refused. With four loops in parallel on one agent, the overshoot stayed at or below $0.008. In each run, the counter matched the sum of the costs in the journal to the nanodollar.

Budgets have five limits.

The possible overshoot is the cost of the actions allowed at the same time for one agent: an agent that starts four calls in parallel can pass its cap by four calls.
An approved action moves the counter at the answer, even when the cap is already reached.
Prices above 200,000 tokens, batch prices and priority prices of the table are not applied.
A budget names one agent. Team budgets wait for a customer to ask for them.
The windows follow UTC: in Paris, the day changes at 1 or 2 AM.