Get Balance

Query the available EUR balance on the Holyheld card. Use this before deciding whether to top up, and again after a top-up to confirm the balance has updated.

Endpoint

GET https://apicore.holyheld.com/v4/ai-agents/balance

Request

No request body. Authentication is the only required input.

Header	Required	Value
Authorization	✅	Bearer <token>

Response

200 OK

{
  "status": "ok",
  "payload": {
    "balance": "94.20"
  }
}

Field	Type	Description
status	"ok"	Always "ok" on success
payload.balance	string	Available balance in EUR, formatted as a decimal string with up to 2 decimal places

The balance is returned as a string, not a number. Parse it with parseFloat() before comparisons.

Examples

curl

curl https://apicore.holyheld.com/v4/ai-agents/balance \
  -H "Authorization: Bearer $HOLYHELD_AGENT_TOKEN"

JavaScript

async function getBalance(token) {
  const response = await fetch(
    'https://apicore.holyheld.com/v4/ai-agents/balance',
    {
      headers: { Authorization: `Bearer ${token}` },
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.errorCode}: ${error.error}`);
  }

  const { payload } = await response.json();
  return parseFloat(payload.balance); // Returns a number, e.g. 94.20
}

Python

import httpx

def get_balance(token: str) -> float:
    response = httpx.get(
        'https://apicore.holyheld.com/v4/ai-agents/balance',
        headers={'Authorization': f'Bearer {token}'},
    )
    response.raise_for_status()
    return float(response.json()['payload']['balance'])

Example response

{
  "status": "ok",
  "payload": {
    "balance": "42.02"
  }
}

When to call this endpoint

Before a top-up — check the current balance to determine how much to add, or whether a top-up is necessary at all.

After a top-up — poll this endpoint to confirm the balance has increased. Top-up settlement takes up to 5 minutes; see Top Up Card for the full polling pattern.

On a schedule — if implementing threshold-based auto top-up, call this endpoint periodically (e.g. every 5 minutes) and trigger a top-up when balance drops below your threshold.

Error responses

HTTP status	Error code	Meaning
401	AI_AUTHORIZATION_INVALID	Authorization header missing
403	AI_AUTHORIZATION_INVALID	Token invalid or agent access disabled
500	INTERNAL_SERVER_ERROR	Server error — retry with backoff

All error responses follow this shape:

{
  "status": "error",
  "errorCode": "AI_AUTHORIZATION_INVALID",
  "error": "Authorization header missing"
}

See Error Reference for recovery guidance on each error code.

Next steps

Ready to add funds? See Top Up Card for the full top-up flow including the async polling pattern.