Amounts & Balances

The Lunch Money API uses four properties — amount, balance, currency, and to_base — consistently across all objects that deal with money. Understanding how they work will help you build accurate, multi-currency-aware integrations.

amount

amount is a string representation of a monetary value, precise to up to four decimal places. It appears on transactions, child transactions, recurring items, budget objects, and rollover pool adjustments.

"amount": "12.5000"

amount is always expressed in the currency specified by the companion currency property on the same object. Amounts are never rounded or converted.

balance

balance is a string representation of an account's running balance, also precise to up to four decimal places. It appears on manual accounts, Plaid accounts, crypto accounts, and balance history entries.

"balance": "1500.0000"

Like amount, balance is always in the currency of the same object and follows the same sign convention.

currency

currency is an ISO 4217 currency code (e.g., "usd", "eur", "gbp"). It is present on every object that carries an amount or balance and tells you what currency those values are in. See the Supported Currencies guide for the full list.

to_base

to_base is a floating-point number that represents the amount or balance converted to the user's primary currency. It is present on transactions, account objects, balance history entries, budget objects, and summary responses.

"amount": "12.5000",
"currency": "eur",
"to_base": 13.62

to_base is calculated by the API at response time and is read-only — it is never accepted on POST or PUT requests.

to_base is the recommended property to use when you need to:

• Display amounts and balances in a single consistent currency across a multi-currency account
• Perform arithmetic across transactions or accounts in different currencies

Sign Convention

Transaction amounts

For amount and to_base on transaction objects, the API uses standard accounting convention (the bank ledger perspective):

For example:

• A $5 coffee purchase has "amount": "5.0000"
• A $1,200 paycheck deposit has "amount": "-1200.0000"

Account balances

For balance on account objects (manual accounts, Plaid accounts, crypto), the sign reflects the account's current standing from the institution's perspective. Positive is the normal direction for both asset and liability accounts:

• A savings account with $5,000 has "balance": "5000.0000" — positive, you hold that amount
• A credit card with $800 owed has "balance": "800.0000" — positive, you owe that amount

A negative balance indicates the reversed state for that account type:

• A savings account in overdraft has a negative balance
• A credit card where the issuer owes you money (e.g., after a refund or overpayment) has a negative balance

Exception: Budget and Summary Amounts

Budget objects and summary response objects don't use the transaction sign convention. Direction is conveyed by the structure of the response rather than the sign of the value — amounts are always positive magnitudes, and the object type or category flag tells you whether that activity is income or expense.

• Budget objects: amount is the positive budgeted value for a category. Whether that represents an income or expense budget is determined by the linked category's is_income flag.
• Summary category totals: fields like other_activity and recurring_activity are always positive. The associated category's is_income flag tells you which direction the activity flows.
• Summary top-level totals: activity is split into separate inflow and outflow objects, each containing positive magnitudes — so direction is explicit in the structure.