Show pageOld revisionsBacklinksBack to top 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 <bootnote info> **What changed in this revision** \\ This page documents the **open-source decoder libraries** that consume the chart API's compact binary response: * A top-level section **[[#Decoder Libraries]]** documenting the JavaScript (``@t4/chart-decoder``), Python (``t4login``) and .NET (``T4APIDemo``) reference decoders, including the streaming handler interface, the ``ChartDataState`` field reference, and the ``ChartDataChange`` / ``MarketMode`` / ``BidOffer`` enumerations. See **[[#Revision Notes / Changelog]]** at the bottom for the detailed list. </bootnote> ===== 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. | **Examples:** * To authorize the request, include the bearer token: <code>Authorization: Bearer YOUR_ACCESS_TOKEN</code> ==== 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. | ==== 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. ===== Decoder Libraries ===== Open-source reference decoders are maintained alongside this API so you do not have to implement the binary format by hand. The libraries are line-for-line ports of the original Java ``com.t4login`` chart-data reader and are validated against each other and against the CSV/JSON output. All of the tools below live in the public **CTS-Futures/t4-api-tools** repository: [[https://github.com/CTS-Futures/t4-api-tools/tree/main/tools|https://github.com/CTS-Futures/t4-api-tools/tree/main/tools]] ^ Language ^ Package / module ^ Location in the repo ^ | JavaScript | ``@t4/chart-decoder`` (ES modules) | ``tools/JavaScript/t4-javascript-api/`` (and a browser copy under ``tools/JavaScript/JSDemo/decoder/``) | | Python | ``t4login`` | ``tools/Python/t4-pythonConversion-api/src/t4login/`` | | .NET (C#) | ``T4APIDemo`` (NuGet) | ``tools/dotNet/T4APIDemo/`` | ==== JavaScript: @t4/chart-decoder ==== Requires **Node 18+** (uses global ``fetch``) or any modern browser. The only runtime dependency is **decimal.js**. === Install === Clone the [[https://github.com/CTS-Futures/t4-api-tools/tree/main/tools|t4-api-tools]] repository, then install dependencies: <code powershell> git clone https://github.com/CTS-Futures/t4-api-tools.git cd t4-api-tools/tools/JavaScript/t4-javascript-api npm install </code> === Aggregated barchart (push / handler model) === ``ChartDataStreamReaderAggr`` decodes the whole stream and dispatches each record to a handler. Any subset of callbacks may be supplied; missing callbacks are skipped. <code javascript> import { ChartClient } from '@t4/chart-decoder'; const client = new ChartClient({ token: 'YOUR_ACCESS_TOKEN' }); await client.getBarchartBinary({ exchangeId: 'CME_Eq', contractId: 'ESM6', barInterval: 'Minute', barPeriod: 1, tradeDateStart: '2026-05-01', tradeDateEnd: '2026-05-02', handler: { onMarketDefinition(def) { /* def.MarketID, def.TickValue, ... */ }, onBar(bar) { console.log(bar.Time.toString(), bar.ClosePrice.toString()); }, onModeChange(marketId, tradeDate, time, mode) { /* ... */ }, onSettlement(marketId, tradeDate, time, price, held) { /* ... */ }, onOpenInterest(marketId, tradeDate, time, oi) { /* ... */ }, }, }); </code> The handler interface: ^ Callback ^ Emitted for tag(s) ^ | ``onMarketDefinition(marketDefinition)`` | ``CTAG_MARKET_DEFINITION`` | | ``onBar(bar)`` | ``CTAG_BAR``, ``CTAG_BAR_DELTA`` | | ``onModeChange(marketId, tradeDate, time, mode)`` | ``CTAG_MARKET_MODE`` | | ``onSettlement(marketId, tradeDate, time, settlementPrice, held)`` | ``CTAG_SETTLEMENT_PRICE`` | | ``onOpenInterest(marketId, tradeDate, time, openInterest)`` | ``CTAG_OPEN_INTEREST`` | === Non-aggregated trade history (pull / state model) === ``ChartDataStreamReader`` is a sequential cursor. Each ``read()`` consumes one record and mutates the public ``reader.state`` object; ``read()`` returns ``false`` at end-of-stream. Branch on ``state.Change``: <code javascript> import { ChartClient, ChartDataChange } from '@t4/chart-decoder'; const reader = await client.getTradehistoryBinary({ exchangeId: 'CME_E', contractId: 'YM', tradeDateStart: '2024-01-08', tradeDateEnd: '2024-01-08', }); while (reader.read()) { const s = reader.state; switch (s.Change) { case ChartDataChange.Trade: console.log(s.LastTimeTicks, s.LastTradePrice.toString(), s.TradeVolume, s.AtBidOrOffer); break; case ChartDataChange.Quote: console.log('BBO', s.BidPrice.toString(), s.OfferPrice.toString()); break; case ChartDataChange.Settlement: console.log('settle', s.SettlementPrice?.toString()); break; // ... MarketMode, OpenInterest, VWAP, TPO, TradeBar, TickChange, RFQ ... } } </code> === Lower-level / advanced usage === You can also decode bytes you already have (e.g. from a saved file) without the HTTP client: <code javascript> import { ByteReader, NDateTime, ChartDataType, ChartDataStreamReader, ChartDataStreamReaderAggr, extractT4BinPayload, } from '@t4/chart-decoder'; // Aggregated: ChartDataStreamReaderAggr.read(extractT4BinPayload(bytes), handler); // Non-aggregated: const reader = new ChartDataStreamReader({ data: new ByteReader(extractT4BinPayload(bytes)), tradeDate: new NDateTime(0n), marketId: 'XCME_E YM (H24)', dataType: ChartDataType.get(0), // Tick }); </code> === Browser (no bundler) === The JSDemo copy ships a ``decoder/loader.js`` ES-module entry point that publishes the decoder on ``window.T4ChartDecoder`` and fires a ``t4-decoder-ready`` event, so classic ``<script>`` code can use it without an ``import`` statement: <code html> <script type="module" src="decoder/loader.js"></script> <script> window.addEventListener('t4-decoder-ready', (e) => { const { ChartDataStreamReaderAggr, extractT4BinPayload } = e.detail; // ... }); </script> </code> ==== Python: t4login ==== The Python package mirrors the JavaScript API one-to-one (same class names, same field names). It is the original conversion the JavaScript port was derived from. === Install === Clone the [[https://github.com/CTS-Futures/t4-api-tools/tree/main/tools|t4-api-tools]] repository, then install dependencies: <code powershell> git clone https://github.com/CTS-Futures/t4-api-tools.git cd t4-api-tools/tools/Python/t4-pythonConversion-api pip install -e . # installs from pyproject.toml </code> === Usage === <code python> from t4login.client.chart_client import ChartClient from t4login.definitions.chartdata.chart_data_change import ChartDataChange client = ChartClient(token="YOUR_ACCESS_TOKEN") # Aggregated (handler model) client.get_barchart_binary( exchange_id="CME_Eq", contract_id="ESM6", trade_date_start="2026-05-01", trade_date_end="2026-05-02", handler=my_handler, ) # Non-aggregated (state model) reader = client.get_tradehistory_binary( exchange_id="CME_E", contract_id="YM", trade_date_start="2024-01-08", trade_date_end="2024-01-08", ) while reader.read(): s = reader.state if s.Change == ChartDataChange.Trade: print(s.LastTradePrice, s.TradeVolume) </code> ==== .NET: T4APIDemo ==== The .NET reference decoder ships as the ``T4APIDemo`` NuGet package in the same repository, under ``tools/dotNet/T4APIDemo/``. It mirrors the JavaScript and Python decoders (same class, handler and ``ChartDataState`` field names) for 1:1 parity across all implementations. === Install === Clone the [[https://github.com/CTS-Futures/t4-api-tools/tree/main/tools|t4-api-tools]] repository, then restore and build the project: <code powershell> git clone https://github.com/CTS-Futures/t4-api-tools.git cd t4-api-tools/tools/dotNet/T4APIDemo dotnet restore dotnet build </code> ==== ChartDataState field reference (T4Bin) ==== Populated by ``ChartDataStreamReader``. Field names are PascalCase for parity across Java/Python/JS. Prices are ``Price`` objects (call ``.toString()`` / Python ``str()``); 64-bit tick times are ``BigInt`` in JS. ^ Group ^ Fields ^ | Change | ``Change`` (a **[[#ChartDataChange]]** value) | | Trade date | ``TradeDate``, ``TradeDateTicks`` | | Market def. | ``MarketDefined``, ``MarketID``, ``Numerator``, ``Denominator``, ``PriceCode``, ``TickValue``, ``VPT``, ``MinCabPrice``, ``MinPriceIncrement``, ``PointValue`` | | Last trade | ``LastTradePrice``, ``TradeVolume``, ``LastTTV``, ``LastTimeTicks``, ``AtBidOrOffer`` (**[[#BidOffer]]**), ``DueToSpread``, ``OrderVolumes`` | | Bar | ``BarStartTime``, ``BarCloseTime``, ``BarOpenPrice``, ``BarHighPrice``, ``BarLowPrice``, ``BarClosePrice``, ``BarVolume``, ``BarBidVolume``, ``BarOfferVolume``, ``BarTrades``, ``BarTradesAtBid``, ``BarTradesAtOffer`` | | TPO | ``TPOStartTime``, ``TPOBasePrice``, ``TPOPrice``, ``TPOVolume``, ``TPOVolumeAtBid``, ``TPOVolumeAtOffer``, ``TPOIsOpening``, ``TPOIsClosing`` | | Quote | ``BidPrice``, ``BidRealVolume``, ``BidImpliedVolume``, ``OfferPrice``, ``OfferRealVolume``, ``OfferImpliedVolume`` | | Session | ``Mode`` (**[[#MarketMode]]**), ``SettlementPrice``, ``SettlementHeldPrice``, ``ClearedVolume``, ``OpenInterest``, ``VWAP_Price`` | | RFQ | ``RFQBuySell`` (**[[#BidOffer]]**), ``RFQVolume`` | ==== Enumerations ==== === ChartDataChange === The ``state.Change`` discriminator after each ``read()``. ^ Value ^ Name ^ ^ Value ^ Name ^ | 0 | ``NONE`` | | 8 | ``TickChange`` | | 1 | ``Trade`` | | 9 | ``RFQ`` | | 2 | ``Quote`` | | 10 | ``HeldSettlement``| | 3 | ``MarketMode`` | | 11 | ``ClearedVolume`` | | 4 | ``Settlement`` | | 12 | ``OpenInterest`` | | 5 | ``TradeBar`` | | 13 | ``VWAP`` | | 6 | ``TradeDate`` | | 14 | ``MarketSwitch`` | | 7 | ``TPO`` | | 15 | ``MarketDefinition`` | === MarketMode === Exchange session lifecycle state (the ``marketMode`` field in JSON, and ``state.Mode`` / ``onModeChange`` in binary). ^ Value ^ Name ^ ^ Value ^ Name ^ | 0 | ``Undefined`` | | 8 | ``Failed`` | | 1 | ``PreOpen`` | | 9 | ``PreCross`` | | 2 | ``Open`` | | 10 | ``Cross`` | | 3 | ``RestrictedOpen`` | | 11 | ``Expired`` | | 4 | ``PreClosed`` | | 12 | ``Rejected`` | | 5 | ``Closed`` | | 13 | ``Unavailable`` | | 6 | ``Suspended`` | | 14 | ``NoPermission`` | | 7 | ``Halted`` | | 15 | ``TrialExpired`` | === BidOffer === Which side of the market a trade/RFQ executed against (mirrors the JSON ``aggressorSide``). ^ Value ^ Name ^ | 1 | ``Bid`` | | 0 | ``Undefined`` | | -1 | ``Offer`` | ===== Revision Notes / Changelog ===== ^ Area ^ Change ^ | New section | **Decoder Libraries** — JavaScript (``@t4/chart-decoder``), Python (``t4login``) and .NET (``T4APIDemo``) usage, the aggregated handler interface, the non-aggregated state-cursor model, browser loader, the ``ChartDataState`` field reference, and the ``ChartDataChange`` / ``MarketMode`` / ``BidOffer`` enumerations. | **Source of truth:** the field and enumeration tables above are generated from the decoder source under ``tools/JavaScript/t4-javascript-api/src`` (mirror under ``tools/JavaScript/JSDemo/decoder``), ``tools/Python/t4-pythonConversion-api/src/t4login`` and ``tools/dotNet/T4APIDemo``. 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. developers/chart.txt Last modified: 2026/06/24 14:59by juan