AM BudgetView

Local tool to investigate your expenses and incomes by bank transactions.

Was renamed from aggregate-inecobank-statement after new banks and features were added.

To control your budget you need to know all expenses and incomes, right? Manually recording all transactions is too time-intensive and error-prone. While nowadays we are usually paying with cards and all our transactions are already recorded by our banks. Banks even send us long lists of these transactions in monthly emails. Looking through all (thousands of them) transactions manually is too time-intensive and error-prone. Using AI/LLM-based solution (ChatGPT/Gemeni/etc.) is quite risky both from privacy/security and halluciantion points of view (they may provide wrong results and expose your data).

So this application is a simple to use and completely local tool to explore your finances aggregated from your transactions on multiple handy charts. It allows to categorize transactions into custom groups, drill-down to details of each category, normalize amounts to multiple currencies and do everything completely offline (even without internet connection).

Results are:

1. Browser page with aggregated information about your budget in intuitive charts:

2. Text report with most important and structured insights into your budget.

See example (numbers are made up, sum may not match):

Statistics for        2024-07-01..2024-07-31 (in    AMD):
  Income  (total  1 groups, filtered sum     423,492.56):
    Salary                               :   423,492.56
  Expenses (total  8 groups, filt-ed sum     144,280.89):
    Utilities and rent                   :    93,436.50
    Subscriptions                        :    11,565.97
    Groceries                            :     9,171.25
    Entertainment                        :     7,964.78
    Taxi                                 :     7,806.02
    Pharmacies                           :     5,255.99
    Health                               :     4,892.15
    Online shopping                      :     4,188.23
Statistics for        2024-08-01..2024-08-31 (in    AMD):
...

3. Beancount double-entry accounting details for exploration in Fava UI.

Application supports two languages for now: English and Russian.

List of supported banks, file formats and relevant notes

In short supported:

Inecobank accounts,
AmeriaBank both individual (aka MyAmeria) and legal accounts,
Ardshinbank individual accounts,
ACBA accounts,
Generic (manually/customly mapped) CSV files with transactions.

Banks usually send transactions/statements by email monthly or yearly and allow to download list of transactions on their websites. Note that files received via email are usually less usable (except Ardshinbank) because they could be protected by password or don't contain Reciever/Payer account number. It makes them hard to use for analysis because:

hard to handle password protection,
account-based categorization won't work,
transfers between "my accounts" can't be detected and will be counted as "other income" and "other expense" thus distorting statistics/sums,
Beancount report won't be possible to build.

How to download transactions from banks

See list of supported banks, supported formats and relevant instructions in below.

Inecobank

[FULL] Inecobank XML (.xml) files downloaded per-account from https://online.inecobank.am/vcAccount/List (click on account, choose dates range, icon to download in right bottom corner). Supports all features native to app and Beancount reports. In config.yaml is referenced by inecobankStatementXmlFilesGlob setting. Parsed by ineco_xml_parser.go.
[NONE] Inecobank Excel (.xls) files downloaded per-account from https://online.inecobank.am/vcAccount/List (the same place as XML above) ARE NOT SUPPORTED - use XML format instead.
[PARTIAL] Inecobank Excel (.xlsx) files which Inecobank sends in emails with password protection. Don't have Reciever/Payer account number. To allow app use such files need to remove password protection first (MS Office official instruction, MS Office community instruction, LibreOffice instruction). In config.yaml is referenced by inecobankStatementXlsxFilesGlob setting. Parsed by ineco_excel_parser.go.

AmeriaBank (Ameria for Business)

