Balances

Who calls these endpoints?External API (s2s)

Base path: /api/v1/wallet
Identity: Ed25519 request signature — X-Key-Id, X-Date, X-Nonce, Digest (when there is a body), X-Signature. ±5 min clock window, single-use nonce, optional per-key IP allow-list.
Authorization: The key must carry the wallet product and the wallet permission the call requires; a call without it gets 403 WALLET_INSUFFICIENT_SCOPE. Permissions per endpoint: Key permissions.
Cross-surface: The same read exists in the merchant panel; the end user reads their own balance through the portal. This endpoint requires a wallet read permission (wallet:enduser:read) on your key.

GET /api/v1/wallet/end-users/{id}/balances

Returns the balance of every account in every wallet of the user in a single response. Balances are read from the ledger; wallet records do not hold a separate balance.

curl "https://api-gateway.lunixi.com/api/v1/wallet/end-users/8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34/balances" \
  -H "X-Key-Id: …" -H "X-Date: …" -H "X-Nonce: …" -H "X-Signature: …"

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "balances": [
      {
        "walletAccountId": "c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47",
        "walletId": "1e7f9a3b-5c2d-4a8e-b6f1-3d9c0e2a7b58",
        "currency": "TRY",
        "balance": "25000",
        "fullWalletNo": "58107634125000",
        "fromCache": false
      },
      {
        "walletAccountId": "7b4e1c9a-2f6d-4a3b-9e8c-1d5f7a2b6c90",
        "walletId": "1e7f9a3b-5c2d-4a8e-b6f1-3d9c0e2a7b58",
        "currency": "USD",
        "balance": "0",
        "fullWalletNo": "58107634125100",
        "fromCache": true
      }
    ]
  },
  "requestId": "…"
}

Fields

Field	Type	Meaning
`walletAccountId`	UUID	The account id. Send this value as the source or destination account in money movements.
`walletId`	UUID	The wallet holding the account.
`currency`	string	The account currency.
`balance`	string	Balance as a minor-unit digit string: `"25000"` = ₺250.00. An account with no activity returns `"0"`.
`fullWalletNo`	string	The account number: the 10-digit `walletNo` + a 4-digit account code.
`fromCache`	boolean	`true` means the value came from a short-lived cache (at most 30 seconds old); `false` means it was read directly from the ledger.

The cache is kept per account; in the same response one account can be fromCache: true and another false. To show the user the fee of an operation and whether their balance is sufficient, use the relevant quote endpoint instead of this one (for example the transfer quote); the quote response returns the source balance and the sufficiency result (sufficientBalance) together.

Blocked amounts

balance shows the available balance. Blocked amounts (for example an amount set aside for a card authorization or a cash-out code) are not included in this field; this response has no separate blocked field. When a block is released, the amount is added back to balance.

Scope

Every account in every wallet of the user is returned; it is not limited to the default wallet.
The balance can be read whatever the user's status (FROZEN, CLOSED).
Store and compare amounts without converting them to floating point (for example with BigInt), so that no precision is lost.

Errors

HTTP	Code	When
400	—	`{id}` is not a UUID
403	`WALLET_INSUFFICIENT_SCOPE`	The key has no wallet read permission
404	`WALLET_NOT_FOUND`	The user does not exist or is not yours
503	`WALLET_LEDGER_UNAVAILABLE`	The balance could not be read from the ledger at that moment; retry shortly

Freeze Limit Status