Skip to main content

​
Introduction

The Exchange API provides programmatic access to trading functionality, market data, and account management. All endpoints accept and return JSON-formatted data.

​
Base URL

All API requests should be made to: 
http://localhost:8080/api/v1
The base URL may vary depending on your deployment environment. Check your configuration for the correct server address.

​
API endpoints

Health

Check API server health status

Users

Create and manage user accounts

Orders

Execute, retrieve, and cancel orders

Market depth

Get order book depth for trading pairs

Trades

Retrieve recent trade history

Klines

Get candlestick/OHLC data

Tickers

Get 24-hour ticker statistics

​
Request format

All POST and DELETE requests require a JSON body with the appropriate parameters. GET requests use query parameters.
Example POST request
{
  "market": "SOL_USDC",
  "price": "150.50",
  "quantity": "10.0",
  "side": "BUY",
  "user_id": "user-123"
}

​
Response format

Successful responses return HTTP 200 with JSON data:
Success response
{
  "order_id": "abc123",
  "status": "filled",
  "filled_quantity": "10.0"
}

​
Error handling

The API uses standard HTTP status codes to indicate success or failure:
Status CodeDescription
200Success
500Internal Server Error - Request failed or timed out
Most endpoints use a Redis pub/sub pattern for processing. If a request times out or the processing service is unavailable, you’ll receive a 500 error.

​
Common patterns

​
Symbol format

Trading pairs use underscore-separated symbols:
  • SOL_USDC
  • BTC_USDC
  • ETH_USDC

​
Decimal precision

Prices and quantities are represented as decimal strings to maintain precision: 
{
  "price": "150.50",
  "quantity": "10.0"
}

​
Order sides

Orders can be either:
  • BUY - Purchase the base asset
  • SELL - Sell the base asset

​
Rate limiting

The API currently uses CORS with permissive settings allowing requests from any origin. No explicit rate limiting is implemented at the API level.

​
Health

​
Check health status

GET /api/v1/health
Returns HTTP 200 OK if the service is running.

​
Users

​
Create user

POST /api/v1/users
Creates a new user account with generated balances.
Currently, user IDs are auto-generated. In production, this would typically be authenticated via JWT or session cookies.

​
Orders

​
Execute order

POST /api/v1/order
Create and execute a new order.

​
Get open order

GET /api/v1/order
Retrieve details of a specific open order.

​
Cancel order

DELETE /api/v1/order
Cancel a specific order.

​
Get all open orders

GET /api/v1/orders
Retrieve all open orders for a user and market.

​
Cancel all orders

DELETE /api/v1/orders
Cancel all open orders for a user and market.

​
Market depth

​
Get order book depth

GET /api/v1/depth?symbol=SOL_USDC
Returns the current order book depth for a trading pair. Query parameters:
  • symbol (required) - Trading pair symbol (e.g., SOL_USDC)

​
Trades

​
Get recent trades

GET /api/v1/trades?symbol=SOL_USDC
Returns recent trade history for a trading pair. Query parameters:
  • symbol (required) - Trading pair symbol (e.g., SOL_USDC)

​
Klines

​
Get candlestick data

GET /api/v1/klines?symbol=SOL_USDC&interval=1h&startTime=1727022600
Returns OHLC candlestick data for charting. Query parameters:
  • symbol (required) - Trading pair symbol (e.g., SOL_USDC)
  • interval (required) - Time interval: 1min, 1h, 1d, 1w, 1m, 1y
  • startTime (required) - Unix timestamp for start of data range
Interval values are case-insensitive and converted to standard formats (minute, hour, day, week, month, year).

​
Tickers

​
Get 24-hour tickers

GET /api/v1/tickers
Returns 24-hour price statistics for all trading pairs.

Build docs developers (and LLMs) love

Get started for freeTalk to us