Get Candles (WebSocket)

Retrieve OHLCV (Open, High, Low, Close, Volume) price data for a specific trading pair through the WebSocket connection. This endpoint provides historical candlestick data for technical analysis and charting without requiring authentication.

Endpoint

ws.send() wss://api.synthetix.io/v1/ws/info

Request

Request Format

{
  "id": "candles-1",
  "method": "post",
  "params": {
    "action": "getCandles",
    "symbol": "BTC-USDT",
    "interval": "1h",
    "limit": 500,
    "startTime": 1704067200000,
    "endTime": 1704153600000
  }
}

Request Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Client-generated unique request identifier
`method`	string	Yes	Must be `"post"`
`params`	object	Yes	Request parameters wrapper
`params.action`	string	Yes	Must be `"getCandles"`
`params.symbol`	string	Yes	Trading pair symbol (e.g., `"BTC-USDT"`)
`params.interval`	string	Yes	Time interval: `1m`, `5m`, `15m`, `1h`, `4h`, `1d`, `1w`, `1M`
`params.limit`	integer	No	Number of candles to return (0 = no limit)
`params.startTime`	integer	No	Start time in milliseconds (default: 24 hours ago)
`params.endTime`	integer	No	End time in milliseconds (default: current time)

Valid Intervals

Interval	Description	Milliseconds
`1m`	1 minute	60,000
`5m`	5 minutes	300,000
`15m`	15 minutes	900,000
`1h`	1 hour	3,600,000
`4h`	4 hours	14,400,000
`1d`	1 day	86,400,000
`1w`	1 week	604,800,000
`1M`	1 month	2,592,000,000

Response

Success Response

{
  "id": "candles-1",
  "status": 200,
  "result": {
    "response": {
      "symbol": "BTC-USDT",
      "interval": "1h",
      "candles": [
        {
          "openTime": 1704067200000,
          "closeTime": 1704070800000,
          "openPrice": "45000.50",
          "highPrice": "45100.00",
          "lowPrice": "44950.00",
          "closePrice": "45050.00",
          "volume": "125.5",
          "quoteVolume": "125500.00",
          "tradeCount": 1523
        },
        {
          "openTime": 1704070800000,
          "closeTime": 1704074400000,
          "openPrice": "45050.00",
          "highPrice": "45200.00",
          "lowPrice": "45000.00",
          "closePrice": "45150.00",
          "volume": "98.2",
          "quoteVolume": "98450.00",
          "tradeCount": 1102
        }
      ]
    },
    "status": "success"
  }
}

Response Fields

Field	Type	Description
`result.response.symbol`	string	Trading pair symbol
`result.response.interval`	string	Time interval used
`result.response.candles`	array	Array of candle objects
`result.status`	string	Always `"success"` for successful responses

Candle Object

Field	Type	Description
`openTime`	integer	Candle open time in milliseconds
`closeTime`	integer	Candle close time in milliseconds
`openPrice`	string	Opening price
`highPrice`	string	Highest price during the period
`lowPrice`	string	Lowest price during the period
`closePrice`	string	Closing price
`volume`	string	Base asset trading volume
`quoteVolume`	string	Quote asset trading volume
`tradeCount`	integer	Number of trades in the period

Error Response

{
  "id": "candles-1",
  "status": 400,
  "result": null,
  "error": {
    "code": 400,
    "message": "Invalid interval"
  }
}

WebSocket Connection Example

const ws = new WebSocket('wss://papi.synthetix.io/v1/ws/info');
 
ws.onopen = () => {
  // Request hourly candles for BTC-USDT
  ws.send(JSON.stringify({
    id: 'candles-1',
    method: 'post',
    params: {
      action: 'getCandles',
      symbol: 'BTC-USDT',
      interval: '1h',
      limit: 100
    }
  }));
};
 
ws.onmessage = (event) => {
  const response = JSON.parse(event.data);
 
  if (response.id === 'candles-1' && response.status === 200) {
    const data = response.result.response;
    console.log(`${data.symbol} ${data.interval} candles:`, data.candles);
 
    // Process candle data
    data.candles.forEach(candle => {
      console.log(`Open: ${candle.openPrice}, High: ${candle.highPrice}, Low: ${candle.lowPrice}, Close: ${candle.closePrice}`);
    });
  }
};

Examples

Get Recent 1-Hour Candles

{
  "id": "candles-hourly",
  "method": "post",
  "params": {
    "action": "getCandles",
    "symbol": "BTC-USDT",
    "interval": "1h",
    "limit": 100
  }
}

Get Daily Candles for Date Range

{
  "id": "candles-daily",
  "method": "post",
  "params": {
    "action": "getCandles",
    "symbol": "ETH-USDT",
    "interval": "1d",
    "startTime": 1704067200000,
    "endTime": 1704153600000,
    "limit": 30
  }
}

Get 5-Minute Candles

{
  "id": "candles-5m",
  "method": "post",
  "params": {
    "action": "getCandles",
    "symbol": "BTC-USDT",
    "interval": "5m",
    "limit": 200
  }
}

Get All Candles (No Limit)

{
  "id": "candles-all",
  "method": "post",
  "params": {
    "action": "getCandles",
    "symbol": "BTC-USDT",
    "interval": "1h",
    "limit": 0,
    "startTime": 1704067200000,
    "endTime": 1704153600000
  }
}

Implementation Notes

Public Data: No authentication required for this endpoint
Symbol Required: A valid market symbol must be provided
Interval Required: A valid time interval must be specified
Limit Usage: Set limit to 0 for no limit, or specify desired number of candles
Time Range: Optional start and end time filtering with millisecond precision
Sorting: Candles are returned in ascending order by time (oldest first)

Use Cases

Technical Analysis

Chart patterns and trend identification
Technical indicator calculations (RSI, MACD, moving averages)
Support and resistance level identification

Trading Strategies

Backtesting algorithmic strategies
Entry and exit point determination
Volatility analysis

Market Research

Historical price movement analysis
Volume trend analysis
Market behavior patterns

Risk Management

Volatility assessment
Drawdown calculations
Portfolio performance tracking

Validation Rules

No authentication required (public Info WebSocket)
Symbol parameter is required and must be a valid market symbol
Interval parameter is required and must be one of the valid intervals
Limit must be non-negative (≥ 0), where 0 means no limit
If both startTime and endTime are provided, startTime must be less than endTime

Common Errors

Error	Description
Symbol required	Missing trading pair symbol
Invalid interval	Unsupported time interval
Invalid limit	Limit must be non-negative
Invalid time range	Start time is after end time
Failed to retrieve data	Internal service error

Performance Considerations

Low Latency: WebSocket connection provides faster response times than REST
Persistent Connection: Reuse the same connection for multiple requests
Efficient Queries: Use specific time ranges to reduce data transfer
Caching: Historical candle data is immutable and suitable for caching

Related Endpoints

Candle Updates - Real-time candle updates via subscription
Get Market Prices - Current mid prices
Get Markets - Available trading pairs
REST Alternative - HTTP request for candles