{"id":31228180,"url":"https://github.com/vaelixbank/vaelix-api","last_synced_at":"2026-04-11T14:03:05.159Z","repository":{"id":306640363,"uuid":"1014833267","full_name":"vaelixbank/vaelix-api","owner":"vaelixbank","description":"The Open-Bancking API source code","archived":false,"fork":false,"pushed_at":"2025-09-05T13:20:32.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-05T15:29:30.380Z","etag":null,"topics":["javascript","nodemon","open-bancking","openapi","talwindcss","typescript","vite","yarn"],"latest_commit_sha":null,"homepage":"https://api.vaelixbank.com","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vaelixbank.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-06T14:00:56.000Z","updated_at":"2025-09-05T13:20:36.000Z","dependencies_parsed_at":"2025-07-26T22:28:26.507Z","dependency_job_id":"cc9bae2a-5024-4ca5-8084-aeb9d43ca1d3","html_url":"https://github.com/vaelixbank/vaelix-api","commit_stats":null,"previous_names":["vaelixbank/vaelix-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vaelixbank/vaelix-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaelixbank%2Fvaelix-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaelixbank%2Fvaelix-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaelixbank%2Fvaelix-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaelixbank%2Fvaelix-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vaelixbank","download_url":"https://codeload.github.com/vaelixbank/vaelix-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaelixbank%2Fvaelix-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276348330,"owners_count":25626605,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-22T02:00:08.972Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","nodemon","open-bancking","openapi","talwindcss","typescript","vite","yarn"],"created_at":"2025-09-22T05:14:26.156Z","updated_at":"2025-12-30T21:21:40.917Z","avatar_url":"https://github.com/vaelixbank.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vaelix Bank API\n\n[![CI/CD](https://github.com/vaelixbank/vaelix-api/actions/workflows/ci.yml/badge.svg)](https://github.com/vaelixbank/vaelix-api/actions/workflows/ci.yml)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-13+-blue)](https://www.postgresql.org/)\n[![Open Banking](https://img.shields.io/badge/Open%20Banking-Ready-green)](https://www.openbanking.org.uk/)\n[![Security](https://img.shields.io/badge/Security-AES256%20Encrypted-red)](SECURITY.md)\n[![codecov](https://codecov.io/gh/vaelixbank/vaelix-api/branch/main/graph/badge.svg)](https://codecov.io/gh/vaelixbank/vaelix-api)\n\n\u003e A production-ready, open-source banking API built on top of Weavr's Multi API, providing managed accounts and cards functionality with enterprise-grade security.\n\n## 📋 Table of Contents\n\n- [🚀 Features](#-features)\n- [🏗️ Architecture](#️-architecture)\n- [📦 Installation](#-installation)\n- [🗄️ Database Setup](#️-database-setup)\n- [⚡ Quick Start](#-quick-start)\n- [📚 Documentation](#-documentation)\n- [🔧 API Endpoints](#-api-endpoints)\n- [🔐 Security](#-security)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n- [🙏 Acknowledgments](#-acknowledgments)\n\n## 🚀 Features\n\n### Core Banking Features\n- ✅ **User Management**: Corporate \u0026 Consumer identity management with KYC/KYB\n- ✅ **Authentication**: Strong Customer Authentication (SCA) with OTP \u0026 Push Notifications\n- ✅ **Account Management**: Managed accounts with virtual IBAN assignment\n- ✅ **Card Services**: Virtual \u0026 physical card management with CVC retrieval\n- ✅ **Transaction Processing**: Sends, transfers, and wire transfers\n- ✅ **Beneficiary Management**: Secure beneficiary management with SCA\n- ✅ **Bulk Operations**: Enterprise-grade bulk processing capabilities\n\n### Security \u0026 Compliance\n- 🔒 **AES256-GCM Encryption**: Sensitive data encrypted at rest\n- 🛡️ **Rate Limiting**: Multi-tier rate limiting for different endpoints\n- 🚫 **Brute Force Protection**: Progressive delays and account locking\n- 📊 **Audit Trails**: Complete transaction history and compliance logs\n- 🔍 **Regulatory Compliance**: PSD2/Open Banking compliant architecture\n- 🔐 **API Key Management**: Encrypted API keys with multiple types\n\n### Developer Experience\n- 📖 **OpenAPI Documentation**: Comprehensive API documentation\n- 🧪 **TypeScript**: Full type safety and IntelliSense support\n- 🐳 **Docker Support**: Containerized deployment ready\n- 📊 **Monitoring**: Built-in health checks and metrics\n- 🔄 **Webhook Integration**: Real-time event notifications\n- 🤖 **CI/CD Pipeline**: Automated testing and deployment\n- 🎯 **Code Quality**: ESLint, Prettier, and Husky pre-commit hooks\n- 📈 **Test Coverage**: Jest with coverage reporting\n\n## 🏗️ Architecture\n\nVaelix Bank uses a **\"Ledger First\"** architecture where the local ledger is the single source of truth for all banking operations. Weavr acts as a regulated intermediary for compliance-required operations only.\n\n```mermaid\ngraph TB\n    A[Vaelix Bank API] --\u003e B[Local Ledger]\n    A --\u003e C[Regulatory Gateway]\n    C --\u003e D[Weavr Multi API]\n    B --\u003e E[(PostgreSQL)]\n    A --\u003e F[External Services]\n\n    style A fill:#e1f5fe\n    style B fill:#f3e5f5\n    style C fill:#e8f5e8\n    style D fill:#fff3e0\n```\n\n### Key Principles\n\n1. **Data Sovereignty**: All business data remains in your infrastructure\n2. **Regulatory Compliance**: Weavr provides licensed banking infrastructure\n3. **Security First**: AES256 encryption and comprehensive audit trails\n4. **Open Banking**: Berlin Group API standards compliant\n\n## 📦 Installation\n\n### Prerequisites\n\n- **Node.js** \u003e= 18.0.0\n- **PostgreSQL** \u003e= 13.0\n- **npm** or **yarn** package manager\n\n### Clone and Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/vaelixbank/vaelix-api.git\ncd vaelix-api\n\n# Install dependencies\nnpm install\n\n# Copy environment configuration\ncp .env.example .env\n```\n\n### Environment Configuration\n\nConfigure your `.env` file with the required environment variables:\n\n```env\n# Server Configuration\nPORT=3000\nNODE_ENV=development\n\n# Database Configuration\nDB_HOST=localhost\nDB_NAME=vaelixbank\nDB_USER=vaelixbank_user\nDB_PASSWORD=your_secure_password\nDB_PORT=5432\n\n# Weavr API Configuration\nWEAVR_API_BASE_URL=https://sandbox.weavr.io\nWEAVR_API_KEY=your_weavr_api_key\n\n# JWT Configuration\nJWT_SECRET=your-super-secret-jwt-key\nJWT_REFRESH_SECRET=your-refresh-secret-key\nJWT_ACCESS_EXPIRY=15m\nJWT_REFRESH_EXPIRY=7d\n\n# Encryption Configuration\nENCRYPTION_KEY=your-64-character-hex-key\n```\n\n## 🗄️ Database Setup\n\n### 1. Create PostgreSQL Database\n\n```bash\n# Create database and user (run as postgres superuser)\nsudo -u postgres psql\n\n# In PostgreSQL shell:\nCREATE DATABASE vaelixbank;\nCREATE USER vaelixbank_user WITH ENCRYPTED PASSWORD 'your_secure_password';\nGRANT ALL PRIVILEGES ON DATABASE vaelixbank TO vaelixbank_user;\n\\q\n```\n\n### 2. Inject Database Schema\n\n**Option A: Automatic Injection (Recommended)**\n\n```bash\n# Configure your .env file with database credentials first\n# Then inject the complete schema automatically\nnpm run db:schema\n```\n\n**Option B: Manual Injection**\n\n```bash\n# Using psql directly\npsql -h localhost -U vaelixbank_user -d vaelixbank -f data/schema-pgsql.sql\n\n# Or using environment variables\npsql -h $DB_HOST -U $DB_USER -d $DB_NAME -f data/schema-pgsql.sql\n```\n\n### 3. Verify Schema Installation\n\n```bash\n# Check table count (should show 73 tables)\npsql -h $DB_HOST -U $DB_USER -d $DB_NAME -c \"SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public';\"\n\n# List all created tables\npsql -h $DB_HOST -U $DB_USER -d $DB_NAME -c \"SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' ORDER BY table_name;\"\n```\n\n### Schema Contents\n\nThe database schema includes **73 tables** covering:\n\n- **🏦 Core Banking**: Users, accounts, transactions, cards\n- **🔓 Open Banking**: Berlin Group API compliance (consents, payments, webhooks)\n- **🏢 BaaS**: Banking as a Service (customers, accounts, cards, transactions)\n- **⚖️ Legal Compliance**: KYC, AML, GDPR, regulatory reporting, audit trails\n- **🔗 Weavr Integration**: Synchronization tables and Weavr-specific fields\n\nFor detailed schema documentation, see [`DATABASE_SETUP.md`](/docs/DATABASE_SETUP.md).\n\n### Docker Setup\n\n```bash\n# Build and run with Docker Compose\ndocker-compose up -d\n\n# Or use Podman\ndocker-compose -f docker-compose-podman.yml up -d\n```\n\n## ⚡ Quick Start\n\n### 1. Create an API Key\n\n```bash\ncurl -X POST http://localhost:3000/api/keys \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"user_id\": 1,\n    \"type\": \"server\",\n    \"name\": \"my-server-key\"\n  }'\n```\n\n### 2. Create a Consumer\n\n```bash\ncurl -X POST http://localhost:3000/api/consumers \\\n  -H \"x-api-key: your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"root_user\": {\n      \"name\": \"John Doe\",\n      \"email\": \"john@example.com\"\n    }\n  }'\n```\n\n### 3. Create a Managed Account\n\n```bash\ncurl -X POST http://localhost:3000/api/accounts \\\n  -H \"x-api-key: your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"profile_id\": \"profile_123\",\n    \"friendlyName\": \"Main Account\"\n  }'\n```\n\n### 4. Retrieve IBAN\n\n```bash\ncurl -X GET http://localhost:3000/api/accounts/123/iban \\\n  -H \"x-api-key: your-api-key\"\n```\n\n## 📚 Documentation\n\n### 📖 API Documentation\n- **[Complete API Reference](docs/API.md)** - All endpoints with examples\n- **[Models Documentation](docs/Models.md)** - Data structures and schemas\n- **[Controllers Guide](docs/Controllers.md)** - Implementation details\n- **[Docker Setup Guide](docs/DOCKER_README.md)** - Complete Docker documentation\n- **[Changelog](CHANGELOG.md)** - Version history and release notes\n\n### 🔧 Technical Documentation\n- **[Services Architecture](docs/Services.md)** - Service layer overview\n- **[Mobile Integration](docs/MOBILE_INTEGRATION.md)** - Mobile app integration\n- **[API Keys Guide](docs/API_KEYS_README.md)** - API key management\n\n### 🔒 Security Documentation\n- **[Security Policy](SECURITY.md)** - Security guidelines and reporting\n- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community standards\n\n## 🔧 API Endpoints\n\n### Authentication \u0026 Users\n- `POST /api/auth/login` - User authentication\n- `POST /api/consumers` - Create consumer profile\n- `POST /api/corporates` - Create corporate profile\n- `GET /api/users/:id` - Get user details\n\n### Accounts \u0026 Cards\n- `POST /api/accounts` - Create managed account\n- `GET /api/accounts/:id/iban` - Retrieve IBAN\n- `POST /api/cards` - Create managed card\n- `GET /api/cards/:id` - Get card details\n\n### Transactions\n- `POST /api/transactions/sends` - Send money\n- `POST /api/transactions/transfers` - Transfer between accounts\n- `GET /api/transactions` - List transactions\n\n### Regulatory Compliance\n- `POST /api/regulatory/transactions` - Process regulated transactions\n- `GET /api/regulatory/accounts/:id/iban` - Get compliance IBAN\n\n### Strong Customer Authentication (SCA)\n- `POST /api/sca/challenges/stepup/otp` - OTP authentication\n- `POST /api/sca/challenges/stepup/push` - Push notification auth\n\n## 🔐 Security\n\n### Encryption \u0026 Data Protection\n- **AES256-GCM** encryption for sensitive data at rest\n- **TLS 1.3** encryption in transit\n- **bcrypt** password hashing with salt rounds\n- **JWT** tokens with configurable expiration\n\n### Access Control\n- **Multi-tier API keys**: client, server, and database types\n- **Role-based access control** (RBAC)\n- **Rate limiting** with progressive delays\n- **Brute force protection** with account locking\n\n### Compliance \u0026 Audit\n- **Complete audit trails** for all operations\n- **GDPR compliant** data handling\n- **PSD2/Open Banking** regulatory compliance\n- **PCI DSS** card data handling standards\n\n### Security Features\n```typescript\n// Example: Encrypted API key storage\nconst encryptedKey = encrypt(apiKey.secret); // AES256-GCM\nawait db.query('INSERT INTO api_keys (secret) VALUES ($1)', [encryptedKey]);\n```\n\n## 🤝 Contributing\n\nWe welcome contributions from the community! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Fork and clone the repository\ngit clone https://github.com/vaelixbank/vaelix-api.git\ncd vaelix-api\n\n# Install dependencies\nnpm install\n\n# Set up pre-commit hooks\nnpm run prepare\n\n# Copy environment configuration\ncp .env.example .env\n\n# Run linting and type checking\nnpm run lint\nnpm run typecheck\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Start development server\nnpm run dev\n```\n\n### Available Commands\n\n```bash\n# Development\nnpm run dev              # Start development server\nnpm run build            # Build for production\nnpm run clean            # Clean build artifacts\n\n# Code Quality\nnpm run lint             # Run ESLint\nnpm run lint:fix         # Fix linting issues\nnpm run format           # Format code with Prettier\nnpm run typecheck        # TypeScript type checking\n\n# Testing\nnpm test                 # Run tests\nnpm run test:watch       # Run tests in watch mode\nnpm run test:coverage    # Run tests with coverage\nnpm run test:integration # Run integration tests\n\n# Docker\nnpm run docker:build     # Build Docker image\nnpm run docker:run       # Run Docker container\n\n# Database\nnpm run migrate          # Run database migrations\n```\n\n### Code Quality\n\n- **ESLint** for code linting with TypeScript support\n- **Prettier** for code formatting\n- **Husky** pre-commit hooks for quality gates\n- **TypeScript** strict mode enabled\n- **EditorConfig** for consistent editor settings\n- **Jest** for unit and integration testing\n- **Codecov** for test coverage reporting\n\n### Testing\n\n```bash\n# Run unit tests\nnpm test\n\n# Run integration tests\nnpm run test:integration\n\n# Generate coverage report\nnpm run test:coverage\n```\n\n## 🚀 Deployment\n\n### Production Deployment\n\nThis API is configured to run under `https://api.vaelixbank.com/`. Make sure to:\n\n1. Set up a reverse proxy (nginx) to forward requests to the API\n2. Configure SSL certificates for HTTPS\n3. Set environment variables appropriately\n4. Use a process manager like PM2 in production\n\n### Environment Variables\n\n```bash\n# Server Configuration\nPORT=3000\nNODE_ENV=production\n\n# Database Configuration\nDB_HOST=your_db_host\nDB_NAME=your_db_name\nDB_USER=your_db_user\nDB_PASSWORD=your_db_password\nDB_PORT=5432\n\n# Weavr API Configuration\nWEAVR_API_BASE_URL=https://api.weavr.io\nWEAVR_API_KEY=your_weavr_api_key\n\n# Security Configuration\nENCRYPTION_KEY=your_64_char_hex_encryption_key\nJWT_SECRET=your_jwt_secret\nJWT_REFRESH_SECRET=your_refresh_secret\n\n# Email Configuration (optional)\nSMTP_HOST=your_smtp_host\nSMTP_PORT=587\nSMTP_USER=your_smtp_user\nSMTP_PASS=your_smtp_password\n```\n\n### Docker Deployment\n\n```bash\n# Quick development setup\nmake dev\n\n# Production deployment\nmake prod\n\n# With monitoring stack\nmake monitoring\n```\n\n#### Available Environments\n\n- **Development**: `docker-compose.dev.yml` - Hot reload, debugging, dev tools\n- **Production**: `docker-compose.prod.yml` - Optimized, secure, scalable\n- **Override**: `docker-compose.override.yml` - Local customizations\n\nSee **[Docker Documentation](docs/DOCKER_README.md)** for complete setup instructions.\n\n### Cloud Deployment\n\nThe API is designed to work with:\n- **AWS**: ECS, EKS, or Lambda\n- **Google Cloud**: Cloud Run or GKE\n- **Azure**: Container Instances or AKS\n- **Heroku**: Standard deployment\n- **DigitalOcean**: App Platform or Droplets\n\n## 📄 License\n\nThis project is licensed under the **Apache License 2.0** - see the [LICENSE](LICENSE) file for details.\n\n```\nCopyright 2024 Vaelix Bank\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\n## 🙏 Acknowledgments\n\n- **Weavr** for providing the regulated banking infrastructure\n- **Open Banking Initiative** for the standards and specifications\n- **The Open Source Community** for the amazing tools and libraries\n\n### Built With\n\n- [Node.js](https://nodejs.org/) - Runtime environment\n- [TypeScript](https://www.typescriptlang.org/) - Type-safe JavaScript\n- [Express.js](https://expressjs.com/) - Web framework\n- [PostgreSQL](https://www.postgresql.org/) - Database\n- [Weavr Multi API](https://weavr.io/) - Banking infrastructure\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Vaelix Bank API** - Empowering Open Banking Innovation\n\n[![GitHub Stars](https://img.shields.io/github/stars/vaelixbank/vaelix-api?style=social)](https://github.com/vaelixbank/vaelix-api)\n[![GitHub Forks](https://img.shields.io/github/forks/vaelixbank/vaelix-api?style=social)](https://github.com/vaelixbank/vaelix-api)\n[![GitHub Issues](https://img.shields.io/github/issues/vaelixbank/vaelix-api)](https://github.com/vaelixbank/vaelix-api/issues)\n\n[📖 Documentation](docs/) • [🐛 Report Bug](https://github.com/vaelixbank/vaelix-api/issues) • [💡 Request Feature](https://github.com/vaelixbank/vaelix-api/issues)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaelixbank%2Fvaelix-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaelixbank%2Fvaelix-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaelixbank%2Fvaelix-api/lists"}