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

The complete API documentation is available via Swagger UI at:

T4 Chart API Documentation

The Swagger documentation provides:

• Complete list of available endpoints
• Request parameters and response formats
• Interactive testing capability
• Authentication requirements

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.

GET https://api-sim.t4login.com/chart/barchart

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

Examples:

• To authorize the request, include the bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

• To receive the response in a compact binary format, set the `Accept` header accordingly:

Accept: application/octet-stream

  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.

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:

{
    "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 ...
    ]
}

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.

GET https://api-sim.t4login.com/chart/tradehistory

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.

{
    "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": [
        ...
    ]
}

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.

When the Accept header requests ``application/octet-stream`` or ``application/t4``, the chart endpoints return a compact binary stream instead of JSON. The binary format is typically an order of magnitude smaller than the equivalent JSON and is the recommended transport for large date ranges or high-resolution (tick / quote) history.

Two closely-related dialects exist:

The HTTP body may contain a small amount of framing before the actual T4Bin payload. The payload begins at a Start-Of-Format (SOF) record whose first bytes form a recognisable signature. A decoder should scan for the first matching signature and treat everything from that offset onward as the stream.

If a non-empty response contains neither signature, the body is almost certainly an error message or an unexpected format and should be treated as a hard error rather than decoded.

Both dialects are a flat sequence of length-prefixed records:

[ length : 7-bit int ] [ tag : 7-bit int ] [ tag-specific payload ... ]

• length — the number of bytes in the record after the length prefix itself (i.e. tag + payload). A decoder reads ``length``, resets a byte counter, reads the tag and payload, then skips any unconsumed trailing bytes so that exactly ``length`` bytes are consumed. This makes the format forward-compatible: unknown tags and extra trailing fields in known tags are skipped safely.
• tag — one of the ``CTAG_*`` constants in the tables below. The tag namespaces are separate for the two dialects (e.g. tag ``11`` means ``CTAG_BAR`` in T4BinAggr but ``CTAG_TICKDATAPOINT_7BIT`` in T4Bin).
• A record with ``length == 0`` is a no-op padding/keepalive and is ignored.

Integers are stored little-endian, 7 bits per byte, with the high bit (``0x80``) used as a continuation flag.

64-bit values (notably tick timestamps) must be decoded with a wide integer type. The JavaScript decoder uses ``BigInt`` throughout to avoid loss of precision above ``2^53``.

Prices and tick values use a .NET ``decimal``-compatible layout: a single header byte (2 bits per chunk, 4 chunks) followed by up to four 7-bit-encoded magnitudes.

• Chunks (MSB→LSB in the header): ``lo``, ``mid``, ``hi`` (the 96-bit unscaled integer split into three 32-bit words) and a ``sign/scale`` chunk.
• Per-chunk 2-bit tag: ``0x00`` = zero (no magnitude bytes follow), ``0x01`` = positive, ``0x02`` = negative, ``0x03`` = the ``Int32.MinValue`` sentinel (no magnitude bytes follow).
• In the sign/scale chunk: bit 31 set ⇒ value is negative; bits 16–23 hold the decimal scale (number of fractional digits).
• Final value = ``(±) unscaled / 10^scale``.

The reference decoders represent decimals with arbitrary-precision libraries (decimal.js at scale 18 in JavaScript, ``decimal.Decimal`` in Python) so that round-tripping matches Java ``BigDecimal`` exactly.

