Skip to content

Commit 1169edf

Browse files
dev-distdev-dist
committed
updated docs and added to sidebar
1 parent edadf28 commit 1169edf

File tree

3 files changed

+305
-215
lines changed

3 files changed

+305
-215
lines changed

‎src/config/sidebar.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -398,9 +398,13 @@ export const SIDEBAR: Partial<Record<Sections, SectionEntry[]>> = {
398398
url: "data-streams/reference/overview",
399399
},
400400
{
401-
title: "REST API",
401+
title: "Data Streams REST API",
402402
url: "data-streams/reference/interface-api",
403403
},
404+
{
405+
title: "Candlestick REST API",
406+
url: "data-streams/reference/candlestick-api",
407+
},
404408
{
405409
title: "WebSocket",
406410
url: "data-streams/reference/interface-ws",

‎src/content/data-streams/reference/candlestick-api.mdx‎

Lines changed: 300 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,300 @@
1+
---
2+
section: dataStreams
3+
date: July 30, 2025
4+
title: "Data Streams Candlestick API"
5+
metadata:
6+
title: "Data Streams Candlestick API Reference | Chainlink Documentation"
7+
description: "Reference for the Chainlink Data Streams Candlestick API. Learn how to authenticate, list available symbols, query historical candlestick (OHLC) data, and stream live price updates over HTTP."
8+
keywords: ["Candlestick API", "OHLC", "HTTP Rest API", "API Client", "Trading View API"]
9+
---
10+
11+
import DataStreams from "@features/data-streams/common/DataStreams.astro"
12+
13+
<DataStreams section="dsNotes" />
14+
15+
The Candlestick API is designed and implemented to satisfy the [TradingView implementation spec](https://www.tradingview.com/broker-api-docs/rest-api-spec/#tag/Data-Integration), the industry standard for sharing aggregated trading data.
16+
17+
Alignment with the TradingView spec allows for TradingView integration and direct customer access to prices without resorting to consuming and decoding reports for non-transactional use cases, like dashboards, analytics platforms, portfolio trackers, research tools, and more.
18+
19+
## Domains
20+
21+
| Description | Testnet URL | Mainnet URL |
22+
| :----------------------- | :----------------------------------------------- | :--------------------------------------- |
23+
| Candlestick API endpoint | `https://priceapi.testnet-dataengine.chain.link` | `https://priceapi.dataengine.chain.link` |
24+
25+
## API Endpoints
26+
27+
### Authorize and get token
28+
29+
##### Endpoint
30+
31+
**`/api/v1/authorize`**
32+
33+
| Type | Description | Parameter(s) |
34+
| :-------- | :------------------------------------------------ | :------------------------------------------------------------------------------ |
35+
| HTTP POST | Authorizes a user and returns a JWT access token. | <ul><li>`login`: The user ID.</li><li>`password`: The user's API key.</li></ul> |
36+
37+
##### Sample request
38+
39+
```bash
40+
curl -X POST \
41+
-H "Content-Type: application/x-www-form-urlencoded" \
42+
-d "login={YOUR_USER_ID}&password={YOUR_API_KEY}" \
43+
https://priceapi.testnet-dataengine.chain.link/api/v1/authorize
44+
```
45+
46+
##### Response
47+
48+
- **Status**: `200`
49+
50+
```json
51+
{
52+
"d": {
53+
"access_token": "[ACCESS_TOKEN]",
54+
"expiration": 1747203979
55+
},
56+
"s": "ok"
57+
}
58+
```
59+
60+
| Field | Type | Description |
61+
| :------------- | :------- | :---------------------------------------- |
62+
| `s` | `string` | The status of the request. |
63+
| `d` | `object` | The data returned by the API call. |
64+
| `access_token` | `string` | The JWT token for subsequent requests. |
65+
| `expiration` | `number` | The expiry timestamp (unix) of the token. |
66+
67+
##### Error Responses
68+
69+
| Status Code | Error Message | Description |
70+
| :---------- | :------------------------------------------------------------------------------ | :---------------------------------------- |
71+
| `400` | `Parse error - Login: missing required field, Password: missing required field` | A required field was missing. |
72+
| `401` | `Unauthorized - Invalid credentials` | The user password (API key) is incorrect. |
73+
| `404` | `Not found - user not found for id {USER_ID}` | The user login was not found. |
74+
| `500` | `Error - Failed to generate token` | The server failed to create a token. |
75+
76+
### Get list of supported symbols
77+
78+
##### Endpoint
79+
80+
**`/api/v1/symbol_info`**
81+
82+
| Type | Description | Parameter(s) |
83+
| :------- | :------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
84+
| HTTP GET | Gets a list of all supported symbols on the environment. | <ul><li>`group` (optional): Filter symbols by group. Currently only supports "crypto".</li></ul> |
85+
86+
##### Sample request
87+
88+
```bash
89+
curl -X GET \
90+
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
91+
https://priceapi.testnet-dataengine.chain.link/api/v1/symbol_info
92+
```
93+
94+
##### Response
95+
96+
- **Status**: `200`
97+
98+
```json
99+
{
100+
"s": "ok",
101+
"symbol": ["ETHUSD", "BTCUSD"],
102+
"currency": ["USD", "USD"],
103+
"base-currency": ["ETH", "BTC"]
104+
}
105+
```
106+
107+
| Field | Type | Description |
108+
| :-------------- | :------- | :------------------------------- |
109+
| `s` | `string` | The status of the request. |
110+
| `symbol` | `array` | Array of supported symbols. |
111+
| `currency` | `array` | Array of symbol currencies. |
112+
| `base-currency` | `array` | Array of symbol base currencies. |
113+
114+
##### Error Responses
115+
116+
| Status Code | Error Message | Description |
117+
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------- |
118+
| `401` | `Unauthorized - Authorization header is required \|\| Invalid authorization header format \|\| token signature is invalid: signature is invalid \|\| ...` | The authorization header was missing or invalid. |
119+
| `500` | `Error - Something went wrong` | An unexpected server error occurred. |
120+
121+
### Get candlestick data (column format)
122+
123+
##### Endpoint
124+
125+
**`/api/v1/history`**
126+
127+
| Type | Description | Parameter(s) |
128+
| :------- | :-------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
129+
| HTTP GET | Gets candlestick data in column format. | <ul><li>`symbol`: The symbol to query.</li><li>`resolution`: Resolution of the data (required but not used, use "1m").</li><li>`from`: Unix timestamp of the leftmost required bar (inclusive).</li><li>`to`: Unix timestamp of the rightmost required bar (inclusive).</li></ul> |
130+
131+
**Note**: The resolution of the data is based on the size of the time window:
132+
133+
| Max time window size | Resolution of candles |
134+
| :------------------- | :-------------------- |
135+
| \<= 24 hours | 1 minute |
136+
| \<= 5 days | 5 minutes |
137+
| \<= 30 days | 30 minutes |
138+
| \<= 90 days | 1 hour |
139+
| \<= 6 months | 2 hours |
140+
| > 6 months | 1 day |
141+
142+
##### Sample request
143+
144+
```bash
145+
curl -X GET \
146+
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
147+
"https://priceapi.testnet-dataengine.chain.link/api/v1/history?symbol=ETHUSD&resolution=1m&from=1746072068&to=1746158468"
148+
```
149+
150+
##### Response
151+
152+
- **Status**: `200`
153+
154+
```json
155+
{
156+
"s": "ok",
157+
"t": [1746158460, 1746158400, 1746158340],
158+
"c": [1.84685e21, 1.848515087189567e21, 1.8490380305e21, 1.8481266e21],
159+
"o": [1.8483674e21, 1.848602513e21, 1.8481267e21],
160+
"h": [1.8498753129131415e21, 1.848875387e21, 1.8490380305e21],
161+
"l": [1.8468008021426886e21, 1.848243519e21, 1.8475677870725296e21],
162+
"v": []
163+
}
164+
```
165+
166+
| Field | Type | Description |
167+
| :---- | :------- | :--------------------------------------------------------------------- |
168+
| `s` | `string` | The status of the request. |
169+
| `t` | `array` | Array of unix timestamps (the time of each candle). |
170+
| `c` | `array` | Array of numbers (the close (last) value of each candle). |
171+
| `o` | `array` | Array of numbers (the open (first) value of each candle). |
172+
| `h` | `array` | Array of numbers (the high (max) value of each candle). |
173+
| `l` | `array` | Array of numbers (the low (min) value of each candle). |
174+
| `v` | `array` | Array of numbers (the volume of each candle. Not currently supported). |
175+
176+
> **Note**: If candles cannot be found for the given symbol/time period, a response with empty arrays will be provided. eg: `{ "s": "ok", "t": [], "c": [], "o": [], "h": [], "l": [], "v": [] }`
177+
178+
##### Error Responses
179+
180+
| Status Code | Error Message | Description |
181+
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------- |
182+
| `400` | `Parse error xxx: missing required field` | A required parameter was missing. |
183+
| `401` | `Unauthorized - Authorization header is required \|\| Invalid authorization header format \|\| token signature is invalid: signature is invalid \|\| ...` | The authorization header was missing or invalid. |
184+
| `404` | `Not found- Could not find feedID for symbol` | The provided symbol is not supported. |
185+
| `500` | `Something went wrong. Please try again later.` | An unexpected server error occurred. |
186+
187+
### Get candlestick data (row format)
188+
189+
##### Endpoint
190+
191+
**`/api/v1/history/rows`**
192+
193+
| Type | Description | Parameter(s) |
194+
| :------- | :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
195+
| HTTP GET | Gets candlestick data in row format. | <ul><li>`symbol`: The symbol to query.</li><li>`resolution`: Resolution of the data (required but not used, use "1m").</li><li>`from`: Unix timestamp of the leftmost required bar (inclusive).</li><li>`to`: Unix timestamp of the rightmost required bar (inclusive).</li></ul> |
196+
197+
##### Sample request
198+
199+
```bash
200+
curl -X GET \
201+
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
202+
"https://priceapi.testnet-dataengine.chain.link/api/v1/history/rows?symbol=ETHUSD&resolution=1m&from=1746072068&to=1746158468"
203+
```
204+
205+
##### Response
206+
207+
- **Status**: `200`
208+
209+
```json
210+
{
211+
"s": "ok",
212+
"candles": [
213+
[1746158460, 1.8483674e21, 1.8498753129131415e21, 1.8468008021426886e21, 1.84685e21, 0],
214+
[1746158400, 1.848602513e21, 1.848875387e21, 1.848243519e21, 1.848515087189567e21, 0],
215+
[1746158340, 1.8481267e21, 1.8490380305e21, 1.8475677870725296e21, 1.8490380305e21, 0]
216+
]
217+
}
218+
```
219+
220+
| Field | Type | Description |
221+
| :-------- | :------- | :-------------------------------------------------------------------------------------------------- |
222+
| `s` | `string` | The status of the request. |
223+
| `candles` | `array` | Array of arrays of numbers. Each array candle contains: `[ time, open, high, low, close, volume ]`. |
224+
225+
> **Note**: If candles cannot be found for the given symbol/time period, a response with an empty `candles` array is provided. eg: `{ "s": "ok", "candles": [] }`
226+
227+
##### Error Responses
228+
229+
| Status Code | Error Message | Description |
230+
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------- |
231+
| `400` | `Parse error xxx: missing required field` | A required parameter was missing. |
232+
| `401` | `Unauthorized - Authorization header is required \|\| Invalid authorization header format \|\| token signature is invalid: signature is invalid \|\| ...` | The authorization header was missing or invalid. |
233+
| `404` | `Not found- Could not find feedID for symbol` | The provided symbol is not supported. |
234+
| `500` | `Something went wrong. Please try again later.` | An unexpected server error occurred. |
235+
236+
### Get streaming price updates
237+
238+
##### Endpoint
239+
240+
**`/api/v1/streaming`**
241+
242+
| Type | Description | Parameter(s) |
243+
| :------- | :-------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
244+
| HTTP GET | Gets streaming price updates using HTTP chunked encoding. | <ul><li>`symbol` or `feedId`: A comma-separated list of symbols or feed IDs to stream.</li></ul> |
245+
246+
##### Sample request
247+
248+
```bash
249+
curl -X GET \
250+
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
251+
-H "Connection: keep-alive" \
252+
"https://priceapi.testnet-dataengine.chain.link/api/v1/streaming?symbol=ETHUSD,BTCUSD"
253+
```
254+
255+
##### Response
256+
257+
- **Status**: `200` (Streaming)
258+
259+
A stream of JSON objects.
260+
261+
**Trade Response:**
262+
263+
```json
264+
{
265+
"f": "t",
266+
"i": "ETHUSD",
267+
"fid": "[FEED_ID]",
268+
"p": 2.68312e21,
269+
"t": 1748525526,
270+
"s": 1
271+
}
272+
```
273+
274+
| Field | Type | Description |
275+
| :---- | :-------- | :------------------------------------------------------------- |
276+
| `f` | `string` | Message type. Will always be “t” to indicate a trade response. |
277+
| `i` | `string` | Identifier. The symbol for this response. |
278+
| `fid` | `string` | The hex-encoded feed ID for this response. |
279+
| `p` | `float64` | The latest price update for the symbol/feedId. |
280+
| `t` | `float64` | The time of the price as a unix timestamp. |
281+
| `s` | `float64` | Size of the trade. This will always be 1. |
282+
283+
**Heartbeat (sent every 5 seconds):**
284+
285+
```json
286+
{ "heartbeat": 1748525528 }
287+
```
288+
289+
| Field | Type | Description |
290+
| :---------- | :-------- | :----------------------------------------------------- |
291+
| `heartbeat` | `float64` | The time of the heartbeat message as a unix timestamp. |
292+
293+
##### Error Responses
294+
295+
| Status Code | Error Message | Description |
296+
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------- |
297+
| `400` | `Parse error xxx: One of symbol or feedId must be provided` | A required parameter was missing. |
298+
| `401` | `Unauthorized - Authorization header is required \|\| Invalid authorization header format \|\| token signature is invalid: signature is invalid \|\| ...` | The authorization header was missing or invalid. |
299+
| `404` | `Not found- Could not find feedID for symbol` | The provided symbol is not supported. |
300+
| `500` | `Something went wrong. Please try again later.` | An unexpected server error occurred. |

0 commit comments

Comments
 (0)