Data Types

Overview

Exchange Web uses strongly-typed TypeScript interfaces for all API requests and responses. All type definitions can be found in source/apps/web/src/utils/types.ts.

Market Data Types

KLine

Represents a candlestick (OHLCV) data point for a specific time interval.

interface KLine {
  close: string;
  end: string;
  high: string;
  low: string;
  open: string;
  quoteVolume: string;
  start: string;
  trades: string;
  volume: string;
}

open

string

Opening price at the start of the period

high

string

Highest price reached during the period

low

string

Lowest price reached during the period

string

Closing price at the end of the period

volume

string

Total volume of base asset traded during the period

quoteVolume

string

Total volume of quote asset traded (price × volume)

start

string

Start timestamp of the candlestick period

end

string

End timestamp of the candlestick period

trades

string

Number of individual trades that occurred during this period

Usage Example:

import { getKlines } from './utils/requests';
import { KLine } from './utils/types';

const klines: KLine[] = await getKlines('SOL_USDC', '1h', Date.now() - 86400000);

klines.forEach((kline) => {
  console.log(`Period: ${kline.start} - ${kline.end}`);
  console.log(`OHLC: ${kline.open}, ${kline.high}, ${kline.low}, ${kline.close}`);
  console.log(`Volume: ${kline.volume}`);
});

Trade

Represents a single trade execution on the exchange.

interface Trade {
  id: number;
  isBuyerMaker: boolean;
  price: string;
  quantity: string;
  quoteQuantity: string;
  timestamp: number;
}

number

Unique identifier for the trade

isBuyerMaker

boolean

true if the buyer placed the maker order (limit order that was on the book first). false if the buyer was the taker (market order or aggressive limit order).

price

string

Execution price of the trade

quantity

string

Amount of base asset traded

quoteQuantity

string

Amount of quote asset traded (price × quantity)

timestamp

number

Unix timestamp in milliseconds when the trade was executed

Usage Example:

import { getTrades } from './utils/requests';
import { Trade } from './utils/types';

const trades: Trade[] = await getTrades('SOL_USDC');

const recentTrade: Trade = trades[0];
console.log(`Trade #${recentTrade.id}`);
console.log(`Price: $${recentTrade.price}`);
console.log(`Amount: ${recentTrade.quantity} SOL`);
console.log(`Side: ${recentTrade.isBuyerMaker ? 'Sell' : 'Buy'}`);
console.log(`Time: ${new Date(recentTrade.timestamp).toLocaleString()}`);

When isBuyerMaker is true, the trade appears as a “sell” on the tape because the buyer matched against a sell order. When false, it appears as a “buy”.

Depth

Represents the current order book depth for a market.

interface Depth {
  bids: [string, string][];
  asks: [string, string][];
  lastUpdateId: string;
}

bids

[string, string][]

Array of bid (buy) orders. Each element is a tuple of [price, quantity].

asks

[string, string][]

Array of ask (sell) orders. Each element is a tuple of [price, quantity].

lastUpdateId

string

Identifier for the last order book update. Used for synchronization with WebSocket depth updates.

Usage Example:

import { getDepth } from './utils/requests';
import { Depth } from './utils/types';

const depth: Depth = await getDepth('SOL_USDC');

// Best bid (highest buy price)
const bestBid = depth.bids[0];
console.log(`Best Bid: $${bestBid[0]} (${bestBid[1]} SOL)`);

// Best ask (lowest sell price)
const bestAsk = depth.asks[0];
console.log(`Best Ask: $${bestAsk[0]} (${bestAsk[1]} SOL)`);

// Spread
const spread = parseFloat(bestAsk[0]) - parseFloat(bestBid[0]);
console.log(`Spread: $${spread}`);

// Total bid volume
const totalBidVolume = depth.bids.reduce(
  (sum, [_, quantity]) => sum + parseFloat(quantity),
  0
);
console.log(`Total Bid Volume: ${totalBidVolume} SOL`);

Bids are typically sorted in descending order (highest price first), while asks are sorted in ascending order (lowest price first).

Ticker

Represents 24-hour statistics for a market.

interface Ticker {
  firstPrice: string;
  high: string;
  lastPrice: string;
  low: string;
  priceChange: string;
  priceChangePercent: string;
  quoteVolume: string;
  symbol: string;
  trades: string;
  volume: string;
}

symbol

string

Market symbol (e.g., SOL_USDC, SOL_USDC)

firstPrice

string

Price 24 hours ago (start of the rolling 24-hour window)

lastPrice

string

Most recent trade price

high

string

Highest price in the last 24 hours

low

string

Lowest price in the last 24 hours

priceChange

string

Absolute price change: lastPrice - firstPrice

priceChangePercent

string

Percentage price change: ((lastPrice - firstPrice) / firstPrice) * 100

volume

string

Total volume of base asset traded in 24 hours

quoteVolume

string

Total volume of quote asset traded in 24 hours

trades

string

Number of trades executed in the last 24 hours

Usage Example:

import { getTicker } from './utils/requests';
import { Ticker } from './utils/types';

const ticker: Ticker = await getTicker('SOL_USDC');

console.log(`${ticker.symbol}`);
console.log(`Price: $${ticker.lastPrice}`);
console.log(`24h Change: ${ticker.priceChange} (${ticker.priceChangePercent}%)`);
console.log(`24h High: $${ticker.high}`);
console.log(`24h Low: $${ticker.low}`);
console.log(`24h Volume: ${ticker.volume} SOL`);
console.log(`24h Trades: ${ticker.trades}`);

