TrendMatrix API

This endpoint returns a multi-timeframe snapshot of trend direction and strength for a symbol.

Use it when you want a compact directional view across multiple timeframes for chart overlays, dashboards, or automation logic.

Endpoint

GET https://api.darwintiq.com/v1/trendmatrix

Query Parameters

Parameter	Required	Type	Description
symbol	Yes	string	Market symbol to query.
begin	No	string	Start time for range mode, formatted as YYYY-MM-DD HH:MM:SS.
sort	No	string	Sort order for range mode: ASC (default) or DESC.
latest	No	integer	Set to 1 to return only the most recent snapshot.
include_candles	No	integer	Set to 1 to include candle payload when available.
includeCandles	No	integer	camelCase alias for include_candles.
attach	No	integer	Set to 1 to request the upstream attach flag for additional context data.

How to Use It

A typical client flow is:

1. Decide whether you need only the latest snapshot or a historical range.
2. Request the endpoint with latest=1 for current state, or use begin for history.
3. Read the data.trend map in latest mode, or the trendmatrix map in range mode.
4. Use dir and strength as compact directional context in your application.

Example Request

curl -H "Authorization: Bearer [YOUR_TOKEN]" \
  "https://api.darwintiq.com/v1/trendmatrix?symbol=EURUSD&latest=1"

Response Example

{
  "status": "success",
  "latest": true,
  "opentime": "2026-02-10 15:00:00",
  "data": {
    "time": "2026-02-10 15:00:00",
    "trend": {
      "M5":  { "dir": "Bullish", "strength": 2 },
      "M30": { "dir": "Ranging", "strength": 0 },
      "H1":  { "dir": "Bearish", "strength": 2 },
      "H4":  { "dir": "Bearish", "strength": 3 },
      "D1":  { "dir": "Ranging", "strength": 0 },
      "W1":  { "dir": "Bullish", "strength": 1 }
    }
  },
  "timeSemantics": {
    "version": 1,
    "fieldBases": {
      "opentime": "BROKER_NY_CLOSE",
      "data.time": "BROKER_NY_CLOSE"
    }
  }
}

Response Field Reference

Field	Type	Description
status	string	success when the request succeeds.
latest	boolean	Whether the response is the latest snapshot only.
opentime	string	Snapshot time in broker chart time (BROKER_NY_CLOSE).
data	object	TrendMatrix snapshot payload.
data.time	string	Snapshot time in broker chart time (BROKER_NY_CLOSE).
data.trend	object	Map of timeframe to trend status.
data.trend.M5	object	Example timeframe block.
data.trend.M5.dir	string	Bullish, Bearish, or Ranging.
data.trend.M5.strength	number	Strength scale (0 = none).
begin	string	Present in range mode responses.
sort	string	Present in range mode responses (ASC/DESC).
count	number	Number of range snapshots.
trendmatrix	object	Range mode map keyed by opentime (if provided by upstream).
trendmatrix.<opentime>	object | null	TrendMatrix snapshot at that broker-time timestamp (BROKER_NY_CLOSE).
candles	array	Optional candles payload (include_candles=1).
meta	object | null	Optional metadata block from upstream.
timeSemantics	object | null	Optional timestamp semantics metadata for interpreting timestamp fields.
timeSemantics.version	number	Metadata version (currently 1).
timeSemantics.fieldBases	object	Map of field paths to time basis identifiers.
timeSemantics.notes	array | null	Optional human-readable notes about timestamp semantics.

Key Field Notes

• dir is one of Bullish, Bearish, or Ranging.
• strength is a relative integer scale where 0 means no clear trend.
• Timeframe keys in data.trend can vary by market or source, for example M1, M5, M15, M30, H1, H4, D1, and W1.
• Friendly symbol aliases are normalized before the upstream request, for example DAX -> GDAXI and SPX500 -> SP500.

Timestamp Semantics

• BROKER_NY_CLOSE means Darwinex/MT4 chart time aligned to New York close, typically UTC+2 in winter and UTC+3 in summer.
• If timeSemantics is present, prefer it over hard-coded assumptions in client code.

Errors

Status	Meaning
400	Missing or invalid symbol.
401	Missing bearer token.
403	Invalid token or no subscription access for the symbol.
429	Per-token rate limit exceeded.
500	Upstream or internal server error.

Repository

Public example code is available here:

https://github.com/darwintIQ/API