Banking Agent OS

SKILL.md

---
name: banking-agent-os
display_name: Banking Agent OS
version: 1.0.0
author: ZhenStaff
category: finance
subcategory: banking
license: MIT-0
description: AI-powered banking system for intelligent agents with account management, transaction processing, and risk control
tags: [banking, ai, agent, fintech, transactions, risk-control, fraud-detection, openai, fastapi, python]
repository: https://github.com/ZhenStaff/openclaw-banking-agent-os
homepage: https://github.com/ZhenStaff/openclaw-banking-agent-os
documentation: https://github.com/ZhenStaff/openclaw-banking-agent-os/blob/main/README.md
---

# Banking Agent OS

AI-powered banking system for intelligent agents - 智能体银行交易系统

## Overview

Banking Agent OS is a comprehensive banking platform designed specifically for AI agents and intelligent systems. It provides secure account management, transaction processing, AI-powered customer service, and advanced risk control.

Perfect for building:
- AI Agent Banking Systems
- Marketplace Transaction Platforms
- Digital Wallet Services
- Automated Risk Management Systems

## Key Features

### 1. Account Management
- **Multi-type accounts**: Checking, Savings, Agent Wallet, Escrow
- **Real-time balance tracking**: Instant updates and queries
- **Account freeze/unfreeze**: Security controls
- **Multi-currency support**: USD and more
- **User and agent accounts**: Flexible account types

### 2. Transaction System
- **Secure fund transfers**: Atomic transactions with rollback
- **Deposits and withdrawals**: Full support
- **Payment processing**: Real-time execution
- **Transaction history**: Complete audit trail
- **Automated reconciliation**: Balance verification

### 3. AI-Powered Services (OpenAI GPT-4)
- **Intelligent customer support**: AI chatbot for banking queries
- **Transaction analysis**: Insights and patterns
- **Personalized financial advice**: AI-generated recommendations
- **Anomaly detection**: Unusual pattern recognition
- **Fraud prevention**: AI-powered security

### 4. Risk Control
- **Real-time risk assessment**: 0.0-1.0 scoring
- **Transaction limit enforcement**: Daily limits and velocity checks
- **Velocity checking**: Rapid transaction detection
- **Fraud detection algorithms**: Multiple risk indicators
- **Comprehensive risk reporting**: Detailed analytics

## Technology Stack

**Backend**:
- Python 3.9+
- FastAPI framework
- SQLAlchemy 2.0 (async)
- Pydantic 2.0 for validation
- OpenAI GPT-4

**Frontend SDK** (optional):
- TypeScript
- Node.js 16+
- Axios HTTP client

## Installation

### Prerequisites

