Skip to main content

​
Quickstart

This guide will help you set up Exchange locally and execute your first order.
Make sure you have Docker and Docker Compose installed on your system before proceeding.

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Installation

1

Clone the repository

Clone the Exchange repository to your local machine:
git clone https://github.com/jogeshwar01/exchange.git
cd exchange
2

Configure environment variables

Copy the example environment file and configure your database credentials:
cp .env.example .env
The default .env configuration looks like this:
PG__USER=root
PG__PASSWORD=root
PG__HOST=localhost
PG__PORT=5000
PG__DBNAME=exchange-db
PG__POOL_MAX_SIZE=16

DATABASE_URL=postgres://${PG__USER}:${PG__PASSWORD}@${PG__HOST}:${PG__PORT}/${PG__DBNAME}
You can customize these values based on your local setup, but the defaults should work for most users.
3

Start infrastructure services

Use Docker Compose to start Redis and Postgres:
docker-compose up -d
This will start:
  • Redis on port 6379 (for pub/sub messaging)
  • Postgres on port 5000 (for persistent storage)
4

Build the project

Build all the Exchange components:
cargo build
This compiles the four main components:
  • Router (REST API server)
  • Engine (order matching engine)
  • WebSocket stream (real-time data)
  • Database processor (async DB writes)
5

Run the services

In separate terminal windows, start each service:Terminal 1 - Engine:
cargo run --bin engine
Terminal 2 - Router:
cargo run --bin router
Terminal 3 - Database Processor:
cargo run --bin db-processor
Terminal 4 - WebSocket Stream:
cargo run --bin ws-stream
The router will start on http://localhost:8080 by default. You should see “Server running at http://…” in the terminal.

​
Create your first order

Now that Exchange is running, let’s create a user and place an order.

​
Create a user

First, create a test user: 
curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test_user",
    "username": "testuser"
  }'

​
Place a limit order

Create a buy order for SOL/USDC: 
curl -X POST http://localhost:8080/api/v1/order \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test_user",
    "symbol": "SOL_USDC",
    "side": "Buy",
    "order_type": "Limit",
    "quantity": "10",
    "price": "150.50"
  }'
You should receive a response with your order details including an order_id.

​
Check your order status

Retrieve your order using the order_id from the previous response: 
curl -X GET "http://localhost:8080/api/v1/order?order_id=YOUR_ORDER_ID&user_id=test_user"

​
Get open orders

View all open orders for your user: 
curl -X GET "http://localhost:8080/api/v1/orders?user_id=test_user&symbol=SOL_USDC"

​
Cancel an order

Cancel a specific order: 
curl -X DELETE http://localhost:8080/api/v1/order \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test_user",
    "order_id": "YOUR_ORDER_ID",
    "symbol": "SOL_USDC"
  }'

​
Explore market data

Exchange provides several endpoints to query market data:

​
Get order book depth

curl -X GET "http://localhost:8080/api/v1/depth?symbol=SOL_USDC"

​
Get recent trades

curl -X GET "http://localhost:8080/api/v1/trades?symbol=SOL_USDC"

​
Get ticker data

curl -X GET "http://localhost:8080/api/v1/tickers?symbol=SOL_USDC"

​
Get kline (candlestick) data

curl -X GET "http://localhost:8080/api/v1/klines?symbol=SOL_USDC&interval=1m&startTime=1727022600"

​
Connect to WebSocket

For real-time updates, connect to the WebSocket server: 
const ws = new WebSocket('ws://localhost:3000');

ws.onopen = () => {
  // Subscribe to depth updates for SOL_USDC
  ws.send(JSON.stringify({
    method: 'SUBSCRIBE',
    params: ['depth@SOL_USDC']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received update:', data);
};
The WebSocket URL may differ based on your configuration. Check the WS_STREAM_URL environment variable.

​
Next steps

Architecture

Learn how Exchange components work together

API reference

Explore all available API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us