🐢 TurboTurtle Exchange: The Fastest Slowpoke in HFT

Welcome to TurboTurtle Exchange – a high-frequency trading (HFT) engine that's as fast as a turtle on rocket fuel! Built with Python for fun, learning, and blazing-fast order matching.

---

Features

• Lightning-fast in-memory order matching engine
• TCP server for high-throughput order entry (just like real exchanges!)
• REST API for market data, order book, and trade history
• Place, cancel, and edit orders
• Time-sortable, unique order IDs (ULID-powered) 😃 Burned My Hand With SnowflakeID & i hate UUID
• Dockerized for easy deployment
• Real Exchange Logic: Doubly linked list order queues and price-time priority (see below!)

---

🛠️ Setup

1. Clone the Turbo Repo

git clone https://github.com/devbijay/TurboTurtle-Exchange
cd turboturtle-exchange

2. Install Python (3.12+ recommended)

Make sure you have Python 3.12 or newer.

3. Install Dependencies

pip install -r requirements.txt

Or, if you use the provided pyproject.toml:

pip install uv
uv sync

4. (Optional) Use Docker 🐳

docker-compose up --build

---

🚦 Running the Exchange

Start the FastAPI + TCP Server

python -m app.main

• FastAPI API: http://localhost:8000/docs
• TCP Server: localhost:9000

---

🎯 Testing TurboTurtle

1. Stress Test with Provided Script

python test.py

2. Manual TCP Order Entry

Connect via nc or telnet:

nc localhost 9000

Send orders in CSV format:

C1,B1,ITC,BUY,100,250.00
C2,B2,ITC,SELL,50,249.50

3. Query the API

• Order Book: GET /trades/order-book/{script_code}
• Trade History: GET /trades/data/{order_id}
• Market Data: GET /market/ltp/{script_code}

Try it out in your browser at http://localhost:8000/docs!

---

📝 Example Order Entry, Edit, and Cancel

TCP (Telnet/Netcat) Examples

1. Place an Order:

C1,B1,ITC,BUY,100,250.00

Response:

OK 01FZQ2YQK2J8KZK2KZK2KZK2KZ

If matched:

OK 01FZQ2YQK2J8KZK2KZK2KZK2KZ
MATCH,01FZQ2YQK2J8KZK2KZK2KZK2KZ_B,01FZQ2YQK2J8KZK2KZK2KZK2KZ_S,250.0,100,1712345678.123456

2. Cancel an Order:

CANCEL 01FZQ2YQK2J8KZK2KZK2KZK2KZ

Response:

OK CANCELLED 01FZQ2YQK2J8KZK2KZK2KZK2KZ

3. Edit an Order:

EDIT 01FZQ2YQK2J8KZK2KZK2KZK2KZ 200 251.00

Response:

OK EDITED 01FZQ2YQK2J8KZK2KZK2KZK2KZ

---

HTTP API Examples

1. Place an Order:

POST /trades/order
Content-Type: application/json

{
  "client_id": "C1",
  "broker_id": "B1",
  "script_code": "ITC",
  "side": "BUY",
  "qty": 100,
  "price": 250.00
}

Response:

{
  "order_id": "01FZQ2YQK2J8KZK2KZK2KZK2KZ",
  "trades": [],
  "status": "PENDING"
}

2. Cancel an Order:

DELETE /trades/order
Content-Type: application/json

{
  "script_code": "ITC",
  "order_id": "01FZQ2YQK2J8KZK2KZK2KZK2KZ"
}

Response:

{
  "status": "OK",
  "order_id": "01FZQ2YQK2J8KZK2KZK2KZK2KZ",
  "script_code": "ITC"
}

3. Get Order/Trade Status:

GET /trades/data/01FZQ2YQK2J8KZK2KZK2KZK2KZ

Response:

{
  "order_id": "01FZQ2YQK2J8KZK2KZK2KZK2KZ",
  "status": "PENDING",
  "type": "BUY",
  "price": 250.0,
  "qty": 100,
  "filled_qty": 0,
  "trades": []
}

---

📈 Viewing Live Market Data (Web UI & WebSocket)

You can watch the market in real time with TurboTurtle's snazzy web UI!

• Visit the Market UI:
  • Open http://localhost:8000/market/ in your browser.
  • Add symbols to your watchlist, see live order books, LTP, and place orders with a click.
• Live Updates via WebSocket:
  • The UI streams market data using a blazing-fast WebSocket (/market/ws/livedata).
  • Add/remove symbols and watch the data update instantly—no page refresh needed!

Want to build your own dashboard? Connect to the WebSocket endpoint directly and subscribe to your favorite symbols for real-time data.

---

🧑‍💻 Project Structure

app/
  core/         # Matching engine, TCP server, core logic
  api/          # FastAPI endpoints (market, trades, TCP pool)
  schemas/      # Pydantic schemas for data validation
  main.py       # App entrypoint (starts FastAPI + TCP server)
  templates/    # HTML templates for market data
Dockerfile      # Container build
docker-compose.yml # Multi-service orchestration
pyproject.toml  # Python dependencies
test.py         # Stress test script

---

💡 Tips

• Order IDs are ULIDs (sortable, unique, and string-based!)
• All state is in-memory (no DB) – restart = fresh start
• Designed for learning, prototyping, and fun!

---

🐢 Stay Turbo & Happy Trading!

🐢 How TurboTurtle Matches Orders (Like a Real Exchange!)

TurboTurtle's order engine is inspired by real-world exchanges:

• Doubly Linked List Magic:
  • Each price level is a doubly linked list, so orders are queued up in the exact order they arrive (first-in, first-out at each price).
  • This makes order cancellation and editing super fast (no slow searching!).
• Price-Time Priority:
  • Orders are matched by best price first (highest buy, lowest sell).
  • If prices are equal, the earliest order gets filled first (time priority).
• In-Memory Speed:
  • Everything runs in RAM for lightning-fast matching (but remember: restart = fresh start!).

This means TurboTurtle is not just fast and fun, but also follows the same matching rules as real exchanges!