🎉 This project uses NX for monorepo management!
Quick Start:
npm install # Install all dependencies with prerequisite checks npm run dev # Start development (frontend + backend)
Alpaca API Wrapper is a Django-based starter project for building your own stock market analysis tools, backtesting engines, or trading bots. It leverages the Alpaca API for real-time market data and provides a full-stack, Dockerized environment.
Use it as a foundation for backtesting, live-trading bots, research notebooks, or data pipelines—with built-in support for watchlists, historical and real-time data, and a dedicated WebSocket service for streaming market data.
🌐 Live Demo:
👉 https://alpaca.mnaveedk.com
Try it instantly as an anonymous user, or sign up to unlock the full real-time experience.
The hosted demo is designed to let you experience the project quickly and keep infrastructure costs sustainable.
Anonymous access is intentionally limited to prevent abuse and protect API workloads.
Anonymous users can:
- Browse historical market data
- View existing example watchlists
- Explore the UI and overall architecture
- Refresh pages to fetch the latest available data snapshot
Anonymous limitations (intentional):
- ⏱ Rate limited (~30 requests/min)
- 🔒 Read-only
- ❌ No creating/modifying watchlists
- ❌ No adding/removing assets
- ❌ No real-time streaming updates
If you sign up, you get the full power of the app on the demo platform.
Registered users can:
- Create and manage watchlists
- Add/remove assets
- See asset data update in real time (streaming)
- Explore the WebSocket + Celery pipeline as intended
The goal is still the same: experience it on the demo → clone it → run locally with your own API keys.
- Alpaca API Wrapper
| Category | What you get |
|---|---|
| Public Demo | Anonymous (read-only + rate limited) and Registered (full real-time) modes |
| Watchlists | Create watchlists, add assets, and manage your market focus |
| Historical Data | Assets in watchlists fetch and cache historical OHLCV data automatically |
| Real-Time Data | Assets in watchlists are subscribed to real-time Alpaca market feeds |
| WebSocket Service | Dedicated Django management command runs in its own container, handling |
| real-time tick processing and candle aggregation (1m and higher timeframes) | |
| Interactive Analysis | Access and experiment with real-time and historical data for your watchlists |
| Session management | Secure session generation with your API key & secret |
| Task orchestration | Celery + Redis for async jobs & scheduling |
| Dockerised stack | docker compose up and you're done |
| Layer | Tech |
|---|---|
| Monorepo | NX · npm workspaces |
| Backend | Django · Django REST Framework |
| Async / broker | Celery · Redis |
| Realtime | Django Channels (WebSockets) |
| Frontend | React · Vite |
| Database | PostgreSQL |
| Container / infra | Docker · Docker Compose |
| Dev tooling | uv (deps) · black (format) · ruff (lint) · pytest (tests) · vitest (FE tests) · Smart setup scripts |
| Service | Purpose | Port | Environment | Notes |
|---|---|---|---|---|
| NX | Monorepo orchestration | N/A | Local | Task runner, caching, parallelization |
| Frontend | React SPA (Vite) | 5173 | Local | Hot module replacement enabled |
| Backend | Django API + WebSockets | 8000 | Docker | ASGI server with Channels |
| PostgreSQL | Primary database | 5432 | Docker | Persistent data storage |
| Redis | Cache + Message broker | 6379 | Docker | Celery task queue |
| Celery Workers | Background tasks | N/A | Docker | Async job processing |
| Celery Beat | Task scheduler | N/A | Docker | Periodic task execution |
| WebSocket | Real-time data stream | N/A | Docker | Market data WebSocket service |
| Flower | Task monitoring | 5555 | Docker | Celery dashboard |
Infrastructure services (backend, db, cache, broker, workers, beat, websocket, flower) are in
docker-compose.yml.
Frontend runs locally via NX for fast hot reload. NX orchestrates all tasks across the monorepo with smart prerequisite checking.
- Node.js (v18 or higher) & npm installed
- Docker & Docker Compose installed
- uv (Python package installer) installed
- An Alpaca API key & secret
- Create a
.envs/.envfile with your API credentials
Note: Alpaca API credentials are not required to try the hosted demo.
They are only needed when running the project locally. Note: The setup will automatically check for all prerequisites and guide you through any missing requirements.
git clone https://github.com/naveedkhan1998/alpaca-main.git
cd alpaca-main
# Install everything automatically (NX + Frontend + Backend)
npm installWhat happens during installation:
- ✅ Checks for Node.js, Docker, and uv installation
- ✅ Validates Alpaca API credentials in
.envs/.env - ✅ Installs NX monorepo tooling
- ✅ Installs frontend dependencies (~768 packages)
- ✅ Installs and syncs backend dependencies (~72 Python packages)
- ✅ Creates setup completion marker
Note: If any prerequisites are missing, the installation will stop and provide clear instructions on what to install.
# Install everything automatically
npm install
# Start all services (frontend + backend infrastructure)
npm run devThis single command will:
- 🚀 Start the frontend Vite dev server (with hot reload)
- 🐳 Start Docker infrastructure (PostgreSQL, Redis, Backend API, Celery, WebSocket, Flower)
- ⚡ Run both in parallel automatically via NX
Note:
npm installincludes prerequisite checks and will guide you if anything is missing.
# Frontend only (requires backend infrastructure running)
npm run dev:frontend
# Backend infrastructure only
npm run dev:backend
# Or manually start Docker services
npm run docker:upOnce everything is running, you can access:
- Frontend Application: http://localhost:5173 — React SPA with Vite HMR
- Backend API: http://localhost:8000 — Django REST API
- Django Admin: http://localhost:8000/admin — Admin interface
- Celery Flower: http://localhost:5555 — Task monitoring dashboard
Note: Frontend runs locally with Vite for fast hot reload. Backend services run in Docker for consistency.
All commands run via NX for intelligent caching and parallel execution:
# Development
npm run dev # Start both frontend + backend
npm run dev:frontend # Frontend only
npm run dev:backend # Backend only
# Code Quality
npm run lint # Lint both projects
npm run lint:fix # Lint and auto-fix both projects
npm run format # Format both projects
npm run format:check # Check formatting without changes
# Testing
npm run test # Test both projects
npm run test:coverage # Test both with coverage reports
# Database Management
npm run makemigrations # Make migrations in Docker container
npm run makemigrations:local # Make migrations locally (faster for development)
npm run migrate # Apply migrations in Docker container
# Docker Management
npm run docker:up # Start Docker services
npm run docker:down # Stop Docker services
npm run docker:logs # View Docker logs
npm run docker:clean # Clean Docker volumes
npm run backend:shell # Shell into backend Docker container
# Build
npm run build # Build frontend for production- Frontend: Vite dev server with instant HMR (Hot Module Replacement)
- Backend: Code mounted as Docker volume, auto-reloads on changes
For faster development iterations, use local migration commands:
# Make migrations locally (faster than Docker)
npm run makemigrations:local
# Apply migrations in container
npm run migrateTip: Use
makemigrations:localduring development for quicker feedback, thenmigrateto apply in the container.
# All tests with NX caching
npm run test
# Tests with coverage reports
npm run test:coverageTip: NX caches test results. Only changed projects and their dependents will re-run tests!
Open http://localhost:5555 in your browser for task-level visibility.
Tip: Configure log-rotation (
logrotate) inside the container—or mount/var/log/celeryto your host—to keep log sizes under control.
If you tried the demo or pulled a release and found this useful, consider starring the repo ⭐ It helps justify continued maintenance and makes the project easier to discover.
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and ensure tests pass
- Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- Follow the existing code style (we use
blackfor Python andprettierfor JavaScript) - Add tests for new features
- Update documentation as needed
- Ensure all tests pass before submitting
Found a bug or have a feature request? Please open an issue with:
- Clear description of the problem or feature
- Steps to reproduce (for bugs)
- Expected vs actual behavior
- Your environment details
This project is licensed under the MIT License - see the LICENSE file for details.
- ✅ Use - Use the software for any purpose
- ✅ Modify - Change the software to suit your needs
- ✅ Distribute - Share the software with others
- ✅ Commercial use - Use the software for commercial purposes
- ❗ Include license - Include the original license when distributing
This project wouldn't be possible without these amazing technologies and resources:
- Alpaca API - The financial data API that powers this wrapper
- NX - Smart monorepo build system with intelligent caching and task orchestration
- Django & Django REST Framework - Web framework and API toolkit
- Django Channels - WebSocket support for Django
- Celery - Distributed task queue
- Redis - In-memory data structure store
- PostgreSQL - Powerful, open source object-relational database
- React & Vite - Frontend framework and build tool
- Docker & Docker Compose - Containerization platform
- npm workspaces - Monorepo package management
- uv - Fast Python package installer
- Black - Python code formatter
- Ruff - Fast Python linter
- pytest - Python testing framework
- Vitest - Vite-native testing framework
- The open source community for creating and maintaining these incredible tools
- All contributors who have helped improve this project
Disclaimer: This project is not affiliated with Alpaca Markets. Use at your own risk and ensure compliance with Alpaca's terms of service.
Naveed Khan 📧 Email: naveedkhan13041998@gmail.com 🐙 GitHub: naveedkhan1998 🌐 Website: mnaveedk.com
docker compose -f docker-compose.yaml -f docker-compose.local.yaml up -d
Happy hacking & good trades! 🚀