Dummy Bank API Documentation

A comprehensive FastAPI-based banking API designed for portfolio analysis and customer data management, optimized for CustomerOID-based operations and MCP (Model Context Protocol) server integration.

🚀 Quick Start

Prerequisites

Python 3.8+
Conda environment (recommended)

Installation & Setup

Set up environment:

conda create -n openbanking-backend python=3.11
conda activate openbanking-backend

Install dependencies:

pip install fastapi uvicorn sqlmodel sqlite3

Start the API server:

conda run -n openbanking-backend uvicorn main:app --host 127.0.0.1 --port 3000 --reload

Access API documentation:
- Swagger UI: http://127.0.0.1:3000/docs
- ReDoc: http://127.0.0.1:3000/redoc

📋 API Overview

Base URL

http://127.0.0.1:3000

Core Features

CustomerOID-centric design: All operations are based on unique Customer IDs (UUID format)
Comprehensive portfolio data: Assets, transactions, bank accounts, spending patterns, derivatives
Customer lifecycle management: Registration, deletion, and data retrieval
MCP server integration ready: Optimized responses for analysis agents
SQLite database: Local file-based storage with indexed CustomerOID fields

🔑 CustomerOID Format

The API uses UUID format for CustomerOIDs:

Format: 550e8400-e29b-41d4-a716-446655440000
Generation: Automatic UUID generation for new customers
Validation: Strict UUID format validation with backward compatibility

📊 Data Models

User

customer_oid (UUID): Unique customer identifier
name (string): Customer name

Asset Holdings

Asset type, symbol, quantity, current value
Market data and performance metrics

Bank Accounts

Account details, balances, institution information
Multiple accounts per customer supported

Transactions

Transaction history with amounts, dates, descriptions
Categorized for analysis

Spending Patterns

Spending categories and amounts
Useful for financial behavior analysis

Derivative Transactions

Options, futures, and other derivative instruments
Advanced portfolio components

🛠 API Endpoints

Customer Management

`GET /customers`

List all registered customers.

Response:

[
  {
    "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John Doe"
  }
]

`POST /register-customer`

Request Body:

{
  "name": "John Doe",
  "customer_oid": "550e8400-e29b-41d4-a716-446655440000"  // Optional
}

Response:

{
  "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John Doe",
  "message": "Customer registered successfully"
}

Features:

Auto-generates UUID if customer_oid not provided
Validates name (minimum 2 characters)
Prevents duplicate registrations
Returns comprehensive error messages

`DELETE /customer/{customer_oid}`

Delete a customer and all associated data.

⚠️ WARNING: This permanently deletes all portfolio data for the customer.

Response:

{
  "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Customer and all associated data deleted successfully"
}

`GET /customer/{customer_oid}/exists`

Quick check if a CustomerOID exists in the system.

Response:

{
  "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
  "exists": true,
  "name": "John Doe"
}

Portfolio Data

`GET /user-portfolio/{customer_oid}`

Get comprehensive portfolio data for a customer.

Response Structure:

{
  "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
  "user": {
    "name": "John Doe",
    "customer_oid": "550e8400-e29b-41d4-a716-446655440000"
  },
  "assets": [
    {
      "id": 1,
      "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
      "asset_type": "stock",
      "symbol": "AAPL",
      "quantity": 100.0,
      "current_value": 15000.0
    }
  ],
  "bank_accounts": [
    {
      "id": 1,
      "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
      "account_number": "ACC-001",
      "account_type": "checking",
      "balance": 25000.0,
      "institution": {
        "id": 1,
        "name": "First National Bank",
        "routing_number": "123456789"
      }
    }
  ],
  "transactions": [...],
  "spending": [...],
  "derivative_transactions": [...],
  "portfolio_summary": {
    "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
    "total_cash_balance": 25000.0,
    "total_spending": 2500.0,
    "total_assets": 3,
    "total_accounts": 2,
    "total_transactions": 10,
    "total_spending_categories": 5,
    "total_derivative_positions": 2,
    "has_data": {
      "assets": true,
      "accounts": true,
      "transactions": true,
      "spending": true,
      "derivatives": true
    }
  }
}

