Concepts

The vocabulary ByteTree MCP tools and the bytetree://glossary resource share. MCP clients (Claude Desktop, Claude Code) pull the glossary in-band so the agent can ground its responses; this page is the human-readable form for customers who want to read before they poke.

ByteTree’s market-data dataset uses a small number of proprietary metrics that aren’t part of any public taxonomy. The definitions below are precise so prompts and tools can be reasoned about correctly.

Naming convention. Prose refers to the two ByteTrend variants as Weekly and Daily. The wire-format field suffixes are …200w and …30d respectively — those map to Weekly and Daily throughout this document. Both variants update every row; the suffix names a moving-average window length, not the score’s update cadence.

Quick reference

The five-key block below is what your LLM client sees inline if it calls summarise_dataset — short framings designed to fit in tool-response context. Use it as a TL;DR before reading the full sections.

{
  CAPR:
    "Currency-Adjusted Price Relative — the asset's USD price divided by the MSCI World close. Rising = outperforming the global benchmark; falling = underperforming. Not a valuation metric.",

  ByteTrend:
    "Composite 0–5 score from 5 binary rules (close-vs-MAs, MAs-rising, last-touch-high). Two variants per axis: **Weekly arc** (fields suffixed `…200w`, with 200-week / 30-week MAs) for long-trend signal, and **Daily arc** (fields suffixed `…30d`, with 200-day / 30-day MAs) for short-trend momentum. Both arcs update every row; the suffix names the MA timescale, not the update cadence.",

  localVsCapr:
    "Every ByteTrend score has a Local (own-price) and CAPR (vs-benchmark) variant. So every asset has four ByteTrend scores per row: Weekly Local, Weekly CAPR, Daily Local, Daily CAPR. Comparing Local vs CAPR for the same arc isolates absolute vs relative leadership.",

  trendRegimes:
    "Five labels: Neutral (most assets, most days), Leading Trend, Emerging Trend, Weakening Trend, Bear Trend. The four named regimes only fire when an asset is simultaneously at a 30-week extreme AND at a specific score level. The Weekly CAPR variant has a confirmation layer: `confirmedRegimeCapr200w` (stable, lags 5 trading days) + `pendingRegimeCapr200w` (candidate during transition) + `pendingRegimeCount200w` (1–4 during a streak, promotes at 5). Other variants (Weekly Local, Daily CAPR, Daily Local) are raw-only.",

  glossary:
    "Full definitions, predicates, and window-size tables: read the bytetree://glossary resource."
}

CAPR — Currency-Adjusted Price Relative

REST cross-link: Data Model, Latest Metrics — Valuation

CAPR is the asset’s USD-denominated price divided by the latest MSCI World close. Both legs are in USD, so FX is normalised out of the ratio implicitly — what remains is a unitless measure of asset-vs-benchmark performance.

• Rising CAPR → asset is outperforming the global benchmark.
• Falling CAPR → asset is underperforming.

The benchmark is the MSCIWORLD index symbol — not the URTH ETF or ACWI.

capr is the split-adjusted CAPR (default exposure on the public MCP); caprRaw is the unadjusted forensic series. The two diverge across stock splits.

ByteTrend score — five binary rules, range 0–5

REST cross-link: Latest Metrics

A composite 0–5 score where each rule contributes +1 if true:

Weekly arc vs Daily arc

ByteTrend has two variants per Local/CAPR axis (so four scores per asset per row). They differ in the timescale of their moving-average inputs, not in how often the score updates — every variant updates every row (trading day for stocks, calendar day for crypto). The wire-format field suffix encodes which variant.

Weekly arc — long-trend signal, suited to multi-year regime calls. Fields: byteTrendCapr200w, byteTrendLocal200w (suffix …200w).

• maLongWindow = 200 weeks → 1000 days for stocks (5d/week), 1400 days for crypto (7d/week).
• maShortWindow = 30 weeks → 150 days for stocks, 210 days for crypto.
• maxMinWindow (for lastTouchMax) = 20 weeks → 100 days for stocks, 140 days for crypto.