[FULL] AmeriaBank for Businesses CSV (.csv) files downloaded per-account from https://online.ameriabank.am/InternetBank/MainForm.wgx, click on account -> Statement, chose period (for custom use "FromDate" and "To" date pickers), set "Show equivalent in AMD" checkbox (to have exchange rates), press "Export to CSV" icon is placed at right top corner. Supports all features native to app and Beancount reports. In config.yaml is referenced by ameriaCsvFilesGlob setting. Parsed by ameria_csv_parser.go.
[NONE] AmeriaBank for Businesses XML (.xml) files downloaded per-account from https://online.ameriabank.am/InternetBank/MainForm.wgx (the same place as CSV above) - ARE NOT SUPPORTED because they don't contain own account number and currency.
[NONE] AmeriaBank for Businesses XLSX (.xlsx) files which AmeriaBank sends via email. They don't contain Reciever/Payer account number, exchange rates.

MyAmeria (Ameria for Inidividuals)

[FULL] MyAmeria History Excel (.xls) file downloaded from https://myameria.am/history. Press on "Filter" button at right, set right dates (leave other fields as is), press "Excel" button in "Actions" section at right. Only one file is needed because it contains transactions for all accounts and cards. In config.yaml is referenced by myAmeriaHistoryXlsFilesGlob setting. Note that it should be accompanied by myAmeriaMyAccounts dictionary with "my" account numbers and relevant currencies because file doesn't provide this data. Without this data most of application's features won't work, so parser would fail with error in terminal. Supports features native to app and Beancount reports except for exchange rates which are not provided in this file as well. Parsed by ameria_history_parser.go. There is an option to download such files semi-automatically via bank_downloader.py script.
How to download MyAmeria "History" semi-automatically

Copy scripts/bank_dowloader_config.yaml.template into new file bank_dowloader_config.yaml in "scripts" folder Next login into https://account.myameria.am, open browser Dev Tools (usually F12 button), switch to "Network" tab in them and find here
- "Client-Id" request header value for client_id field,
- "Authorization" request header value for auth_token field (note that it starts with "Bearer " and expires in 15 minutes). Put into since-DD-MM-YYYY field start date you want to download transactions from. Correct history_path value accordingly (optional).
Run python scripts/bank_downloader.py (or make bank-downloader) to download transactions history starting from since-DD-MM-YYYY date until today. Notes:
1. Due to script gets data from bank's API it directly generates "Generic" CSV file, not "MyAmeria History" Excel file.
2. Need to update auth_token value in bank_dowloader_config.yaml file each time after it expires, usually in 15 minutes.
[OUTDATED, backward compatibility] MyAmeria Account Statements Excel (.xls) dowloaded from pages like https://myameria.am/cards-and-accounts/account-statement/******. before 2025. Note that it haven't worked for cards, only for accounts. Left to extract information from files downloaded before 2025 (was the main source of data in here), since 2025 use '2025+ History Excel' option instead. In config.yaml is referenced by myAmeriaAccountStatementXlsxFilesGlob setting. Parsed by ameria_stmt_parser.go.
[NONE] MyAmeria Account/Card Statements CSV files downloaded from pages like https://myameria.am/cards-and-accounts/account-statement/****** and https://myameria.am/cards-and-accounts/card-statement/****** in 2025+. Bank changed format somewhere on border of 2024-2025 and new format doesn't have Reciever/Payer account number and doesn't have amount in native bank currency, therefore has less data than '2025+ History Excel' option.

Ardshinbank

[FULL] Ardshinbank XLSX files received via email monthly or yearly, inside there are 3 sheets on different languages: English, Russian and Armenian. Armenian sheet has more details so app uses it. Account number of a peer (receiver or sender) looks like could only be inner Ardshinbank account number, which limits ability to track "transfer my own funds" from other banks. Supports all features native to app and Beancount reports. In config.yaml is referenced by ardshinbankXlsxFilesGlob setting. Parsed by ardshin_xlsx_parser.go.
[NONE] Ardshinbank XLSX files downloaded from https://ardshinbank.am/ ARE NOT SUPPORTED because they either the same as XLSX above or have less data.

ACBA

