List Candles

curl --request POST \
  --url https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles \
  --header 'Content-Type: application/json' \
  --data '
{
  "security_id": {
    "guid": "6ef11658-5a1c-4baf-9387-d977dcca6129"
  },
  "time_frame": {
    "time_unit": "DAY",
    "count": 1
  },
  "range": {
    "count": -5,
    "first_bound_time": "2024-08-16T00:00:00Z"
  }
}
'

import requests

url = "https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles"

payload = {
    "security_id": { "guid": "6ef11658-5a1c-4baf-9387-d977dcca6129" },
    "time_frame": {
        "time_unit": "DAY",
        "count": 1
    },
    "range": {
        "count": -5,
        "first_bound_time": "2024-08-16T00:00:00Z"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    security_id: {guid: '6ef11658-5a1c-4baf-9387-d977dcca6129'},
    time_frame: {time_unit: 'DAY', count: 1},
    range: {count: -5, first_bound_time: '2024-08-16T00:00:00Z'}
  })
};

fetch('https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'security_id' => [
        'guid' => '6ef11658-5a1c-4baf-9387-d977dcca6129'
    ],
    'time_frame' => [
        'time_unit' => 'DAY',
        'count' => 1
    ],
    'range' => [
        'count' => -5,
        'first_bound_time' => '2024-08-16T00:00:00Z'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles"

	payload := strings.NewReader("{\n  \"security_id\": {\n    \"guid\": \"6ef11658-5a1c-4baf-9387-d977dcca6129\"\n  },\n  \"time_frame\": {\n    \"time_unit\": \"DAY\",\n    \"count\": 1\n  },\n  \"range\": {\n    \"count\": -5,\n    \"first_bound_time\": \"2024-08-16T00:00:00Z\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles")
  .header("Content-Type", "application/json")
  .body("{\n  \"security_id\": {\n    \"guid\": \"6ef11658-5a1c-4baf-9387-d977dcca6129\"\n  },\n  \"time_frame\": {\n    \"time_unit\": \"DAY\",\n    \"count\": 1\n  },\n  \"range\": {\n    \"count\": -5,\n    \"first_bound_time\": \"2024-08-16T00:00:00Z\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"security_id\": {\n    \"guid\": \"6ef11658-5a1c-4baf-9387-d977dcca6129\"\n  },\n  \"time_frame\": {\n    \"time_unit\": \"DAY\",\n    \"count\": 1\n  },\n  \"range\": {\n    \"count\": -5,\n    \"first_bound_time\": \"2024-08-16T00:00:00Z\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "candles": [
    {
      "time": "2024-08-09T00:00:00Z",
      "open": {
        "value": "21210",
        "scale": "100"
      },
      "high": {
        "value": "21678",
        "scale": "100"
      },
      "low": {
        "value": "21197",
        "scale": "100"
      },
      "close": {
        "value": "21624",
        "scale": "100"
      },
      "volume": {
        "value": "42201600",
        "scale": "1"
      },
      "session_type": 0
    },
    {
      "time": "2024-08-12T00:00:00Z",
      "open": {
        "value": "21607",
        "scale": "100"
      },
      "high": {
        "value": "21951",
        "scale": "100"
      },
      "low": {
        "value": "21560",
        "scale": "100"
      },
      "close": {
        "value": "21753",
        "scale": "100"
      },
      "volume": {
        "value": "38028100",
        "scale": "1"
      },
      "session_type": 0
    },
    {
      "time": "2024-08-13T00:00:00Z",
      "open": {
        "value": "21901",
        "scale": "100"
      },
      "high": {
        "value": "22189",
        "scale": "100"
      },
      "low": {
        "value": "21901",
        "scale": "100"
      },
      "close": {
        "value": "22127",
        "scale": "100"
      },
      "volume": {
        "value": "44155300",
        "scale": "1"
      },
      "session_type": 0
    },
    {
      "time": "2024-08-14T00:00:00Z",
      "open": {
        "value": "22057",
        "scale": "100"
      },
      "high": {
        "value": "22303",
        "scale": "100"
      },
      "low": {
        "value": "21970",
        "scale": "100"
      },
      "close": {
        "value": "22172",
        "scale": "100"
      },
      "volume": {
        "value": "41960600",
        "scale": "1"
      },
      "session_type": 0
    },
    {
      "time": "2024-08-15T00:00:00Z",
      "open": {
        "value": "22460",
        "scale": "100"
      },
      "high": {
        "value": "22535",
        "scale": "100"
      },
      "low": {
        "value": "22276",
        "scale": "100"
      },
      "close": {
        "value": "22472",
        "scale": "100"
      },
      "volume": {
        "value": "46414000",
        "scale": "1"
      },
      "session_type": 0
    }
  ]
}

Marketdata API

List Candles

The ListCandles method retrieves historical candlestick data for a given security, time frame, and range. This documentation provides details on how to use the ListCandles endpoint, including request and response formats, and includes JSON schemas for the request and response.

Request Body

