Budgets

Budgets let you cap USDC spend at two levels: per-team and per-wallet. When a limit is reached, further requests are rejected until the window resets.

All amounts are in USDC (e.g. 10.0 = $10.00 USDC).

Team budgets

Set a team budget

Requires admin or owner role.

PUT /v1/orgs/018f1a2b-.../teams/019c3d4e-.../budget
Authorization: Bearer <admin-token | solvela_k_...>
Content-Type: application/json

{
  "hourly": 5.0,
  "daily": 50.0,
  "monthly": 500.0
}

Request fields — all optional; omit any field to leave that window unlimited.

Response — 200 OK

{
  "updated": true
}

Get team budget and spend

Requires member role or higher.

GET /v1/orgs/018f1a2b-.../teams/019c3d4e-.../budget
Authorization: Bearer <admin-token | solvela_k_...>

Response — 200 OK

{
  "hourly_limit": 5.0,
  "daily_limit": 50.0,
  "monthly_limit": 500.0,
  "hourly_spend": 1.25,
  "daily_spend": 12.50,
  "monthly_spend": 87.00
}

Org budget rollup

There is no org-level budget, and setting one is intentionally not supported: Solvela enforces spend caps at the leaf (team and wallet) level only. For reporting, the org stats endpoint surfaces a derived budget object that is the per-period sum of the org's team budgets — useful for answering "how much of its aggregate budget has the org spent?" without introducing a second enforcement layer.

"budget": {
  "hourly_limit_usdc": null,
  "daily_limit_usdc": 150.0,
  "monthly_limit_usdc": 4000.0,
  "teams_total": 3,
  "teams_with_hourly_budget": 0,
  "teams_with_daily_budget": 2,
  "teams_with_monthly_budget": 3
}

Semantics to keep in mind:

• A team with no limit for a period is treated as unlimited and adds nothing to that period's sum (matching how the limit behaves in enforcement).
• Therefore the sum is a true ceiling for a period only when every team has a budget for it. The teams_with_*_budget counts (against teams_total) expose partial coverage so the figure is never silently misleading.
• A null limit means no team set one for that period — it is not a 0 cap. Do not render null as "$0".

This figure is reporting-only and is computed live from team budgets; there is nothing extra to configure.

Wallet budgets

Wallet budgets are set and read using the admin token only.

Set a wallet budget

PUT /v1/wallets/AgEnTwALLetAddReSs.../budget
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "daily": 25.0
}

Get a wallet budget and spend

GET /v1/wallets/AgEnTwALLetAddReSs.../budget
Authorization: Bearer <admin-token>