cTrader/docs/symbol-metadata.md

Per-symbol price metadata (<SYMBOL>.meta.json)

Alongside the price files (<SYMBOL>_YYYY_MM.m1 / .tick) the export driver writes one small JSON sidecar per symbol, <SYMBOL>.meta.json. Its sole purpose is to let a reader interpret the historical price data — the price files contain only raw OHLC / spread / volume numbers, with nothing that says how to read them (how many decimals a price has, what a "pip" is, which currency the price is quoted in, what one lot is worth). Those facts are known only to the broker, exposed through cTrader's Symbol object inside a running cBot. This sidecar captures them so a downstream reader does not have to hardcode (and drift on) a per-symbol table. The per-instrument differences are real and easy to get wrong by hand: a JPY pair's pip is 0.01 (not 0.0001); gold's lot size is 100 (not the FX 100000).

Scope: price-interpretation geometry only

The file carries only the geometry needed to interpret the price series — facts that are intrinsic to the data and effectively constant over its whole multi-year span:

Field	cTrader source	Meaning
digits	Symbol.Digits	price decimal places
pipSize	Symbol.PipSize	price units per pip (EURUSD 0.0001, USDJPY 0.01, XAUUSD 0.1)
tickSize	Symbol.TickSize	smallest price increment
lotSize	Symbol.LotSize	base-currency units per 1.0 lot — turns a price move into money (FX 100000, XAUUSD 100)
baseAsset	Symbol.BaseAsset.Name	base asset / currency ISO label
quoteAsset	Symbol.QuoteAsset.Name	quote asset / currency the price is denominated in
description	Symbol.Description	human-readable name

Plus provenance: schemaVersion, symbol, generatedAtUtc, generator.

What is deliberately NOT here — and why

cTrader's Symbol also exposes costs (Commission*, Swap*), volume limits (VolumeInUnits*), trading status (TradingMode, IsTradingEnabled) and deposit-currency pip/tick values (PipValue, TickValue). These are intentionally excluded, because they do not describe the historical price series — they are a point-in-time snapshot of today's trading conditions:

• The cBot only ever sees the current contract. A backtest runs against the symbol as it is defined now, never as it stood in a historical month. So the bot physically cannot emit a historically-accurate swap rate or commission for 2015 — only today's. Swap rates in particular change weekly; stamping a single 2026 value onto a 15-year series would misrepresent it.
• PipValue / TickValue are additionally account-dependent. cTrader reports them already converted into the exporting account's deposit currency at the export-time FX rate, so they are a property of (account × moment), not of the instrument. The stable, account-free pip value is pure arithmetic: lotSize × pipSize, in the quote currency.

If a consumer needs current trading conditions (for a friction model, position sizing, etc.), those are a separate, time-varying concern and belong in their own time-indexed source — not baked into a per-symbol price-geometry file as if they held across history.

Mechanism

• MS_SimpleExport cBot, MetaOnly mode (src/MS_SimpleExport/MS_SimpleExport.cs). Run with --MetaOnly=true --MetaFile=<path>, the bot does no price export: in OnStart it reads Symbol, serializes the geometry fields to JSON at MetaFile, prints META_SUCCESS, and stops.
• export-runner.sh, write_meta. Once per symbol per run (mode-independent), the driver spawns a short MetaOnly backtest, writes <SYMBOL>.meta.json.tmp, validates it is parseable JSON, then renames it to <SYMBOL>.meta.json.
  • Best-effort by design: a metadata failure is logged (⚠️) and never aborts the export run; a pre-existing sidecar is left untouched (overwrite only on a validated success).
  • Cadence: refreshed at most once per META_MAX_AGE_DAYS (default 7) so scheduled runs stay short. EXPORT_META=0 disables; META_MAX_AGE_DAYS=0 forces a refresh every run.

Format

A flat JSON object. Conventions:

• Numbers use invariant formatting — a pip size is 0.0001, never a locale 0,0001. Round-trip formatting may emit scientific notation (1E-05); valid JSON, parses as a number.
• A non-finite broker value (NaN / Infinity) is emitted as JSON null.
• schemaVersion is bumped on any incompatible change to field names or units (currently 2).

Example

{
  "schemaVersion": 2,
  "symbol": "EURUSD",
  "generatedAtUtc": "2026-06-25T11:06:01Z",
  "generator": "MS_SimpleExport (cTrader.Automate)",
  "description": "Euro vs US Dollar",
  "digits": 5,
  "pipSize": 0.0001,
  "tickSize": 1E-05,
  "lotSize": 100000,
  "baseAsset": "EUR",
  "quoteAsset": "USD"
}

Consumer-side derivations

A reader composes whatever shape it wants from these raw fields, e.g.:

contract_size      = lotSize
pip_value_per_lot  = lotSize * pipSize           # in quoteAsset (EURUSD: 100000*0.0001 = 10 USD)
point_size         = 10 ** -digits

Trading constraints a consumer's own instrument spec might want — minimum lot, lot step, a stable instrument id — are not price-interpretation geometry and are not in this file; the consumer authors those itself (an id is a registry choice; min-lot / lot-step are current order limits, not facts about the historical bars).

Worked geometry, verified against the live broker:

symbol	digits	pipSize	tickSize	lotSize	base/quote	→ pip_value_per_lot
EURUSD	5	0.0001	1E-05	100000	EUR/USD	10.0 USD
USDJPY	3	0.01	0.001	100000	USD/JPY	1000 JPY
XAUUSD	2	0.1	0.01	100	XAU/USD	10.0 USD