---
url: 'https://docs.brrr.network/docs/agentic/introduction.md'
description: >-
  Give your AI agent a spending card. Let agents check balance, retrieve card
  details, and top up a Holyheld card autonomously with a simple HTTP API.
---

# Payments for AI Agents

The Payments for AI Agents API lets an AI agent autonomously check and replenish a Holyheld card balance, and retrieve card details when needed for checkout. It is a purpose-built HTTP API designed to be called directly by AI systems — Claude, GPT, LangChain agents, or any orchestration layer that can make HTTP requests.

::: info Early access
This API is at version `0.0.1`. Endpoints and schemas are stable for the use cases documented here, but the surface may expand as new capabilities are added.
:::

## What an agent can do

| Action | Endpoint | Description |
|--------|----------|-------------|
| Check balance | `GET /balance` | Query the current EUR balance available on the Holyheld card |
| Get card data | `GET /card-data` | Retrieve card number, expiration date, CVV, cardholder name, and billing address |
| Top up | `POST /topup-request` | Transfer funds from the user's Holyheld main account to the card |

That is the complete API surface. An agent that can call these three endpoints can manage card balance and execute card-funded checkout flows within the limits the user configures.

## Use cases

**Autonomous expense management** — An agent monitors a card balance and tops it up before it runs low, ensuring uninterrupted spending without user intervention.

**Threshold-based top-up** — An agent is instructed: *"Keep my card above €50 at all times."* It checks balance on a schedule, and triggers a top-up whenever the threshold is breached.

**Pre-spend balance check** — Before booking a service on behalf of a user, an agent checks that sufficient funds are available and tops up if needed.

**Checkout automation** — An agent verifies balance, retrieves the card details only when required, and completes a payment flow on the user's behalf without exposing the card data beyond the active session.

**Budgeted agent spending** — Users grant an agent a spending limit (configured in the Holyheld dashboard). The agent operates within that limit; any attempt beyond the limit is rejected with `AI_TOPUP_LIMIT_EXCEEDED`.

## How it works

```
┌─────────────────────────────────────────────────────────┐
│                     Your AI Agent                       │
│  (Claude MCP server, GPT function, LangChain tool, …)   │
└────────────────────────┬────────────────────────────────┘
                         │ Bearer token
                         ▼
         ┌───────────────────────────────┐
         │   Payments for AI Agents API   │
         │  apicore.holyheld.com/v4/ai-agents  │
         │                               │
         │  GET  /balance      ──────────┼──► EUR balance on card
         │  GET  /card-data    ──────────┼──► Card details for checkout
         │  POST /topup-request ─────────┼──► Top up from main account balance
         └───────────────────────────────┘
                         │
                         │ (settlement, up to 5 min)
                         ▼
         ┌───────────────────────────────┐
         │       Holyheld card           │
         │  Balance updated in EUR       │
         └───────────────────────────────┘
```

## How it differs from the APIs

The APIs (`api.brrr.network`) are for **platform developers** building settlement flows for their end users. The Payments for AI Agents API is for **AI agents** acting on behalf of a single user's own Holyheld account.

| | APIs | Payments for AI Agents API |
|---|---|---|
| **Who uses it** | Platform backends (B2B) | AI agents (personal) |
| **Base URL** | `https://api.brrr.network` | `https://apicore.holyheld.com/v4/ai-agents` |
| **Authentication** | `X-Api-Key` header | `Authorization: Bearer <token>` |
| **Endpoints** | Full product surfaces | 3 (balance + card data + top-up) |
| **Manages** | Multiple end-user accounts | One user's own card |
| **Key obtained via** | Holyheld partner onboarding | Agent instructions for a Holyheld card |

## Environment

| Environment | Base URL |
|-------------|----------|
| **Production** | `https://apicore.holyheld.com/v4/ai-agents` |

## Prerequisites

Before making your first request you need:

1. **A Holyheld account** with an active card and available balance on the main Holyheld account
2. **Agent instructions** copied for that card; the instructions include the Bearer token
3. **A spending limit** configured for the card's agent access (the dashboard lets you set a maximum cumulative top-up amount)

## Next steps

::: tip Get started

1. [Configure authentication](/docs/agentic/authentication) — copy the card's agent instructions and learn how to use them
2. [Check balance](/docs/agentic/get-balance) — make your first API call
3. [Get card data](/docs/agentic/card-data) — retrieve card details safely for checkout flows
4. [Top up the card](/docs/agentic/topup) — trigger a top-up and handle the asynchronous confirmation
5. [Build an MCP server](/docs/agentic/mcp-guide) — expose these endpoints as Claude tools in minutes
   :::