Candlestick Data
GET /v1/predexon/candlesticks/{condition_id} — Retrieve historical OHLCV (Open, High, Low, Close, Volume) candlestick data for a condition at multiple time intervals.
- Base URL:
https://api.predexon.com/v1
- Auth:
x-api-key: YOUR_API_KEY
- Time: All timestamps are Unix timestamps (seconds)
- Rate Limits: 100 requests/minute per API key. Returns
429 when exceeded. Use exponential backoff on 429/503 responses.
Endpoint
GET /v1/predexon/candlesticks/{condition_id}
Path parameters
| Parameter | Type | Description |
|---|
condition_id | string | Ethereum condition address (e.g., 0x1234...). Required. |
Query parameters
| Parameter | Type | Required | Description |
|---|
start_time | integer | Yes | Unix timestamp (seconds) for start of time range. Must be >= 0. |
end_time | integer | Yes | Unix timestamp (seconds) for end of time range. Must be >= 0 and > start_time. |
interval | integer | No | Candlestick interval. Default: 1 (1-minute). See interval limits below. |
Interval values and range limits
The interval parameter controls the candlestick granularity and maximum time range:
| Interval | Duration | Max Time Range | Use Case |
|---|
1 | 1 minute | 1 week (604,800 seconds) | Intraday tick analysis |
60 | 1 hour | 1 month (2,592,000 seconds) | Daily and weekly trends |
1440 | 1 day | 1 year (31,536,000 seconds) | Long-term historical analysis |
Range validation: The time range (end_time - start_time) must not exceed the maximum allowed for the selected interval. For example, with interval=1, the range cannot exceed 1 week. Requests exceeding the limit will return a 400 validation error.
Response schema
{
"candlesticks": [
{
"timestamp": 1735660800,
"open": 0.52,
"high": 0.58,
"low": 0.51,
"close": 0.56,
"volume": 12345.67
},
{
"timestamp": 1735661860,
"open": 0.56,
"high": 0.59,
"low": 0.54,
"close": 0.57,
"volume": 11200.45
}
]
}
Field reference
| Field | Type | Description |
|---|
candlesticks | array | Array of candlestick bars in chronological order. |
candlesticks[].timestamp | integer | Unix timestamp (seconds) marking the start of the candlestick period. |
candlesticks[].open | number | Opening price for the period. |
candlesticks[].high | number | Highest price reached during the period. |
candlesticks[].low | number | Lowest price reached during the period. |
candlesticks[].close | number | Closing price at the end of the period. |
candlesticks[].volume | number | Total traded volume during the period. |
Data semantics
- Candlesticks are returned in chronological order (oldest first).
timestamp marks the left-closed boundary of the candlestick period (inclusive).- Each candlestick represents a complete period; no partial bars are included.
- Volume is reported in units of the underlying asset.
- All price fields are decimal numbers; maintain precision when processing.
Examples
curl -s "https://api.predexon.com/v1/predexon/candlesticks/0x1234567890abcdef1234567890abcdef12345678?start_time=1735574400&end_time=1735660800&interval=1" \
-H "x-api-key: YOUR_API_KEY"
{
"candlesticks": [
{
"timestamp": 1735660800,
"open": 0.52,
"high": 0.58,
"low": 0.51,
"close": 0.56,
"volume": 12345.67
},
{
"timestamp": 1735661860,
"open": 0.56,
"high": 0.59,
"low": 0.54,
"close": 0.57,
"volume": 11200.45
}
]
}
Errors
All errors return standard HTTP status codes with JSON error messages:
{
"message": "Range exceeds maximum for interval. Max 1 week for 1-minute candlesticks.",
"status": 400
}
| HTTP Status | Error Type | Description | Common Causes |
|---|
400 | Invalid range | Time range exceeds maximum for interval | Requesting >1 week of 1-minute data, >1 month of 1-hour data, or >1 year of 1-day data |
400 | Invalid interval | Invalid interval parameter | Using values other than 1, 60, or 1440 |
400 | Invalid timestamp | Malformed or invalid timestamp | Negative timestamps, non-integer values, or start_time >= end_time |
401 | Unauthorized | Missing or invalid API key | Missing x-api-key header or invalid key |
404 | Not found | Condition does not exist | Invalid or non-existent condition_id |
429 | Rate limit exceeded | Too many requests | Exceeded 100 req/min key limit |
500 | Internal error | Server error | Retry with exponential backoff |
503 | Service unavailable | Temporary service issue | Retry with exponential backoff |
Best practices
-
Respect interval limits: Always stay within the maximum time range for your chosen interval. Batch requests if you need data beyond the limits.
-
Align to interval boundaries: For cleaner data, align
start_time and end_time to multiples of the interval (e.g., for hourly data, use times that are multiples of 3600 seconds).
-
Cache results: Candlestick data for past periods is immutable. Cache completed requests to avoid redundant API calls.
-
Progressive backfill: When building historical datasets, fetch newer data first, then extend backward in time. This minimizes the impact of data corrections.
-
Volume validation: Check for unusual volume spikes or zero-volume candles, which may indicate data issues or low liquidity periods.
-
Use appropriate intervals:
- 1-minute: Real-time and intraday analysis (not beyond 1 week)
- 1-hour: Swing trading and trend analysis (up to 1 month)
- 1-day: Long-term trend analysis and historical backtesting
-
Handle decimals carefully: Store prices and volumes as high-precision decimals (strings or decimal types) to avoid floating-point precision loss.