// Calculate if market is up or down
const isUp = parseFloat(ticker.priceChange) > 0;
console.log(`Trend: ${isUp ? '📈 Up' : '📉 Down'}`);

Trading Types

CreateOrder

Request payload for creating a new order.

interface CreateOrder {
  market: string;
  side: string;
  quantity: number;
  price: number;
  userId: string;
}

market

string

Market symbol to place the order on (e.g., SOL_USDC)

side

string

Order side: "buy" or "sell"

quantity

number

Amount of base asset to buy or sell

price

number

Limit price for the order

userId

string

User identifier for authentication (obtained from createUser())

Usage Example:

import { createOrder, createUser } from './utils/requests';
import { CreateOrder, UserId } from './utils/types';

// First, create a user if you don't have one
const userResponse: UserId = await createUser();
const userId = userResponse.user_id;

// Create a buy order
const buyOrder: CreateOrder = {
  market: 'SOL_USDC',
  side: 'buy',
  quantity: 0.5,
  price: 50000,
  userId: userId
};

const orderId: string = await createOrder(buyOrder);
console.log(`Order created: ${orderId}`);

// Create a sell order
const sellOrder: CreateOrder = {
  market: 'SOL_USDC',
  side: 'sell',
  quantity: 0.25,
  price: 51000,
  userId: userId
};

const sellOrderId: string = await createOrder(sellOrder);
console.log(`Sell order created: ${sellOrderId}`);

All orders are limit orders. You must specify both quantity and price.

User Management Types

UserId

Response from user creation endpoint.

interface UserId {
  status: string;
  user_id: string;
}

status

string

Status of the user creation request (e.g., "success")

user_id

string

Unique identifier assigned to the newly created user

Usage Example:

import { createUser } from './utils/requests';
import { UserId } from './utils/types';

const userResponse: UserId = await createUser();

if (userResponse.status === 'success') {
  // Store the user_id for future use
  localStorage.setItem('userId', userResponse.user_id);
  console.log(`User created: ${userResponse.user_id}`);
} else {
  console.error('Failed to create user');
}

// Retrieve stored user_id for orders
const storedUserId = localStorage.getItem('userId');
if (storedUserId) {
  // Use in order creation
  const order = {
    market: 'SOL_USDC',
    side: 'buy',
    quantity: 0.1,
    price: 50000,
    userId: storedUserId
  };
}

Utility Types

Stat

Generic label-value pair for displaying statistics.

interface Stat {
  label: string;
  value: string;
}

label

string

Display label for the statistic

value

string

Value to display

Usage Example:

import { getTicker } from './utils/requests';
import { Stat, Ticker } from './utils/types';

const ticker: Ticker = await getTicker('SOL_USDC');

// Convert ticker to display stats
const stats: Stat[] = [
  { label: 'Last Price', value: `$${ticker.lastPrice}` },
  { label: '24h Change', value: `${ticker.priceChangePercent}%` },
  { label: '24h High', value: `$${ticker.high}` },
  { label: '24h Low', value: `$${ticker.low}` },
  { label: '24h Volume', value: `${ticker.volume} SOL` },
  { label: 'Trades', value: ticker.trades }
];

// Render stats in UI
stats.forEach((stat) => {
  console.log(`${stat.label}: ${stat.value}`);
});

Type Import Examples

All types can be imported from the types module:

import {
  KLine,
  Trade,
  Depth,
  Ticker,
  CreateOrder,
  UserId,
  Stat
} from './utils/types';

Full typing example:

import { getDepth, getTrades, getKlines, createOrder } from './utils/requests';
import { Depth, Trade, KLine, CreateOrder } from './utils/types';

async function tradingExample() {
  // Strongly typed API calls
  const depth: Depth = await getDepth('SOL_USDC');
  const trades: Trade[] = await getTrades('SOL_USDC');
  const klines: KLine[] = await getKlines('SOL_USDC', '1h', Date.now() - 86400000);

  // Type-safe order creation
  const order: CreateOrder = {
    market: 'SOL_USDC',
    side: 'buy',
    quantity: 0.1,
    price: 50000,
    userId: 'user-123'
  };

  const orderId: string = await createOrder(order);
}

Notes on Type Safety

String Numbers: Most numeric values are represented as strings to preserve precision. Parse them with parseFloat() or Number() when performing calculations.

Timestamps: Trade timestamps are Unix milliseconds (number). KLine start/end times are strings. Use new Date() for conversion.

Array Tuples: The Depth interface uses tuple types [string, string][] for bids and asks. First element is price, second is quantity.

Type Reference Location

All type definitions are located at: source/apps/web/src/utils/types.ts:1-58

Backend Integration

Components

Utils

Overview

Market Data Types

KLine

Trade

Depth

Ticker

Trading Types

CreateOrder

User Management Types

UserId

Utility Types

Stat

Type Import Examples

Notes on Type Safety

Type Reference Location

Build docs developers (and LLMs) love

Backend Integration

Components

Utils

​Overview

​Market Data Types

​KLine

​Trade

​Depth

​Ticker

​Trading Types

​CreateOrder

​User Management Types

​UserId

​Utility Types

​Stat

​Type Import Examples

​Notes on Type Safety

​Type Reference Location

Build docs developers (and LLMs) love

Overview

Market Data Types

KLine

Trade

Depth

Ticker

Trading Types

CreateOrder

User Management Types

UserId

Utility Types

Stat

Type Import Examples

Notes on Type Safety

Type Reference Location