Plaid-Cybrid Recurring BTC Purchase Service

A comprehensive automated Bitcoin purchasing service that integrates Plaid for bank account management and Cybrid for cryptocurrency trading. This service allows users to set up recurring purchases of Bitcoin using their connected bank accounts.

🚀 Features

Core Functionality

• Automated BTC Purchases: Set up recurring purchases with configurable frequency
• Plaid Integration: Secure bank account connection and balance monitoring
• Cybrid Trading: Professional-grade cryptocurrency trading execution
• Cron Scheduling: Flexible scheduling using cron expressions
• Real-time Monitoring: Track purchase history and statistics
• RESTful API: Complete API for integration and management

Advanced Features

• Balance Validation: Automatic fund availability checking before purchases
• Error Handling: Comprehensive error handling and logging
• Purchase History: Complete audit trail of all transactions
• Configurable Amounts: Adjustable purchase amounts and frequency
• Manual Purchases: One-time purchase execution capability
• Health Monitoring: Service health checks and status endpoints

🏗️ Architecture

src/
├── config.ts                 # Configuration management
├── types.ts                  # TypeScript interfaces
├── index.ts                  # Application entry point
├── app.ts                    # Express server setup
└── services/
    ├── plaidService.ts       # Plaid API integration
    ├── cybridService.ts      # Cybrid trading API
    └── recurringPurchaseService.ts  # Core business logic

📋 Prerequisites

• Node.js 18+
• npm or yarn
• Plaid API credentials (sandbox or production)
• Cybrid API credentials (sandbox or production)

🛠️ Installation

1. Clone the repository

   git clone <repository-url>
   cd plaid-cybrid

2. Install dependencies

   npm install

3. Set up environment variables Create a .env file in the root directory:

   # Plaid Configuration
   PLAID_CLIENT_ID=your_plaid_client_id
   PLAID_SECRET=your_plaid_secret
   PLAID_ENVIRONMENT=sandbox
   PLAID_INSTITUTION_ID=ins_109508
   
   # Cybrid Configuration
   CYBRID_CLIENT_ID=your_cybrid_client_id
   CYBRID_CLIENT_SECRET=your_cybrid_client_secret
   CYBRID_BASE_URL=https://bank.sandbox.cybrid.app/api
   CYBRID_AUTH_URL=https://id.sandbox.cybrid.app/oauth/token
   
   # Trading Configuration
   PURCHASE_AMOUNT=50
   PURCHASE_FREQUENCY=0 9 * * *
   MAX_PURCHASE_AMOUNT=1000
   MIN_ACCOUNT_BALANCE=100
   
   # Server Configuration
   PORT=3000
   CORS_ORIGINS=http://localhost:3000,http://localhost:3001
   
   # Logging
   LOG_LEVEL=info
   ENABLE_FILE_LOGGING=false

4. Build the project

   npm run build

5. Start the service

   npm start

🚀 Usage

Starting the Service

# Development mode
npm run dev

# Production mode
npm run build
npm start

API Endpoints

Health Check

GET /health

Plaid Operations

# Create sandbox user
POST /api/plaid/create-user

# Get account balance
GET /api/plaid/balance/:accessToken

Cybrid Operations

# Authenticate
POST /api/cybrid/authenticate

# Create customer
POST /api/cybrid/customer
Body: { "firstName": "John", "lastName": "Doe" }

# Create bank
POST /api/cybrid/bank
Body: { "customerGuid": "customer_guid" }

Recurring Purchases

# Start recurring purchases
POST /api/recurring/start

# Stop recurring purchases
POST /api/recurring/stop

# Get status
GET /api/recurring/status

# Get purchase history
GET /api/recurring/history

# Get statistics
GET /api/recurring/stats

# Update purchase amount
PUT /api/recurring/amount
Body: { "amount": 100 }

# Update frequency
PUT /api/recurring/frequency
Body: { "cronExpression": "0 9 * * *" }

Manual Purchases

# Execute manual purchase
POST /api/purchase/manual
Body: {
  "amount": 100,
  "customerGuid": "customer_guid",
  "bankGuid": "bank_guid"
}

Cron Expression Examples

• Daily at 9 AM: 0 9 * * *
• Every Monday at 10 AM: 0 10 * * 1
• Every hour: 0 * * * *
• Every 15 minutes: */15 * * * *

🔧 Configuration

Trading Settings

• PURCHASE_AMOUNT: Default amount for each purchase (USD)
• PURCHASE_FREQUENCY: Cron expression for purchase frequency
• MAX_PURCHASE_AMOUNT: Maximum allowed purchase amount
• MIN_ACCOUNT_BALANCE: Minimum required account balance

Server Settings

• PORT: Server port number
• CORS_ORIGINS: Allowed CORS origins (comma-separated)

📊 Monitoring

Purchase Statistics

The service provides comprehensive statistics including:

• Total number of purchases
• Total amount spent
• Total BTC acquired
• Success rate
• Last purchase timestamp

Health Monitoring

• Service status endpoint
• Error logging
• Performance metrics

🔒 Security

• Environment variable configuration
• CORS protection
• Input validation
• Error handling without sensitive data exposure
• Secure API key management

🧪 Testing

Sandbox Environment

The service is configured for sandbox testing by default:

• Plaid sandbox for bank simulation
• Cybrid sandbox for trading simulation
• Safe testing environment

Production Deployment

For production use:

1. Update environment variables to production endpoints
2. Ensure proper SSL/TLS configuration
3. Set up monitoring and alerting
4. Configure proper logging levels

📝 Logging

The service provides comprehensive logging:

• Request/response logging
• Error tracking
• Purchase execution logs
• Service status updates

🚨 Error Handling

• Graceful error handling
• Detailed error messages
• Fallback mechanisms
• Service recovery

🔄 Troubleshooting

Common Issues

1. Authentication Errors

   • Verify API credentials
   • Check environment variables
   • Ensure proper scopes

2. Purchase Failures

   • Verify account balance
   • Check trading limits
   • Review error logs

3. Service Not Starting

   • Check port availability
   • Verify dependencies
   • Review configuration

📈 Future Enhancements

• Database integration for persistent storage
• Webhook notifications
• Advanced trading strategies
• Multi-currency support
• User authentication and authorization
• Dashboard interface
• Mobile app support

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the ISC License.

⚠️ Disclaimer

This software is for educational and development purposes. Use at your own risk. Always test thoroughly in sandbox environments before using with real funds.

🆘 Support

For support and questions:

• Create an issue in the repository
• Review the documentation
• Check the logs for error details

---

Happy Trading! 🚀📈