APIs Introduction

BRRR's APIs are organised into four independent products. Each one is summarised on the API Sections page, which also includes flow diagrams and endpoint tables.

Section	What it does
Web3 API	Blockchain-related read helpers: tokens, balances, price charts, holytag info. Useful for building rich UI around crypto.
OTC API	Simple crypto ↔ EUR OTC settlement for BRRR partners with registered IBANs.
Multi-tenant Settlement API	Partners settle crypto to EUR bank accounts of their own customers, with risk scanning integrated into the flow.
Card API	Integration with individual Holyheld customers: offramp to card or SEPA, onramp to buy crypto. 2FA confirmation required from the customer's Holyheld App.

API endpoint

All API requests must be sent to the following HTTPS endpoint:

https://api.brrr.network

This endpoint is shared across all integrations. Authentication and access control are handled using API keys — see Authentication.

Request format

All requests must use HTTPS. Request bodies must be JSON with the Content-Type: application/json header. Responses are always JSON.

Timestamps in request and response bodies are Unix timestamps in seconds unless otherwise noted.

Rate limits

The APIs enforce rate limits per API key. Requests that exceed the limit receive a 429 Too Many Requests response with a Retry-After header indicating when to retry.

Use exponential backoff when handling 429 responses:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const retryAfter = parseInt(response.headers.get('Retry-After') ?? '1', 10);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000 * Math.pow(2, attempt)));
  }
  throw new Error('Max retries exceeded');
}

Contact your Holyheld point of contact for information about rate limit thresholds for your integration tier.

Idempotency

Understanding which API operations are safe to retry is important for building reliable integrations.

Idempotent by design (safe to retry):

Operation	Behaviour on repeat call
GET requests (risk scores, settlement status, rates)	Always safe — read-only, no side effects.
Register a customer (POST /partner/customer/register)	Returns CUSTOMER_EXISTS (400) if the customerId is already registered. Your system can treat this as a success if you were retrying a registration.
Add address to a customer (POST /partner/customer/add-address)	Returns ADDRESS_EXISTS (400) if the address is already registered.

Not idempotent — do not retry without checking:

Operation	Risk
Create Settlement Quote (POST /partner/settlement/quote)	Each call creates a new quote with a new quoteId and a new 15-minute expiry window.
Execute Settlement (POST /partner/settlement/execute)	Submitting the same quoteId twice returns an error (quote already executed). Always check settlement status before retrying.

Check before retrying settlements

If a network error prevents you from receiving the Execute Settlement response, call Get Settlement Status using the quoteId before retrying. The settlement may have already been accepted.

Next steps

Start by authenticating your requests — see Authentication. Then open API Sections to find the section, flow diagram, and endpoint list that match your integration.