README_API.md

Bank Balance API for Chatbots

A simple FastAPI application that provides a bank balance checking endpoint for chatbot integration. This is a demo/play tool that simulates bank account balance queries using PIN authentication.

Features

• POST /api/balance: Check account balance using PIN
• GET /api/balance/{pin}: Alternative GET endpoint (demo only)
• GET /health: Health check endpoint
• GET /docs: Interactive API documentation (Swagger UI)
• GET /redoc: Alternative API documentation

Test Accounts

The following PINs are available for testing:

PIN	Balance	Currency	Account Name
1234	15,420.50	USD	John Doe
5678	8,932.75	EUR	Jane Smith
9012	23,500.00	GBP	Bob Johnson
3456	567.25	USD	Alice Williams
7890	45,123.80	CAD	Charlie Brown

Local Testing

1. Install dependencies:

pip install -r requirements.txt

2. Run the application:

python app.py

3. Access the API at http://localhost:7860

4. View interactive docs at http://localhost:7860/docs

API Usage Examples

Using cURL (POST)

# Valid PIN
curl -X POST "http://localhost:7860/api/balance" \
  -H "Content-Type: application/json" \
  -d '{"pin": "1234"}'

# Invalid PIN
curl -X POST "http://localhost:7860/api/balance" \
  -H "Content-Type: application/json" \
  -d '{"pin": "0000"}'

Using cURL (GET)

curl "http://localhost:7860/api/balance/1234"

Using Python

import requests

# Check balance
response = requests.post(
    "http://localhost:7860/api/balance",
    json={"pin": "1234"}
)

data = response.json()
if data["success"]:
    print(f"Balance: {data['balance']} {data['currency']}")
    print(f"Account: {data['account_name']}")
else:
    print(f"Error: {data['message']}")

Using JavaScript/Fetch

fetch('http://localhost:7860/api/balance', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ pin: '1234' })
})
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log(`Balance: ${data.balance} ${data.currency}`);
      console.log(`Account: ${data.account_name}`);
    } else {
      console.log(`Error: ${data.message}`);
    }
  });

Response Format

Successful Response

{
  "success": true,
  "balance": 15420.50,
  "currency": "USD",
  "account_name": "John Doe",
  "message": "Balance retrieved successfully"
}

Failed Response (Invalid PIN)

{
  "success": false,
  "balance": null,
  "currency": null,
  "account_name": null,
  "message": "Access denied. Invalid PIN."
}

Error Response (Invalid Format)

{
  "detail": "Invalid PIN format. PIN must be a 4-digit number."
}

Deploying to Hugging Face Spaces

1. Create a new Space on Hugging Face

2. Select "Gradio" or "Docker" as the SDK (Docker recommended for FastAPI)

3. Upload these files:

   • app.py
   • requirements.txt
   • README.md (optional)

4. If using Docker SDK, create a Dockerfile:

FROM python:3.9

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

Chatbot Integration

For chatbot integration (e.g., with LangChain, OpenAI Functions, etc.), the API can be described as:

{
  "name": "check_bank_balance",
  "description": "Check a user's bank account balance using their PIN number. Returns the balance amount and currency type.",
  "parameters": {
    "type": "object",
    "properties": {
      "pin": {
        "type": "string",
        "description": "The 4-digit PIN number for the bank account"
      }
    },
    "required": ["pin"]
  }
}

Security Notes

⚠️ This is a demo application for educational purposes only!

• PINs are stored in plain text
• No actual authentication/authorization
• No rate limiting
• No encryption
• Not suitable for production use with real financial data

For production applications, implement:

• Proper authentication (OAuth2, JWT)
• Encrypted PIN storage
• Rate limiting
• HTTPS only
• Audit logging
• Multi-factor authentication