**Required**:
- Python 3.9 or higher
- OpenAI API Key (get from https://platform.openai.com/api-keys)

**Optional** (for JavaScript SDK):
- Node.js 16+ and npm

### Method 1: Python Package via PyPI (Recommended)

```bash
# Install the package
pip install banking-agent-os

# Create configuration file
cat > .env << EOF
OPENAI_API_KEY=your_openai_api_key_here
DATABASE_URL=sqlite+aiosqlite:///./banking_agent.db
EOF

# Start the server
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```

### Method 2: JavaScript SDK via npm (For SDK Users)

```bash
# Install the SDK
npm install openclaw-banking-agent-os
```

Then use in your Node.js/TypeScript project:

```typescript
import { BankingAgentClient, AccountType } from 'openclaw-banking-agent-os';

const client = new BankingAgentClient({
  baseURL: 'http://localhost:8000'  // Points to running backend
});
```

**Note**: The npm package is a client SDK only. You still need the Python backend running.

### Method 3: ClawHub Installation

```bash
# Install via ClawHub
clawhub install banking-agent-os

# The skill will be installed in your skills directory
cd skills/banking-agent-os

# Configure environment
cp .env.example .env
# Edit .env to add your OPENAI_API_KEY

# Start server
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```

## Quick Start

### 1. Ensure Python Backend is Running

Before using the banking system, the backend server must be running:

```bash
# Check if server is running
curl http://localhost:8000/health

# If not running, start it:
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```

Expected response:
```json
{
  "status": "healthy",
  "database": "connected",
  "ai_service": "ready"
}
```

### 2. Create an Account

```bash
curl -X POST http://localhost:8000/api/accounts \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "user_123",
    "account_type": "checking",
    "currency": "USD",
    "initial_balance": 1000.00
  }'
```

Response:
```json
{
  "id": "acc_xxx",
  "account_number": "ACC123456",
  "balance": 1000.00,
  "status": "active"
}
```

### 3. Transfer Funds

```bash
curl -X POST http://localhost:8000/api/transactions \
  -H 'Content-Type: application/json' \
  -d '{
    "from_account_id": "acc_xxx",
    "to_account_id": "acc_yyy",
    "amount": 100.00,
    "transaction_type": "transfer",
    "description": "Payment"
  }'
```

### 4. AI Customer Support

```bash
curl -X POST http://localhost:8000/api/ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "How do I check my account balance?"
  }'
```

## API Endpoints

### Accounts (3 endpoints)
- `POST /api/accounts` - Create new account
- `GET /api/accounts/{account_id}` - Get account details
- `GET /api/accounts/user/{user_id}` - Get user's accounts

### Transactions (3 endpoints)
- `POST /api/transactions` - Create transaction
- `GET /api/transactions/{transaction_id}` - Get transaction details
- `GET /api/transactions/account/{account_id}` - Get account transactions

### AI Service (4 endpoints)
- `POST /api/ai/chat` - AI customer support
- `POST /api/ai/analyze-transaction` - Analyze transaction
- `POST /api/ai/financial-advice` - Get financial advice
- `POST /api/ai/detect-anomalies` - Detect anomalies

### Risk Control (2 endpoints)
- `POST /api/risk/assess` - Assess transaction risk
- `GET /api/risk/report/{account_id}` - Get risk report

### System (2 endpoints)
- `GET /` - Root endpoint
- `GET /health` - Health check

## Usage Examples

### Python API Usage

```python
import uvicorn
from app.main import app

# Start the server programmatically
if __name__ == "__main__":
    uvicorn.run(
        app,
        host="0.0.0.0",
        port=8000,
        log_level="info"
    )
```

### TypeScript SDK Usage

```typescript
import { BankingAgentClient, AccountType, TransactionType } from 'openclaw-banking-agent-os';

// Initialize client
const client = new BankingAgentClient({
  baseURL: 'http://localhost:8000'
});

// Create account
const account = await client.accounts.create({
  user_id: 'user_123',
  account_type: AccountType.CHECKING,
  initial_balance: 1000.00
});

console.log('Account created:', account.account_number);

// Process transaction
const transaction = await client.transactions.create({
  from_account_id: account.id,
  to_account_id: recipient_id,
  amount: 100.00,
  currency: 'USD',
  transaction_type: TransactionType.TRANSFER,
  description: 'Payment'
});

console.log('Transaction completed:', transaction.id);

// AI chat
const response = await client.ai.chat({
  message: 'How do I transfer money?'
});

console.log('AI Response:', response.response);
```

### JavaScript (CommonJS) Usage

```javascript
const { BankingAgentClient } = require('openclaw-banking-agent-os');

const client = new BankingAgentClient({
  baseURL: 'http://localhost:8000'
});

async function main() {
  // Create account
  const account = await client.accounts.create({
    user_id: 'user_123',
    account_type: 'checking',
    initial_balance: 1000.00
  });

  console.log('Account created:', account.id);
}

main();
```

## Use Cases

### 1. AI Agent Banking
Autonomous agents that need their own financial accounts and transaction capabilities.

### 2. Marketplace Transactions
E-commerce platforms with escrow services and automated payouts.

### 3. Digital Wallet Services
Agent wallet management with real-time balance tracking.

### 4. Risk Management
Real-time fraud detection and prevention for all transactions.

## Configuration

### Required Environment Variables

```bash
# REQUIRED: OpenAI API Key for AI features
OPENAI_API_KEY=sk-...

# OPTIONAL: Database configuration (defaults to SQLite)
DATABASE_URL=sqlite+aiosqlite:///./banking_agent.db

# For production, use PostgreSQL:
# DATABASE_URL=postgresql+asyncpg://user:password@localhost/banking_agent
```

### Python Dependencies

When installed via `pip install banking-agent-os`, all dependencies are automatically installed:

- fastapi>=0.104.0
- uvicorn[standard]>=0.24.0
- sqlalchemy>=2.0.0
- aiosqlite>=0.19.0
- pydantic>=2.0.0
- openai>=1.0.0
- python-dotenv>=1.0.0

### Node.js Dependencies (SDK Only)

When installed via `npm install openclaw-banking-agent-os`:

- axios
- TypeScript types included

## Security Considerations

### API Key Safety
- Never commit `.env` files to version control
- Store `OPENAI_API_KEY` securely
- Rotate API keys regularly
- Use environment-specific keys

### Input Validation
- All inputs validated with Pydantic
- SQL injection protection via SQLAlchemy
- Type checking throughout

### Transaction Safety
- Atomic operations with rollback
- Balance verification
- Risk assessment for all transactions
- Fraud detection enabled

## Platform Links

| Platform | Package Name | Link |
|----------|--------------|------|
| **PyPI** | `banking-agent-os` | Coming soon |
| **npm** | `openclaw-banking-agent-os` | https://www.npmjs.com/package/openclaw-banking-agent-os |
| **GitHub** | `openclaw-banking-agent-os` | https://github.com/ZhenStaff/openclaw-banking-agent-os |
| **ClawHub** | `banking-agent-os` | https://clawhub.ai/skills/banking-agent-os |

## Documentation

- **Quick Start**: [QUICKSTART.md](https://github.com/ZhenStaff/openclaw-banking-agent-os/blob/main/docs/QUICKSTART.md)
- **API Documentation**: [API_DOCUMENTATION.md](https://github.com/ZhenStaff/openclaw-banking-agent-os/blob/main/docs/API_DOCUMENTATION.md)
- **Architecture**: [ARCHITECTURE.md](https://github.com/ZhenStaff/openclaw-banking-agent-os/blob/main/docs/ARCHITECTURE.md)
- **Full README**: [README.md](https://github.com/ZhenStaff/openclaw-banking-agent-os/blob/main/README.md)

## Testing

The package includes comprehensive tests. After installation:

```bash
# Install test dependencies
pip install pytest pytest-asyncio httpx

# Run tests
pytest tests/ -v
```

## Troubleshooting

### Q: AI features not working?
**A**: Ensure `OPENAI_API_KEY` is set in your `.env` file. Get a key from https://platform.openai.com/api-keys

### Q: Database errors?
**A**: Check `DATABASE_URL` configuration. SQLite is fine for development. Use PostgreSQL for production.

### Q: Import errors?
**A**: Ensure package is installed: `pip install banking-agent-os`

### Q: Port already in use?
**A**: Change port: `uvicorn app.main:app --port 8001`

### Q: TypeScript SDK can't connect?
**A**: Ensure Python backend is running at the correct URL. Check `baseURL` in client configuration.

## Performance

- **Transaction Processing**: < 100ms average
- **AI Response Time**: 1-3 seconds (depends on OpenAI)
- **Concurrent Users**: Supports 100+ concurrent connections
- **Database**: Async SQLAlchemy for high performance

## Roadmap

### v1.1.0 (Planned)
- Rate limiting and throttling
- Webhook notifications
- Enhanced fraud detection models
- Multi-language support for AI

### v1.2.0 (Planned)
- Real-time WebSocket updates
- Advanced analytics dashboard
- Batch transaction processing
- Enhanced security features

## Support

- **GitHub Issues**: https://github.com/ZhenStaff/openclaw-banking-agent-os/issues
- **Email**: team@openclaw.ai
- **Documentation**: https://github.com/ZhenStaff/openclaw-banking-agent-os#readme

## License

MIT License - see [LICENSE](https://github.com/ZhenStaff/openclaw-banking-agent-os/blob/main/LICENSE) file for details.

## Authors

- **OpenClaw Team** - Initial work and maintenance
- **Contributors** - See [GitHub contributors](https://github.com/ZhenStaff/openclaw-banking-agent-os/graphs/contributors)

---

**Version**: 1.0.0
**Last Updated**: 2026-03-09
**Status**: Production Ready
**Installation**: `pip install banking-agent-os` or `clawhub install banking-agent-os`