Balance Reconciliation

The platform provides a unified accounting layer across all 60+ blockchains — a single source of truth for balances, transactions, and fees. This guide covers how to use the accounting API to validate balances, generate statements, and build automated reconciliation pipelines that feed your internal ledger, ERP, or compliance systems.

Balance Levels

The platform provides balances at three levels of granularity:

Level	Endpoint	Use Case
Vault	GET /vaults/{id}?relations[]=balances	High-level treasury overview
Account	GET /accounts/{id}?relations[]=balances	Per-customer or per-department balances
Address	GET /addresses/{id}	Per-address balance (includes all assets)

Real-Time Balances

Vault Balances

curl -H "Authorization: Bearer $TOKEN" \
     "https://api.carabaas.com/api/v1/vaults/{vaultId}?relations[]=balances"

Response includes per-network, per-asset balances with both raw and formatted amounts:

{
  "data": {
    "balances": [
      {
        "network": "ethereum-mainnet",
        "asset": "c1",
        "amount": "5000000000000000000",
        "amountFormatted": "5.0",
        "availableBalance": "4800000000000000000",
        "availableBalanceFormatted": "4.8"
      }
    ]
  }
}

The availableBalance reflects the balance minus any pending outgoing transactions.

Top Addresses by Balance

Identify the largest addresses in a vault:

curl -H "Authorization: Bearer $TOKEN" \
     https://api.carabaas.com/api/v1/accounting/vaults/{vaultId}/top

Historical Statements

Generate balance snapshots for a date range:

curl -H "Authorization: Bearer $TOKEN" \
     "https://api.carabaas.com/api/v1/accounting/statements?startDate=2026-01-01&endDate=2026-01-31&vaultId=kR7mNpX2wQvL9sYhBjD4eT"

Filter Options

Parameter	Description
startDate	Start date (YYYY-MM-DD)
endDate	End date (YYYY-MM-DD)
vaultId	Filter by vault
accountId	Filter by account
network	Filter by network
filter[asset]	Filter by specific asset

Accounting Transactions

List transactions with balance change details for reconciliation:

curl -H "Authorization: Bearer $TOKEN" \
     "https://api.carabaas.com/api/v1/accounting/transactions?organizationId=djk2wDuMhsx9KR2r7JgBQW"

Each transaction includes detailed balanceChanges — the exact amounts credited or debited per address, including fee breakdowns.

Reconciliation Pipeline

Recommended Architecture

Steps

1. Capture events — subscribe to all three webhook streams (incoming, outgoing, blockchain)
2. Queue processing — process events asynchronously to handle bursts
3. Validate balances — after processing each event, verify the balance via API
4. Update ledger — update your internal ledger only after validation
5. Periodic reconciliation — run daily/hourly balance comparisons between your ledger and the platform

Daily Reconciliation

Compare your internal ledger against historical statements:

curl -H "Authorization: Bearer $TOKEN" \
     "https://api.carabaas.com/api/v1/accounting/statements?startDate=2026-04-19&endDate=2026-04-19&vaultId=kR7mNpX2wQvL9sYhBjD4eT"

Flag any discrepancies for investigation.

Best Practices

• Never credit users based solely on webhooks — always validate via the API
• Track the orderId — use it as the primary key for deposit/withdrawal reconciliation
• Monitor availableBalance — it accounts for pending transactions
• Use balanceChanges from webhooks — they include fee breakdowns for accurate accounting
• Run periodic full reconciliation — compare your ledger against platform statements daily
• Retain transaction history — store all webhook events and API responses for audit

See Also

• Accounting & Statements
• Webhooks
• Processing Deposits