Balance

Every Bitcall product spends from the same balance. An OTP rental, an eSIM purchase, an SMS send and an HLR lookup all draw on one account, so there is one endpoint to read it:

GET /v1/balance

Full schema in the Account API Reference.

Use an account key. A tenant-owner (admin) key has no wallet of its own and answers 404. See Which keys can read a balance.

It takes no parameters

The account is identified by the API key itself. There is no id to pass and no way to ask for another account's balance:

curl https://api.bitcall.io/v1/balance \
  -H "x-key-id: $BITCALL_KEY_ID" \
  -H "x-api-secret: $BITCALL_API_SECRET"

{
  "balance": 42.5,
  "reserved": 12,
  "currency": "EUR"
}

currency is the ISO 4217 code your balance is denominated in — the unit these figures are measured in, straight off the ledger. It is absent only if your account declares no currency, in which case the figures are still exact and only the label is unknown. Read it rather than assuming one: no default is substituted for you.

`balance` and `reserved`

Field	What it is
`balance`	What you can spend right now, with holds and any credit limit already applied.
`reserved`	Funds committed to orders that have not settled yet.

When you place an order, its cost is held against your account immediately and only settles when the order finishes — captured if it succeeds, released back if it does not. reserved is the total currently sitting in that state.

Do not add them together. balance already excludes reserved. In the example above the account can spend 42.50 and has 12.00 held — not 54.50. Displaying a sum would overstate what the user can actually spend.

reserved is 0 when nothing is on hold. It is absent only if your account reports no held figure at all, so treat a missing field as "unknown", not as zero.

Both figures are a live reading, not an accounting one. A hold lands before its order completes, so neither will match the sum of your settled transactions. If you need a number that reconciles against invoices, use your transaction history — not this endpoint.

Using it before a purchase

Reading your balance first is useful for showing a user what they have — balance and reserved together are what you need to render "42.50 available, 12.00 on hold". It is not a reliable way to guarantee a purchase will succeed.

Between your balance check and your order, another request on the same account can spend the same funds — extra keys do not mean separate wallets. The authoritative check happens when the order is placed.

Do not gate purchases on this endpoint. Place the order and handle INSUFFICIENT_BALANCE, which is the only answer that actually settles the question. A pre-flight check can pass and the order still fail.

Which keys can read a balance

A balance belongs to an account. An account key reads its own and needs nothing else.

A tenant-owner (admin) key is not an account — it identifies the customer that owns the accounts, and no wallet is published for it. Such a key gets:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No such resource.",
    "requestId": "…"
  }
}

This 404 is permanent for that key — it is not a transient failure, and retrying will never change it. Read the balance with the account key whose balance you want.

Never cached

Responses carry Cache-Control: no-store, private. A balance is per-account and changes without warning, so it must not be written to any cache or proxy, yours included.

Errors

Status	Code	What it means
`401`	`AUTHENTICATION_REQUIRED`	No key was sent.
`401`	`INVALID_API_KEY`	The key is unknown, expired, or its account is not active.
`404`	`NOT_FOUND`	No wallet is published for this key — see above. Permanent; do not retry.
`429`	`RATE_LIMITED`	Too many requests — see Rate Limits.
`503`	`SERVICE_UNAVAILABLE`	The balance could not be read. Your key is fine; retry shortly.

A 503 here means we could not reach the ledger, not that your balance is zero. Never treat it as an empty account — retry instead.

See Errors for the full response format.