Accounts

Overview

Accounts represent your financial containers - where your money lives. Your Finance App supports multiple account types, each serving different purposes in your financial life.

Multiple Account Types

Wallets, Savings, Investments, and Credit Cards in one place

Multi-Currency

Each account has its own currency (ARS, USD, EUR)

Savings Goals

Set target amounts and track progress for savings accounts

Real-Time Balance

Automatic balance updates with every transaction

Account Types

Your Finance App supports four types of accounts:

WALLET

Your everyday spending account. Use it for:

Daily expenses
Bill payments
Regular income deposits

Wallets are your primary transaction accounts.

SAVINGS

Accounts for setting aside money for specific goals:

Emergency fund
Vacation savings
Large purchases

Savings accounts support target amounts and progress tracking.

INVESTMENT

Track your investment portfolios:

Stock accounts
Crypto wallets
Retirement accounts

Investment accounts help you monitor your net worth.

CREDIT_CARD

Manage credit card balances:

Track spending on credit
Monitor credit utilization
Plan repayments

Credit cards show as negative balances when you owe money.

Creating an Account

Create a new account with POST /accounts:

{
  "name": "Main Wallet",
  "type": "WALLET",
  "currency": "ARS",
  "color": "#10B981",
  "icon": "wallet"
}

Request Parameters

name

string

required

Account name (e.g., “Main Wallet”, “Emergency Fund”)

type

enum

required

Account type: WALLET, SAVINGS, INVESTMENT, or CREDIT_CARD

currency

enum

required

Currency code: ARS, USD, or EUR

color

string