[PARTIAL] ACBA XLS files downloaded from ACBA Digital. See [ACBA get transactions.md file](/docsdata/ACBA/ACBA get transactions.md) for more details. Choose account or card, select "Transactions" menu option, set dates range, set Armenian language, set "Excel" format, press "Download" button. Note that statement files downloaded on Armenian language contain more information than on English and regular account statements contain more information than card statements. Due to only part of transactions (and only for regular accounts) have Reciever/Payer account number then Beancount report couldn't be built (application would show warning in terminal about it) and account-based categorization wouldn't work. In config.yaml there are two settings for this: acbaRegularAccountXlsFilesGlob and acbaCardXlsFilesGlob. Parsed by acba_xls_stmt_card_parser.go and acba_xls_stmt_regular_account_parser.go accordingly.

Generic

[FULL] Generic CSV files with transactions from the any source. In config.yaml is referenced by genericCsvFilesGlob setting. Parsed by generic_csv_parser.go. Supports all features native to app and Beancount reports. Own account number and currency deduced from fields below. Supported fields/headers (first row in file):
- Date - string with date of the transaction in YYYY-MM-DD format.
- FromAccount - string with account number of the sender.
- ToAccount - string with account number of the receiver.
- IsExpense - boolean value, true if the transaction is an expense (i.e, FromAccount is your account), false if it is an income (i.e, ToAccount is your account).
- Amount - string with amount of the transaction in account currency, dot and 2 digits precision (like "1,500.30" for 1500 dollars and 30 cents).
- Details - string with details/comments of the transaction (main source of categorization).
- AccountCurrency - 3 chars ISO code of the account (card) currency.
- OriginCurrency - (optional) 3 chars ISO code of the currency of the transaction before conversion.
- OriginCurrencyAmount - (optional) string with amount of the transaction in origin currency.

To add new bank support please create an issue in repository with example of file with transactions downloaded from the bank application and instructions how you got this file. File may have corrections to hide sensitive information but of the same format/length/character set as original file.

How to use

Инструкция на русском:

Загрузите исполняемый файл приложения (имя начинается с "am-budget-view-"), скомпилированный для вашей операционной системы со страницы Releases:

Для Windows используйте "am-budget-view-windows-amd64.exe". Даже если у вас процессор Intel. Используйте версию "arm", только если у вас ARM процессор.
Для Mac OS X с процессором M1+ используйте "am-budget-view-darwin-arm64". Для старых Macbook (до 2020 года) используйте "am-budget-view-darwin-amd64".
Для большинства Linux-ов выберите "am-budget-view-linux-amd64".

Скачайте statement/transactions файлы из банковских сайтов или электронных писем и поместите их рядом с исполняемым файлом ("am-budget-view-..."). Подробности см. на List of supported banks, file formats and relevant notes.
Запустите приложение ("am-budget-view-*-*"). Если все в порядке то через пару секунд откроется новая вкладка в браузере с агрегированными данными из банковских транзакций, которые были предоставлены через "Выписка" файлы. В противном случае откроется текстовый файл с описанием ошибки. В случае ошибки необходимо ее исправить чтобы продолжить работу. Самая распространенная ошибка — это когда файлы банковских транзакций, загруженные на шаге № 2, не соответствуют inecobankStatementXmlFilesGlob, inecobankStatementXlsxFilesGlob, myAmeriaAccountStatementXlsxFilesGlob, ameriaCsvFilesGlob, myAmeriaHistoryXlsFilesGlob шаблонам поиска glob объявленным в файле "config.yaml" (приложение создает файл "config.yaml" при первом запуске). При успешном запуске страница браузера, скорее всего, будет содержать несколько начальных категорий и одну большую категорию "Unknown" созданную из еще не категоризированных транзакций.
Для категоризации транзакций используйте кнопку "Категоризация транзакций" в правом верхнем углу. Откроется страница со списком не категоризованных транзакций где у каждый строки справа будет кнопка "Категоризовать". При нажатии на неё откроется модальное окно для создания нового правила категоризации. Окно содержит выбор категории, способа категоризации и значения. Приложение поддерживает следующие способы категоризации (типы правил):

