Ticks history

Data

Get historical tick data for a symbol. Response required fields changed, validation relaxed, and new parameter options added.

6 breaking changes - code updates required

Critical Changes:

Required fields in history and candles response objects changed. The echo_req field is no longer guaranteed.

Quick comparison

Aspect	Legacy	New	Action required
Endpoint ✅ Same	ticks_history	ticks_history	None
Auth Required ✅ Same	No	No	None
subscribe Values ⚠️ Changed	1 only	0 or 1	Optional: use 0 for one-time request
adjust_start_time Values ⚠️ Changed	1 only	0 or 1	Optional: use 0 to disable
Granularity Restriction ⚠️ Changed	Fixed enum values	Any integer	More flexibility available
history.prices/times ⚠️ Changed	Optional	Required	Can safely access directly
Candle Fields ⚠️ Changed	All optional	All required	Can safely access directly
echo_req ⚠️ Changed	Required	Optional	Add existence check

Breaking changes

1. Required fields in history object changed

What Changed: The prices and times arrays inside the history object are now required fields.

Legacy: Both prices and times were optional
New: Both are now required when history object is present

Migration: You can now safely access history.prices and history.times without null checks when the history object exists.

2. Required fields in candles array changed

What Changed: All candle properties (close, epoch, high, low, open) are now required.

Legacy: All candle properties were optional
New: All five properties are required within each candle object

Migration: You can now safely destructure all candle properties without null checks.

3. echo_req no longer required in response

What Changed: The echo_req field is no longer a required field in the response.

Legacy: echo_req and msg_type were required
New: Only msg_type is required

Migration: Add existence checks before accessing response.echo_req.

4. Granularity enum restriction removed

What Changed: The granularity parameter no longer has a fixed set of allowed values.

Legacy: Restricted to [60, 120, 180, 300, 600, 900, 1800, 3600, 7200, 14400, 28800, 86400]
New: Any integer value is accepted

Migration: You now have more flexibility in granularity values. If you had client-side validation matching the legacy enum, you may want to update or remove it.

5. Input validation patterns removed

What Changed: Pattern validation on ticks_history and end parameters has been removed.

Legacy: ticks_history required pattern ^\w{2,30}$
Legacy: end required pattern ^(latest|[0-9]{1,10})$
New: No pattern validation on these parameters

Migration: This change relaxes input validation. If you relied on the API to validate input format, consider adding client-side validation.

6. subscribe and adjust_start_time now accept 0

What Changed: Both parameters now accept 0 as a valid value in addition to 1.

Legacy: Both parameters only accepted 1
New: Both accept 0 or 1

Migration: This is a new capability. Use subscribe: 0 for one-time requests without subscription. Use adjust_start_time: 0 to explicitly disable start time adjustment.

Request structure

Legacy Request Example

1// Tick history with subscription
2{
3  "ticks_history": "frxEURUSD",
4  "end": "latest",
5  "start": 1234567890,
6  "style": "ticks",
7  "count": 100,
8  "adjust_start_time": 1,  // Only 1 allowed
9  "subscribe": 1           // Only 1 allowed
10}
11
12// Candle history (fixed granularity values)
13{
14  "ticks_history": "frxEURUSD",
15  "end": "latest",
16  "style": "candles",
17  "granularity": 3600  // Must be from fixed list
18}

New Request Example

1// Tick history with subscription
2{
3  "ticks_history": "frxEURUSD",
4  "end": "latest",
5  "start": 1234567890,
6  "style": "ticks",
7  "count": 100,
8  "adjust_start_time": 1,
9  "subscribe": 1
10}
11
12// One-time request (NEW in v4)
13{
14  "ticks_history": "frxEURUSD",
15  "end": "latest",
16  "style": "ticks",
17  "subscribe": 0,          // Explicitly no subscription
18  "adjust_start_time": 0   // Explicitly disable adjustment
19}
20
21// Candle history (flexible granularity)
22{
23  "ticks_history": "frxEURUSD",
24  "end": "latest",
25  "style": "candles",
26  "granularity": 900  // Any integer now accepted
27}

Response structure

Legacy Response Example

