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 (default: 500, max: 1000)
`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",
  "timestamp": "2025-01-01T00:00:00Z"
}

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: Up to 1000 candles per request
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 between 1 and 1000
startTime must be less than endTime if both provided
No authentication required

Error Handling

Common error scenarios:

Error	Description
Invalid signature	EIP-712 signature validation failed
Invalid market symbol	Market symbol not recognized
Nonce already used	Nonce must be greater than previous value
Rate limit exceeded	Too many requests in time window
Request expired	`expiresAfter` timestamp has passed

Error	Description
Symbol required	Missing trading pair symbol
Invalid interval	Unsupported time interval
Invalid limit	Limit outside allowed range (1-1000)
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