This README is the one indexed from the repository at its latest ref, not from the tag for this version.

monobank_api

Crystal library for Monobank open API (v250818).

About

API для отримання інформації про виписки та стан особистого рахунку та рахунків ФОП. Для надання доступу потрібно пройти авторизацію у особистому кабінеті https://api.monobank.ua/ та отримати токен для персонального використання.

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     monobank_api:
       github: mamantoha/monobank_api

2. Run shards install

Usage

require "monobank_api"

token = "YOUR_TOKEN_HERE"
client = MonobankApi::Client.new(token)

# Get currency rates
currencies = client.currencies

# Get client info with accounts and jars
info = client.info

# Get account statements
account_id = "YOUR_ACCOUNT_ID"
from = 7.days.ago
to = Time.local

statements = client.statements(account_id, from, to)

# Get MCC descriptions and currency info for transactions
statements.each do |statement|
  puts statement.time                  # => 2025-12-29 09:20:00 UTC
  puts statement.description           # => "Spotify"
  puts statement.amount                # => -21138
  puts statement.balance               # => 100000
  puts statement.mcc_short_description # => "Цифрові товари"
  puts statement.mcc_full_description  # => "Цифрові товари: книги, фільми, музика"
  puts statement.mcc_group_type        # => "MS"
  puts statement.mcc_group_description # => "Інші магазини"

  # Multi-language support for MCC
  puts statement.mcc_short_description(:en) # => "Digital Goods"
  puts statement.mcc_full_description(:ru)  # => "Цифровые товары: книги, фильмы, музыка"

  # Currency information
  puts statement.currency_code_alpha # => "UAH"
  puts statement.currency_name       # => "Ukrainian Hryvnia"
  puts statement.currency_symbol     # => "₴"
end

# Use MCC module directly
MonobankApi::MCC.short_description(5411)     # => "Продукти"
MonobankApi::MCC.full_description(5411, :en) # => "Grocery Stores, Supermarkets"
MonobankApi::MCC.group_type(5411)            # => "ROS"

# Use Currency module directly
MonobankApi::CurrencyData.name(980)       # => "Ukrainian Hryvnia"
MonobankApi::CurrencyData.code_alpha(980) # => "UAH"
MonobankApi::CurrencyData.symbol(980)     # => "₴"

# Convert currencies (amount, from, to)
converter = MonobankApi::CurrencyConverter.new
converter.convert(100, "USD", "EUR") # => 83.8632

Converting Currency

Бібліотека надає зручний конвертер валют, який використовує актуальні курси з Monobank API.

converter = MonobankApi::CurrencyConverter.new
result = converter.convert(100, "USD", "EUR")
puts "100 USD = #{result.round(2)} EUR"

Конвертер автоматично отримує актуальні курси валют з публічного API Monobank при ініціалізації. Підтримується конвертація між будь-якими валютами через прямі курси або через UAH як проміжну валюту.

Якщо у вас вже є кешований список курсів, ви можете ініціалізувати конвертер без запиту до API:

# варіант 1: з масиву курсів
rates = MonobankApi::Client.new("").currencies
converter = MonobankApi::CurrencyConverter.new(rates)

# варіант 2: з кешованого JSON
rates_json = rates.to_json
converter = MonobankApi::CurrencyConverter.new(rates_json)

converter.convert(100, "USD", "EUR")

Currency Information

Бібліотека включає в себе дані про валюти за ISO 4217 кодами з підтримкою багатомовних назв та символів. Дані взято з репозиторію Our World in Data - Currency.

Можливості Currency

• Назва валюти - MonobankApi::CurrencyData.name(iso_num) (наприклад, "Ukrainian Hryvnia")
• ISO 4217 Код - MonobankApi::CurrencyData.code_alpha(iso_num) (наприклад, "UAH")
• Символ - MonobankApi::CurrencyData.symbol(iso_num) (наприклад, "₴")
• Рідний символ - MonobankApi::CurrencyData.symbol_native(iso_num) (наприклад, "грн")

MCC Codes

Бібліотека включає в себе описи кодів MCC (Merchant Category Code) з підтримкою мультимовності (українська, англійська, російська) та групування категорій. Дані взято з репозиторію Oleksios/Merchant-Category-Codes.

Можливості MCC

• Коротка назва - MonobankApi::MCC.short_description(mcc, :uk/:en/:ru)
• Повна назва - MonobankApi::MCC.full_description(mcc, :uk/:en/:ru)
• Тип групи - MonobankApi::MCC.group_type(mcc) (повертає код групи, наприклад "ROS", "HR", "AL")
• Назва групи - MonobankApi::MCC.group_description(mcc, :uk/:en/:ru)

За замовчуванням використовується українська мова.

Documentation

Документація Monobank API доступна на https://api.monobank.ua/docs/index.html

Contributing

1. Fork it (https://github.com/mamantoha/monobank_api/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Anton Maminov - creator and maintainer