developers:chart [Documentation]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== T4 Chart API ======

Our chart API provides data in aggregated or non-aggregated (raw trade) formats.

<bootnote>
All times are in CST.
</bootnote>


The complete API documentation is available via Swagger UI at:

[[https://api-sim.t4login.com/chart/swagger/index.html|T4 Chart API Documentation]]

The Swagger documentation provides:
  * Complete list of available endpoints
  * Request parameters and response formats
  * Interactive testing capability
  * Authentication requirements

===== Aggregated Chart Data =====

==== Overview ====
The **GetBarChart** API retrieves bar chart data for a specified trading instrument over a given date range. This API supports various chart types and bar intervals, tailored for detailed data analysis in financial contexts.

==== API Endpoint ====
<code>GET https://api-sim.t4login.com/chart/barchart</code>

==== Headers ====

For proper access and response handling, the **GetBarChart** API requires certain HTTP headers to be set in the request.

^ Header           ^ Value                                                   ^ Description                                                                             ^
| Authorization    | Bearer <token>                                          | **Required**. A valid bearer token to authenticate the request.                         |
| Accept           | application/json, text/csv, application/octet-stream, application/t4               | **Optional**. Specifies the response format the client can handle. If omitted, the API returns JSON. Use text/csv to request CSV, or application/octet-stream / application/t4 to request the compact binary format. |

**Examples:**

  * To authorize the request, include the bearer token:
    <code>Authorization: Bearer YOUR_ACCESS_TOKEN</code>

  * To receive the response in a compact binary format, set the `Accept` header accordingly:
    <code>Accept: application/octet-stream</code>
    or
    <code>Accept: application/t4</code>

Setting the `Accept` header is optional, and if it is not included, the API will return the response in a JSON format.

==== Parameters ====
^ Parameter        ^ Description                                                                                       ^
| **exchangeId**       | **Required**. Identifier for the exchange.                                                        |
| **contractId**       | **Required**. Identifier for the contract.                                                        |
| **chartType**        | **Required**. Type of chart to compute. Currently, only **Bar** type is supported.              |
| **barInterval**      | **Required**. Interval at which bars are aggregated. Possible values:\\ • **Tick**: Bars aggregated based on trade count.\\ • **TickRange**: Bars aggregated based on price range.\\ • **Volume**: Bars aggregated based on number of contracts traded.\\ • **Second**: Bars aggregated into multiples of seconds.\\ • **Minute**: Bars aggregated into multiples of minutes.\\ • **Hour**: Bars aggregated into multiples of hours.\\ • **Day**: Bars aggregated into multiples of days.\\ • **Week**: Bars aggregated into multiples of weeks. |
| **barPeriod**        | **Required**. Period for the bars.                                                                |
| **tradeDateStart**   | **Required**. Start date for the trade data.                                                      |
| **tradeDateEnd**     | **Required**. End date for the trade data.                                                        |
| marketID         | Market ID (optional). Can be omitted when using ContinuationType.                                 |
| continuationType | Method of continuation for the chart. Only **Volume** is currently supported.                      |
| resetInterval    | Interval at which bar computations reset (not applicable when ContinuationType.Volume is used). \\ Defaults to **TradingDay**. Other possible values:\\ • **None**: No reset interval.\\ • **TradingWeek**: Reset on the trading week boundary.\\ • **ExpiryChange**: Reset on an expiry change. |
| contractMonths   | Contract months to include (not applicable when **ContinuationType.Volume** is used).             |
| rolloverThreshold| Rollover threshold (not applicable when **ContinuationType.Volume** is used).                      |
| forwardMonths    | Forward months (not applicable when **ContinuationType.Volume** is used).                         |

==== Response ====

The response from the **GetBarChart** API is a JSON object containing detailed information about the bar chart data. Below is the structure of the response along with a description of each element:

=== Bars ===
^ Element         ^ Description                                      ^
| tradeDate       | Date of the trade.                               |
| time            | Time when the bar data starts.                   |
| closeTime       | Time when the bar data ends.                     |
| marketID        | Identifier for the market.                       |
| openPrice       | Opening price for this bar.                      |
| highPrice       | Highest price in this bar.                       |
| lowPrice        | Lowest price in this bar.                        |
| closePrice      | Closing price for this bar.                      |
| volume          | Total volume of trades in this bar.              |
| volumeAtBid     | Volume of trades at the bid price.               |
| volumeAtOffer   | Volume of trades at the offer price.             |
| trades          | Total number of trades in this bar.              |
| tradesAtBid     | Number of trades at the bid price.               |
| tradesAtOffer   | Number of trades at the offer price.             |

=== MarketDefinitions ===
^ Element           ^ Description                                              ^
| marketID          | Identifier for the market.                               |
| minPriceIncrement | Minimum increment of the market's price.                 |
| priceCode         | Code related to the pricing of the market.               |
| tickValue         | Value of each tick in the market's pricing.              |
| vpt               | Additional market-specific information (variable).       |

=== ModeChanges ===
^ Element         ^ Description                                ^
| marketID        | Identifier for the market.                 |
| tradeDate       | Date of the trade.                         |
| time            | Time when the mode change occurred.        |
| marketMode      | The mode of the market at the given time.  |

=== OpenInterests ===
^ Element         ^ Description                                ^
| marketID        | Identifier for the market.                 |
| tradeDate       | Date of the trade.                         |
| time            | Time of the recorded open interest.        |
| openInterest    | The amount of open interest.               |

=== Settlements ===
^ Element           ^ Description                                           ^
| marketID          | Identifier for the market.                            |
| tradeDate         | Date of the trade.                                    |
| time              | Time when the settlement information was recorded.    |
| settlementPrice   | Price at which the trade was settled.                 |
| isHeld            | Indicates if the settlement was held (boolean).       |

==== Example JSON Response ====

<code>
{
    "tradeDateStart": "2024-01-08T00:00:00",
    "tradeDateEnd": "2024-01-08T00:00:00",
    "activeMarket": "XCME_Eq ES (H24)",
    "bars": [
        {
            "tradeDate": "2024-01-08T00:00:00",
            "time": "2024-01-08T00:00:00",
            "closeTime": "2024-01-08T15:59:59.5853624",
            "marketID": "XCME_Eq ES (H24)",
            "openPrice": "473575",
            "highPrice": "480325",
            "lowPrice": "471525",
            "closePrice": "479800",
            "volume": 1339989,
            "volumeAtBid": 665050,
            "volumeAtOffer": 674939,
            "trades": 320624,
            "tradesAtBid": 152333,
            "tradesAtOffer": 168291
        }
    ],
    "marketDefinitions": [
        {
            "marketID": "XCME_Eq ES (H24)",
            "minPriceIncrement": "25",
            "priceCode": "",
            "tickValue": 12.5,
            "vpt": ""
        }
    ],
    "modeChanges": [
        {
            "marketID": "XCME_Eq ES (H24)",
            "tradeDate": "2024-01-08T00:00:00",
            "time": "2024-01-07T08:04:27.7736882",
            "marketMode": 5
        },
        // ... additional mode changes ...
    ],
    "openInterests": [
        {
            "marketID": "XCME_Eq ES (H24)",
            "tradeDate": "2024-01-08T00:00:00",
            "time": "2024-01-07T12:43:16.8256856",
            "openInterest": 2211632
        },
        // ... additional open interests ...
    ],
    "settlements": [
        {
            "marketID": "XCME_Eq ES (H24)",
            "tradeDate": "2024-01-08T00:00:00",
            "time": "2024-01-05T16:38:39.9345143",
            "settlementPrice": "473475"
        },
        {
            "marketID": "XCME_Eq ES (H24)",
            "tradeDate": "2024-01-08T00:00:00",
            "time": "2024-01-08T15:01:01.4810068",
            "isHeld": true
        }
        // ... additional settlements ...
    ]
}
</code>





===== Non-Aggregated Chart Data (Trade History) =====

==== Overview ====
The **GetTradeHistory** API retrieves historical trade data for a specified trading instrument within a given date and time range. This API allows for querying trade data based on the trade date or specific start and end timestamps.

==== API Endpoint ====
<code>GET https://api-sim.t4login.com/chart/tradehistory</code>

==== Headers ====
^ Header        ^ Value                                                      ^ Description                                                                             ^
| Authorization | Bearer <token>                                             | **Required**. A valid bearer token to authenticate the request.                         |
| Accept        | application/octet-stream, application/t4                   | **Optional**. Specifies the content type that the client can handle. Use this header to request a compact binary format response. If omitted, the default response format is JSON. |

==== Parameters ====
^ Parameter        ^ Description                                                                                       ^
| exchangeId       | **Required**. Identifier for the exchange.                                                        |
| contractId       | **Required**. Identifier for the contract.                                                        |
| marketID         | Market ID (optional).                                                                            |
| tradeDateStart   | The start date for the trade history based on trade dates (optional).                            |
| tradeDateEnd     | The end date for the trade history based on trade dates (optional).                              |
| start            | The calendar start date and time for the request in CST (optional).                              |
| end              | The calendar end date and time for the request in CST (optional).                                |
| since            | Filters data to only include trades after the specified date and time (optional).                |

**Note:** Pass either **tradeDateStart** and **tradeDateEnd** OR **start** and **end**. Including both will result in an error. Use **since** to further filter data to only include trades after the specified date and time.

=== Response ===
^ Element            ^ Description                                                                                                  ^
| exchangeID         | Identifier for the exchange.                                                                                  |
| contractID         | Identifier for the contract.                                                                                  |
| marketID           | Identifier for the market.                                                                                    |
| requestStatusMessage| Any status messages or errors related to the request.                                                          |
| tradeDateStart     | The starting date of the trade data.                                                                          |
| tradeDateEnd       | The ending date of the trade data.                                                                            |
| trades             | An array of trade objects, each detailing individual trades.                                                  |
| marketDefinitions  | An array of market definition objects, detailing market-specific information.                                |
| modeChanges        | An array of mode change objects, each showing changes in the market mode.                                    |
| openInterests      | An array containing information about open interests.                                                        |
| settlements        | An array detailing settlement information, including prices.                                                 |
| vwaPs              | An array detailing volume-weighted average prices (VWAP).                                                    |

=== Trades ===

^ Element        ^ Description                                                         ^
| marketID       | Identifier for the market.                                          |
| tradeDate      | The date of the trade as per trade date convention.                |
| time           | The specific time when the trade occurred.                         |
| tradePrice     | The price at which the trade was executed.                         |
| aggressorSide  | Indicates the side of the aggressor of the trade. 1 for buyer, -1 for seller. |

=== VWAP(s) ===

^ Element    ^ Description                                                         ^
| marketID   | Identifier for the market.                                          |
| tradeDate  | The date of the trade as per trade date convention.                |
| time       | The specific time when the VWAP is calculated.                     |
| vwapPrice  | The volume-weighted average price for the trades up to the specified time. |


==== Example JSON Response ====

<code>
{
    "exchangeID": "CME_E",
    "contractID": "YM",
    "marketID": "XCME_E YM (H24)",
    "requestStatusMessage": "",
    "tradeDateStart": "2024-01-08T00:00:00",
    "tradeDateEnd": "2024-01-08T00:00:00",
    "trades": [
        {
            "marketID": "XCME_E YM (H24)",
            "tradeDate": "2024-01-08T00:00:00",
            "time": "2024-01-07T17:00:00",
            "tradePrice": "37674",
            "aggressorSide": 1
        },
        ...
    ],
    "marketDefinitions": [],
    "modeChanges": [
        ...
    ],
    "openInterests": [
        ...
    ],
    "settlements": [
        ...
    ],
    "vwaPs": [
        ...
    ]
}
</code>

The response is structured as a JSON object with various elements containing detailed trade data and related information for the specified contract and exchange within the requested time frame.