Retrieve the balance for a specific currency so you can confirm whether your organization is ready to quote, fund, or execute a transaction.

⏱️
Time to integrate: Most teams can validate this endpoint in under 5 minutes once authentication is working and they know which currency they need to check.

What this endpoint does

Use this endpoint to retrieve the balance for a specific currency in your NadaPay organization.

This is the fastest way to confirm whether you have the available balance needed for a transaction flow in that currency.

When to call this endpoint

Call this endpoint when you need to:

confirm available balance before generating a quote
check funding readiness before executing a transaction
monitor treasury position for a specific currency
troubleshoot failed transactions caused by insufficient funds

For most payout and treasury workflows, this endpoint should be checked before transaction execution.

How this differs from fetching all accounts

Use the accounts endpoint when you need to see the full account inventory for the organization.

Use the currency balance endpoint when you already know which currency matters and you need a direct funding check for that specific balance.

Authentication

Send your API key in the x-api-key header on every request.

Item	Value
Authentication method	API key
Required header	`x-api-key`
Rate limit scope	Per API key

Recommended workflow

Use this endpoint in the core operating sequence:

Fetch organization accounts.
Check verification status.
Create a beneficiary.
Add a beneficiary account.
Resolve bank account details if required.
Check the source currency balance.
Generate a quote.
Recheck balance if needed before execution.
Execute the transaction.

What to verify before using the result

Before you rely on this balance in a transaction flow, confirm:

you are checking the intended currency
the environment matches the credentials you are using
the balance belongs to the correct organization account context
your internal workflow understands whether the returned amount is available, pending, or otherwise restricted

⚠️
Needs confirmation: The exact response fields, balance semantics, available versus pending amounts, and currency parameter format should be confirmed in the API definition.

How to use the response

Use the returned balance to decide whether your flow can continue.

If the balance is sufficient

You can proceed to:

generate a quote
execute a transaction
continue treasury or reconciliation workflows

If the balance is insufficient

You should:

pause execution
fund the account or use the correct account if another source is available
recheck the balance before retrying

Common use cases

Pre-execution funding check

Confirm the account has enough balance in the required currency before using a quote for execution.

Treasury monitoring

Use this endpoint in internal dashboards or monitoring jobs to track operational balances by currency.

Failed transaction investigation

If a transaction fails because funds are unavailable, use this endpoint to verify current balance before retrying.

Production notes

Before using this endpoint in production:

Define when your system checks balance in the transaction flow.
Decide whether your application should recheck balance immediately before execution.
Log balance checks that influence quote or execution decisions.
Separate scheduled treasury checks from user-triggered transaction flows where possible.

For live transaction systems, stale balance assumptions are risky. Recheck close to execution when the business impact is material.

Common failure cases

Authentication fails

Check these items first:

the x-api-key header is present
the API key belongs to the intended environment
the base URL is correct

The balance looks wrong or unexpected

If the returned amount does not match what your team expects:

confirm you are checking the correct currency
confirm you are in the intended environment
compare the result against recent funding, execution, or reconciliation activity
verify whether your workflow should distinguish between total and available balance

A transaction still fails after a positive balance check

If execution fails even though balance was checked earlier:

recheck the current balance close to execution time
verify the quote still matches the intended transaction
verify the correct source account and currency were used
review any concurrent activity that may have consumed the balance

Repeated balance polling hits limits

Because rate limits are enforced per API key:

avoid unnecessary high-frequency polling
cache balance data for low-risk read-only views when appropriate
use tighter polling only for operational workflows that truly require it

⚠️
Needs confirmation: Exact rate limit thresholds, error codes, and whether balance values are strongly consistent or eventually updated should be documented from the API schema and backend behavior.

Enterprise implementation notes

Access control

Restrict balance visibility to services and operators that need treasury or transaction-readiness access.

Auditability

Record:

currency checked
returned balance value used in a decision
request timestamp
initiating service or user
related quote or transaction reference when applicable

Monitoring

Track:

low-balance conditions by currency
repeated insufficient-funds failures
unusual balance drops before batch execution windows
repeated polling behavior per API key

Troubleshooting checklist

Use this checklist if funding readiness is blocking your flow:

Confirm authentication with x-api-key.
Confirm you are checking the correct currency.
Confirm you are using the correct environment.
Confirm the balance is sufficient for the intended flow.
Recheck balance close to execution if there was any delay.
Continue to quote or execution only after the result is trusted.

Recommended next endpoints

After you check currency balance, continue with:

Related pages

Fetch all accounts belonging to the organization

Use the accounts list to find the right account context before checking a currency-specific balance.

Generate Quote

Confirm funding readiness before pricing the transaction.

Get Deposit Instructions

Retrieve funding instructions if the required balance is not yet available.