API Reference

Programmable wallets for AI agents. Create wallets, enforce budgets, and track spending.

Getting Started

Quick Start

1

Generate an API Key

Create an API key to authenticate your requests. The key will be prefixed with tvpk_.

Request
curl -X POST https://trove-qjow.polsia.app/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'
2

Create a Wallet

Create a wallet for your agent with a budget limit. The balance starts at $0.

Request
curl -X POST https://trove-qjow.polsia.app/api/wallets \
  -H "Content-Type: application/json" \
  -H "X-Trove-Key: tvpk_your_key_here" \
  -d '{"agent_id": "research-bot", "name": "Research Agent", "budget_limit_usd": 50}'
3

Execute a Purchase

Make a purchase from the wallet. Transactions are rejected if they exceed the remaining budget.

Request
curl -X POST https://trove-qjow.polsia.app/api/wallets/1/purchase \
  -H "Content-Type: application/json" \
  -H "X-Trove-Key: tvpk_your_key_here" \
  -d '{"amount_usd": 5.00, "description": "Twilio SMS", "vendor": "twilio"}'
4

Check Balance

Get current balance, total spent, and remaining budget.

Request
curl https://trove-qjow.polsia.app/api/wallets/1/balance \
  -H "X-Trove-Key: tvpk_your_key_here"
Authentication

API Keys

All wallet endpoints require authentication via the X-Trove-Key header. API keys are prefixed with tvpk_.

Example
curl https://trove-qjow.polsia.app/api/wallets/1/balance \
  -H "X-Trove-Key: tvpk_abc123..."
Reference

Endpoints

POST /api/keys

Generate a new API key. The key is returned once — save it immediately.

Parameter Type Description
name required string A name to identify this key (e.g., "production", "staging")
Response
{   "success": true,   "api_key": "tvpk_abc123...",   "name": "my-app",   "id": 1,   "created_at": "2026-04-04T12:00:00Z",   "message": "Save this key - it will not be shown again" }
POST /api/wallets

Create a new wallet for an agent with a budget limit.

Parameter Type Description
agent_id required string Unique identifier for the agent (e.g., "research-bot")
name required string Human-readable name for the wallet
budget_limit_usd required number Maximum amount the agent can spend (USD)
Example Request
const response = await fetch('/api/wallets', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Trove-Key': 'tvpk_your_key'
  },
  body: JSON.stringify({
    agent_id: 'research-bot',
    name: 'Research Agent',
    budget_limit_usd: 50
  })
});
Response
{   "success": true,
  "wallet": {
    "id": 1,
    "agent_id": "research-bot",
    "name": "Research Agent",
    "budget_limit_usd": 50,
    "balance_usd": 0,
    "created_at": "2026-04-04T12:00:00Z"
  }
}
POST /api/wallets/:id/purchase

Execute a purchase from the wallet. Returns 402 if insufficient funds.

Parameter Type Description
:id path integer Wallet ID
amount_usd required number Amount to charge (positive number)
description string Optional description of the purchase
vendor string Optional vendor name (e.g., "twilio", "openai")
Example
const response = await fetch('/api/wallets/1/purchase', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Trove-Key': 'tvpk_your_key'
  },
  body: JSON.stringify({
    amount_usd: 5.00,
    description: "Twilio SMS",
    vendor: "twilio"
  })
});
Response
{   "success": true,
  "transaction": {
    "id": 1,
    "wallet_id": 1,
    "amount_usd": 5.00,
    "description": "Twilio SMS",
    "vendor": "twilio",
    "type": "debit",
    "created_at": "2026-04-04T12:00:00Z"
  },
  "wallet": {
    "id": 1,
    "balance_usd": 5.00
  }
}
GET /api/wallets/:id/balance

Get current balance, total spent, remaining budget, and transaction count.

Parameter Type Description
:id path integer Wallet ID
Response
{   "success": true,
  "wallet": {
    "id": 1,
    "agent_id": "research-bot",
    "name": "Research Agent"
  },
  "balance": {
    "current_balance": 5.00,
    "total_spent": 5.00,
    "remaining_budget": 45.00,
    "transaction_count": 1
  }
}
GET /api/wallets/:id/transactions

Get paginated transaction history for a wallet.

Parameter Type Description
:id path integer Wallet ID
page query Page number (default: 1)
limit query Items per page (default: 20, max: 100)
Response
{   "success": true,
  "wallet": {
    "id": 1,
    "agent_id": "research-bot",
    "name": "Research Agent"
  },
  "transactions": [
    {
      "id": 1,
      "wallet_id": 1,
      "amount_usd": 5.00,
      "description": "Twilio SMS",
      "vendor": "twilio",
      "type": "debit",
      "created_at": "2026-04-04T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}
Error Handling

Error Codes

Code Status Description
400 Bad Request Missing or invalid parameters. Check the message for details.
401 Unauthorized Missing or invalid X-Trove-Key header.
402 Payment Required Insufficient funds. The purchase amount exceeds remaining budget.
404 Not Found Wallet not found. Check the wallet ID.
500 Server Error Internal error. Try again later.