Skip to main content

​
Overview

SpendWisely George integrates with Fold Money to provide real-time bank account aggregation and transaction synchronization. Fold Money uses India’s Account Aggregator framework to securely fetch transactions from connected bank accounts.
Fold Money is currently invite-only. You must connect your bank accounts using the Fold mobile app before using this integration.

​
Authentication

The integration uses OTP-based authentication via the Fold Money API.

​
Login Flow

1

Request OTP

Send an OTP to the user’s registered phone number:
POST https://api.fold.money/v1/auth/otp
Content-Type: application/json

{
  "phone": "+919876543210",
  "channel": "sms"
}
Phone numbers are automatically formatted with +91 prefix if not provided.
2

Verify OTP

Verify the OTP and receive authentication tokens:
POST https://api.fold.money/v1/auth/otp/verify
Content-Type: application/json

{
  "phone": "+919876543210",
  "otp": "123456"
}
Response:
{
  "data": {
    "access_token": "eyJhbGc...",
    "refresh_token": "eyJhbGc...",
    "user_meta": {
      "uuid": "user-uuid-here"
    }
  }
}
3

Store Configuration

Save the tokens in unfold_config.yaml:
token:
  access: "eyJhbGc..."
  refresh: "eyJhbGc..."
fold_user:
  uuid: "user-uuid-here"
device_hash: "python-client-a1b2c3d4"

​
API Endpoints

​
Check Login Status

GET /api/fold/status
Response: 
{
  "logged_in": true
}

​
Login Request

POST /api/fold/login
Content-Type: application/json

{
  "phone": "9876543210"
}
Implementation: server.py:89-103

​
Verify OTP

POST /api/fold/verify
Content-Type: application/json

{
  "phone": "9876543210",
  "otp": "123456"
}
Response: 
{
  "status": "success"
}
Implementation: server.py:106-128

​
Transaction Synchronization

Transactions are fetched using the Unfold CLI binary and stored in a local SQLite database.

​
Sync Process

1

Trigger Sync

Initiate a manual sync:
POST /api/sync
This executes:
./unfold/unfold transactions --db --config ./unfold_config.yaml
2

Fetch Transactions

Retrieve synced transactions:
GET /api/transactions
Response:
[
  {
    "uuid": "tx-uuid",
    "amount": -250.0,
    "current_balance": 15430.50,
    "timestamp": "2024-03-15T14:30:00Z",
    "type": "DEBIT",
    "account": "HDFC-****1234",
    "merchant": "Starbucks Coffee"
  }
]
Implementation: server.py:147-188

​
Database Schema

Transactions are stored in unfold/db.sqlite: 
CREATE TABLE transactions (
  uuid TEXT PRIMARY KEY,
  amount REAL,
  current_balance REAL,
  timestamp TEXT,
  type TEXT,
  account TEXT,
  merchant TEXT
);

​
Unfold CLI

SpendWisely George uses the Unfold CLI binary for Fold Money integration.

​
Configuration

  • Binary Path: ./unfold/unfold
  • Config File: ./unfold_config.yaml
  • Database: ./unfold/db.sqlite

​
Common Commands

unfold login

​
Security Considerations

Session Conflict: Fold Money does not support multiple concurrent sessions. Logging in via the CLI will automatically log you out of the mobile app.
  • Tokens are stored locally in unfold_config.yaml
  • API is unofficial and reverse-engineered from the Fold mobile app
  • Use at your own risk - unforeseen consequences may occur

​
Rate Limits

The Fold Money API does not publicly document rate limits. Based on usage:
  • OTP Requests: Limited to prevent abuse
  • Transaction Fetches: Recommended to sync at most once every 20 seconds
  • Token Expiry: Refresh tokens periodically using unfold refresh

​
Error Handling

try:
    subprocess.run(
        [UNFOLD_BINARY, "transactions", "--db", "--config", UNFOLD_CONFIG],
        check=True
    )
except subprocess.CalledProcessError:
    raise HTTPException(
        status_code=500,
        detail="Failed to sync. Ensure you are logged in."
    )
Implementation: server.py:190-198

​
Frontend Integration

The UI provides a complete login flow:
1

Open Settings

Click the “G” button to open the settings panel.
2

Enter Phone

Input your Fold-registered phone number (automatically prefixed with +91).
3

Verify OTP

Enter the OTP received via SMS and verify.
4

Sync Bank

Click “SYNC BANK” to fetch latest transactions.
Implementation: index.html:588-631

​
Troubleshooting

​
”Not logged in” Error

  1. Check if unfold_config.yaml exists
  2. Verify token validity: unfold user
  3. Re-authenticate using /api/fold/login

​
No Transactions Found

  1. Ensure banks are connected in Fold mobile app first
  2. Check database exists: ls unfold/db.sqlite
  3. Run manual sync: POST /api/sync

​
Sync Failed

  • Verify Unfold binary is executable: chmod +x unfold/unfold
  • Check config file path matches UNFOLD_CONFIG constant
  • Ensure you’re logged in: GET /api/fold/status

Build docs developers (and LLMs) love

Get started for freeTalk to us