Skip to main content

​
Introduction

SpendWisely George provides a RESTful API built with FastAPI that manages financial transactions, portfolio tracking, and mutual fund holdings. The API integrates with Fold Money for transaction data and MFApi for mutual fund NAV information.

​
Base URL

http://localhost:8000
For production deployments, the base URL will be determined by your hosting environment. The port can be configured via the PORT environment variable (default: 8000).

​
API Architecture

The backend consists of four main functional areas:

​
Authentication

  • OTP-based login flow using Fold Money API
  • Token management and session persistence
  • Status checking for logged-in state

​
Transactions

  • Fetches transaction history from Fold Money
  • Stores data locally in SQLite database
  • Manual sync endpoint for data refresh

​
Portfolio

  • Real-time portfolio valuation
  • NAV calculation using MFApi integration
  • Aggregated total value across all holdings

​
Holdings

  • CRUD operations for mutual fund holdings
  • Local JSON file storage
  • Scheme code and units tracking

​
Response Format

All API responses use JSON format. Successful responses return the requested data directly: 
{
  "status": "success",
  "data": { ... }
}
For list endpoints, the response is an array: 
[
  { "uuid": "...", "amount": 1000 },
  { "uuid": "...", "amount": 2000 }
]

​
Error Handling

Errors follow FastAPI’s HTTPException pattern with appropriate status codes:

​
Error Response Structure

{
  "detail": "Error message describing what went wrong"
}

​
Common Status Codes

​
200
Success
Request completed successfully
​
400
Bad Request
Invalid request parameters or authentication failure
​
500
Internal Server Error
Server-side error during processing (e.g., sync failure)

​
Example Error Response

{
  "detail": "Verification failed: Invalid OTP"
}

​
Authentication Flow

The API uses a two-step OTP authentication process:
  1. Request OTP: Send phone number to /api/fold/login
  2. Verify OTP: Submit OTP code to /api/fold/verify
  3. Token Storage: Tokens are stored in unfold_config.yaml for subsequent requests

​
Data Storage

The API uses multiple storage mechanisms:
  • unfold_config.yaml: Authentication tokens and user UUID
  • unfold/db.sqlite: Transaction history from Fold Money
  • holdings.json: User’s mutual fund holdings

​
CORS Configuration

The API is configured with permissive CORS settings for development: 
allow_origins=["*"]
allow_methods=["*"]
allow_headers=["*"]
For production deployments, restrict CORS origins to your frontend domain only.

​
Rate Limiting

The API does not implement rate limiting, but be aware of external API limits:
  • Fold Money API: Subject to their rate limits
  • MFApi: Public API with no documented rate limits

​
Next Steps

Authentication

Set up Fold Money OTP login

Transactions

Fetch and sync transaction data

Portfolio

Get real-time portfolio valuation

Holdings

Manage mutual fund holdings

Build docs developers (and LLMs) love

Get started for freeTalk to us