security_id (object, required): Identifier of the security.
- One of:
  - guid (string): Global Unique Identifier of the security.
  - ticker_code (object):
    - ticker (string): Ticker symbol.
    - exchange_code (string): Exchange code.
time_frame (object, required): Time frame for the candles.
- time_unit (string, required): Unit of time. Possible values: MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, YEAR.
- count (integer): Number of time_units per candle (e.g., 1 for daily candles).
range (object, required): Range of the historical data.
- One of:
  - first_bound_time (string): The starting time (ISO 8601 format).
  - second_bound_time (string): The ending time (ISO 8601 format).
  - duration (string): Duration of the range (e.g., "PT5H" for 5 hours).
  - count (integer): Number of candles to retrieve. Negative for past data relative to first_bound_time.

Response

candles (array): An array of candle objects.
- Each candle object contains:
  - time (string): The start time of the candle in ISO 8601 format.
  - open (object): Open price.
    - value (string): Numeric value as a string.
    - scale (string): Scale factor (divisor).
  - high (object): High price.
  - low (object): Low price.
  - close (object): Close price.
  - volume (object): Volume.
  - session_type (integer): Session type (e.g., 0 for MAINSESSION).

JSON Schemas

Request Schema

{
  "type": "object",
  "properties": {
    "security_id": {
      "type": "object",
      "oneOf": [
        {
          "properties": {
            "guid": {
              "type": "string"
            }
          },
          "required": ["guid"]
        },
        {
          "properties": {
            "ticker_code": {
              "type": "object",
              "properties": {
                "ticker": {
                  "type": "string"
                },
                "exchange_code": {
                  "type": "string"
                }
              },
              "required": ["ticker", "exchange_code"]
            }
          },
          "required": ["ticker_code"]
        }
      ]
    },
    "time_frame": {
      "type": "object",
      "properties": {
        "time_unit": {
          "type": "string",
          "enum": ["MINUTE", "HOUR", "DAY", "WEEK", "MONTH", "QUARTER", "YEAR"]
        },
        "count": {
          "type": "integer",
          "minimum": 1
        }
      },
      "required": ["time_unit"]
    },
    "range": {
      "type": "object",
      "oneOf": [
        {
          "properties": {
            "first_bound_time": {
              "type": "string",
              "format": "date-time"
            },
            "second_bound_time": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": ["first_bound_time", "second_bound_time"]
        },
        {
          "properties": {
            "first_bound_time": {
              "type": "string",
              "format": "date-time"
            },
            "duration": {
              "type": "string"
            }
          },
          "required": ["first_bound_time", "duration"]
        },
        {
          "properties": {
            "first_bound_time": {
              "type": "string",
              "format": "date-time"
            },
            "count": {
              "type": "integer"
            }
          },
          "required": ["first_bound_time", "count"]
        }
      ]
    },
    "properties": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["OPEN", "HIGH", "LOW", "CLOSE", "VALUE", "VOLUME", "SESSION_TYPE"]
      }
    },
    "session_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["MAINSESSION", "PRE_MARKET", "POST_MARKET"]
      }
    }
  },
  "required": ["security_id", "time_frame", "range"]
}

Response Schema

{
  "type": "object",
  "properties": {
    "candles": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "time": {
            "type": "string",
            "format": "date-time"
          },
          "open": {
            "$ref": "#/definitions/Decimal"
          },
          "high": {
            "$ref": "#/definitions/Decimal"
          },
          "low": {
            "$ref": "#/definitions/Decimal"
          },
          "close": {
            "$ref": "#/definitions/Decimal"
          },
          "volume": {
            "$ref": "#/definitions/Decimal"
          },
          "session_type": {
            "type": "integer",
            "enum": [0, 1, 2]
          }
        },
        "required": ["time"]
      }
    }
  },
  "definitions": {
    "Decimal": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string"
        },
        "scale": {
          "type": "string"
        }
      },
      "required": ["value", "scale"]
    }
  }
}

Usage Recommendations

Authorization: Always use a valid access_token in the accesstoken header.
Error Handling: Check the status field in the response to determine the success of the operation.
Time Zones: All times are in UTC. Ensure your application handles time zones appropriately.
Data Interpretation:
- Decimal Fields: To calculate the real value of decimal fields, use real_value = value / scale. For example, if value is "21210" and scale is "100", the real value is 21210 / 100 = 212.10.

Frequently Asked Questions

How do I interpret the `Decimal` fields?

The Decimal fields use a value and scale to represent decimal numbers precisely. Compute the real value as value / scale.

What is the `session_type` field?

The session_type indicates the trading session:

0: MAINSESSION
1: PRE_MARKET
2: POST_MARKET

Can I request candles for a custom time frame?

Yes, you can specify the time_frame with different time_unit and count values to create custom time frames, such as 5-minute or 15-minute candles.

Additional Resources

POST

takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles

List Candles

curl --request POST \
  --url https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles \
  --header 'Content-Type: application/json' \
  --data '
{
  "security_id": {
    "guid": "6ef11658-5a1c-4baf-9387-d977dcca6129"
  },
  "time_frame": {
    "time_unit": "DAY",
    "count": 1
  },
  "range": {
    "count": -5,
    "first_bound_time": "2024-08-16T00:00:00Z"
  }
}
'

