OHLCV Data

Access OHLCV (Open, High, Low, Close, Volume) candlestick data via REST API for historical queries and WebSocket for real-time streaming. Build price charts, analytics, and trading indicators with complete market data.

Overview

Monaco Protocol provides comprehensive candlestick data through two complementary methods:

REST API - Fetch historical candlestick data for any time range
WebSocket - Stream real-time candlestick updates as they form

Perfect for building live price charts, technical analysis tools, and market monitoring dashboards.

Use Cases

Live Price Charts - Build real-time candlestick charts with historical context
Technical Analysis - Calculate indicators on historical and live data
Market Monitoring - Track price movements across timeframes
Trading Bots - Analyze historical patterns and react to live price action
Data Export - Download historical price data for backtesting

Key Features

Multiple Timeframes - 1m, 5m, 15m, 1h, 4h, 1d intervals
Real-time Updates - Instant candlestick updates as they form
Multiple Subscriptions - Subscribe to multiple pairs and intervals simultaneously
No Authentication - OHLCV streaming is public, no login required
Automatic Reconnection - Built-in connection reliability
TypeScript Support - Fully typed candlestick interfaces

Supported Intervals

Interval	Description	Use Case
`1m`	1 minute	Scalping, very short-term trading
`5m`	5 minutes	Short-term trading, quick analysis
`15m`	15 minutes	Intraday trading, trend identification
`1h`	1 hour	Swing trading, multi-hour trends
`4h`	4 hours	Position trading, daily analysis
`1d`	1 day	Long-term trends, investment analysis

REST API Query Parameters

The candlestick REST API supports flexible querying through optional parameters that can be used independently or in combination:

Parameters

startTime (optional) - Unix timestamp in milliseconds (UTC) defining the beginning of the time range
endTime (optional) - Unix timestamp in milliseconds (UTC) defining the end of the time range
limit (optional) - Maximum number of candlesticks to return
- Default: 350 bars
- Maximum: 500 bars per request
priceType (optional) - Which price series to chart
- trade (default) - the trade-derived OHLCV series
- mark - the mark-price series, available for margin pairs only. This series is close-only: each candle’s open, high, low, and close are all the bucket’s closing mark and volume is 0. Requesting mark on a spot pair returns a 400.
- Omit for the trade series.

Query Behavior

Time Constraints: Time parameters can be used independently—you may specify startTime only, endTime only, both together, or neither. When both are provided, startTime must be less than endTime. Time Bounds: startTime and endTime are both inclusive, and the window is absolute — no bar outside it is ever returned. A window holding fewer bars than limit comes back short rather than being padded with earlier history. Response Size: limit is a hard cap on the number of bars in the response, gap-filled bars included. When a time range contains more bars than the limit, the API returns the first limit bars from the range, enabling pagination through large datasets. Gap Filling: Buckets with no trades in them are returned as flat bars carrying the previous close, so a response has no holes. These bars count towards limit. Ordering: All candlesticks are returned in ascending chronological order (oldest to newest).

Query Patterns

// Get trading pair first
const pair = await sdk.market.getTradingPairBySymbol('BTC-USDC');

// Get 350 most recent bars (default limit)
await sdk.market.getCandlesticks(pair.id, '1m');

// Latest bars with custom limit
await sdk.market.getCandlesticks(pair.id, '1m', { limit: 100 });
// Returns: 100 most recent 1-minute candlesticks

// Mark-price series (margin pairs only, close-only bars)
await sdk.market.getCandlesticks(pair.id, '1m', { limit: 100, priceType: 'mark' });
// Returns: 100 most recent 1-minute mark candles (O=H=L=C=closing mark, volume 0)

// Time range query
await sdk.market.getCandlesticks(pair.id, '5m', {
  startTime: 1736000000000,
  endTime: 1737000000000,
  limit: 200
});
// Returns: Up to 200 candlesticks, all of them inside the range. Fewer if the
// range itself holds fewer than 200 buckets.

// Forward pagination (fetching data chronologically)
await sdk.market.getCandlesticks(pair.id, '1h', {
  startTime: 1736000000000,
  limit: 500
});
// Returns: Up to 500 candlesticks starting from startTime

// Backward pagination (TradingView pattern)
await sdk.market.getCandlesticks(pair.id, '1h', {
  endTime: 1736742000000,
  limit: 350
});
// Returns: Up to 350 candlesticks ending at endTime

Pagination

