TrendMatrix API

Use this endpoint to retrieve a multi-timeframe snapshot of trend direction and strength.

Endpoint

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

Query parameters

symbol (required)
begin (optional) — start time (YYYY-MM-DD HH:MM:SS) for range mode
sort (optional) — ASC (default) | DESC
latest (optional) — 1 for most recent snapshot
include_candles (optional) — 1 to include candle payload when available
attach (optional) — upstream attach flag for additional context data

Example

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

Notes

dir is one of Bullish | Bearish | Ranging
strength is an integer scale (0 = no clear trend)

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.

Notes

Timeframe keys in data.trend can vary by market/source (e.g. M1, M5, M15, M30, H1, H4, D1, W1).
dir values are categorical; strength is a relative integer indicator.
BROKER_NY_CLOSE means Darwinex/MT4 chart time aligned to New York close (typically UTC+2 in winter / UTC+3 in summer).
If timeSemantics is present, prefer it over hard-coded assumptions in API clients.

Errors

400 missing or invalid symbol
401 missing bearer token
403 invalid token or no subscription access for symbol
429 per-token rate limit exceeded
500 upstream or internal error