Market data / API reference
Get exchange candles
Request and response reference for GET /v1/exchange/candles.
GET
/v1/exchange/candlesAuthentication: Feed bearer
Use the base URL and access configuration provided to your institution. Examples are request templates, not transaction results. Field tables focus on client fields; preserve additional metadata returned by the configured service.
Request
Use your feed-scoped bearer token against the market-data service. Feed access does not authorize exchange execution.
curl -X GET "$OSAI_MARKET_DATA_BASE_URL/v1/exchange/candles?feed_id=$FEED_ID&feed_version=$FEED_VERSION&pair=$PAIR&interval=$INTERVAL&from=$FROM&to=$TO&limit=$LIMIT" \
-H "Authorization: Bearer $OSAI_FEED_TOKEN"Parameters
| Name | Location | Requirement | Description |
|---|---|---|---|
feed_id | query · string | Required | Scoped feed ID from candle-series discovery. |
feed_version | query · string | Required | Exact version string from discovery. |
pair | query · string | Required | Canonical pair; must match configured feed. |
interval | query · string | Required | Resolution independent of visible range. |
from | query · string | Required | Inclusive UTC-aligned bucket open; current retention applies. |
to | query · string | Required | Exclusive UTC-aligned end; full window bounded by maximum_query_buckets. |
limit | query · integer | Required | Bucket count INCLUDING gaps, also bounded by configured feed policy. |
as_of | query · string | Optional | Optional snapshot; carry unchanged with next_from and original to/interval/feed. Snapshot is not source freshness and does not bypass current retention. |
Request body
This operation does not define a JSON request body.
Responses
Inspect HTTP status before parsing a body. These tables describe client response fields rather than invented successful transaction payloads.
200 · HTTP 200 response
| Field | Type | Description & constraints |
|---|---|---|
contract_versionRequired in parent object | string | Defined by the resource contract.Values: osai-candles/v1 |
price_scaleRequired in parent object | string | Defined by the resource contract.Pattern: ^[1-9][0-9]*$ |
feed_versionRequired in parent object | string | Defined by the resource contract.Pattern: ^[1-9][0-9]*$ |
pair_versionRequired in parent object | string | Defined by the resource contract.Pattern: ^[1-9][0-9]*$ |
feedRequired in parent object | object | Legacy internal feed-policy object. Browser consumers use top-level string price_scale/feed_version/pair_version, not numeric copies in this object. |
intervalRequired in parent object | string | Defined by the resource contract.Values: 1m, 5m, 15m, 1h, 4h, 1d |
orderRequired in parent object | string | Defined by the resource contract.Values: ASC |
timestamp_precisionRequired in parent object | string | Defined by the resource contract.Values: MILLISECOND |
aggregationRequired in parent object | string | Defined by the resource contract.Values: EVENT_TIME_THEN_SEQUENCE_THEN_EVENT_ID |
aggregation_versionRequired in parent object | string | Defined by the resource contract.Values: osai-indicative-candles/v1 |
as_ofRequired in parent object | stringdate-time | Defined by the resource contract. |
window_fromRequired in parent object | stringdate-time | Defined by the resource contract. |
window_toRequired in parent object | stringdate-time | Defined by the resource contract. |
next_fromOptional | stringdate-time | Defined by the resource contract. |
candlesRequired in parent object | array | Defined by the resource contract. |
candles[].timestampRequired in parent object | stringdate-time | Defined by the resource contract. |
candles[].openRequired in parent object | string | Defined by the resource contract.Pattern: ^[1-9][0-9]*$ |
candles[].highRequired in parent object | string | Defined by the resource contract.Pattern: ^[1-9][0-9]*$ |
candles[].lowRequired in parent object | string | Defined by the resource contract.Pattern: ^[1-9][0-9]*$ |
candles[].closeRequired in parent object | string | Defined by the resource contract.Pattern: ^[1-9][0-9]*$ |
candles[].volumeRequired in parent object | string | null | Always null for this indicative contract; undefined volume is never zero. |
candles[].source_typeRequired in parent object | string | Defined by the resource contract.Values: INDICATIVE |
candles[].is_completeRequired in parent object | boolean | Defined by the resource contract. |
candles[].updated_atRequired in parent object | stringdate-time | Defined by the resource contract. |
candles[].revision_hashRequired in parent object | string | Defined by the resource contract.Pattern: ^[a-f0-9]{64}$ |
candles[].qualityRequired in parent object | array | Defined by the resource contract. |
gapsRequired in parent object | array | Defined by the resource contract. |
executableRequired in parent object | boolean | Defined by the resource contract.Values: false |
externally_releasedRequired in parent object | boolean | Defined by the resource contract.Values: false |
400 · HTTP 400 response
| Field | Type | Description & constraints |
|---|---|---|
errorRequired in parent object | string | Defined by the resource contract. |
401 · HTTP 401 response
| Field | Type | Description & constraints |
|---|---|---|
errorRequired in parent object | string | Defined by the resource contract. |
403 · HTTP 403 response
| Field | Type | Description & constraints |
|---|---|---|
errorRequired in parent object | string | Defined by the resource contract. |
404 · HTTP 404 response
| Field | Type | Description & constraints |
|---|---|---|
errorRequired in parent object | string | Defined by the resource contract. |
405 · HTTP 405 response
| Field | Type | Description & constraints |
|---|---|---|
errorRequired in parent object | string | Defined by the resource contract. |
429 · HTTP 429 response
Response headers: Retry-After.
| Field | Type | Description & constraints |
|---|---|---|
errorRequired in parent object | string | Defined by the resource contract. |
503 · HTTP 503 response
| Field | Type | Description & constraints |
|---|---|---|
errorRequired in parent object | string | Defined by the resource contract. |
Retries & recovery
Keep the original request identifiers and any required idempotency key. A timeout does not establish failure. Read the original resource or command before another financial write; use expected versions for concurrent changes.