For large time ranges exceeding the 500-bar maximum, retrieve data incrementally using the timestamp of the last received candlestick:

const pair = await sdk.market.getTradingPairBySymbol('BTC-USDC');
let allCandles = [];
let currentStart = initialStartTime;
const endTime = Date.now();

while (currentStart < endTime) {
  const batch = await sdk.market.getCandlesticks(pair.id, '1h', {
    startTime: currentStart,
    endTime: endTime,
    limit: 500
  });
  
  if (batch.length === 0) break;
  
  allCandles = allCandles.concat(batch);
  currentStart = batch[batch.length - 1].T + 1; // Next timestamp after last candle
}

Fetching Historical Data

Use the REST API to fetch historical candlestick data for any time range:

import { MonacoSDK } from '@0xmonaco/core';
import { createWalletClient, custom } from 'viem';
import { seiTestnet } from 'viem/chains';

const [account] = await window.ethereum.request({ 
  method: 'eth_requestAccounts' 
});

const walletClient = createWalletClient({
  account,
  chain: seiTestnet,
  transport: custom(window.ethereum)
});

const sdk = new MonacoSDK({
  walletClient,
  network: 'staging',
  seiRpcUrl: 'https://evm-rpc-testnet.sei-apis.com', // public testnet RPC — use a private provider in production
});

// Get trading pair
const pair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

// Fetch last 24 hours of hourly candles
const endTime = Date.now();
const startTime = endTime - (24 * 60 * 60 * 1000);

const candles = await sdk.market.getCandlesticks(pair.id, '1h', {
  startTime,
  endTime
});

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

Common Time Ranges

const pair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

const last1Hour = await sdk.market.getCandlesticks(pair.id, '1m', {
  startTime: Date.now() - (60 * 60 * 1000),
  endTime: Date.now()
});

// Last 7 days (hourly candles)
const last7Days = await sdk.market.getCandlesticks(pair.id, '1h', {
  startTime: Date.now() - (7 * 24 * 60 * 60 * 1000),
  endTime: Date.now()
});

// Last 30 days (daily candles)
const last30Days = await sdk.market.getCandlesticks(pair.id, '1d', {
  startTime: Date.now() - (30 * 24 * 60 * 60 * 1000),
  endTime: Date.now()
});

Real-time OHLCV Streaming

Subscribe to live candlestick updates via WebSocket. No authentication required.

Basic Subscription

const pair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

const unsubscribe = sdk.ws.ohlcv(
  pair.id,    // Trading pair ID (UUID)
  'SPOT',     // Trading mode
  '1m',       // Interval
  (event) => {
    const candle = event.candlestick;
    console.log('Open:', candle.o);
    console.log('High:', candle.h);
    console.log('Low:', candle.l);
    console.log('Close:', candle.c);
    console.log('Volume:', candle.v);
  }
);

// Later, to unsubscribe:
unsubscribe();

Candlestick Structure

import type { Interval, TradingMode } from '@0xmonaco/types';

interface OHLCVEvent {
  tradingPairId: string;
  tradingMode: TradingMode | (string & {});
  interval: Interval | (string & {});
  priceType?: "trade" | "mark" | (string & {}); // concrete series; absent on legacy frames
  candlestick: {
    T: number;  // Period start timestamp (ms, UTC)
    t: number;  // Period end timestamp (ms, UTC)
    o: string;  // Open price
    h: string;  // High price
    l: string;  // Low price
    c: string;  // Close price
    v: string;  // Volume
    s: string;  // Symbol
    i: string;  // Interval
    n: number;  // Number of trades
  };
}

Usage Examples

Multiple Timeframes

Subscribe to multiple intervals for the same pair:

const pair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

// 1-minute candles for scalping
const unsub1m = sdk.ws.ohlcv(pair.id, 'SPOT', '1m', (event) => {
  console.log('1m:', event.candlestick.c);
});

// Hourly candles for trend analysis
const unsub1h = sdk.ws.ohlcv(pair.id, 'SPOT', '1h', (event) => {
  console.log('1h:', event.candlestick.c);
});

// Daily candles for long-term view
const unsub1d = sdk.ws.ohlcv(pair.id, 'SPOT', '1d', (event) => {
  console.log('1d:', event.candlestick.c);
});

// Cleanup all
// unsub1m(); unsub1h(); unsub1d();

Calculate Price Change

const pair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

