OHLCV

Fetch OHLCV (Open, High, Low, Close, Volume) candlestick data for a specific Deepbook pool. This endpoint aggregates trade data into time-based candles, enabling price charting, technical analysis, and historical trend visualization.

Endpoint

GET /deepbook/{poolName}/ohlcv/{timeframe}

Use Cases

• Price Charts — Display candlestick, bar, or line charts in trading interfaces
• Technical Analysis — Calculate indicators like moving averages, RSI, MACD, Bollinger Bands
• Historical Performance — Analyze price trends and volatility over time
• Backtesting — Test trading strategies against historical price data
• Market Reports — Generate daily/weekly/monthly market summaries

Parameters

Path Parameters

Parameter	Type	Required	Description
poolName	string	Yes	The Deepbook pool name (e.g., "SUI_USDC")
timeframe	string	Yes	Candlestick timeframe: 1m, 5m, 15m, 1h, 4h, 1d

Query Parameters

Parameter	Type	Required	Default	Description
limit	number	No	100	Maximum number of OHLCV candles to return (min 1, max 100)
from	number	No	-1 day	Start timestamp in seconds (UNIX timestamp). Defaults to 1 day ago.
to	number	No	now	End timestamp in seconds (UNIX timestamp). Defaults to current time.
api-key	string	Yes	—	Your Surflux API key for authentication

Supported Timeframes

Timeframe	Description	Typical Use Case
1m	1 minute	High-frequency trading, scalping
5m	5 minutes	Intraday trading
15m	15 minutes	Short-term trading
1h	1 hour	Swing trading, day trading
4h	4 hours	Position trading
1d	1 day	Long-term analysis, investment decisions

Response

Returns an array of OHLCV candle objects, ordered from oldest to newest.

Field	Type	Description
timestamp	string	ISO 8601 timestamp marking the start of the candle period
open	number	Opening price (first trade in the period, in smallest units)
high	number	Highest price during the period (in smallest units)
low	number	Lowest price during the period (in smallest units)
close	number	Closing price (last trade in the period, in smallest units)
volume_base	string	Total base asset volume traded during the period
volume_quote	string	Total quote asset volume traded during the period
trade_count	number	Number of trades executed during the period

Example Response

[
  {
    "timestamp": "2025-09-23T09:50:00",
    "open": 3367400,
    "high": 3367700,
    "low": 3367400,
    "close": 3367700,
    "volume_base": "1336200000000",
    "volume_quote": "4499653500",
    "trade_count": 3
  },
  {
    "timestamp": "2025-09-23T09:49:00",
    "open": 3368200,
    "high": 3368200,
    "low": 3362700,
    "close": 3366600,
    "volume_base": "9790100000000",
    "volume_quote": "32945858910",
    "trade_count": 24
  }
]

Example Request

curl "https://api.surflux.dev/deepbook/SUI_USDC/ohlcv/1h?limit=100&api-key=YOUR_API_KEY"

const apiKey = 'YOUR_API_KEY';
const poolName = 'SUI_USDC';
const timeframe = '1h';

// Get last 100 hourly candles
const url = `https://api.surflux.dev/deepbook/${poolName}/ohlcv/${timeframe}?limit=100&api-key=${apiKey}`;

const response = await fetch(url);
const candles = await response.json();

console.log(`Fetched ${candles.length} ${timeframe} candles`);

// Calculate 24h price change
const latest = candles[candles.length - 1];
const dayAgo = candles[candles.length - 24];

if (dayAgo) {
  const priceChange = ((latest.close - dayAgo.close) / dayAgo.close) * 100;
  console.log(`24h price change: ${priceChange.toFixed(2)}%`);
}

Understanding OHLCV Data

Price Values

All price fields (open, high, low, close) are in smallest units based on asset decimals. Convert using pool metadata:

// For SUI_USDC with 6 quote decimals
const rawClose = 3367700;
const humanClose = rawClose / Math.pow(10, 6); // = 3.3677 USDC per SUI

Volume Values

Volume fields are returned as strings due to large numbers:

// Base volume (SUI with 9 decimals)
const baseVolume = parseFloat(candle.volume_base) / Math.pow(10, 9);
// = 1336.2 SUI

// Quote volume (USDC with 6 decimals)
const quoteVolume = parseFloat(candle.volume_quote) / Math.pow(10, 6);
// = 4499.65 USDC

Timestamp Alignment

Timestamps mark the start of each candle period. For example, a 1-hour candle with timestamp 2025-09-23T09:00:00 includes all trades from 09:00:00 to 09:59:59.

Charting with OHLCV Data

Candlestick Chart Example

// Using a charting library like Chart.js or TradingView
const chartData = candles.map(candle => ({
  time: new Date(candle.timestamp).getTime() / 1000,
  open: candle.open / 1e6,
  high: candle.high / 1e6,
  low: candle.low / 1e6,
  close: candle.close / 1e6,
}));

// Feed to your charting library
chart.setData(chartData);

Calculating Technical Indicators

// Simple Moving Average (SMA)
function calculateSMA(candles, period) {
  return candles.map((candle, index, array) => {
    if (index < period - 1) return null;

    const slice = array.slice(index - period + 1, index + 1);
    const sum = slice.reduce((acc, c) => acc + c.close, 0);
    return sum / period;
  });
}

const sma20 = calculateSMA(candles, 20);
const sma50 = calculateSMA(candles, 50);

Time Range Queries

Request specific historical periods using from and to:

// Last 30 days of daily candles
const thirtyDaysAgo = Math.floor(Date.now() / 1000) - (30 * 86400);
const url = `...ohlcv/1d?from=${thirtyDaysAgo}&limit=30&api-key=...`;

// Specific month
const startOfMonth = new Date('2025-01-01').getTime() / 1000;
const endOfMonth = new Date('2025-01-31').getTime() / 1000;
const url = `...ohlcv/1d?from=${startOfMonth}&to=${endOfMonth}&api-key=...`;

Best Practices

• Choose Appropriate Timeframes — Match timeframe to your use case. Day traders need 5m-1h, long-term analysts need 1d.
• Request Sufficient Data — The limit is capped at 100 candles. For longer periods, make multiple requests using from and to parameters.
• Cache Historical Candles — Past candles never change. Cache them locally and only fetch new candles.
• Calculate Change Percentages — Compare close values between candles to show price movement: ((current - previous) / previous) * 100.
• Use Volume for Confirmation — High volume during price moves indicates stronger trends. Use trade_count to detect low-liquidity periods.
• Convert to User's Timezone — The timestamp field is in UTC. Convert to the user's local timezone for better UX.
• Handle Missing Candles — If no trades occurred during a period, that candle may be missing. Fill gaps in your chart with previous close values.

Performance Tips

Optimizing Chart Load Times

// Initial load: Get recent data
const dailyCandles = await fetch('...ohlcv/1d?limit=100&api-key=...');

// For longer periods, make multiple requests with time ranges
const startTime = visibleRange.start;
const endTime = visibleRange.end;
const detailedCandles = await fetch(
  `...ohlcv/5m?from=${startTime}&to=${endTime}&limit=100&api-key=...`
);

Progressive Loading

// Load recent data first, then backfill historical
const recentCandles = await fetch('...ohlcv/1h?limit=100&api-key=...');
displayChart(recentCandles);

// Backfill older data in background by making multiple requests
const olderStart = Math.floor(Date.now() / 1000) - (200 * 3600); // 200 hours ago
const historicalCandles = await fetch(`...ohlcv/1h?from=${olderStart}&limit=100&api-key=...`);
updateChart(historicalCandles);