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

• Auth API Documentation

• ISO 8601 Date Format