Skip to content

Balance & Transactions

Get balance

GET /accounts/{account_id}/balance

Returns the current USDC balance directly from the ledger.

{
  "account_id": "3f8a1b2c-...",
  "balance_usdc": 42.50,
  "currency": "USDC"
}

List transactions

GET /accounts/{account_id}/transactions

Returns the transaction history for an account, sorted newest first.

Query parameters:

Parameter Default Description
type (all) Filter by type: deposit or withdrawal
status (all) Filter by status: pending, completed, failed
created_from — Return transactions on or after this timestamp (ISO 8601)
created_to — Return transactions on or before this timestamp (ISO 8601)
limit 20 Results per page (max 100)
page 1 Page number

Response:

{
  "account_id": "3f8a1b2c-...",
  "total_count": 5,
  "page": 1,
  "limit": 20,
  "transactions": [
    {
      "transaction_id": "tx-uuid-...",
      "transaction_type": "deposit",
      "status": "completed",
      "fiat_amount": 5000.0,
      "crypto_amount": 38.07,
      "exchange_rate": 131.35,
      "currency": "KES",
      "created_at": "2026-07-20T10:00:00Z"
    }
  ]
}

List all transactions (bulk)

GET /transactions

Returns transaction history across all accounts in your tenant, sorted newest first. Each row includes external_user_id so you can match transactions back to your own user records without a separate lookup.

Use this for reconciliation exports and accounting integrations. For single-account history use GET /accounts/{account_id}/transactions.

Query parameters:

Parameter Default Description
account_id (all) Optionally filter to a specific account
type (all) deposit or withdrawal
status (all) pending, completed, or failed
created_from — ISO 8601 lower bound on created_at
created_to — ISO 8601 upper bound on created_at
limit 20 Results per page (max 100)
page 1 Page number

Response:

{
  "total_count": 312,
  "page": 1,
  "limit": 20,
  "transactions": [
    {
      "transaction_id": "tx-uuid-...",
      "account_id": "3f8a1b2c-...",
      "external_user_id": "your-internal-user-id",
      "transaction_type": "deposit",
      "status": "completed",
      "fiat_amount": 5000.0,
      "crypto_amount": 38.07,
      "exchange_rate": 131.35,
      "fee": 0.38,
      "currency": "KES",
      "created_at": "2026-07-20T10:00:00Z",
      "updated_at": "2026-07-20T10:01:30Z"
    }
  ]
}

Get transaction by ID

GET /transactions/{transaction_id}

Retrieves any transaction by its ID across all accounts in your tenant. Returns 404 for transactions that don't belong to your tenant (to avoid leaking cross-tenant existence).

{
  "status": "success",
  "data": {
    "transaction_id": "tx-uuid-...",
    "transaction_type": "deposit",
    "status": "completed",
    "fiat_amount": 5000.0,
    "crypto_amount": 38.07,
    "exchange_rate": 131.35,
    "currency": "KES",
    "created_at": "2026-07-20T10:00:00Z"
  }
}