Economic API
Budget-aware authorization endpoints for priced tool calls, including session, agent, and cumulative category spend tracking plus approval escalation.
The economic API is Veto Cloud's control plane for priced actions. It authorizes quoted spend before execution, commits actual spend after execution, and returns budget state for the current session, agent, and category policies.
This is designed for MCP-side integrations that need one authority over:
- Trade notional
- Paid x402 research calls
- Shared approval workflows for expensive actions
Category policies are cumulative across the current organization or project scope. They do not reset per session. Live authorizations reserve budget temporarily. If a caller never commits, the reservation stops counting after the configured approval window and must be re-authorized.
POST /v1/economic/authorize
Authorize a priced action before execution.
Headers
| Header | Required | Description |
|---|---|---|
X-Veto-API-Key or Authorization | Yes | API key or Bearer JWT |
Content-Type | Yes | application/json |
Body
{
"actionId": "8c4d03fd-3ed8-429d-8d53-e1fdc7b0f7d7",
"sessionId": "session-abc",
"agentId": "profile/defaults",
"toolName": "order_market",
"category": "trade",
"payer": "trader-wallet",
"mode": "live",
"estimatedSpendUsd": 75,
"maxAcceptableSpendUsd": 80,
"budgetScopes": ["session", "agent", "category"],
"metadata": {
"token": "12345",
"side": "buy"
}
}Decisions
The response uses one of three decisions:
allow: execution may proceeddeny: execution must not proceedrequire_approval: a human must resolve an approval first
Allow response
{
"decision": "allow",
"reasonCode": "economic_authorized",
"message": "Economic authorization granted",
"authority": "cloud",
"payer": "trader-wallet",
"quotedSpendUsd": 75,
"budget": {
"currency": "USD",
"asOf": "2026-03-11T12:00:00.000Z",
"source": "cloud",
"session": {
"limitUsd": 500,
"spentUsd": 75,
"remainingUsd": 425
}
}
}Approval response
{
"decision": "require_approval",
"reasonCode": "approval_required",
"message": "Economic approval required",
"approvalId": "32a7a8c0-3f28-49f4-a4f0-9184bc15e13e",
"authority": "cloud",
"payer": "trader-wallet",
"quotedSpendUsd": 250
}Simulation behavior
If the request uses "mode": "simulation" and would require approval in live mode, the API returns:
decision: "allow"provisional: truereasonCode: "approval_required"
This lets the client preview the cost without creating a real approval record.
POST /v1/economic/commit
Commit the actual spend after execution succeeds.
Body
{
"actionId": "8c4d03fd-3ed8-429d-8d53-e1fdc7b0f7d7",
"sessionId": "session-abc",
"agentId": "profile/defaults",
"toolName": "order_market",
"category": "trade",
"payer": "trader-wallet",
"quotedSpendUsd": 75,
"actualSpendUsd": 74.82,
"approvalId": "32a7a8c0-3f28-49f4-a4f0-9184bc15e13e"
}Response
{
"status": "committed",
"authority": "cloud",
"category": "trade",
"payer": "trader-wallet",
"quotedSpendUsd": 75,
"actualSpendUsd": 74.82,
"approvalId": "32a7a8c0-3f28-49f4-a4f0-9184bc15e13e",
"reasonCode": "economic_committed",
"message": "Economic spend committed",
"budget": {
"currency": "USD",
"asOf": "2026-03-11T12:01:00.000Z",
"source": "cloud"
}
}POST /v1/economic/status
Get budget status for the current session and agent.
Body
{
"sessionId": "session-abc",
"agentId": "profile/defaults"
}Response
{
"enabled": true,
"authority": "cloud",
"healthy": true,
"pendingApprovals": [
"32a7a8c0-3f28-49f4-a4f0-9184bc15e13e"
],
"budget": {
"currency": "USD",
"asOf": "2026-03-11T12:02:00.000Z",
"source": "cloud"
}
}GET /v1/economic/config
Returns the current economic policy config for the organization or API-key project scope.
PUT /v1/economic/config
Update the economic policy config for the organization or API-key project scope.
Body
{
"defaultPayer": "trader-wallet",
"approvedPayers": ["trader-wallet", "research-wallet"],
"perActionApprovalThresholdUsd": 100,
"sessionLimitUsd": 500,
"agentLimitUsd": 1000,
"categoryPolicies": {
"trade": {
"limitUsd": 450,
"approvalThresholdUsd": 250
},
"x402_research": {
"limitUsd": 50,
"approvalThresholdUsd": 20
}
},
"approvalWindowSeconds": 600
}Notes
- Economic approvals reuse Veto's existing approvals queue.
- Authorization is idempotent on
actionId. - Commit is idempotent on
actionId. approvalWindowSecondsalso bounds how long an uncommitted live authorization continues reserving capital.- Project-scoped API keys read and write project-scoped economic policies and ledger entries.