System Health

`GET /health`

Health check endpoint for monitoring.

Response:

{
  "status": "healthy",
  "service": "dummy-bank-api"
}

🗄 Database Schema

Tables

users: Customer information with UUID CustomerOID (indexed)
assets: Investment holdings per customer
bank_accounts: Banking account details
institutions: Bank and financial institution data
transactions: Transaction history
spending: Spending pattern data
derivative_transactions: Derivative instrument trades

Key Features

Indexed CustomerOID: All tables indexed on customer_oid for fast queries
Referential integrity: Proper foreign key relationships
SQLModel ORM: Type-safe database operations
Automatic seeding: Sample data for testing and development

🧪 Testing

Test Files Included

test_api.py: Comprehensive API testing
test_registration.py: User registration workflow testing
reset_database.py: Database reset and reseeding

Running Tests

# Test API endpoints
conda run -n openbanking-backend python test_api.py

# Test registration functionality
conda run -n openbanking-backend python test_registration.py

# Reset database with sample data
conda run -n openbanking-backend python reset_database.py

🔧 Configuration

Environment Variables

Port: Default 3000 (configurable)
Host: Default 127.0.0.1
Database: SQLite file banking.db

Sample Data

The API includes comprehensive sample data for 5 customers:

Complete portfolio data
Multiple asset types
Various transaction patterns
Diverse spending categories
Derivative instruments

🎯 MCP Server Integration

This API is optimized for MCP (Model Context Protocol) server integration:

Key Features for MCP

CustomerOID-centric design: Easy customer identification
Comprehensive data structure: All portfolio data in single endpoint
Analysis-ready format: Pre-calculated summaries and metrics
Efficient queries: Indexed database operations
Standardized responses: Consistent JSON structure

Recommended MCP Usage

Customer Discovery: Use /customers to list available customers
Portfolio Analysis: Use /user-portfolio/{customer_oid} for complete data
Customer Management: Use registration/deletion endpoints for lifecycle management
Health Monitoring: Use /health for system status

🚨 Error Handling

Common Error Codes

400: Invalid CustomerOID format or validation errors
404: Customer not found
409: Duplicate customer registration
500: Internal server errors

Error Response Format

{
  "detail": "Customer with CustomerOID '550e8400-e29b-41d4-a716-446655440000' not found"
}

🔄 Development Workflow

Making Changes

Edit code: Modify main.py or db.py
Restart server: Server restart required for validation changes
Test changes: Run test scripts to verify functionality
Reset data: Use reset script if database schema changes

Adding New Customers

# Method 1: Use registration endpoint
curl -X POST "http://127.0.0.1:3000/register-customer" \
     -H "Content-Type: application/json" \
     -d '{"name": "New Customer"}'

# Method 2: Specify custom UUID
curl -X POST "http://127.0.0.1:3000/register-customer" \
     -H "Content-Type: application/json" \
     -d '{"name": "New Customer", "customer_oid": "550e8400-e29b-41d4-a716-446655440001"}'

📝 Best Practices

CustomerOID Management

Always use UUID format for new customers
Validate CustomerOID before database operations
Use the provided validation function consistently

Database Operations

Use dependency injection for database sessions
Implement proper error handling and rollbacks
Close sessions properly to prevent leaks

API Design

Follow RESTful conventions
Provide comprehensive error messages
Include validation for all inputs
Document all endpoints clearly

🤝 Contributing

Follow the existing code structure
Add tests for new functionality
Update documentation for API changes
Ensure CustomerOID validation is maintained
Test with sample data before deployment

📄 License

This is a dummy/example implementation for development and testing purposes.

Need help? Check the Swagger documentation at http://127.0.0.1:3000/docs when the server is running.

Dummy Bank API Documentation

A comprehensive FastAPI-based banking API designed for portfolio analysis and customer data management, optimized for CustomerOID-based operations and MCP (Model Context Protocol) server integration.

🚀 Quick Start

Prerequisites

Python 3.8+
Conda environment (recommended)

Installation & Setup

Set up environment:

conda create -n openbanking-backend python=3.11
conda activate openbanking-backend

Install dependencies:

pip install fastapi uvicorn sqlmodel sqlite3

Start the API server:

conda run -n openbanking-backend uvicorn main:app --host 127.0.0.1 --port 3000 --reload

Access API documentation:
- Swagger UI: http://127.0.0.1:3000/docs
- ReDoc: http://127.0.0.1:3000/redoc

📋 API Overview

Base URL

http://127.0.0.1:3000

Core Features

CustomerOID-centric design: All operations are based on unique Customer IDs (UUID format)
Comprehensive portfolio data: Assets, transactions, bank accounts, spending patterns, derivatives
Customer lifecycle management: Registration, deletion, and data retrieval
MCP server integration ready: Optimized responses for analysis agents
SQLite database: Local file-based storage with indexed CustomerOID fields

🔑 CustomerOID Format

The API uses UUID format for CustomerOIDs:

Format: 550e8400-e29b-41d4-a716-446655440000
Generation: Automatic UUID generation for new customers
Validation: Strict UUID format validation with backward compatibility

📊 Data Models

User

customer_oid (UUID): Unique customer identifier
name (string): Customer name

Asset Holdings

Asset type, symbol, quantity, current value
Market data and performance metrics

Bank Accounts

Account details, balances, institution information
Multiple accounts per customer supported

Transactions

Transaction history with amounts, dates, descriptions
Categorized for analysis

Spending Patterns

Spending categories and amounts
Useful for financial behavior analysis

Derivative Transactions

Options, futures, and other derivative instruments
Advanced portfolio components

🛠 API Endpoints

Customer Management

`GET /customers`

List all registered customers.

Response:

[
  {
    "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John Doe"
  }
]

`POST /register-customer`

Request Body:

{
  "name": "John Doe",
  "customer_oid": "550e8400-e29b-41d4-a716-446655440000"  // Optional
}

Response:

{
  "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John Doe",
  "message": "Customer registered successfully"
}

Features:

Auto-generates UUID if customer_oid not provided
Validates name (minimum 2 characters)
Prevents duplicate registrations
Returns comprehensive error messages

`DELETE /customer/{customer_oid}`

Delete a customer and all associated data.

⚠️ WARNING: This permanently deletes all portfolio data for the customer.

Response:

{
  "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Customer and all associated data deleted successfully"
}

`GET /customer/{customer_oid}/exists`

Quick check if a CustomerOID exists in the system.

Response:

{
  "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
  "exists": true,
  "name": "John Doe"
}

Portfolio Data

`GET /user-portfolio/{customer_oid}`

Get comprehensive portfolio data for a customer.

Response Structure:

{
  "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
  "user": {
    "name": "John Doe",
    "customer_oid": "550e8400-e29b-41d4-a716-446655440000"
  },
  "assets": [
    {
      "id": 1,
      "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
      "asset_type": "stock",
      "symbol": "AAPL",
      "quantity": 100.0,
      "current_value": 15000.0
    }
  ],
  "bank_accounts": [
    {
      "id": 1,
      "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
      "account_number": "ACC-001",
      "account_type": "checking",
      "balance": 25000.0,
      "institution": {
        "id": 1,
        "name": "First National Bank",
        "routing_number": "123456789"
      }
    }
  ],
  "transactions": [...],
  "spending": [...],
  "derivative_transactions": [...],
  "portfolio_summary": {
    "customer_oid": "550e8400-e29b-41d4-a716-446655440000",
    "total_cash_balance": 25000.0,
    "total_spending": 2500.0,
    "total_assets": 3,
    "total_accounts": 2,
    "total_transactions": 10,
    "total_spending_categories": 5,
    "total_derivative_positions": 2,
    "has_data": {
      "assets": true,
      "accounts": true,
      "transactions": true,
      "spending": true,
      "derivatives": true
    }
  }
}

System Health

`GET /health`

Health check endpoint for monitoring.

Response:

{
  "status": "healthy",
  "service": "dummy-bank-api"
}

🗄 Database Schema

Tables

users: Customer information with UUID CustomerOID (indexed)
assets: Investment holdings per customer
bank_accounts: Banking account details
institutions: Bank and financial institution data
transactions: Transaction history
spending: Spending pattern data
derivative_transactions: Derivative instrument trades

Key Features

Indexed CustomerOID: All tables indexed on customer_oid for fast queries
Referential integrity: Proper foreign key relationships
SQLModel ORM: Type-safe database operations
Automatic seeding: Sample data for testing and development

🧪 Testing

Test Files Included

test_api.py: Comprehensive API testing
test_registration.py: User registration workflow testing
reset_database.py: Database reset and reseeding

Running Tests

# Test API endpoints
conda run -n openbanking-backend python test_api.py

# Test registration functionality
conda run -n openbanking-backend python test_registration.py

# Reset database with sample data
conda run -n openbanking-backend python reset_database.py

🔧 Configuration

Environment Variables

Port: Default 3000 (configurable)
Host: Default 127.0.0.1
Database: SQLite file banking.db

Sample Data

The API includes comprehensive sample data for 5 customers:

Complete portfolio data
Multiple asset types
Various transaction patterns
Diverse spending categories
Derivative instruments

🎯 MCP Server Integration

This API is optimized for MCP (Model Context Protocol) server integration:

Key Features for MCP

CustomerOID-centric design: Easy customer identification
Comprehensive data structure: All portfolio data in single endpoint
Analysis-ready format: Pre-calculated summaries and metrics
Efficient queries: Indexed database operations
Standardized responses: Consistent JSON structure

Recommended MCP Usage

Customer Discovery: Use /customers to list available customers
Portfolio Analysis: Use /user-portfolio/{customer_oid} for complete data
Customer Management: Use registration/deletion endpoints for lifecycle management
Health Monitoring: Use /health for system status

🚨 Error Handling

Common Error Codes

400: Invalid CustomerOID format or validation errors
404: Customer not found
409: Duplicate customer registration
500: Internal server errors

Error Response Format

{
  "detail": "Customer with CustomerOID '550e8400-e29b-41d4-a716-446655440000' not found"
}

🔄 Development Workflow

Making Changes

Edit code: Modify main.py or db.py
Restart server: Server restart required for validation changes
Test changes: Run test scripts to verify functionality
Reset data: Use reset script if database schema changes

Adding New Customers

# Method 1: Use registration endpoint
curl -X POST "http://127.0.0.1:3000/register-customer" \
     -H "Content-Type: application/json" \
     -d '{"name": "New Customer"}'

# Method 2: Specify custom UUID
curl -X POST "http://127.0.0.1:3000/register-customer" \
     -H "Content-Type: application/json" \
     -d '{"name": "New Customer", "customer_oid": "550e8400-e29b-41d4-a716-446655440001"}'

📝 Best Practices

CustomerOID Management

Always use UUID format for new customers
Validate CustomerOID before database operations
Use the provided validation function consistently

Database Operations

Use dependency injection for database sessions
Implement proper error handling and rollbacks
Close sessions properly to prevent leaks

API Design

Follow RESTful conventions
Provide comprehensive error messages
Include validation for all inputs
Document all endpoints clearly

🤝 Contributing

Follow the existing code structure
Add tests for new functionality
Update documentation for API changes
Ensure CustomerOID validation is maintained
Test with sample data before deployment

📄 License

This is a dummy/example implementation for development and testing purposes.

Need help? Check the Swagger documentation at http://127.0.0.1:3000/docs when the server is running.