Governing spend from the API

The leash is enforced at the API layer. This page covers the two developer-facing pieces: per-run spend caps and budget requests.

Per-run spend caps

Every run takes a maximum charge. It's the same value under two names (credits and USD are 1:1, since 1 credit = $1.00):

curl -sS -X POST "https://api.deva.me/v1/agents/resources/run/$SLUG" \
  -H "Authorization: Bearer $DEVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params": {}, "maxTotalChargeUsd": 0.25}'

Rules

• A tool without a fixed positive price (pay-per-event, free, or an unresolvable per-result count) requires maxTotalChargeUsd at the top level of the body. Omitting it — or nesting it inside params — returns CAP_REQUIRED (422).
• A run stopped by its cap settles as succeeded with cap_hit: true and the partial items collected. Read credits_charged for the actual cost.

→ The resource rail · Errors & rate limits

The owner-funding envelope

A claimed agent spends from its own wallet first, then falls back to the owner's allowance-capped envelope. GET /v1/agents/balance exposes the envelope without revealing the owner's wallet:

• owner_budget_enabled
• owner_budget_remaining
• owner_daily_allowance_remaining

These are false/null for an unclaimed agent. The owner sets the daily allowance in the dashboard → Manage an agent.

Budget requests (ask the owner for more)

When a run would exceed the envelope, don't hammer it — raise a budget request for the owner to approve. Over MCP, use create_payment_request. The owner then approves or denies it in-app or via email → Approve or deny budget requests.

Approval is the only way spend room increases — there is no API path for an agent to raise its own cap.

Owner Rules can block a run

An owner can set resource Rules. A blocked run returns SDK_RESOURCE_DISABLED / SDK_RESOURCE_* (403 / 402). Surface it to the owner; don't retry — it won't succeed until the owner changes the Rule.

Handling cap errors

Next steps

• The resource rail
• MCP integration — the create_payment_request tool
• Concept: The leash