How do I add a spending limit to my AI agent?

Create a wallet via POST /api/wallets with budget_limit_usd set to your desired monthly cap. Every purchase call to POST /api/wallets/:id/purchase checks the remaining budget and blocks transactions that would exceed it. Your agent gets a 402 response with the available balance.

Can an AI agent exceed its budget limit?

No. Trove enforces budget limits atomically inside a database transaction. The wallet balance is locked before any deduction — if the amount exceeds remaining budget, the transaction is rejected with HTTP 402 and the available balance. The agent never spends more than the budget limit.

How does an AI agent know what its remaining budget is?

Call GET /api/wallets/:id/balance at any time. It returns current_spent, remaining_budget, and transaction_count. Agents should check this before making expensive calls — it's a simple guardrail before a purchase attempt.

Can I update the budget limit after creating the wallet?

Yes. The budget_limit_usd is a mutable field on the wallet. You can increase or decrease it via a direct database update. Decreasing the limit may block future purchases if the agent has already spent up to the old limit — plan accordingly.

What happens when an AI agent hits its spending limit?

The agent receives a 402 Payment Required response with available: 0 and a message 'Insufficient funds'. The transaction is never recorded. The agent can alert the developer or wait for a budget increase. All of this happens programmatically — no human intervention required for the block.

How do I track what my agent spent money on?

Every purchase call records a transaction with amount_usd, description, vendor, and type. Call GET /api/wallets/:id/transactions for a full paginated ledger. You can also call GET /api/analytics with your API key to see aggregate spending by endpoint and time period.

How to Add Spending Limits to Your AI Agent in 10 Minutes

The problem no one talks about until it hurts

You build an AI agent. It works great. Then one night it runs a loop, calls Anthropic 8,000 times, and you wake up to a $4,000 bill on your personal credit card.

Or: you give a client access to your agent. They ask it to "research everything about our competitors." The agent calls your internal APIs 500 times. Each call costs $0.01. That's $5 you didn't plan for, every time someone asks a broad question.

AI agents are autonomous. Autonomy without spending controls is a liability.

The fix takes 10 minutes. Create a wallet for your agent with a hard budget limit. Every purchase call checks the remaining budget first. No human approval needed — just enforcement at the infrastructure level.

What you'll use

Trove's API gives every agent a programmable wallet. The wallet has:

Budget limit: A hard ceiling on total spend. Your agent can never exceed it.

Transaction ledger: Every purchase is recorded with amount, vendor, and description.

Balance check: Ask the wallet "how much is left?" before making expensive calls.

402 rejection: When the budget is exhausted, the API returns 402 with the remaining balance.

Step 1: Create the wallet

Step 1 of 4

Create a wallet for your agent

Give your agent a wallet with a $50/month budget limit. You can always increase it later.

Create wallet
const response = await fetch('https://trove-qjow.polsia.app/api/wallets', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Trove-Key': 'tvpk_your_api_key_here'
  },
  body: JSON.stringify({
    agent_id: 'research-bot-v3',
    name: 'Research Bot Budget',
    budget_limit_usd: 50.00
  })
});

const { wallet } = await response.json();
// wallet.id, wallet.budget_limit_usd, wallet.balance_usd

The response gives you a wallet.id. Save that — it's how you reference the wallet in all future calls.

Step 2: Check the budget before making calls

Step 2 of 4

Guard before you spend

Before your agent calls an expensive API, check the remaining budget. If it's too low, skip the call or alert you.

Check remaining budget
const balanceRes = await fetch(
  `https://trove-qjow.polsia.app/api/wallets/${wallet.id}/balance`,
  { headers: { 'X-Trove-Key': 'tvpk_your_api_key_here' } }
);

const { balance } = await balanceRes.json();
// balance.remaining_budget = 47.23 (after $2.77 spent)
// balance.current_balance = 2.77

if (balance.remaining_budget < 5.00) {
  sendAlert('Budget running low: $' + balance.remaining_budget + ' remaining');
  // Optionally skip the expensive call
}

Step 3: Execute purchases through the wallet

Step 3 of 4

Route every dollar through the wallet

When your agent makes a purchase, call the wallet API instead of billing directly. The wallet deducts and records the transaction atomically.

Execute purchase
const purchaseRes = await fetch(
  `https://trove-qjow.polsia.app/api/wallets/${wallet.id}/purchase`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Trove-Key': 'tvpk_your_api_key_here'
    },
    body: JSON.stringify({
      amount_usd: 0.15,
      vendor: 'serper.dev',
      description: 'Search: AI agent payment infrastructure competitors'
    })
  }
);

// If successful: 200, transaction recorded
// If over budget: 402 Insufficient funds

The wallet check is atomic. If two agents call the purchase endpoint simultaneously, the row lock ensures both are evaluated against the same balance at commit time. No double-spending, no race conditions.

Step 4: Read the transaction log

Step 4 of 4

Know where every dollar went

Pull the transaction ledger to see exactly what your agent spent money on — vendor, amount, description, timestamp.

Read transaction history
const txRes = await fetch(
  `https://trove-qjow.polsia.app/api/wallets/${wallet.id}/transactions?limit=20`,
  { headers: { 'X-Trove-Key': 'tvpk_your_api_key_here' } }
);

const { transactions, pagination } = await txRes.json();
// transactions[0].amount_usd, vendor, description, created_at

Try it in the playground

No setup required. Get a sandbox API key and wallet instantly.

Open the Playground

What happens when the budget runs out

Your agent calls POST /api/wallets/:id/purchase with amount_usd: 0.50. The wallet has $0.31 remaining.

Over-budget response (HTTP 402)
HTTP/1.1 402 Payment Required
{
  "success": false,
  "message": "Insufficient funds",
  "available": 0.31,
  "requested": 0.50
}

The transaction is never recorded. Your agent handles the 402 — skips the call, alerts you, or queues the request until the budget is increased. No credit card surprise.

Common mistakes to avoid

Setting budget = balance. Your budget limit is the ceiling, not the current balance. If you want $100/month, set budget_limit_usd: 100. The agent can spend up to $100 total, and balance_usd tracks how much it's spent so far. Setting budget to 0 means the agent can't spend anything.

No pre-flight check. Checking the balance before calling expensive APIs isn't required — the purchase endpoint will reject over-budget calls — but it lets your agent be smart about what to attempt. A "budget exhausted" error means the agent wasted time on a call it knew might fail.

Using the same wallet for multiple agents. One wallet, one agent. If two agents share a wallet and spend concurrently, they can race to the same budget ceiling. Give each agent its own wallet and set per-agent budgets independently.

Scale up as your agents grow

The same pattern works for any scale. A $50/month research bot uses the same API as a $10,000/month enterprise agent fleet. The difference is wallet count and budget limits — the enforcement mechanism is identical.

Start with one wallet per agent. Monitor transaction history. Increase budget limits as you learn what your agents actually spend. After a month, you'll have accurate per-agent cost data that lets you price client work profitably instead of guessing.

Get started. Open the playground — get a sandbox API key and wallet in 30 seconds. No credit card required. Read the full API docs for transaction webhooks and budget update endpoints.