Some fields (e.g. a market's minimum cabinet price) are nullable: a single header byte is read first; if bit 0 is clear the value is ``null`` and no further bytes follow, otherwise a decimal (above) follows.

• Prices are exposed as a ``Price`` type — a decimal quantized to scale 18 with HALF_EVEN rounding. Many tick records encode a price as a tick increment relative to a running value; the decoder converts these to absolute prices via the market's denominator / minimum-price-increment / VPT. The JSON ``openPrice`` etc. fields (which are integer-tick strings such as ``“473575”``) correspond to the decoded ``Price`` after conversion.
• Timestamps are .NET-style ticks: 1 tick = 100 ns since ``0001-01-01 00:00:00``. The decoder wraps these in an ``NDateTime`` type. As with the JSON API, all times are CST.
• Many time fields are delta-encoded against the previous record. A decoded “delta” larger than a threshold (~ year 1900 in ticks, ``599266080000000000``) is interpreted as an absolute tick value rather than a delta — a decoder must apply this rule to reconstruct timestamps correctly.

Record tags emitted on ``/chart/barchart`` with a binary ``Accept`` header. Format version constant ``CVAL_T4BINAGGR_VERSION = 1``.

Each decoded ``Bar`` exposes the same fields as the JSON Bars array (``TradeDate``, ``Time``, ``CloseTime``, ``MarketID``, ``OpenPrice``, ``HighPrice``, ``LowPrice``, ``ClosePrice``, ``Volume``, ``VolumeAtBid``, ``VolumeAtOffer``, ``Trades``, ``TradesAtBid``, ``TradesAtOffer``), with PascalCase names for parity with the Java/Python sources.

Record tags emitted on ``/chart/tradehistory`` with a binary ``Accept`` header. Format version constant ``CVAL_T4BIN_VERSION = 1``. Each record updates the decoder's ``ChartDataState`` and sets ``state.Change`` to the corresponding ChartDataChange value.

Open-source reference decoders are maintained alongside this API so you do not have to implement the binary format by hand. Both 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

Requires Node 18+ (uses global ``fetch``) or any modern browser. The only runtime dependency is decimal.js.

Clone the t4-api-tools repository, then install dependencies:

git clone https://github.com/CTS-Futures/t4-api-tools.git
cd t4-api-tools/tools/JavaScript/t4-javascript-api
npm install

``ChartDataStreamReaderAggr`` decodes the whole stream and dispatches each record to a handler. Any subset of callbacks may be supplied; missing callbacks are skipped.

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) { /* ... */ },
  },
});

The handler interface:

``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``:

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 ...
  }
}

You can also decode bytes you already have (e.g. from a saved file) without the HTTP client:

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
});

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:

<script type="module" src="decoder/loader.js"></script>
<script>
  window.addEventListener('t4-decoder-ready', (e) => {
    const { ChartDataStreamReaderAggr, extractT4BinPayload } = e.detail;
    // ...
  });
</script>

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.

Clone the t4-api-tools repository, then install dependencies:

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

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)

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.

The ``state.Change`` discriminator after each ``read()``.

Exchange session lifecycle state (the ``marketMode`` field in JSON, and ``state.Mode`` / ``onModeChange`` in binary).

Which side of the market a trade/RFQ executed against (mirrors the JSON ``aggressorSide``).

• 64-bit ticks / 7-bit-long values use BigInt (JS) / native ``int`` (Python).
• 96-bit unscaled decimals use decimal.js at scale 18 with ``ROUND_HALF_EVEN`` (JS) / ``decimal.Decimal`` (Python), matching Java ``BigDecimal``.
• Field naming preserves Java/Python PascalCase on ``ChartDataState``, ``Bar``, and ``MarketDefinition`` for 1:1 parity across all three implementations.

This revision adds documentation for the binary transport and the reference decoders. Nothing in the original JSON documentation was removed or semantically altered.

Source of truth: the tables above are generated from the decoder source in ``tools/JavaScript/t4-javascript-api/src`` (mirror under ``tools/JavaScript/JSDemo/decoder``) and ``tools/Python/t4-pythonConversion-api/src/t4login``. If the format version constants (``CVAL_T4BIN_VERSION`` / ``CVAL_T4BINAGGR_VERSION``) change, regenerate the tag tables from ``ChartFormat`` / ``ChartFormatAggr``. </content> </invoke>