Why agents need wallets

Every autonomous agent hits the same problem: it needs to pay for things. A research bot needs Serper API credits. A content agent needs image generation tokens. An outreach agent needs email delivery.

The current options are terrible. Hardcoding your credit card into a prompt is a security nightmare. Building a custom billing layer takes months. Human-in-the-loop approvals defeat the point of autonomous agents.

What you're building: A programmable wallet for your AI agent. Budget limits enforced automatically. Transaction history for auditing. Simple REST API for integration.

This tutorial uses the Trove Wallet SDK — five endpoints, no dependencies beyond Node.js, deployed on your own infrastructure.

What you need

Before we start, make sure you have:

  • Node.js 18+ — installed on your machine
  • npm — comes with Node
  • A Trove instance — we'll create the API key in Step 1

That's it. No Stripe account, no crypto wallet, no credit card. Just a running Trove instance.

01 Get an API key

Every wallet needs an API key to authenticate. Create one with a simple POST request:

bash
curl -X POST https://trove-qjow.polsia.app/api/keys \ -H "Content-Type: application/json" \ -d '{"name": "my-agent-wallet"}'
Response
{ "success": true, "api_key": "tvpk_a1b2c3d4e5f6g7h8i9j0", "name": "my-agent-wallet", "created_at": "2026-04-04T12:00:00Z" }

The key starts with tvpk_ — that's how you'll identify it in requests. Keep this key secret. It authenticates all wallet operations.

02 Create a wallet

Now create a wallet for your agent. You define the agent ID, a friendly name, and most importantly — a budget limit that Trove enforces automatically.

bash
curl -X POST https://trove-qjow.polsia.app/api/wallets \ -H "Content-Type: application/json" \ -H "X-Trove-Key: tvpk_a1b2c3d4e5f6g7h8i9j0" \ -d '{ "agent_id": "research-bot-001", "name": "Research Bot Wallet", "budget_limit_usd": 50.00 }'
Response
{ "success": true, "wallet": { "id": "w_live_a1b2c3d4e5", "agent_id": "research-bot-001", "name": "Research Bot Wallet", "budget_limit_usd": 50.00, "remaining_budget": 50.00, "total_spent": 0.00, "status": "active", "created_at": "2026-04-04T12:01:00Z" } }

Budget enforcement: Every purchase is checked against remaining_budget before approval. If the purchase would exceed the limit, it's rejected. No surprises on your bill.

03 Execute a purchase

Now your agent can make purchases. Each purchase records the amount, description, and vendor — all automatically deducted from the budget.

bash
curl -X POST https://trove-qjow.polsia.app/api/wallets/w_live_a1b2c3d4e5/purchase \ -H "Content-Type: application/json" \ -H "X-Trove-Key: tvpk_a1b2c3d4e5f6g7h8i9j0" \ -d '{ "amount_usd": 5.00, "description": "Serper API - 1000 search credits", "vendor": "serper.dev" }'
Response
{ "success": true, "purchase": { "id": "tx_live_x1y2z3", "wallet_id": "w_live_a1b2c3d4e5", "amount_usd": 5.00, "description": "Serper API - 1000 search credits", "vendor": "serper.dev", "status": "approved", "created_at": "2026-04-04T12:02:00Z" } }

The purchase is approved because $5 is well under the $50 budget. Let's make another one to see the budget deduction in action:

bash
curl -X POST https://trove-qjow.polsia.app/api/wallets/w_live_a1b2c3d4e5/purchase \ -H "Content-Type: application/json" \ -H "X-Trove-Key: tvpk_a1b2c3d4e5f6g7h8i9j0" \ -d '{ "amount_usd": 12.50, "description": "Fal.ai - 50 flux-schnell images", "vendor": "fal.ai" }'
Response
{ "success": true, "purchase": { "id": "tx_live_y2z3a4", "wallet_id": "w_live_a1b2c3d4e5", "amount_usd": 12.50, "description": "Fal.ai - 50 flux-schnell images", "vendor": "fal.ai", "status": "approved", "created_at": "2026-04-04T12:03:00Z" } }
04 Check the balance

At any time, check how much budget remains. This is the endpoint your monitoring systems call.

bash
curl https://trove-qjow.polsia.app/api/wallets/w_live_a1b2c3d4e5/balance \ -H "X-Trove-Key: tvpk_a1b2c3d4e5f6g7h8i9j0"
Response
{ "success": true, "wallet_id": "w_live_a1b2c3d4e5", "agent_id": "research-bot-001", "budget_limit_usd": 50.00, "total_spent": 17.50, "remaining_budget": 32.50, "status": "active" }

$17.50 spent, $32.50 remaining. The wallet tracks every penny.

05 View transaction history

For auditing and reporting, fetch the complete transaction history with pagination.

bash
curl "https://trove-qjow.polsia.app/api/wallets/w_live_a1b2c3d4e5/transactions?limit=10&offset=0" \ -H "X-Trove-Key: tvpk_a1b2c3d4e5f6g7h8i9j0"
Response
{ "success": true, "transactions": [ { "id": "tx_live_y2z3a4", "wallet_id": "w_live_a1b2c3d4e5", "amount_usd": 12.50, "description": "Fal.ai - 50 flux-schnell images", "vendor": "fal.ai", "status": "approved", "created_at": "2026-04-04T12:03:00Z" }, { "id": "tx_live_x1y2z3", "wallet_id": "w_live_a1b2c3d4e5", "amount_usd": 5.00, "description": "Serper API - 1000 search credits", "vendor": "serper.dev", "status": "approved", "created_at": "2026-04-04T12:02:00Z" } ], "pagination": { "limit": 10, "offset": 0, "total": 2 } }

Transactions are returned newest-first. Use limit and offset for paginated access to large histories.

What's next

You've got the basics working. Here are the features that take this from "proof of concept" to production:

Spending rules

Add per-vendor limits, time-based restrictions (no spending outside business hours), or require approval for purchases over a threshold. Rules are evaluated before every purchase.

Analytics dashboard

See spending by vendor, by agent, over time. Identify which agents are costliest and where you can optimize.

Multi-agent wallets

Create parent-child wallet hierarchies. A "team" wallet funds individual agent wallets with their own limits. Roll up spend into one bill.

Webhook notifications

Get notified on every purchase, or only when budgets hit thresholds. Integrate with your existing monitoring stack.

All of this is in the full API reference. Go deeper on spending rules, webhook configuration, and multi-wallet hierarchies.

Ready to give your agents wallets?

Start with the full API docs or join the waitlist for the hosted version.

Read the Docs Join Waitlist