Skip to main content
GET
/
api
/
transactions
/
balance
Get Balance
curl --request GET \
  --url https://api.example.com/api/transactions/balance \
  --header 'Authorization: <authorization>'
{
  "401": {},
  "500": {},
  "netWorth": {}
}

​
Authentication

This endpoint requires authentication using a Bearer token.
​
Authorization
string
required
Bearer token for authentication

​
Description

This endpoint calculates the user’s total net worth by aggregating balances from all their accounts, grouped by currency. This provides a quick overview of the user’s total assets across different currencies.

​
Calculation Logic

The balance is calculated as follows:
  1. Fetch all accounts belonging to the authenticated user
  2. Group accounts by their currency
  3. Sum the balance for each currency group
  4. Return an object with currency codes as keys and total balances as values
Note: This endpoint does NOT calculate balances from transactions directly. Instead, it reads the current balance field from each account, which is automatically maintained by the create, update, and delete transaction endpoints.

​
Response

​
netWorth
object
Object containing balance by currency. Keys are currency codes (e.g., “ARS”, “USD”, “EUR”) and values are the total balance in that currency.

​
Error Responses

​
401
error
Unauthorized - Missing or invalid authentication token
​
500
error
Internal Server Error - Database error while calculating balance

​
Example Request

curl -X GET https://api.yourfinanceapp.com/api/transactions/balance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Example Response

{
  "netWorth": {
    "ARS": 125000.50,
    "USD": 5430.25,
    "EUR": 1200.00
  }
}

​
Example Scenarios

​
Scenario 1: Single Currency User

User has 3 accounts, all in ARS:
  • Checking Account: $50,000 ARS
  • Savings Account: $75,000.50 ARS
  • Emergency Fund: $0 ARS
Response: 
{
  "netWorth": {
    "ARS": 125000.50
  }
}

​
Scenario 2: Multi-Currency User

User has accounts in multiple currencies:
  • ARS Wallet: $85,000 ARS
  • ARS Savings: $40,000.50 ARS
  • USD Account: $5,430.25 USD
  • EUR Savings: $1,200.00 EUR
Response: 
{
  "netWorth": {
    "ARS": 125000.50,
    "USD": 5430.25,
    "EUR": 1200.00
  }
}

​
Scenario 3: New User with No Accounts

User has no accounts created yet. Response: 
{
  "netWorth": {}
}

​
Notes

  • This endpoint does not perform currency conversion. Each currency is totaled separately.
  • The balance reflects the current state of accounts, including all completed transactions.
  • Soft-deleted transactions do not affect the balance (their impact was already reversed upon deletion).
  • Zero-balance accounts are included in the calculation (contributing 0 to their currency total).
  • If a user has no accounts in a particular currency, that currency will not appear in the response.
  • The endpoint is optimized to only fetch balance and currency fields from the accounts table.

Build docs developers (and LLMs) love

Get started for freeTalk to us