"Подстрока" - выбранная подстрока ищется в столбце "Пометки".
"Со счёта" - выбранный номер счёта ищется в столбце "Со счёта".
"На счёт" - выбранный номер счёта ищется в столбце "На счёт". После нажатия на кнопку "Добавить" новое правило категоризации будет добавлено в конфигурационный файл "config.yaml" и страница будет обновлена с применением нового правила. Таким образом большой список транзакций можно будет категоризировать достаточно быстро. Если нужно добавить новую категорию то используйте кнопку "Создать новую категорию" в правом верхнем углу. Если нужно удалить уже существующую категорию или посмотреть все категории и правила то нажмите кнопку "Категории" - откроется отдельная страница со список категорий и кнопкой "Удалить" для каждой из них.

После того, как вы классифицируете все транзакции, вы получите готовый и интуитивно понятный отчет о расходах и доходах, сравнения месяцев, принятия финансовых решений и т.д. Обратите внимание, что чем больше счетов будет предоставлено приложению, тем более полной будет финансовая картина.
С прошествием времени достаточно добавить новые или обновить старые "Statement" файлы с новыми транзакциями и снова запустить приложение или нажать кнопку "Обновить файлы" в правом верхнем углу. Возможно потребуется добавить новые правила категоризации для новых транзакций. Конфигурационный файл "config.yaml" будет обновляться приложением и содержит все Ваши персональные правила категоризации.

Script in English:

Download the application executable file (name starts with "am-budget-view-") compiled for your operating system from the Releases page:
- For Windows use "am-budget-view-windows-amd64.exe". Even if you have an Intel CPU. Use "arm" version only if your CPU is ARM-based.
- For Mac OS X with M1+ CPU/core use "am-budget-view-darwin-arm64". For older Macbooks (before 2020) use "am-budget-view-darwin-amd64".
- For most of Linux-es choose "am-budget-view-linux-amd64".
Download statement/transaction files from bank websites or emails and put them near the executable file ("am-budget-view-..."). See details on List of supported banks, file formats and relevant notes.
Run application ("am-budget-view-*-*" file). If everything is OK then after a couple of seconds it would open a new tab in browser with aggregated details from bank transactions which where provided via "Statement" files. Otherwise it would open a text file with the error description. In case of an error it is required to fix it to proceed. Most common error is when bank transactions files downloaded on #2 step doesn't match inecobankStatementXmlFilesGlob, inecobankStatementXlsxFilesGlob, myAmeriaAccountStatementXlsxFilesGlob, ameriaCsvFilesGlob, myAmeriaHistoryXlsFilesGlob glob file patterns declared in "config.yaml" file (app would create default "config.yaml" file near it). But in a successful case browser page most probably would contain some pre-defined groups and one big "Unknown" group made from all uncategorized yet transactions.
To categorize transactions use "Transaction Categorization" button at the top right. It would open a page with a list of uncategorized transactions where each row would have a "Categorize" button on the right. When pressed it would open a modal window for creating a new categorization rule. This window contains group (category) selection, rule type and value. Application supports the following categorization types (rule types):
- "Substring" - selected substring is searched in "Details" column. Most popular but lowest by priority.
- "From Account" - selected account number is searched in "From Account" column.
- "To Account" - selected account number is searched in "To Account" column. After pressing "Add" button new categorization rule would be added to "config.yaml" file and page would be updated with new rule applied. Thus a big list of transactions could be categorized quickly if use wide enough rules. If you need to add a new category use "Create New Group" button at the top right. If you need to delete an existing category or see all categories and rules then press "Groups" button - it would open a separate page with a list of groups (categories) with abilities to modify relevant rules.
After you categorize all transactions you would get a ready and intuitive report about expenses and incomes, comparison of months, making financial decisions and so on. Note that more statement files are provided to the application, the more full financial picture would be. So try to add all accounts you have.
With time it is enough to add new or update old "Statement" files with new transactions and run application again or press "Refresh Files" button at the top right. It may be required to add new categorization rules for new transactions. File "config.yaml" would be updated by application and contains all your personal categorization rules.

