aitbc/docs/apps/exchange/exchange.md

Exchange

Status

✅ Operational

Overview

Cross-chain exchange and trading platform supporting multiple blockchain networks with real-time price tracking and order matching.

Architecture

Core Components

• Order Book: Central order book for all trading pairs
• Matching Engine: Real-time order matching and execution
• Price Ticker: Real-time price updates and market data
• Cross-Chain Bridge: Bridge for cross-chain asset transfers
• Health Monitor: System health monitoring and alerting
• API Server: RESTful API for exchange operations

Supported Features

• Multiple trading pairs
• Cross-chain asset transfers
• Real-time price updates
• Order management (limit, market, stop orders)
• Health monitoring
• Multi-chain support

Quick Start (End Users)

Prerequisites

• Python 3.13+
• PostgreSQL database (production default)
• Redis for caching
• Access to blockchain RPC endpoints

Installation

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

Configuration

Set environment variables in .env:

DATABASE_URL=postgresql://user:pass@localhost/exchange
REDIS_URL=redis://localhost:6379
BLOCKCHAIN_RPC_URL=http://localhost:8006
CROSS_CHAIN_ENABLED=true

Running the Service

# Start the exchange server
python server.py

# Or use the production launcher
bash deploy_real_exchange.sh

Web Interface

Open index.html in a browser to access the web interface.

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: See database.py
5. Configure environment variables
6. Run tests: pytest tests/

Project Structure

exchange/
├── server.py                # Main server
├── exchange_api.py           # Exchange API endpoints
├── multichain_exchange_api.py # Multi-chain API
├── simple_exchange_api.py   # Simple exchange API
├── cross_chain_exchange.py  # Cross-chain exchange logic
├── real_exchange_integration.py # Real exchange integration
├── models.py                 # Database models
├── database.py               # Database connection
├── health_monitor.py         # Health monitoring
├── index.html                # Web interface
├── styles.css                # Web styles
├── update_price_ticker.js    # Price ticker update script
└── scripts/                  # Utility scripts

Testing

# Run all tests
pytest tests/

# Run API tests
pytest tests/test_api.py

# Run cross-chain tests
pytest tests/test_cross_chain.py

API Reference

Market Data

Get Order Book

GET /api/v1/orderbook?pair=BTC_AIT

Get Price Ticker

GET /api/v1/ticker?pair=BTC_AIT

Get Market Summary

GET /api/v1/market/summary

Orders

Place Order

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

{
  "pair": "BTC_AIT",
  "side": "buy|sell",
  "type": "limit|market|stop",
  "amount": 100,
  "price": 1.0,
  "user_id": "string"
}

Get Order Status

GET /api/v1/orders/{order_id}

Cancel Order

DELETE /api/v1/orders/{order_id}

Get User Orders

GET /api/v1/orders?user_id=string&status=open

Cross-Chain

Initiate Cross-Chain Transfer

POST /api/v1/crosschain/transfer
Content-Type: application/json

{
  "from_chain": "ait-mainnet",
  "to_chain": "btc-mainnet",
  "asset": "BTC",
  "amount": 100,
  "recipient": "address"
}

Get Transfer Status

GET /api/v1/crosschain/transfers/{transfer_id}

Health

Get Health Status

GET /health

Get System Metrics

GET /metrics

Configuration

Environment Variables

• DATABASE_URL: PostgreSQL connection string
• REDIS_URL: Redis connection string
• BLOCKCHAIN_RPC_URL: Blockchain RPC endpoint
• CROSS_CHAIN_ENABLED: Enable cross-chain transfers
• MAX_ORDER_SIZE: Maximum order size
• MIN_ORDER_SIZE: Minimum order size
• TRADING_FEE_PERCENTAGE: Trading fee percentage
• ORDER_TIMEOUT: Order timeout in seconds

Trading Parameters

• Order Types: limit, market, stop orders
• Order Sides: buy, sell
• Trading Pairs: Configurable trading pairs
• Fee Structure: Percentage-based trading fees

Troubleshooting

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

Cross-chain transfer failed: Verify blockchain connectivity and bridge status.

Price ticker not updating: Check WebSocket connection and data feed.

Database connection errors: Verify DATABASE_URL and database server status.

Security Notes

• Use API keys for authentication
• Implement rate limiting for API endpoints
• Validate all order parameters
• Encrypt sensitive data at rest
• Monitor for suspicious trading patterns
• Regularly audit order history