FAQ

General

What is BRRR?

BRRR is the developer platform behind the Holyheld card. It exposes two integration surfaces: APIs for server-to-server settlement, and the SDK for embedding payment flows in apps.

What's the difference between the API and the SDK?

The APIs are for partners who need to programmatically register customers, monitor blockchain addresses, and trigger fiat settlements — typically as part of a compliance-governed payment workflow. All requests are server-side.

The SDK is for applications that need to initiate on-ramp or off-ramp transactions directly from a user-facing interface. It handles wallet interaction, smart contract calls, and transaction signing.

What currencies and tokens are supported?

Off-ramp and on-ramp settle in EUR. The SDK and API support a range of EVM-compatible tokens (USDC, USDT, ETH, and others) across multiple networks. See Supported Networks for the full list.

Authentication

How do I get an API key?

API keys are issued during the partner onboarding process. Contact your Holyheld point of contact to obtain or rotate a key.

Is there a test environment?

For SDK integrations, see Testing. API integrations should use the credentials and rollout process provided during onboarding.

Can I use my API key in frontend code?

No. Production API keys must be kept server-side. A leaked key grants access to your entire integration. The SDK uses a separate SDK API key, which has restricted scope and is safer to use in client code.

Onboarding & Customers

What KYC status is required before registering a customer?

Customers must have a SumSub KYC status of GREEN or FINISHED before registration. BRRR will not begin monitoring or settle transactions for customers who have not passed KYC.

Can a single customer have multiple wallet addresses?

Yes. Use POST /partner/customer/add-address to add additional addresses to an existing customer. Each address is monitored independently.

What happens if I register the same customer twice?

The API returns 400 CUSTOMER_EXISTS. This is safe to treat as a success if you were retrying a failed request — the original registration was processed.

Settlement

How long is a settlement quote valid?

Quotes expire after 15 minutes. If the user does not submit the on-chain transaction within that window, the quote status transitions to EXPIRED and you must request a new quote.

What are the terminal settlement statuses?

FINISHED (success) and ERROR (failed). The full status progression is:

CREATED → CONFIRMED → PROCESSING → SENT → FINISHED
                                        → ERROR

EXPIRED is also terminal — see Get Settlement Status for the full status reference.

What is FULFILLMENT_DENIED?

This means the settlement was rejected because the wallet or customer had a HIGH or VERY HIGH risk score at execution time.

Can I retry a failed Execute Settlement call?

Always call Get Settlement Status before retrying. If the original request was received, retrying with the same quoteId will return an error. Only retry if you have confirmed the settlement does not exist.

SDK

Do I need a wallet library to use the SDK?

Yes. The SDK integrates with Viem for EVM chains and requires a publicClient and walletClient. For Solana, you supply a Connection and Wallet adapter. See Web3 Providers for setup examples.

How does the user confirm an on-ramp?

After calling requestOnRamp, the user must open the Holyheld mobile app and approve the request within 3 minutes. There is no in-browser confirmation step. Use watchRequestId to listen for the result.

What happens if the user rejects the transaction in their wallet?

The SDK throws an error with code UserRejectedTransaction or UserRejectedSignature. Catch this specifically and prompt the user to try again — it does not indicate a settlement problem.

Payments for AI Agents

What is the Payments for AI Agents API?

It is an HTTP API that lets an AI agent autonomously manage a Holyheld card. An agent can call GET /balance to read the current EUR balance, GET /card-data to retrieve card details for checkout, and POST /topup-request to transfer funds from the Holyheld main account to the card. The agent acts on behalf of a single user's own Holyheld account.

This is separate from the APIs, which are for platform developers managing settlement flows for multiple end users.

How is the Bearer token different from the API key?

They are entirely different credentials:

	APIs	Payments for AI Agents
Header	X-Api-Key	Authorization: Bearer <token>
Obtained via	Holyheld partner onboarding	Agent instructions for a Holyheld card
Scope	Partner's entire integration	One user's card top-up capability
Base URL	https://api.brrr.network	https://apicore.holyheld.com/v4/ai-agents

The two keys cannot be used interchangeably.

How do I set a spending limit for an agent?

When you enable agent access for a Holyheld card, you can configure a cumulative spending limit — the maximum total EUR amount the agent may top up across all requests. The limit applies to that card's agent access, not to a chat session.

Can an agent reset its own spending limit?

No. When an agent reaches its spending limit, the API returns AI_TOPUP_LIMIT_EXCEEDED. The agent cannot reset this limit — only the user can, from the Holyheld dashboard. A well-behaved agent should surface this to the user immediately and stop retrying.

How long does a card top-up take to appear?

The POST /topup-request response confirms the request was accepted. The actual balance update is asynchronous and typically takes 1–3 minutes, but may take up to 5 minutes during high network load. Agents should poll GET /balance every 30 seconds for up to 5 minutes to confirm settlement.

Can an agent retrieve card details?

Yes. GET /card-data returns the card number, expiration date, CVV, cardholder name, and billing address. Because this is sensitive payment data, agents should fetch it only when actively completing a payment flow, never log it, and avoid storing it longer than necessary.

Is the top-up endpoint idempotent?

No. Each call to POST /topup-request creates a new top-up request. If you receive a network error and are unsure whether the request was accepted, check whether the balance has already moved before deciding to retry. See Agent Patterns for the safe retry sequence.

Regions & Compliance

Which countries support off-ramp and on-ramp?

Off-ramp and on-ramp are available in 31 countries across the European Economic Area and Switzerland. See Supported Regions for the full country-by-country breakdown.

Are there restricted countries?

Yes. Customers located in sanctioned countries cannot use any BRRR feature. Attempting to onboard such customers will be rejected at the KYC stage. The restricted list is included in the Supported Regions table.