Limit-Order Exchange Mini Engine

A full-stack limit-order exchange application built with Laravel API backend and Vue.js frontend, featuring real-time order matching, WebSocket updates, and financial data integrity.

Features

• User authentication with Laravel Sanctum
• USD balance and cryptocurrency asset management (BTC, ETH)
• Limit order placement (Buy/Sell)
• Automatic order matching engine with atomic transactions
• 1.5% commission on matched trades
• Real-time updates via Pusher WebSockets
• Race-condition safe balance & asset management
• Order cancellation with locked funds release

Tech Stack

Backend:

• Laravel 12 (latest)
• MySQL/PostgreSQL (using SQLite for development)
• Laravel Sanctum for API authentication
• Pusher for real-time broadcasting
• BCMath for precise decimal calculations

Frontend:

• Vue.js 3 with Composition API
• TypeScript
• Pinia for state management
• Vue Router
• Tailwind CSS
• Axios for API requests
• Laravel Echo & Pusher-js for WebSocket

Installation

Prerequisites

• PHP >= 8.2
• Composer
• Node.js >= 22.12.0
• npm or yarn

Backend Setup

1. Navigate to backend directory:

cd backend

2. Install PHP dependencies:

composer install

3. Configure environment:

cp .env.example .env
php artisan key:generate

4. Update .env with your Pusher credentials:

BROADCAST_CONNECTION=pusher

PUSHER_APP_ID=your_app_id
PUSHER_APP_KEY=your_app_key
PUSHER_APP_SECRET=your_app_secret
PUSHER_APP_CLUSTER=mt1

5. Run migrations:

php artisan migrate

6. Start the development server:

php artisan serve

The API will be available at http://localhost:8000

Frontend Setup

1. Navigate to frontend directory:

cd frontend

2. Install dependencies:

npm install

3. Create .env file:

cp .env.example .env

4. Update .env with Pusher credentials:

VITE_API_URL=http://localhost:8000
VITE_PUSHER_APP_KEY=your_app_key
VITE_PUSHER_APP_CLUSTER=mt1

5. Start the development server:

npm run dev

The frontend will be available at http://localhost:5173

API Endpoints

Authentication

• POST /api/register - Register new user
• POST /api/login - Login user
• POST /api/logout - Logout user (authenticated)

Profile

• GET /api/profile - Get user balance and assets (authenticated)

Orders

• GET /api/orders?symbol=BTC - Get orderbook for a symbol
• POST /api/orders - Place a new order (authenticated)
• POST /api/orders/{id}/cancel - Cancel an order (authenticated)
• GET /api/my-orders - Get user's order history (authenticated)

Order Matching Logic

Buy Order Flow:

1. Check if users.balance >= amount * price
2. Deduct USD from user balance
3. Create open buy order
4. Match with first available sell order where sell.price <= buy.price
5. Execute trade and update balances/assets

Sell Order Flow:

1. Check if assets.amount >= amount
2. Move amount from assets.amount to assets.locked_amount
3. Create open sell order
4. Match with first available buy order where buy.price >= sell.price
5. Execute trade and update balances/assets

Commission:

• 1.5% commission on total USD value of trade
• Deducted from seller's proceeds
• Example: 0.01 BTC @ $95,000 = $950 total, commission = $14.25

Real-Time Features

The application uses Pusher WebSockets for real-time updates:

• Order matched events broadcast to both buyer and seller
• Private channels: private-user.{userId}
• Frontend automatically updates balance, assets, and order list

Database Schema

Users Table

• id
• name
• email
• password
• balance (decimal 20,8) - USD funds

Assets Table

• id
• user_id
• symbol (BTC, ETH)
• amount (decimal 20,8) - Available amount
• locked_amount (decimal 20,8) - Reserved for open sell orders

Orders Table

• id
• user_id
• symbol
• side (buy/sell)
• price (decimal 20,8)
• amount (decimal 20,8)
• status (1=open, 2=filled, 3=cancelled)

Trades Table

• id
• buy_order_id
• sell_order_id
• buyer_id
• seller_id
• symbol
• price (decimal 20,8)
• amount (decimal 20,8)
• total (decimal 20,8)
• commission (decimal 20,8)

Testing the Application

1. Register two users (Buyer and Seller)
2. Each user starts with $100,000 USD balance
3. Seller needs assets first - place a sell order at a high price
4. Manually add assets to seller in database or create a seeder
5. Place matching buy/sell orders
6. Observe real-time updates in both user sessions

Example Test Scenario:

User A (Seller):

1. Needs 0.1 BTC in assets
2. Places sell order: 0.01 BTC @ $95,000

User B (Buyer):

1. Has $100,000 USD balance
2. Places buy order: 0.01 BTC @ $95,000 or higher

Result:

• Trade executes at $95,000
• Total: $950
• Commission: $14.25
• Buyer receives 0.01 BTC
• Seller receives $935.75 ($950 - $14.25)
• Both users see real-time updates

Security Features

• CSRF protection
• SQL injection prevention via Eloquent ORM
• XSS protection
• Atomic database transactions
• Row-level locking to prevent race conditions
• Input validation on all endpoints
• Password hashing with bcrypt

Production Deployment

1. Set APP_ENV=production in .env
2. Set APP_DEBUG=false
3. Configure proper database (MySQL/PostgreSQL)
4. Set up queue workers for background jobs:

php artisan queue:work

5. Configure proper Pusher credentials
6. Set up CORS for your frontend domain
7. Build frontend for production:

npm run build

Development Notes

• Uses BCMath for precise financial calculations
• All monetary values stored as decimal(20,8)
• Database transactions ensure atomic operations
• Lock-for-update prevents race conditions
• Full order matching happens only (no partial fills)

License

This project is open-source and available under the MIT License.

Support

For issues or questions, please open an issue in the GitHub repository.