Monobank Statements

Fetches transaction history via GET /personal/statement/{account}/{from}/{to}.

Prerequisites

1. API token — from https://api.monobank.ua/ (QR code scan in Monobank app)
2. Account ID — obtained from the client-info endpoint (see mono-client-info skill). Use 0 for the default account.

Key constraints

• Rate limit: 1 request per 60 seconds. HTTP 429 on excess.
• Max date range: 31 days + 1 hour per request
• Max transactions per response: 500 (undocumented but confirmed by community)
• Sort order: Transactions returned from newest to oldest (from to toward from)
• Auth: X-Token header

How to use

Step 1: Determine the date range

Convert desired dates to Unix timestamps in seconds.

# Last 30 days
FROM=$(date -d "30 days ago" +%s)
TO=$(date +%s)

# Specific date range
FROM=$(date -d "2026-03-01" +%s)
TO=$(date -d "2026-03-31 23:59:59" +%s)

Step 2: Fetch statements

curl -s "https://api.monobank.ua/personal/statement/{account_id}/${FROM}/${TO}" \
  -H "X-Token: YOUR_TOKEN_HERE"

Use account ID 0 for the default (primary) account, or a specific account ID from client-info.

Step 3: Handle pagination (if 500 transactions returned)

The API returns a maximum of 500 transactions per request, sorted newest-first. If you receive exactly 500 transactions:

1. Take the time field from the last (oldest) transaction in the response
2. Make a new request with the same from but set to to that timestamp
3. Repeat until you receive fewer than 500 transactions
4. Deduplicate by id across pages (edge case: multiple transactions at the same timestamp)

# Pagination loop pseudocode:
# page1 = fetch(from=START, to=END)
# if len(page1) == 500:
#   last_time = page1[-1].time
#   page2 = fetch(from=START, to=last_time)
#   # continue until len(pageN) < 500

Important: Respect the 60-second rate limit between pagination requests. For heavy accounts, fetching a full month may take several minutes.

Step 4: Parse transaction objects

Each transaction object contains:

Step 5: Convert amounts

All amounts are in minor currency units (kopiyky/cents). Divide by 100 for display.

• Negative amount = money spent (expense)
• Positive amount = money received (income)

Step 6: Analyze and present

When analyzing transactions for the user:

1. Summary totals:

• Total income (sum of positive amounts)
• Total expenses (sum of negative amounts, show as positive)
• Net change
• Total cashback earned

1. Category breakdown by MCC:

Use MCC codes to group spending. Common categories:

• 5411, 5412, 5441 — Groceries
• 5812, 5813, 5814 — Restaurants & cafes
• 5541, 5542, 5983 — Gas stations / fuel
• 4111, 4112, 4121, 4131 — Transportation
• 5912 — Pharmacies
• 6011, 6010 — ATM withdrawals
• 5691, 5699, 5631 — Clothing
• 4814, 4816, 4899 — Telecom & utilities
• 7832, 7922, 7941 — Entertainment
• 5045, 5732, 5734 — Electronics & software
• 6012, 6051 — Financial services / transfers

1. Top merchants: Group by description, sum amounts, sort by total spent

1. Time analysis: Group by day/week to show spending patterns

1. Hold transactions: Flag any with hold: true — these are authorized but not yet settled

Example output format

📊 Statement: 01.03.2026 — 31.03.2026 (UAH account ****1234)

💰 Summary:
  Income:   +45,000.00 ₴
  Expenses: -32,450.75 ₴
  Net:      +12,549.25 ₴
  Cashback:    +324.50 ₴

📂 Top categories:
  🛒 Groceries:      8,420.00 ₴ (26%)
  🍕 Restaurants:    4,150.30 ₴ (13%)
  ⛽ Fuel:           3,200.00 ₴ (10%)
  💊 Pharmacy:       1,850.00 ₴ (6%)

🏪 Top merchants:
  1. АТБ-Маркет      — 4,250.00 ₴ (18 txns)
  2. Сільпо           — 2,830.00 ₴ (12 txns)
  3. Bolt             — 1,920.00 ₴ (8 txns)

Error handling

• HTTP 401: Invalid or expired token
• HTTP 429: Rate limit (1 req/60s). Queue and retry after 60 seconds.
• HTTP 403: AWS WAF block. Wait 24h or change IP.
• Empty array `[]`: No transactions in the specified period (valid response)
• Date range > 31 days + 1 hour: API will return an error. Split into multiple 31-day chunks.

Advanced patterns

Multi-account statement

To get a full picture, fetch client-info first, then iterate over all accounts:

1. Call /personal/client-info → get all account IDs
2. For each account, call /personal/statement/{id}/{from}/{to}
3. Wait 60 seconds between each call
4. Merge and sort all transactions by time

Currency conversion in transactions

When currencyCode differs from the account currency, the operationAmount shows the original amount and amount shows the converted amount charged to the account. The difference reveals the exchange rate applied.