Get Candles

Retrieve OHLCV (Open, High, Low, Close, Volume) price data for a specific trading pair.

Endpoint

POST https://papi.synthetix.io/v1/info

Request

Request Format

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

Request Parameters

Parameter	Type	Required	Description
`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

{
  "status": "ok",
  "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
      }
    ]
  },
  "request_id": "5ccf215d37e3ae6d"
}

Candle Response Object

Field	Type	Description
`symbol`	string	Trading pair symbol
`interval`	string	Time interval used
`candles`	array	Array of candle objects

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

{
  "status": "error",
  "error": {
    "message": "Invalid request parameters",
    "code": "VALIDATION_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d"
}

Code Examples

Get Recent 1-Hour Candles

{
  "params": {
    "action": "getCandles",
    "symbol": "BTC-USDT",
    "interval": "1h",
    "limit": 100
  }
}

Get Daily Candles for Date Range

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

Candle Data Information

OHLCV Format: Standard Open, High, Low, Close, Volume data
Flexible Timeframes: Multiple intervals from 1 minute to 1 month
Configurable Limits: Set limit to 0 for no limit, or specify desired number of candles
Time Range Support: Optional start and end time filtering
Real-time Data: Latest market data with minimal delay

Use Cases

Technical Analysis: Chart patterns, indicators, and analysis
Trading Strategies: Backtesting and strategy development
Market Research: Historical price movement analysis
Risk Management: Volatility and trend analysis
Performance Tracking: Portfolio performance over time

Validation Rules

symbol must be a valid trading pair
interval must be one of the valid intervals
limit must be non-negative (≥ 0), where 0 means no limit
startTime must be less than endTime if both provided
No authentication required

Error Handling

Common error scenarios:

Error Code	Description	Retryable
`UNAUTHORIZED`	EIP-712 signature validation failed	No
`VALIDATION_ERROR`	Request validation failed	No
`MISSING_REQUIRED_FIELD`	Required field is missing	No
`INVALID_FORMAT`	Field format is invalid	No
`INVALID_VALUE`	Invalid parameter value	No
`RATE_LIMIT_EXCEEDED`	Too many requests in time window	Yes
`INSUFFICIENT_MARGIN`	Not enough margin for trade	No
`ORDER_NOT_FOUND`	Order does not exist	No
`OPERATION_TIMEOUT`	Operation timed out	Yes

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

Rate Limiting

Default: 1000 requests per minute per IP
Burst: Up to 100 requests per second
Data Volume: Large requests may be rate-limited

Related Endpoints

Get Markets - Market configuration
Get Market Prices - Current prices
Get Orderbook - Order book depth