Wallets

Current, held and available balance of one wallet

GET/api/v1/tenant/wallets/{uid}/balance

Scope wallets:read

Path parameters

Name	Type	Required	Description
uid	string	yes

Response · 200

Field	Type	Description
walletUid	string
currency	string
currentMinor	number	Integer minor units (e.g. 250000 = ETB 2,500.00).
heldMinor	number	Minor units.
availableMinor	number	Minor units; the only figure a debit is authorized against.
status	enum	One of pending, active, debit_blocked, credit_blocked, frozen, dormant, closed.
asOf	string	When the balance last changed.

Example (generated from the schema)

{
  "walletUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "currency": "ETB",
  "currentMinor": 0,
  "heldMinor": 0,
  "availableMinor": 0,
  "status": "pending",
  "asOf": "string"
}

Errors

400 401 403 404 429 500 503 — one body shape for all of them, see Errors.

Paginated statement of one wallet, newest first

GET/api/v1/tenant/wallets/{uid}/transactions

Scope wallets:read

Only operations that have moved funds or reached a final state are listed unless includePending=true. For a closed period (from/to in the past) the same query returns the same rows whenever it is asked: history is never changed.

Path parameters

Name	Type	Required	Description
uid	string	yes

Query parameters

Name	Type	Required	Description
type	string	no	Operation type code
state	string	no	Operation state
from	string	no	ISO-8601 instant, inclusive lower bound on createdAt
to	string	no	ISO-8601 instant, inclusive upper bound on createdAt
includePending	boolean	no	Also list in-flight operations
page	number	no	Page to retrieve, 1-based. Example: 1 Default Value: 1
limit	number	no	Records per page. Values above the maximum are clamped, not rejected. Default Value: 20 Max Value: 100
sortBy	enum[]	no	Sort key. Repeat the param to sort by several fields; URL order sets precedence. Format: fieldName:DIRECTION Example: sortBy=createdAt:DESC&sortBy=id:ASC Default Value: createdAt:DESC,id:DESC Available Fields createdAt id Any other field is rejected with 400.

Response · 200

Field	Type	Description
data	object[]
data[].operationUid	string
data[].amountMinor	number	Integer minor units (e.g. 250000 = ETB 2,500.00).
data[].feeMinor	number	Minor units.
data[].taxMinor	number	Minor units.
data[].direction	enum	Relative to the wallet in the path. One of inbound, outbound.
data[].state	string	Operation state: created, awaiting_authorization, authorized, held, processing, pending_provider, confirmed, failed, reversed or completed.
data[].clientReference	object | null	Your reference, exactly as you supplied it.
data[].counterpartyHint	object | null	Masked; never the clear counterparty.
data[].createdAt	string
data[].completedAt	object | null
data[].receipt	string	API-relative path of the receipt (GET /tenant/operations/{uid}/receipt).
meta	object
meta.total	number
meta.page	number
meta.limit	number
meta.totalPages	number

Example (generated from the schema)

{
  "data": [
    {
      "operationUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
      "amountMinor": 0,
      "feeMinor": 0,
      "taxMinor": 0,
      "direction": "inbound",
      "state": "string",
      "clientReference": {},
      "counterpartyHint": {},
      "createdAt": "2026-09-03T10:15:30.000Z",
      "completedAt": {},
      "receipt": "string"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

Errors

400 401 403 404 429 500 503 — one body shape for all of them, see Errors.