import requests

url = "https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles"

payload = {
    "security_id": { "guid": "6ef11658-5a1c-4baf-9387-d977dcca6129" },
    "time_frame": {
        "time_unit": "DAY",
        "count": 1
    },
    "range": {
        "count": -5,
        "first_bound_time": "2024-08-16T00:00:00Z"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    security_id: {guid: '6ef11658-5a1c-4baf-9387-d977dcca6129'},
    time_frame: {time_unit: 'DAY', count: 1},
    range: {count: -5, first_bound_time: '2024-08-16T00:00:00Z'}
  })
};

fetch('https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'security_id' => [
        'guid' => '6ef11658-5a1c-4baf-9387-d977dcca6129'
    ],
    'time_frame' => [
        'time_unit' => 'DAY',
        'count' => 1
    ],
    'range' => [
        'count' => -5,
        'first_bound_time' => '2024-08-16T00:00:00Z'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles"

	payload := strings.NewReader("{\n  \"security_id\": {\n    \"guid\": \"6ef11658-5a1c-4baf-9387-d977dcca6129\"\n  },\n  \"time_frame\": {\n    \"time_unit\": \"DAY\",\n    \"count\": 1\n  },\n  \"range\": {\n    \"count\": -5,\n    \"first_bound_time\": \"2024-08-16T00:00:00Z\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles")
  .header("Content-Type", "application/json")
  .body("{\n  \"security_id\": {\n    \"guid\": \"6ef11658-5a1c-4baf-9387-d977dcca6129\"\n  },\n  \"time_frame\": {\n    \"time_unit\": \"DAY\",\n    \"count\": 1\n  },\n  \"range\": {\n    \"count\": -5,\n    \"first_bound_time\": \"2024-08-16T00:00:00Z\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dev.tpinf.in/takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"security_id\": {\n    \"guid\": \"6ef11658-5a1c-4baf-9387-d977dcca6129\"\n  },\n  \"time_frame\": {\n    \"time_unit\": \"DAY\",\n    \"count\": 1\n  },\n  \"range\": {\n    \"count\": -5,\n    \"first_bound_time\": \"2024-08-16T00:00:00Z\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "candles": [
    {
      "time": "2024-08-09T00:00:00Z",
      "open": {
        "value": "21210",
        "scale": "100"
      },
      "high": {
        "value": "21678",
        "scale": "100"
      },
      "low": {
        "value": "21197",
        "scale": "100"
      },
      "close": {
        "value": "21624",
        "scale": "100"
      },
      "volume": {
        "value": "42201600",
        "scale": "1"
      },
      "session_type": 0
    },
    {
      "time": "2024-08-12T00:00:00Z",
      "open": {
        "value": "21607",
        "scale": "100"
      },
      "high": {
        "value": "21951",
        "scale": "100"
      },
      "low": {
        "value": "21560",
        "scale": "100"
      },
      "close": {
        "value": "21753",
        "scale": "100"
      },
      "volume": {
        "value": "38028100",
        "scale": "1"
      },
      "session_type": 0
    },
    {
      "time": "2024-08-13T00:00:00Z",
      "open": {
        "value": "21901",
        "scale": "100"
      },
      "high": {
        "value": "22189",
        "scale": "100"
      },
      "low": {
        "value": "21901",
        "scale": "100"
      },
      "close": {
        "value": "22127",
        "scale": "100"
      },
      "volume": {
        "value": "44155300",
        "scale": "1"
      },
      "session_type": 0
    },
    {
      "time": "2024-08-14T00:00:00Z",
      "open": {
        "value": "22057",
        "scale": "100"
      },
      "high": {
        "value": "22303",
        "scale": "100"
      },
      "low": {
        "value": "21970",
        "scale": "100"
      },
      "close": {
        "value": "22172",
        "scale": "100"
      },
      "volume": {
        "value": "41960600",
        "scale": "1"
      },
      "session_type": 0
    },
    {
      "time": "2024-08-15T00:00:00Z",
      "open": {
        "value": "22460",
        "scale": "100"
      },
      "high": {
        "value": "22535",
        "scale": "100"
      },
      "low": {
        "value": "22276",
        "scale": "100"
      },
      "close": {
        "value": "22472",
        "scale": "100"
      },
      "volume": {
        "value": "46414000",
        "scale": "1"
      },
      "session_type": 0
    }
  ]
}

Headers

accesstoken

string

JWT access token

Body

application/json

The body is of type object.

Response

200 - application/json

The response is of type object.

Getting Started

Credentials

Link

Reference API

Marketdata API

List Candles

Request Body

Response

JSON Schemas

Request Schema

Response Schema

Usage Recommendations

Frequently Asked Questions

How do I interpret the `Decimal` fields?

What is the `session_type` field?

Can I request candles for a custom time frame?

Additional Resources

Headers

Body

Response