Notes:

It is a command line application and may work completely in the terminal. Run it with -h for details. It would explain how to switch between configuration files and get information directly in terminal.
By-default application automatically starts in "local HTTP server mode" and opens page in a default browser. No external requests are made.
Application supports 3 "reporting" modes:
- 'web' - default,
- 'file' - to open text report in TXT files veiwer,
- 'none' - only STDOUT (appeared first historically).
In "not web" mode application supports "categorization" flow in interactive mode
- need to set categorizeMode: true in configuration file. This mode is useful to find transactions without categories in terminal.

Use with Beancount and Fava UI

Application generates Beancount file which then could be viewed in Fava UI. Beancount report allows to do full double-entry accounting. It could be hard to understand for those who don't have solid accounting knowledge, so consider to use built-in HTML UI instead.

To install Fava UI (built with Python) run something like pip3 install fava.

After getting log like Built Beancount file 'AM Budget View.beancount' with 1818 transactions. from am-budget-view run in the same folder fava AM\ Budget\ View.beancount - it should print Starting Fava on http://127.0.0.1:5000. Open this link in browser and it would show graphs and other accounting visualization, financial statistic about your transactions. To regenerate Beancount report (for example with corrected configuration) need to re-run am-budget-view (it generates this file only once) while Fava UI would catch up changes by pressing relevant button in page.

Limitations

Application is designed to work completely offline so it tries to parse currencies exchange rates from transactions files. Also it supports constant values from exchangeRates structure in "config.yaml" file. App converts currencies with direct exchange rates first, next with best (by dates difference) multi-hop conversion option found by Dijkstra algorithm. Precision is almost always measured as a number of days between current day and each exchange rate date used for conversion hop. When target date is the same date where we have direct exchange rate then precision still would be 1, because precision 0 means "no conversion", i.e. transaction currency is a target currency. For exchangeRates entries precision is always 100500 - app treats it as "rate for the date of the last provided transaction".
Application can't (and won't) download files from banks itself - it is designed to work completely offline. See "scripts" folder for such capabilities.
Application does not support a way to categorize transactions in a different way for different accounts/banks.

Config.yaml file

The main configuration is stored in config.yaml file. This file is generated from binary on the first run in the folder where app was executed and later is getting updated by the application if it was executed in "web" mode (default).

The main settings are explained directly in the file as comments. Remained (optional and not important) settings are explained below.

uiPort - port to use for local HTTP server. By default it is 8080.
timeZoneLocation - time zone to use for the application. By default it is system timezone.
minCurrencyTimespanPercent - minimum percentage of days between current day and exchange rate date to use it for conversion. By default it is 80%.
maxCurrencyTimespanGapDays - maximum gap in days between current day and exchange rate date to use it for conversion. By default it is 30 days.
categorizeMode - flag to just print details for all uncategorized transactions in terminal. Skips any other actions. By default it is false.

Contributions

Feel free to contribute your features, fixes and so on. It is a usual Go repository with some useful shortcuts in Makefile.

Development

Setup

Install Go v1.21+
go mod init
Made your changes, run test via Makefile targets and test manually with go run .
Make a pull request.

Release

Merge to "master", next push tag with name "releaseX.X.X" and some comment to put into release log. CI will do the rest.

Demo data

Demo data files are generated by generate_demo.py script and allows to try application for yourself with synthetic data. Results of this script could be found in demo folder.

To run application from sources with demo data - execute go run . config-demo.yaml. To run binary with demo data execute something like am-budget-view-windows-amd64.exe config-demo.yaml.

