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.

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

Get started

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