AI Platforms

Who it's for. Builders of AI agent platforms, MCP server authors, LangChain tool authors, and anyone giving an LLM the ability to transact on a user's behalf. The agent is the actor; the user holds the card; BRRR is the boundary that enforces the budget.

This vertical is intentionally isolated from the rest of the API surface. It uses a different base URL, a different auth scheme (Bearer token, not X-Api-Key), a different scope (one user's own card, not a multi-tenant integration), and a deliberately minimal endpoint set. That isolation is the safety property — an Agentic credential cannot accidentally invoke a settlement or a card-data call outside its narrow surface.

Typical scenarios

• Threshold-based top-up. "Keep my Holyheld card above €50 at all times." The agent polls balance on a schedule and triggers a Deposit (top-up from the user's main account) whenever the threshold is breached.
• Pre-spend balance check. Before booking a service for the user, the agent verifies the card has enough EUR — and tops up if not — without surfacing a "low balance" error mid-checkout.
• One-time card-data retrieval for checkout. The agent fetches card number / CVV / expiry only at the exact moment a payment form needs them, never logs them, and never persists them past the session.
• Budgeted autonomous spending. A user grants the agent a cumulative spending limit in the Holyheld dashboard. The agent operates within that limit; any attempt beyond it is rejected with AI_TOPUP_LIMIT_EXCEEDED and the agent must surface the rejection back to the user.

Recommended stack

Need	Reach for
Read current EUR balance on the card	GET /balance
Retrieve card credentials for an active checkout	GET /card-data
Move EUR from the user's Holyheld main account to the card	POST /topup-request
Expose these three calls as tools to Claude	MCP server guide
Patterns for retries, polling, error escalation	Agent patterns

That's the entire surface. Three endpoints. A complete agent integration is small by design — the smaller the surface, the smaller the blast radius if a prompt-injection or jailbreak tries to push the agent past its boundary.

Architecture at a glance

   ┌──────────────────────────────────┐
   │           AI Agent               │
   │  (Claude MCP server, LangChain   │
   │   tool, OpenAI function call)    │
   └──────────────┬───────────────────┘
                  │ Authorization: Bearer <token>
                  ▼
   ┌──────────────────────────────────┐
   │   Payments for AI Agents API     │
   │  apicore.holyheld.com            │
   │     /v4/ai-agents                │
   │                                  │
   │  GET  /balance      ← read       │
   │  GET  /card-data    ← read       │
   │  POST /topup-request ← write     │
   └──────────────┬───────────────────┘
                  │  enforces cumulative
                  │  spending-limit policy
                  ▼
   ┌──────────────────────────────────┐
   │   User's Holyheld card balance   │
   │   (funded from main account)     │
   └──────────────────────────────────┘

The Bearer token comes from the agent instructions for a Holyheld card, not through a partner-onboarding flow. Each card has its own agent scope, and a user may have multiple cards. There is no multi-tenant fan-out — if you operate an agent platform serving many users, each user provides the agent instructions for the card they want the agent to manage, and the agent stores that token for that user-card pair.

Where to start

1. Payments for AI Agents — Introduction
2. Authentication — copy card agent instructions and use the Bearer token
3. MCP Guide — wrap the three endpoints as Claude tools in minutes

Where to next

• GET /balance, GET /card-data, POST /topup-request
• Agent patterns — threshold polling, retry budgets, error escalation
• Errors — AI_TOPUP_LIMIT_EXCEEDED, AI_TOPUP_INSUFFICIENT_BALANCE, and how an agent should react