Budget requests

Budgets are optional. Once an agent has one approved budget, every later payment needs an active budget. When it expires or runs out, request a new one. Both the budget and policies must pass for a payment to go through.

How it works

The agent requests a budget

The agent calls request_budget with an amount and a purpose. The request appears on the Budgets tab in the dashboard.

A person approves or declines

The reviewer can adjust the amount before approving. The agent calls get_budget_request to check whether it was approved.

The agent pays as usual

Standard payment requests, x402 pre-authorizations, and MPP pre-authorizations are all checked against the budget. Spend is deducted after each payment executes.

The budget runs out

Once the budget is spent, further payments are blocked. The dashboard shows spend progress.

Lifecycle

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

Each agent can have one active request at a time. Creating another 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": "cmm59z8k40001abcd1234efgh",
  "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": "cmm59z8k40001abcd1234efgh",
  "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": "cmm59z8k40001abcd1234efgh",
      "status": "approved",
      "amount": 50.0,
      "approvedAmount": 25.0,
      "spent": 12.5,
      "remaining": 12.5,
      "purpose": "Research 200 companies and generate reports",
      "category": "research",
      "currency": "USDC",
      "expiresAt": "2026-04-08T12:00:00.000Z",
      "approvedAt": "2026-04-07T12:05: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

Once an agent has had a budget approved, every payment flow checks it: 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: holds the amount against the budget before sending and records it as spend when the payment succeeds
x402/record: decrements budget when recording x402 payments
mpp/record: decrements budget when recording MPP payments

In-flight managed payments hold budget until they settle or fail. remaining subtracts those holds and spent counts recorded spend. A failed onchain transfer returns its amount to the budget. x402 and MPP pre-authorizations do not hold budget, so a grant does not guarantee budget remains when you record the payment. If a payment would exceed the remaining budget, x402 and MPP pre-authorization return the response below. payments/request returns HTTP 403 with code: "PAYMENT_DENIED", and payments/approve returns approved: false with reasonCodes: ["BUDGET_INSUFFICIENT"].

{
  "authorized": false,
  "decision": "declined",
  "message": "Payment is outside the available budget.",
  "reasons": ["The available payment budget is insufficient."],
  "reasonCodes": ["BUDGET_INSUFFICIENT"]
}

Dashboard

Budget requests appear on the Budgets tab of Alerts & Approvals. Requests that need review show the agent name, purpose, requested amount, and category. 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 request on the Budgets tab and choose Approve or Do not approve. To approve a different amount than requested, enter it in the optional amount field.

Audit trail

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

Example: agent workflow

import { Conto } from '@conto_finance/sdk';

const CONTO_API_BASE = 'https://conto.finance';
const apiKey = process.env.CONTO_API_KEY;
if (!apiKey) throw new Error('CONTO_API_KEY is required');

const conto = new Conto({ apiKey });

// 1. Request a budget
const createResponse = await fetch(`${CONTO_API_BASE}/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',
  }),
});
const budget = await createResponse.json();
if (!createResponse.ok) throw new Error(`Budget request failed: ${budget.error}`);

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

// 2. Poll until the request leaves review
let req;
while (true) {
  const statusResponse = await fetch(
    `${CONTO_API_BASE}/api/sdk/budget-request?requestId=${encodeURIComponent(budget.requestId)}`,
    { headers: { Authorization: `Bearer ${apiKey}` } }
  );
  if (!statusResponse.ok) throw new Error(`Status check failed: ${statusResponse.status}`);
  req = (await statusResponse.json()).requests[0];
  if (req.status !== 'review_required') break;
  await new Promise((r) => setTimeout(r, 5000));
}

// declined, expired, and used are final. A new budget needs a new request.
if (req.status !== 'approved') throw new Error(`Budget ${req.status}`);
console.log(`Approved: $${req.approvedAmount} budget, $${req.remaining} remaining`);

// 3. Make payments normally. The budget is enforced automatically.
await conto.payments.pay({
  amount: 0.05,
  recipientAddress: '0x0000000000000000000000000000000000000001',
  purpose: 'Paid research API call',
});
// Recorded spend reduces the remaining budget by $0.05

Get started

Integrate

Payments

Conto Commerce

Spending controls

Operate

Conto Pay

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

​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

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