Budget Requests

Budget requests let an agent ask for a spending budget that a human reviews and approves in the dashboard. Once approved, spend is tracked against the approved amount across standard, x402, and MPP payments. When the budget is exhausted, further payments are blocked.

Budget requests are optional. If no active budget exists for an agent, all payment flows work normally using existing spend limits and policies. When an active budget does exist, both the budget and policies must pass for a payment to go through.

How It Works

Agent                                    Human (Dashboard)
  │                                          │
  ├─ request_budget ──────────────────────>  │ Sees request in Budgets tab
  │  (amount, purpose)                       │
  │                                          │
  ├─ get_budget_request ◄──────────────────  │ Approves (optionally adjusts
  │  (polls for approved)                    │ amount) or declines
  │                                          │
  ├─ Makes payments normally:                │
  │  • payments/request ──> budget check     │
  │  • x402/pre-authorize ──> budget check   │
  │  • mpp/pre-authorize ──> budget check    │
  │  • After execution ──> spend decremented │
  │                                          │
  └─ Budget exhausted → payments blocked     │ Sees spend progress bar

Lifecycle

A budget request moves through these customer-facing states:

Status	Description
`review_required`	Awaiting human review. Expires after 24 hours if it is not reviewed.
`approved`	Approved and available for spend until its expiry.
`declined`	Not approved by a reviewer.
`expired`	Timed out before review, or the approved budget window elapsed.
`used`	The approved amount has been spent.

Constraints:

One active request per agent at a time
Creating another request while one is active returns HTTP 409

SDK API

Create a Budget Request

curl -X POST https://conto.finance/api/sdk/budget-request \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "purpose": "Research 200 companies and generate reports",
    "category": "research"
  }'

Parameters:

Parameter	Type	Required	Description
`amount`	number	Yes	Requested budget in USDC
`purpose`	string	Yes	What this budget is for (shown to the reviewer)
`category`	string	No	Customer-defined spend category

Response (201):

{
  "requestId": "req_01J...",
  "status": "review_required",
  "amount": 50.0,
  "purpose": "Research 200 companies and generate reports",
  "category": "research",
  "createdAt": "2026-04-07T12:00:00.000Z"
}

Error (409), active request already exists:

{
  "error": "A budget request is already active",
  "requestId": "req_01J...",
  "status": "review_required"
}

Check Budget Request Status

curl https://conto.finance/api/sdk/budget-request?status=approved \
  -H "Authorization: Bearer $CONTO_API_KEY"

Query Parameters:

Parameter	Type	Required	Description
`requestId`	string	No	Specific budget request ID
`status`	string	No	`review_required`, `approved`, `declined`, `expired`, or `used`

Response (200):

{
  "requests": [
    {
      "requestId": "req_01J...",
      "status": "approved",
      "amount": 50.0,
      "approvedAmount": 25.0,
      "spent": 12.5,
      "remaining": 12.5,
      "purpose": "Research 200 companies and generate reports",
      "category": "research",
      "expiresAt": "2026-04-08T12:00:00.000Z",
      "createdAt": "2026-04-07T12:00:00.000Z"
    }
  ]
}

MCP Tools

request_budget

Request a spending budget for payments. Submits a request for human approval. Only one active budget request per agent at a time. Applies to all payment types.

Parameter	Type	Required	Description
`amount`	number	Yes	Requested budget in USDC
`purpose`	string	Yes	What this budget is for (shown to reviewer)
`category`	string	No	Customer-defined spend category

get_budget_request

Check status and remaining balance of your budget requests. Use to poll for approval and monitor remaining budget.

Parameter	Type	Required	Description
`requestId`	string	No	Specific request ID
`status`	string	No	`review_required`, `approved`, `declined`, `expired`, or `used`

Payment Flow Integration

When an active (approved, non-expired) budget exists, every payment flow checks it automatically: Pre-execution (blocking):

payments/request: checks budget before policy evaluation
payments/approve: checks budget for external wallet payments
x402/pre-authorize: checks budget before authorizing x402 payments
mpp/pre-authorize: checks budget before authorizing MPP payments

Post-execution (decrement):

payments/execute: decrements budget after successful execution
x402/record: decrements budget when recording x402 payments
mpp/record: decrements budget when recording MPP payments

If a payment would exceed the remaining budget, the authorization response stays customer-facing:

{
  "authorized": false,
  "decision": "declined",
  "message": "Payment is outside the available budget."
}

Dashboard

Budget requests appear in the Budgets tab on the Alerts & Approvals page. Requests that need review show:

Agent name, purpose, requested amount, category
Approve / Reject buttons
Optional amount adjustment field (approve a different amount than requested)

Approved requests show:

Spend progress bar showing spent and approved amounts
Remaining balance and expiry countdown
Whether the amount was adjusted from the original request

Completed requests show whether they were declined, expired, or fully used.

Approving a Request

Open the pending request in Alerts & Approvals, review the agent, purpose, amount, and expiry, then choose Approve or Reject. An approver can lower the approved amount or shorten the budget window before confirming.

Audit Trail

Budget requests, review decisions, spend, and expiry are recorded in the organization’s audit history using the same customer-facing labels shown in the dashboard.

Example: Agent Workflow

// 1. Request a budget
const budget = await fetch('/api/sdk/budget-request', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 50,
    purpose: 'Research 200 companies via paid APIs',
    category: 'research',
  }),
}).then((r) => r.json());

console.log('Budget request:', budget.requestId); // review_required

// 2. Poll for approval
let approved = false;
while (!approved) {
  const status = await fetch(`/api/sdk/budget-request?requestId=${budget.requestId}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  }).then((r) => r.json());

  const req = status.requests[0];
  if (req.status === 'approved') {
    console.log(`Approved: $${req.approvedAmount} budget`);
    approved = true;
  } else if (req.status === 'declined' || req.status === 'expired') {
    throw new Error(`Budget ${req.status}`);
  }

  await new Promise((r) => setTimeout(r, 5000));
}

// 3. Make payments normally, budget is enforced automatically
await conto.payments.pay({
  amount: 0.05,
  recipientAddress: '0x...',
  purpose: 'Paid research API call',
});
// Budget decremented: $49.95 remaining

Next Steps

Payments

Standard payment request and execution

x402 Payments

HTTP 402 micropayment handling

Spend Limits

Configure wallet spend limits

MCP Tools

Full MCP tools reference

Start

Products

Build

Guides

Reference

Changelog

Budget Requests

Budget Requests

How It Works

Lifecycle

SDK API

Create a Budget Request

Check Budget Request Status

MCP Tools

request_budget

get_budget_request

Payment Flow Integration

Dashboard

Approving a Request

Audit Trail

Example: Agent Workflow

Next Steps

Payments

x402 Payments

Spend Limits

MCP Tools

​Budget Requests

​How It Works

​Lifecycle

​SDK API

​Create a Budget Request

​Check Budget Request Status

​MCP Tools

​request_budget

​get_budget_request

​Payment Flow Integration

​Dashboard

​Approving a Request

​Audit Trail

​Example: Agent Workflow

​Next Steps

Payments

x402 Payments

Spend Limits

MCP Tools

Budget Requests

How It Works

Lifecycle

SDK API

Create a Budget Request

Check Budget Request Status

MCP Tools

request_budget

get_budget_request

Payment Flow Integration

Dashboard

Approving a Request

Audit Trail

Example: Agent Workflow

Next Steps