Hex color code for visual identification (e.g., #10B981)

icon

string

Icon name (default: “wallet”)

targetAmount

number

Target amount for savings goals (SAVINGS accounts only)

targetDate

string

Target date for reaching savings goal (ISO date string)

Response

{
  "id": "uuid",
  "name": "Main Wallet",
  "type": "WALLET",
  "currency": "ARS",
  "balance": 0,
  "color": "#10B981",
  "icon": "wallet",
  "isDefault": false,
  "targetAmount": null,
  "targetDate": null,
  "userId": "user-uuid",
  "createdAt": "2026-03-04T10:00:00.000Z",
  "updatedAt": "2026-03-04T10:00:00.000Z"
}

New accounts always start with a balance of 0. Use the deposit endpoint or create income transactions to add funds.

Savings Goals

Set targets for SAVINGS accounts to track progress:

{
  "name": "Emergency Fund",
  "type": "SAVINGS",
  "currency": "USD",
  "targetAmount": 10000,
  "targetDate": "2027-01-01T00:00:00.000Z"
}

When listing accounts, the system calculates your progress:

{
  "id": "uuid",
  "name": "Emergency Fund",
  "type": "SAVINGS",
  "balance": 6500,
  "targetAmount": 10000,
  "targetDate": "2027-01-01T00:00:00.000Z",
  "progress": 65
}

Progress Calculation: Progress = (current balance / target amount) × 100, capped at 100%.

Listing Accounts

Get all your accounts with GET /accounts:

GET /accounts

Response:

[
  {
    "id": "uuid-1",
    "name": "Main Wallet",
    "type": "WALLET",
    "currency": "ARS",
    "balance": 125000.50,
    "color": "#10B981",
    "icon": "wallet",
    "isDefault": true,
    "targetAmount": null,
    "progress": 0
  },
  {
    "id": "uuid-2",
    "name": "Emergency Fund",
    "type": "SAVINGS",
    "currency": "USD",
    "balance": 6500,
    "color": "#F59E0B",
    "icon": "piggy-bank",
    "isDefault": false,
    "targetAmount": 10000,
    "progress": 65
  }
]

Accounts are sorted by creation date (oldest first).

Balance Tracking

Account balances update automatically when you:

Create a transaction
Update a transaction
Delete a transaction
Transfer between accounts
Make a deposit

Don’t Modify Balance Directly: The balance is calculated from transactions. Always create transactions to change balances, never edit the balance field directly.

Currency Rules

Each account has a fixed currency that cannot be changed:

Single Currency Per Account

Once created, an account’s currency is permanent. This ensures:

Clear transaction history
Accurate balance calculations
No currency conversion confusion

To work with multiple currencies, create separate accounts.

Transaction Currency Validation

All transactions on an account must match its currency:

// ❌ This will fail on an ARS account
{
  "accountId": "ars-account-uuid",
  "currency": "USD",
  "amount": 100
}

Error: “No puedes crear una transacción en USD en una cuenta configurada en ARS.”

Transferring Between Accounts

Move money between your accounts with POST /accounts/transfer:

{
  "sourceAccountId": "wallet-uuid",
  "targetAccountId": "savings-uuid",
  "amount": 5000,
  "description": "Monthly savings",
  "date": "2026-03-04T10:00:00.000Z"
}

Transfer Rules

Same Currency Required

Source and target accounts must have the same currency. Cross-currency transfers are not yet supported.

Sufficient Funds

The source account must have enough balance to cover the transfer amount.

Automatic Transactions

Transfers create two transactions:

TRANSFER (outgoing) from source account
INCOME (incoming) to target account

Both use the “Transferencia” category (created automatically).

Atomic Operation

The entire transfer succeeds or fails as one unit. You’ll never have money disappear.

Transfer Response

{
  "source": {
    "id": "wallet-uuid",
    "name": "Main Wallet",
    "balance": 120000.50
  },
  "target": {
    "id": "savings-uuid",
    "name": "Emergency Fund",
    "balance": 11500
  }
}

Depositing Funds

Add funds to an account (useful for testing) with POST /accounts/:id/deposit:

{
  "amount": 1000,
  "description": "Test deposit"
}

This creates an INCOME transaction and updates the balance.

The deposit endpoint is primarily for testing. In production, create regular income transactions instead.

Updating Accounts

Update account properties with PATCH /accounts/:id:

{
  "name": "Primary Wallet",
  "color": "#3B82F6",
  "targetAmount": 15000
}

You can update:

Name
Color
Icon
Target amount (for SAVINGS accounts)
Target date (for SAVINGS accounts)
Default status

Cannot Change: Account type and currency cannot be modified after creation.

Default Account

Mark one account as default for quick access:

PATCH /accounts/:id
{
  "isDefault": true
}

Default accounts can be used for:

Quick transaction creation in mobile apps
Automatic transaction assignment
Dashboard primary view

Deleting Accounts

Delete an account with DELETE /accounts/:id:

DELETE /accounts/:id

Deletion Rules

Cannot Delete Default

You cannot delete an account marked as default. Set another account as default first.

Transactions Remain

Deleting an account doesn’t delete its transactions. They remain in the database for historical records.

Hard Delete

Unlike categories and transactions, accounts are hard-deleted (permanently removed).

Best Practice: Before deleting an account, transfer its balance to another account to maintain accurate net worth.

Best Practices

Separate Currencies

Create one account per currency you use regularly. This makes tracking and reporting easier.

Name Descriptively

Use clear names like “USD Savings” or “Daily ARS Wallet” instead of “Account 1”.

Set Realistic Goals

For savings accounts, set achievable target amounts based on your income and timeline.

Use Colors Consistently

Group related accounts with similar colors (e.g., all USD accounts in blue).

Review Regularly

Check your account balances weekly to catch any unexpected changes.

Common Workflows

Setting Up Your Accounts

# 1. Create primary wallet
POST /accounts
{
  "name": "Main ARS Wallet",
  "type": "WALLET",
  "currency": "ARS",
  "color": "#10B981"
}

# 2. Create savings account with goal
POST /accounts
{
  "name": "Emergency Fund",
  "type": "SAVINGS",
  "currency": "USD",
  "targetAmount": 10000,
  "targetDate": "2027-12-31T00:00:00.000Z",
  "color": "#F59E0B"
}

# 3. Set primary wallet as default
PATCH /accounts/:id
{
  "isDefault": true
}

Monthly Savings Routine

# Transfer to savings on payday
POST /accounts/transfer
{
  "sourceAccountId": "wallet-uuid",
  "targetAccountId": "savings-uuid",
  "amount": 5000,
  "description": "Monthly savings - March 2026"
}

# Check progress
GET /accounts
# Look at the "progress" field in the savings account

Get Started

Architecture

Core Features

Advanced

Overview

Multiple Account Types

Multi-Currency

Savings Goals

Real-Time Balance

Account Types

Creating an Account

Request Parameters

Response

Savings Goals

Listing Accounts

Balance Tracking

Currency Rules

Transferring Between Accounts

Transfer Rules

Transfer Response

Depositing Funds

Updating Accounts

Default Account

Deleting Accounts

Deletion Rules

Best Practices

Common Workflows

Setting Up Your Accounts

Monthly Savings Routine

Build docs developers (and LLMs) love

Get Started

Architecture

Core Features

Advanced

​Overview

Multiple Account Types

Multi-Currency

Savings Goals

Real-Time Balance

​Account Types

​Creating an Account

​Request Parameters

​Response

​Savings Goals

​Listing Accounts

​Balance Tracking

​Currency Rules

​Transferring Between Accounts

​Transfer Rules

​Transfer Response

​Depositing Funds

​Updating Accounts

​Default Account

​Deleting Accounts

​Deletion Rules

​Best Practices

​Common Workflows

​Setting Up Your Accounts

​Monthly Savings Routine

Build docs developers (and LLMs) love

Overview

Account Types

Creating an Account

Request Parameters

Response

Savings Goals

Listing Accounts

Balance Tracking

Currency Rules

Transferring Between Accounts

Transfer Rules

Transfer Response

Depositing Funds

Updating Accounts

Default Account

Deleting Accounts

Deletion Rules

Best Practices

Common Workflows

Setting Up Your Accounts

Monthly Savings Routine