Balances
The account you hold with us, what the number means, how fresh it is, and why it is not the number to build a spending check on.
GET /v1/balances returns the account you hold with us and what is available
in it.
Response — 200 OK:
{
"kes": {
"available": "150000.50",
"accountNumber": "00000000123456",
"currency": "KES",
"asOf": "2026-09-08T12:00:00.000Z"
}
}It needs the balances:read scope. See
Products and scopes.
What each field is for
available is a decimal string in shillings and cents, like every other
amount on this API — never a JSON number. Convert it to integer minor units at
your boundary and do arithmetic there. See Money.
accountNumber is the same account your inbound instructions point at, so
a credit you see arrive and the balance you read afterwards are the same
account. Receive money in Kenya is how
money gets there.
asOf is the instant the figure was read. It can be up to thirty seconds
behind, because the balance is cached for that long rather than fetched on
every call. Show it wherever you show the number: a balance with no timestamp
invites a reader to treat it as live.
It is a reading, not a fact about now
Do not treat a balance you read as live
Reading a balance tells you what was available when it was read, up to thirty seconds before the call returned. It holds nothing and reserves nothing, and a credit can land between the read and whatever you do with the figure.
Use it for what a reading is good for: displaying a figure beside its asOf,
and reconciling at the end of a period against the credits we attributed to
your orders. Nothing on this API draws on this balance today — shillings leave
on a sell order, to a bank account you registered — so it is not a spending
check, and it should not be the number a decision waits on.
When there is no account to report
503 with PARTNER_VA_NOT_ALLOCATED, PARTNER_VA_ACTIVATING or
PARTNER_VA_SUSPENDED means there is no active account behind the balance
yet. None of the three is self-serve and none is worth retrying in a tight
loop — see Errors for what each one means and what to do.
What is not here yet
The response carries your KES account. It does not carry a USDT figure: your
USDT position is the deposit address on GET /v1/funding and the orders you
have open against it, and there is no balance endpoint for it today.