Daily arc — short-trend momentum signal, suited to month-scale moves. Fields: byteTrendCapr30d, byteTrendLocal30d (suffix …30d).

• maLongWindow = 200 days for stocks, 280 days for crypto.
• maShortWindow = 30 days for stocks, 42 days for crypto.
• maxMinWindow = 20 days.

The suffix can be misleading at first read: …200w names the long MA period (so on a Weekly variant, aboveMaLong checks close > 200-week MA), while …30d names the short MA (so on a Daily variant, aboveMaLong checks close > 200-day MA). Both arcs check both MAs.

Local vs CAPR variants

The five rules are evaluated against different series, not different predicates:

• Local — score the asset’s own price series (its own close in its own currency, sub-currency-normalised).
• CAPR — score the asset’s CAPR series (price-vs-MSCI-World ratio).

Every asset has four ByteTrend scores per row: Weekly Local, Weekly CAPR, Daily Local, Daily CAPR. Comparing Local vs CAPR for the same arc isolates absolute vs relative leadership. A stock with Weekly Local = 5 (byteTrendLocal200w) and Weekly CAPR = 2 (byteTrendCapr200w) is rising in price but losing relative ground.

Trend regime taxonomy

REST cross-link: Latest Metrics, Regime Transitions

Five labels, classified per first-match:

• atHigh = devFromHigh30w >= 0 (the asset’s CAPR or local price equals the 30-week max)
• atLow = devFromLow30w <= 0 (equals the 30-week min)

The 30-week deviation is always 30 weeks for the regime classifier, regardless of which ByteTrend variant (Weekly or Daily, Local or CAPR) is being classified — it’s a separate signal from the score’s own MA window pair. Each asset gets four regime labels per row, one per variant (trendRegimeLocal200w, trendRegimeCapr200w, trendRegimeLocal30d, trendRegimeCapr30d).

Most days, most assets are in Neutral. The four named regimes are corner cases that fire only when the asset is simultaneously at a 30-week extreme AND at a specific score level. A Leading Trend asset can fall to Neutral simply by drifting off its 30-week high without any score change at all.

A null score (data gap) yields a null label, and the caller carries the previous label forward.

Confirmed, pending, and raw regime — the Weekly CAPR state machine

The confirmation layer applies only to Weekly CAPR (the trendRegimeCapr200w family). The other three regime variants — Weekly Local (trendRegimeLocal200w), Daily CAPR (trendRegimeCapr30d), Daily Local (trendRegimeLocal30d) — are raw-only. They flip immediately and have no confirmed or pending companion.

For the Weekly CAPR variant, four fields work together:

State transitions

REGIME_CONFIRMATION_DAYS = 5. Five branches, evaluated in order each trading day:

1. Data gap (raw is null) → freeze confirmed, pending, count, and trendAge200w at their previous values.
2. First valid day (no prior confirmed) → adopt raw immediately. confirmed = raw, pending = null, count = 0, age = 1.
3. Raw matches confirmed → confirmed unchanged, pending = null, count = 0 (cancels any active streak), age increments.
4. Raw matches the active pending (the candidate streak holds another day) → increment count. If count reaches 5: promote — confirmed = raw, pending = null, count = 0, age resets to 5. Otherwise stay in pending state — confirmed unchanged, pending = raw, count incremented, age increments.
5. New candidate (raw differs from both confirmed and any active pending) → start a fresh pending streak. pending = raw, count = 1, age increments.

Reading the state in practice

• A new regime label takes at least 5 trading-day rows to surface in confirmedRegimeCapr200w. Until then it sits in pendingRegimeCapr200w with pendingRegimeCount200w ticking up.
• A non-null pendingRegimeCapr200w with pendingRegimeCount200w >= 1 is “this label is on track to become confirmed in (5 − pendingRegimeCount200w) more days if it holds.” Useful for early signal of a regime change.
• A 1-day flicker (raw flips one day, then back the next) leaves confirmedRegimeCapr200w untouched — that’s the noise-absorption that makes the confirmed series usable for historical reasoning.

trendAge200w — Weekly trend age

REST cross-link: Latest Metrics