const unsubscribe = sdk.ws.ohlcv(pair.id, 'SPOT', '1h', (event) => {
  const candle = event.candlestick;
  const open = parseFloat(candle.o);
  const close = parseFloat(candle.c);
  const change = ((close - open) / open) * 100;
  
  console.log(`BTC 1h: ${close} (${change.toFixed(2)}%)`);
});

Building a Chart

const candleHistory: Candlestick[] = [];
const pair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

const unsubscribe = sdk.ws.ohlcv(pair.id, 'SPOT', '5m', (event) => {
  const candle = event.candlestick;
  
  // Check if updating existing or new candle
  const lastCandle = candleHistory[candleHistory.length - 1];
  if (lastCandle && lastCandle.T === candle.T) {
    // Update existing candle
    candleHistory[candleHistory.length - 1] = candle;
  } else {
    // New candle period
    candleHistory.push(candle);
    if (candleHistory.length > 100) {
      candleHistory.shift();
    }
  }
  
  updateChart(candleHistory);
});

Technical Indicators

Calculate a simple moving average:

const closes: number[] = [];
const pair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

const unsubscribe = sdk.ws.ohlcv(pair.id, 'SPOT', '5m', (event) => {
  const close = parseFloat(event.candlestick.c);
  closes.push(close);
  
  // Keep last 20 periods
  if (closes.length > 20) {
    closes.shift();
  }
  
  // Calculate SMA(20)
  if (closes.length >= 20) {
    const sma20 = closes.reduce((a, b) => a + b) / 20;
    console.log('SMA(20):', sma20.toFixed(2));
    
    if (close > sma20) {
      console.log('Price above SMA - Bullish');
    } else {
      console.log('Price below SMA - Bearish');
    }
  }
});

Combining Historical + Live Data

Initialize charts with historical data, then stream live updates:

const pair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

// 1. Load historical data
const historicalCandles = await sdk.market.getCandlesticks(pair.id, '5m', {
  startTime: Date.now() - (12 * 60 * 60 * 1000), // Last 12 hours
  endTime: Date.now()
});

const chartData = [...historicalCandles];
updateChart(chartData);

// 2. Stream live updates
const unsubscribe = sdk.ws.ohlcv(pair.id, 'SPOT', '5m', (event) => {
  const newCandle = event.candlestick;
  const lastCandle = chartData[chartData.length - 1];
  
  if (lastCandle && lastCandle.T === newCandle.T) {
    // Update existing candle
    chartData[chartData.length - 1] = newCandle;
  } else {
    // New candle period
    chartData.push(newCandle);
  }
  
  updateChart(chartData);
});

Complete Example

import { MonacoSDK } from '@0xmonaco/core';
import { createWalletClient, custom } from 'viem';
import { seiTestnet } from 'viem/chains';

async function setupPriceMonitor() {
  // 1. Setup SDK
  const [account] = await window.ethereum.request({ 
    method: 'eth_requestAccounts' 
  });

  const walletClient = createWalletClient({
    account,
    chain: seiTestnet,
    transport: custom(window.ethereum)
  });

  const sdk = new MonacoSDK({
    walletClient,
    network: 'staging',
    seiRpcUrl: 'https://evm-rpc-testnet.sei-apis.com',
  });

  // 2. Get trading pair
  const pair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

  // 3. Subscribe to multiple timeframes
  const priceData = { '1m': '', '1h': '', '1d': '' };

  const unsub1m = sdk.ws.ohlcv(pair.id, 'SPOT', '1m', (event) => {
    priceData['1m'] = event.candlestick.c;
    console.log('1m price:', priceData['1m']);
  });

  const unsub1h = sdk.ws.ohlcv(pair.id, 'SPOT', '1h', (event) => {
    priceData['1h'] = event.candlestick.c;
    console.log('1h price:', priceData['1h']);
  });

  const unsub1d = sdk.ws.ohlcv(pair.id, 'SPOT', '1d', (event) => {
    priceData['1d'] = event.candlestick.c;
    console.log('Daily candle:', event.candlestick);
  });

  // 4. Cleanup when done
  // unsub1m(); unsub1h(); unsub1d();
}

setupPriceMonitor().catch(console.error);

React Integration

import { useEffect, useState } from 'react';
import { useMonacoSDK } from '@0xmonaco/react';

