API Authentication

All API requests must be authenticated using an API key passed as a request header. There is no OAuth flow or token exchange — the key is sent directly with every request.

Authentication header

Include this header in every request:

X-Api-Key: <your API key>

Complete request example

curl

curl -X POST https://api.brrr.network/api/v4/partner/customer/register \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerId": "cust_a1b2c3", "addressEVM": "0xAbCd...1234"}'

JavaScript

const response = await fetch('https://api.brrr.network/api/v4/partner/customer/register', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.BRRR_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customerId: 'cust_a1b2c3',
    addressEVM: '0xAbCd...1234',
  }),
});
const data = await response.json();

Python

import httpx, os

response = httpx.post(
    'https://api.brrr.network/api/v4/partner/customer/register',
    headers={'X-Api-Key': os.environ['BRRR_API_KEY']},
    json={'customerId': 'cust_a1b2c3', 'addressEVM': '0xAbCd...1234'},
)
data = response.json()

Security best practices

• Server-side only — never include your API key in client-side JavaScript, mobile apps, or public repositories. All requests must originate from your backend.
• Environment variables — store the key in an environment variable (BRRR_API_KEY), not hardcoded in source files.
• Rotate on compromise — if you suspect your key has been exposed, contact support@holyheld.com immediately. Do not wait — a leaked key allows anyone to make requests on your behalf.

Rate limits

The APIs enforce rate limits per API key. Requests that exceed the limit receive a 429 Too Many Requests response.

Recommended handling:

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.

Authentication errors

A missing or invalid key returns 403 Forbidden:

{
  "status": "error",
  "error": "Access denied",
  "errorCode": "ACCESS_DENIED"
}

Verify that:

1. The X-Api-Key header is present in every request
2. The key value is correct and has not expired or been revoked
3. You are not sending the key as a query parameter — it must be a header