A daily counter coupled to the Weekly CAPR regime state machine. The naming suggests “days since the current regime began” but the actual semantics are slightly more nuanced — read carefully if precision matters.

Behaviour by branch (same state machine as the regime fields):

• During a stable confirmed regime (raw = confirmed): increments cleanly every non-null day. In this case it does mean “days at the current confirmed regime.”
• During an active pending streak (raw ≠ confirmed, accumulating candidate): continues incrementing past the prior regime’s end. The counter doesn’t pause for the streak.
• On the day a pending streak completes confirmation (count reaches 5): resets to exactly 5 (one for each day the streak ran). Empirically verified across thousands of confirmed regime flips at trendAge200w === 5; query semantics can use strict equality. Then increments normally from there.
• On a data-gap day (raw is null): keeps yesterday’s value rather than incrementing or resetting.

The clean reading (“strictly days since the current confirmed regime began”) only holds while pendingRegimeCapr200w === null. During an active pending streak the counter is approximate — it’s overcounting by the length of the streak so far. After confirmation it snaps back to a clean count.

No Daily-arc equivalent. trendAge only exists for Weekly CAPR; the other three regime variants have no age counter, since they have no confirmation layer to anchor “since this regime was confirmed.”

Unit is days at the price-data row cadence, asset-type-dependent:

• Stocks: trading days only (no rows on weekends/holidays).
• Crypto: all days (24/7 markets).

A trendAge200w: 100 on a stock means ~5 calendar months; on a crypto it means ~3.3 calendar months. LLMs tend to read “100 days” as calendar days — be explicit about cadence when surfacing this number.

Score history fields

REST cross-link: Latest Metrics

Five fields encode a short rolling history of the Weekly Local ByteTrend score (byteTrendLocal200w) on every metrics row. They make trend-stability checks cheap from a single get_latest_metrics call — no series fetch needed.

_scoreLag1 … _scoreLag4

Internal lag storage for the Weekly Local ByteTrend score:

“Rows ago” follows the same cadence as the price-data feed: trading days for stocks, calendar days for crypto. The chain is walked forward each day (today’s _scoreLag1 was yesterday’s byteTrendLocal200w; today’s _scoreLag2 was yesterday’s _scoreLag1; etc.). The leading underscore marks them as engine-internal — they exist to support scoreVelocity5d200w rather than as primary signals — but they’re exposed in the metrics blob and are useful for snapshot-readable trend stability checks.

scoreVelocity5d200w

5-day rate of change of the Weekly Local ByteTrend score, in score points per day:

scoreVelocity5d200w = (byteTrendLocal200w − byteTrendLocal200w-5-rows-ago) / 5

The denominator is a constant 5 (not “5 calendar days”); units are score-points-per-row at the asset’s row cadence. Range is bounded because byteTrendLocal200w is 0–5: max possible delta over 5 rows is ±5, so velocity is ±1.

Important scope note. These fields track the Weekly Local variant only. There is no scoreVelocity field for Weekly CAPR, none for either Daily-arc variant, and no per-rule lag chain. If an LLM client reasons “score trajectory is healthy” from scoreVelocity5d200w, that’s specifically the absolute-price-based ByteTrend trajectory — for the relative-to-MSCI-World trajectory, you’d need to compute byteTrendCapr200w[t] − byteTrendCapr200w[t-5] from a get_metrics_series call.

Universes

REST cross-link: Universes reference, Groups

Asset groupings are partitioned into named universes. Two are seeded:

• default — five dimensions (region, sector, industry, type, country), all sourced from provider-native classification fields with direct or mapped lookups.
• global-trends-200 — ByteTree’s curated dimension set. Customises region, sector + industry with bespoke mappings for cross-asset analysis. The remaining two dimensions (type, country) fall back to default at aggregation time.

Country is fixed across universes

ISO codes mapped to full country names. The same per-country grouping appears under both universes; it is not customisable per universe.

Use list_grouping_configs to discover all (universe, dimension) combinations and their slugs. Use get_group_metrics to query the aggregated metrics for a (universe, dimension, group) tuple.