interface Candlestick {
  T: number;  // Period start timestamp (ms, UTC)
  t: number;  // Period end timestamp (ms, UTC)
  o: string;  // Open price
  h: string;  // High price
  l: string;  // Low price
  c: string;  // Close price
  v: string;  // Volume
  s: string;  // Symbol
  i: string;  // Interval
  n: number;  // Number of trades
}

function PriceChart({ tradingPairId, interval }: { 
  tradingPairId: string; 
  interval: '1m' | '5m' | '15m' | '1h' | '4h' | '1d';
}) {
  const { sdk } = useMonacoSDK();
  const [candles, setCandles] = useState<Candlestick[]>([]);

  useEffect(() => {
    if (!sdk) return;

    const unsubscribe = sdk.ws.ohlcv(
      tradingPairId,
      'SPOT',
      interval,
      (event) => {
        setCandles(prev => {
          const updated = [...prev];
          const last = updated[updated.length - 1];
          
          if (last && last.T === event.candlestick.T) {
            updated[updated.length - 1] = event.candlestick;
          } else {
            updated.push(event.candlestick);
          }
          
          return updated.slice(-100);
        });
      }
    );

    return () => unsubscribe();
  }, [sdk, tradingPairId, interval]);

  const latestPrice = candles.length > 0 
    ? candles[candles.length - 1].c 
    : 'Loading...';

  return (
    <div>
      <h3>Price: {latestPrice}</h3>
      <p>Candles: {candles.length}</p>
    </div>
  );
}

Best Practices

1. Use Trading Pair IDs

// Get the trading pair ID first
const pair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

// Use the UUID for subscriptions
sdk.ws.ohlcv(pair.id, 'SPOT', '1m', handler);

2. Clean Up Subscriptions

const unsubscribe = sdk.ws.ohlcv(pairId, 'SPOT', '1m', handler);

// When done
unsubscribe();

3. Parse Prices Correctly

sdk.ws.ohlcv(pairId, 'SPOT', '1m', (event) => {
  // Prices are strings - convert to numbers for calculations
  const open = parseFloat(event.candlestick.o);
  const close = parseFloat(event.candlestick.c);
  const change = close - open;
});

4. Handle Timestamps

sdk.ws.ohlcv(pairId, 'SPOT', '1m', (event) => {
  const candle = event.candlestick;
  
  // T = Start time, t = End time (both Unix milliseconds in UTC)
  const startDate = new Date(candle.T);
  const endDate = new Date(candle.t);
  
  console.log('Candle period:', startDate, 'to', endDate);
});

Next Steps

WebSocket API - All real-time streaming channels
Trades API - REST API for trade history
Order Management - Place and manage orders

Learn

Build

Libraries

APIs

Resources

Overview

Use Cases

Key Features

Supported Intervals

REST API Query Parameters

Parameters

Query Behavior

Query Patterns

Fetching Historical Data

Common Time Ranges

Real-time OHLCV Streaming

Basic Subscription

Candlestick Structure

Usage Examples

Multiple Timeframes

Calculate Price Change

Building a Chart

Technical Indicators

Combining Historical + Live Data

Complete Example

React Integration

Best Practices

1. Use Trading Pair IDs

2. Clean Up Subscriptions

3. Parse Prices Correctly

4. Handle Timestamps

Next Steps

​Overview

​Use Cases

​Key Features

​Supported Intervals

​REST API Query Parameters

​Parameters

​Query Behavior

​Query Patterns

​Pagination

​Fetching Historical Data

​Common Time Ranges

​Real-time OHLCV Streaming

​Basic Subscription

​Candlestick Structure

​Usage Examples

​Multiple Timeframes

​Calculate Price Change

​Building a Chart

​Technical Indicators

​Combining Historical + Live Data

​Complete Example

​React Integration

​Best Practices

​1. Use Trading Pair IDs

​2. Clean Up Subscriptions

​3. Parse Prices Correctly

​4. Handle Timestamps

​Next Steps

Overview

Use Cases

Key Features

Supported Intervals

REST API Query Parameters

Parameters

Query Behavior

Query Patterns

Pagination

Fetching Historical Data

Common Time Ranges

Real-time OHLCV Streaming

Basic Subscription

Candlestick Structure

Usage Examples

Multiple Timeframes

Calculate Price Change

Building a Chart

Technical Indicators

Combining Historical + Live Data

Complete Example

React Integration

Best Practices

1. Use Trading Pair IDs

2. Clean Up Subscriptions

3. Parse Prices Correctly

4. Handle Timestamps

Next Steps