1// Tick history response
2{
3  "echo_req": {              // REQUIRED in legacy
4    "ticks_history": "frxEURUSD",
5    "end": "latest"
6  },
7  "history": {
8    "prices": [1.0850, 1.0851],  // Optional
9    "times": [1234567890, 1234567891]  // Optional
10  },
11  "pip_size": 5,
12  "msg_type": "history"
13}
14
15// Candle response
16{
17  "echo_req": { ... },       // REQUIRED
18  "candles": [
19    {
20      "close": 1.0851,       // Optional
21      "epoch": 1234567890,   // Optional
22      "high": 1.0855,        // Optional
23      "low": 1.0848,         // Optional
24      "open": 1.0850         // Optional
25    }
26  ],
27  "pip_size": 5,
28  "msg_type": "candles"
29}

New Response Example

1// Tick history response
2{
3  "echo_req": {              // Now OPTIONAL
4    "ticks_history": "frxEURUSD",
5    "end": "latest"
6  },
7  "history": {
8    "prices": [1.0850, 1.0851],  // REQUIRED
9    "times": [1234567890, 1234567891]  // REQUIRED
10  },
11  "pip_size": 5,
12  "msg_type": "history"      // Only required field
13}
14
15// Candle response
16{
17  "echo_req": { ... },       // OPTIONAL
18  "candles": [
19    {
20      "close": 1.0851,       // REQUIRED
21      "epoch": 1234567890,   // REQUIRED
22      "high": 1.0855,        // REQUIRED
23      "low": 1.0848,         // REQUIRED
24      "open": 1.0850         // REQUIRED
25    }
26  ],
27  "pip_size": 5,
28  "msg_type": "candles"
29}

Code examples

Legacy Implementation

1async function getTicksHistory(symbol) {
2  const request = {
3    ticks_history: symbol,
4    end: "latest",
5    start: Date.now() / 1000 - 86400,
6    style: "ticks",
7    count: 100,
8    adjust_start_time: 1,  // Only 1 is valid
9    subscribe: 1           // Only 1 is valid
10  };
11
12  ws.send(JSON.stringify(request));
13
14  ws.onmessage = (event) => {
15    const response = JSON.parse(event.data);
16    
17    // echo_req is guaranteed
18    console.log('Request:', response.echo_req);
19    
20    if (response.msg_type === 'history') {
21      // history.prices and history.times may be missing
22      if (response.history) {
23        if (response.history.prices) {
24          console.log('Prices:', response.history.prices);
25        }
26        if (response.history.times) {
27          console.log('Times:', response.history.times);
28        }
29      }
30    }
31    
32    if (response.msg_type === 'candles') {
33      response.candles?.forEach(candle => {
34        // Each property may be missing
35        const close = candle.close ?? null;
36        const open = candle.open ?? null;
37        const high = candle.high ?? null;
38        const low = candle.low ?? null;
39        console.log({ open, high, low, close });
40      });
41    }
42  };
43}

New Implementation

1async function getTicksHistory(symbol, subscribe = 1) {
2  const request = {
3    ticks_history: symbol,
4    end: "latest",
5    start: Date.now() / 1000 - 86400,
6    style: "ticks",
7    count: 100,
8    adjust_start_time: 1,
9    subscribe  // Can be 0 or 1
10  };
11
12  ws.send(JSON.stringify(request));
13
14  ws.onmessage = (event) => {
15    const response = JSON.parse(event.data);
16    
17    // echo_req may not be present
18    if (response.echo_req) {
19      console.log('Request:', response.echo_req);
20    }
21    
22    if (response.msg_type === 'history') {
23      // prices and times are guaranteed
24      const { prices, times } = response.history;
25      console.log('Prices:', prices);
26      console.log('Times:', times);
27      
28      // Combine into data points
29      const dataPoints = prices.map((price, i) => ({
30        price,
31        time: times[i]
32      }));
33    }
34    
35    if (response.msg_type === 'candles') {
36      // All candle properties are guaranteed
37      response.candles.forEach(candle => {
38        const { open, high, low, close, epoch } = candle;
39        console.log({ epoch, open, high, low, close });
40      });
41    }
42  };
43}
44
45// New: One-time request without subscription
46async function getTicksHistoryOnce(symbol) {
47  const request = {
48    ticks_history: symbol,
49    end: "latest",
50    style: "ticks",
51    subscribe: 0,           // New in v4
52    adjust_start_time: 0    // New in v4
53  };
54  ws.send(JSON.stringify(request));
55}

Ticks Transaction