Skip to main content

​
Overview

The Transactions API provides access to your Fold Money transaction history. Data is fetched using the Unfold CLI tool and stored locally in a SQLite database for fast retrieval.

​
Get Transactions

​
/api/transactions
GET
Retrieves transaction history from the local SQLite database

​
Behavior

  • Returns up to 50 most recent transactions
  • Automatically creates DB on first request if logged in
  • Returns empty array if DB doesn’t exist or has no transactions
  • Transactions are sorted by timestamp in descending order (newest first)

​
Example Request

curl http://localhost:8000/api/transactions

​
Response

Returns an array of transaction objects:
​
uuid
string
Unique identifier for the transaction
​
amount
number
Transaction amount (positive for credits, negative for debits)
​
current_balance
number
Account balance after this transaction
​
timestamp
string
ISO 8601 formatted timestamp of the transaction
​
type
string
Transaction type (e.g., “debit”, “credit”)
​
account
string
Account identifier or name
​
merchant
string
Merchant name or transaction description

​
Example Response

[
  {
    "uuid": "txn_9f8e7d6c5b4a3210",
    "amount": -1250.50,
    "current_balance": 45780.25,
    "timestamp": "2026-03-04T14:32:18Z",
    "type": "debit",
    "account": "Fold Money Account",
    "merchant": "Swiggy"
  },
  {
    "uuid": "txn_8e7d6c5b4a32109f",
    "amount": 5000.00,
    "current_balance": 47030.75,
    "timestamp": "2026-03-01T09:15:42Z",
    "type": "credit",
    "account": "Fold Money Account",
    "merchant": "Salary Credit"
  },
  {
    "uuid": "txn_7d6c5b4a32109f8e",
    "amount": -450.00,
    "current_balance": 42030.75,
    "timestamp": "2026-02-28T18:45:12Z",
    "type": "debit",
    "account": "Fold Money Account",
    "merchant": "Amazon"
  }
]

​
Empty Response

When no transactions are available: 
[]

​
Sync Transactions

This endpoint manually triggers a sync with Fold Money to fetch the latest transactions.
​
/api/sync
POST
Synchronizes transaction data from Fold Money API to local database

​
Prerequisites

You must be authenticated (logged in via /api/fold/verify) before syncing.
The sync process:
  1. Reads authentication tokens from unfold_config.yaml
  2. Executes the Unfold CLI: ./unfold/unfold transactions --db --config ./unfold_config.yaml
  3. Updates the local SQLite database at ./unfold/db.sqlite

​
Example Request

curl -X POST http://localhost:8000/api/sync

​
Response

​
status
string
Returns "success" when sync completes successfully
{
  "status": "success"
}

​
Error Responses

Not Logged In: 
{
  "detail": "Failed to sync. Ensure you are logged in."
}
Sync Failure: 
{
  "detail": "Unfold binary not found or execution failed"
}
​
detail
string
Error message describing sync failure (500 status code)

​
Database Schema

Transactions are stored in SQLite at ./unfold/db.sqlite:

​
Table: transactions

ColumnTypeDescription
uuidTEXTPrimary key, unique transaction ID
amountREALTransaction amount
current_balanceREALBalance after transaction
timestampTEXTISO 8601 timestamp
typeTEXTTransaction type
accountTEXTAccount identifier
merchantTEXTMerchant/description

​
Query Details

The API executes this SQL query: 
SELECT uuid, amount, current_balance, timestamp, type, account, merchant 
FROM transactions 
ORDER BY timestamp DESC 
LIMIT 50

​
Data Flow

1

Authentication

User logs in via /api/fold/verify, tokens saved to unfold_config.yaml
2

Initial Sync

First call to /api/transactions or manual /api/sync creates DB
3

Unfold CLI Execution

CLI fetches transactions from Fold Money API using stored tokens
4

Database Update

Transactions are inserted/updated in SQLite database
5

Data Retrieval

/api/transactions reads from local DB for fast access

​
Configuration

The API uses these constants: 
UNFOLD_BINARY = "./unfold/unfold"
UNFOLD_CONFIG = "./unfold_config.yaml"
DB_PATH = "./unfold/db.sqlite"
Ensure the Unfold binary has execute permissions: chmod +x ./unfold/unfold

​
Error Handling

ScenarioStatusResponse
DB doesn’t exist200[] (empty array)
Table doesn’t exist200[] (empty array)
DB read error200[] (empty array)
Sync not authenticated500{"detail": "Failed to sync..."}
Unfold binary error500{"detail": "execution error"}
Database errors are caught and return empty arrays rather than error responses to prevent crashes.

​
Best Practices

​
Periodic Syncing

Implement periodic syncing in your frontend: 
// Sync every 5 minutes
setInterval(async () => {
  await fetch('http://localhost:8000/api/sync', { method: 'POST' });
  const transactions = await fetch('http://localhost:8000/api/transactions').then(r => r.json());
  updateUI(transactions);
}, 300000);

​
Error Handling

Always check authentication status before syncing: 
const status = await fetch('http://localhost:8000/api/fold/status').then(r => r.json());
if (!status.logged_in) {
  // Redirect to login
  return;
}

await fetch('http://localhost:8000/api/sync', { method: 'POST' });

​
Next Steps

Portfolio Valuation

Calculate portfolio value with current NAV

Manage Holdings

Add or update mutual fund holdings

Build docs developers (and LLMs) love

Get started for freeTalk to us