aitbc/docs/apps/exchange/trading-engine.md

Trading Engine

Status

✅ Operational

Overview

High-performance trading engine for order matching, execution, and trade settlement with support for multiple order types and trading strategies.

Architecture

Core Components

• Order Matching Engine: Real-time order matching algorithm
• Trade Executor: Executes matched trades
• Risk Manager: Risk assessment and position management
• Settlement Engine: Trade settlement and clearing
• Order Book Manager: Manages order book state
• Price Engine: Calculates fair market prices

Quick Start (End Users)

Prerequisites

• Python 3.13+
• PostgreSQL database
• Redis for caching
• Access to exchange APIs

Installation

cd /opt/aitbc/apps/trading-engine
.venv/bin/pip install -r requirements.txt

Configuration

Set environment variables in .env:

DATABASE_URL=postgresql://user:pass@localhost/trading
REDIS_URL=redis://localhost:6379
EXCHANGE_API_KEY=your-api-key
RISK_LIMITS_ENABLED=true

Running the Service

.venv/bin/python main.py

Developer Guide

Development Setup

1. Clone the repository
2. Create virtual environment: python -m venv .venv
3. Install dependencies: pip install -r requirements.txt
4. Set up database
5. Configure environment variables
6. Run tests: pytest tests/

Project Structure

trading-engine/
├── src/
│   ├── matching_engine/      # Order matching logic
│   ├── trade_executor/       # Trade execution
│   ├── risk_manager/         # Risk management
│   ├── settlement_engine/    # Trade settlement
│   ├── order_book/           # Order book management
│   └── price_engine/         # Price calculation
├── tests/                    # Test suite
└── pyproject.toml            # Project configuration

Testing

# Run all tests
pytest tests/

# Run matching engine tests
pytest tests/test_matching.py

# Run risk manager tests
pytest tests/test_risk.py

API Reference

Order Management

Submit Order

POST /api/v1/trading/orders
Content-Type: application/json

{
  "user_id": "string",
  "symbol": "BTC_AIT",
  "side": "buy|sell",
  "type": "limit|market|stop",
  "quantity": 100,
  "price": 1.0,
  "stop_price": 1.1
}

Cancel Order

DELETE /api/v1/trading/orders/{order_id}

Get Order Status

GET /api/v1/trading/orders/{order_id}

Trade Execution

Get Trade History

GET /api/v1/trading/trades?symbol=BTC_AIT&limit=100

Get User Trades

GET /api/v1/trading/users/{user_id}/trades

Risk Management

Check Risk Limits

POST /api/v1/trading/risk/check
Content-Type: application/json

{
  "user_id": "string",
  "order": {}
}

Get User Risk Profile

GET /api/v1/trading/users/{user_id}/risk-profile

Settlement

Get Settlement Status

GET /api/v1/trading/settlement/{trade_id}

Trigger Settlement

POST /api/v1/trading/settlement/trigger
Content-Type: application/json

{
  "trade_ids": ["trade1", "trade2"]
}

Configuration

Environment Variables

• DATABASE_URL: PostgreSQL connection string
• REDIS_URL: Redis connection string
• EXCHANGE_API_KEY: Exchange API key
• RISK_LIMITS_ENABLED: Enable risk management
• MAX_POSITION_SIZE: Maximum position size
• MARGIN_REQUIREMENT: Margin requirement percentage
• LIQUIDATION_THRESHOLD: Liquidation threshold

Order Types

• Limit Order: Execute at specified price or better
• Market Order: Execute immediately at market price
• Stop Order: Trigger when price reaches stop price
• Stop-Limit: Limit order triggered by stop price

Risk Parameters

• Position Limits: Maximum position sizes
• Margin Requirements: Required margin for leverage
• Liquidation Threshold: Price at which positions are liquidated

Troubleshooting

Order not matched: Check order book depth and price settings.

Trade execution failed: Verify exchange connectivity and balance.

Risk check failed: Review user risk profile and position limits.

Settlement delayed: Check blockchain network status and gas fees.

Security Notes

• Implement order validation
• Use rate limiting for order submission
• Monitor for wash trading
• Validate user authentication
• Implement position limits
• Regularly audit trade history