To generate different demo data - setup "main" function in generate_demo.py and run it via make generate-demo (needs exactly Python 3.12) or alike. It would replace files in demo folder.

TODO/Roadmap

Completed far ago:

Recent:

Name		Name	Last commit message	Last commit date
Latest commit History 143 Commits
.github/workflows		.github/workflows
demo		demo
docsdata		docsdata
locales		locales
scripts		scripts
static		static
templates		templates
testdata		testdata
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
acba_xls_stmt_card_parser.go		acba_xls_stmt_card_parser.go
acba_xls_stmt_card_parser_test.go		acba_xls_stmt_card_parser_test.go
acba_xls_stmt_regular_account_parser.go		acba_xls_stmt_regular_account_parser.go
acba_xls_stmt_regular_account_parser_test.go		acba_xls_stmt_regular_account_parser_test.go
ameria_csv_parser.go		ameria_csv_parser.go
ameria_csv_parser_test.go		ameria_csv_parser_test.go
ameria_history_xls_parser.go		ameria_history_xls_parser.go
ameria_history_xls_parser_test.go		ameria_history_xls_parser_test.go
ameria_xls_stmt_parser.go		ameria_xls_stmt_parser.go
ardshin_xlsx_parser.go		ardshin_xlsx_parser.go
ardshin_xlsx_parser_test.go		ardshin_xlsx_parser_test.go
beancount.go		beancount.go
categorization.go		categorization.go
config-demo.yaml		config-demo.yaml
config.yaml		config.yaml
configuration.go		configuration.go
configuration_test.go		configuration_test.go
constants.go		constants.go
currencies.go		currencies.go
currencies_test.go		currencies_test.go
entities.go		entities.go
entities_test.go		entities_test.go
generic_csv_parser.go		generic_csv_parser.go
generic_csv_parser_test.go		generic_csv_parser_test.go
go.mod		go.mod
go.sum		go.sum
helpers.go		helpers.go
i18n.go		i18n.go
i18n_test.go		i18n_test.go
ineco_xlsx_parser.go		ineco_xlsx_parser.go
ineco_xlsx_parser_test.go		ineco_xlsx_parser_test.go
ineco_xml_parser.go		ineco_xml_parser.go
main.go		main.go
main_test.go		main_test.go
statistic.go		statistic.go
statistic_test.go		statistic_test.go
terminal.go		terminal.go
test_helpers.go		test_helpers.go
ui.go		ui.go
utf16.go		utf16.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

AM BudgetView

1. Browser page with aggregated information about your budget in intuitive charts:

2. Text report with most important and structured insights into your budget.

3. Beancount double-entry accounting details for exploration in Fava UI.

List of supported banks, file formats and relevant notes

How to download transactions from banks

Inecobank

AmeriaBank (Ameria for Business)

MyAmeria (Ameria for Inidividuals)

Ardshinbank

ACBA

Generic

How to use

Notes:

Use with Beancount and Fava UI

Limitations

Config.yaml file

Contributions

Development

Setup

Release

Demo data

TODO/Roadmap

About

Uh oh!

Releases 15

Packages

Uh oh!

Contributors 2

Uh oh!

Languages

License

AlexanderMakarov/am-budget-view

Folders and files

Latest commit

History

Repository files navigation

AM BudgetView

1. Browser page with aggregated information about your budget in intuitive charts:

2. Text report with most important and structured insights into your budget.

3. Beancount double-entry accounting details for exploration in Fava UI.

List of supported banks, file formats and relevant notes

How to download transactions from banks

Inecobank

AmeriaBank (Ameria for Business)

MyAmeria (Ameria for Inidividuals)

Ardshinbank

ACBA

Generic

How to use

Notes:

Use with Beancount and Fava UI

Limitations

Config.yaml file

Contributions

Development

Setup

Release

Demo data

TODO/Roadmap

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages