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:
📋 API Overview
Base URL
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
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 identifiername (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
Register a new customer in the system.
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 testingtest_registration.py: User registration workflow testingreset_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
{
"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.