Symbols and intervals

Symbols and intervals

Marketfeed symbols are self-describing. The base grammar is:

class:venue:ticker[:qualifier...]

Each part answers a different question:

  • class says what kind of instrument this is, so qualifiers can be validated without consulting a registry;
  • venue identifies the listing or publishing venue, normally with a MIC-like code;
  • ticker is the product or instrument name at that venue;
  • qualifiers select an adjustment stream, dated futures contract or other class-specific view.

Common classes and examples are:

ClassMeaningExample
eqEquity or ETFeq:XNAS:AAPL
futFuturefut:XCME:ES or fut:XCME:ES:M26
idxIndexidx:XNAS:NDX
volVolatility indexvol:CBOE:VIX
mkintMarket internalmkint:US:ADVSP
fxForeign exchangefx:RBA:AUD-USD
macroEconomic seriesmacro:FRED:GDP
cotCommitments of Traderscot:CFTC:13874A:MM

The venue is part of identity, not decoration. XNAS is Nasdaq, ARCX is NYSE Arca, XCME is CME, XCEC is COMEX and XNYM is NYMEX in common archive symbols. Marketfeed’s symbol registry supplies the longer exchange description, timezone, sessions, tick size, point value, currency and vendor aliases. Strategies can read the engine’s resolved subset with ctx.Instrument(symbol).

Do not pass vendor notation such as Databento’s ES.c.0 to the adapter. Databento parent and continuous symbols are acquisition-side aliases; the local archive and Algolang run use canonical marketfeed names.

Symbols are case-insensitive

fut:xcme:es and fut:XCME:ES name the same instrument (GLE-514). The engine gives every symbol its canonical spelling where it enters a run, so the adapters, the series cache, the run id, the report and order matching all see one spelling:

  • --symbols, --symbol, --calendar-revisions and --calendar-accept-unverified, and the algodata and rollsched symbol flags;
  • a run-config file’s symbols, once {placeholders} are substituted, its calendar keys and its benchmark symbols;
  • the symbols a strategy names: its declared series, its tradeable symbols, its instrument filter, and the symbol of every order and combo leg.

The canonical case is: class lowercase; venue, ticker, contract codes, calendar spreads and COT groups uppercase; cont and the adj=, ofs= and straddle= keys lowercase, with adj and straddle values lowercase and ofs values uppercase. Only ASCII letters change.

bin/algo run --strategy bin/hello --symbols fut:xcme:es --bar-interval 5m
# runs fut:XCME:ES, exactly as if it had been typed that way

Two spellings of one symbol are one symbol, so --symbols fut:XCME:ES:H26,fut:xcme:es:h26 is refused as a symbol given twice. A symbol outside this grammar (a bare MSFT, an unknown class) and anything after an @ are passed on as written. The bundled adapters match those in any case too, and serve what they find under the spelling the run asked for. A strategy may name a symbol in any case: ctx.Series and ctx.Position find the canonical one. Series ids are the strategy’s own names, not symbols, and are left alone.

Session names are case-insensitive too (GLE-1327): --session RTH, Rth and rth name one session, as do CUSTOM:0830-1500 and custom:0830-1500. The engine lowercases eth, rth, session, utc-day and the custom: prefix where a session enters a run: the --session flag, a run-config file’s session keys, a strategy’s declared series and a library caller’s plan. Any other name is passed on as written, so its refusal quotes it.

Equity qualifiers

An equity with no qualifier means the raw series. The explicit forms are:

SymbolPrice view
eq:XNAS:AAPL:adj=rawUnadjusted prices.
eq:XNAS:AAPL:adj=splitSplit-adjusted prices.
eq:XNAS:AAPL:adj=splitdivSplit-and-dividend-adjusted prices.

The feed serves the view the symbol names, and the engine adjusts nothing (GLE-328, GLE-228 Decision 5a). An adj=split or adj=splitdiv bar arrives with is_adjusted set, the raw prices in raw_* and the symbol’s cumulative_price_ratio. The strategy receives it as served, so OHLC and indicators run in the adjusted view and the raw accessors described earlier expose the venue-real one, while the fill simulator, the corporate-action firing passes and the report recorder receive its raw projection, so fills are at historical prices. A bar whose raw view cannot be promoted is a feed defect and refuses the run: a raw field of 0 beside a served price that is not 0 (raw_view_unset) or a raw field that is not finite (raw_view_not_finite), GLE-546; see Equities and live reconciliation. An order placed in the adjusted view is translated onto raw prices by the symbol’s latest served ratio, and a fill is translated back by the ratio of the bar it filled in. Corporate actions are fetched for every eq symbol, raw or adjusted, on the run symbol as given, so a split rewrites the held quantity and a dividend is credited whatever the price view. The two adjusted forms travel on the protobuf wire only and force it in auto negotiation, and a feed that serves plain bars under an adjusted name is refused before the first bar. A declared eq: reference series is served as is, with no accounting. See Equities and live reconciliation.

Futures qualifiers

A futures root and a dated contract are different requests:

SymbolMeaning
fut:XCME:ESBare E-mini S&P 500 root; runs as marketfeed’s Panama-adjusted composite (:cont:adj=panama on the wire).
fut:XCME:ES:M26June 2026 dated contract.
fut:XCME:ES:M26-U26The exchange’s June/September 2026 calendar spread (GLE-414): its own bars, price and volume, legs in listed order, for roots that keep their spreads (ES). The price is the exchange’s as listed and can be negative; ES lists the deferred leg minus the front. A declared reference series only: as a run symbol or a tradeable symbol it is refused; trade the spread as a combo order on its legs (Combo orders, GLE-409).
fut:XCME:ES:contMarketfeed’s schedule-backed composite, rolled on the feed’s served schedule. algo run runs it through the same continuous path as the bare root (GLE-325): it may carry one adj=panama|ratio|none (bare :cont is panama) and one ofs=B1, B2 or B3 naming a deferred composite (GLE-410, Contract curves); ofs=F, straddle= and an @ suffix are refused (see Continuous futures). Report benchmarks fetch it for their futures sleeves.

Futures month letters are F G H J K M N Q U V X Z, January through December. A dated qualifier is one letter plus a two-digit year, so H27 is March 2027 and Z26 is December 2026. A calendar spread joins two of them with a hyphen in the order the exchange lists the instrument (M26-U26).

Relative forms such as fut:XCME:ES+1 or fut:XCME:ES+V are valid members of marketfeed’s wider grammar, but its data readers do not resolve them. They encode a roll decision, which belongs to the engine. Use a dated contract for one contract or a configured continuous root for a stitched series.

Synthetic spreads

marketfeed also serves spreads it builds itself from other series (GLE-1425): a weighted sum or a ratio of 2 to 12 legs, written in AlgoChart’s spread syntax. A strategy reads one as a declared reference series, with the same values the chart draws.

  • Additive: spr:c1*leg1,c2*leg2,… adds 2 to 12 terms, each multiplied by its coefficient. A negative coefficient subtracts, so spr:1*fut:XNYM:CL,-1*fut:XNYM:BZ is WTI minus Brent. A term with no coefficient counts once.
  • Ratio: ratio:leg1,leg2 is leg1 ÷ leg2, with exactly two legs and no coefficients. For example, ratio:fut:XCEC:GC,fut:XCEC:SI is gold over silver.
  • Mixed: put a spread in brackets to use it as one leg of another. spr:2*(ratio:fut:XCEC:GC,fut:XCEC:SI),-1*macro:FRED:DGS10 is 2 × (gold ÷ silver) minus the 10-year yield, and ratio:(spr:1*fut:XNYM:CL,-1*fut:XNYM:BZ),fut:XNYM:CL is (WTI − Brent) ÷ WTI. Brackets nest up to four levels deep, with at most 48 plain legs in all.

A leg is any symbol marketfeed serves bars for: a futures root, dated contract or composite, an equity, an index, an FX rate, a FRED or EIA series, a COT report. The first plain leg (following the first term down through its brackets) sets the spread’s clock: the spread has a bar wherever that leg has one, and each later leg contributes the bar it had published by then. A later leg that has not yet printed holds its previous value for up to three months (the adapter’s MaxCarry input: none, 0, or a number with d, w or mo, for example --adapter-inputs Dir=/usr/local/marketfeed,MaxCarry=2w); past that the spread has no bar. A futures root or :cont leg is read raw (adj=none), because back-adjusted levels use roll gaps learned later; name adj=panama or adj=ratio on the leg to choose otherwise.

A spread whose first plain leg is release-stamped (macro:, cot:, fx:RBA:) is a release-stamped series itself (Release-stamped series): it is served at that leg’s release instants whatever the interval, each bar’s Ref is that leg’s reference period, and it takes no session. The WPSR stocks of crude, gasoline and distillate together are spr:1*macro:EIA:WCESTUS1,1*macro:EIA:WGTSTUS1,1*macro:EIA:WDISTUS1, and a later report leg published late in a week holds its previous week, exactly as the chart shows it. A spread clocked by a price leg takes the run’s interval and an eth, rth or session trading-day session at 1d or 1w; an intraday grid or a custom session is refused.

A synthetic spread is data only. It has no book: a run symbol or a tradeable symbol that is one is refused, with a message saying to trade its legs. It is served on the stdio-pb-v1 and stdio-csv-v1 wires (auto negotiation leaves DBN out when one is planned), its symbol is passed through as written (the case rules of Symbols are case-insensitive do not apply to it), and it answers coverage for bars only. A strategy declares one like any reference series:

func (s *Crack) DataRequirements() []algolang.DataRequirement {
    return []algolang.DataRequirement{{
        SeriesID: "crack",
        Symbol:   "spr:-3*fut:XNYM:CL,84*fut:XNYM:RB,42*fut:XNYM:HO", // 3-2-1 crack, $/bbl
        Lookback: 260,
        Schema:   algolang.DataSchemaSpec{Kind: algolang.Bars, BarKind: algolang.BarsTime, Interval: "1d"},
    }}
}

RB and HO trade in dollars a gallon and CL in dollars a barrel, so the 3-2-1 crack weights the products by 42 gallons a barrel.

Intervals and ranges

The bar interval is not part of the symbol. It is a property of the requested series, supplied with --bar-interval for a time-bar run:

--symbols eq:XNAS:AAPL --bar-interval 1d
--symbols fut:XCME:ES:M26 --bar-interval 5m

Intervals use duration-style tokens such as 1s, 5m, 1h, and 1d. --date-from and --date-to each take a date (YYYY-MM-DD) or an RFC 3339 timestamp, in single-run and config mode alike; see The date range. Marketfeed may hold different native granularities in different eras. The adapter composes those eras and follows the platform rule: coarsening is allowed only by whole multiples, refinement is refused. Thus a 5-minute request can be built from 1-minute storage, but a 30-second request cannot be made from that same storage.

When a coarse bar was constructed from finer stored bars, --include-path asks marketfeed to carry those constituents to the engine. The simulator uses them to resolve intra-bar execution ordering; the strategy still sees one ordinary coarse bar.

The date range

--date-from and --date-to set a run’s window, in single-run and config mode alike, and so do the config keys date-from and date-to. Each takes a date (YYYY-MM-DD) or an RFC 3339 timestamp:

--date-from 2024-01-02 --date-to 2024-06-28
--date-from 2024-01-02T14:30:00Z --date-to 2024-01-02T21:00:00Z

A bar owns its close. A bar, a session and a day each include their closing instant, and the next one starts 1 ns later, so midnight ends a day. A run keeps a bar when its close is after the start and at or before the end: start < ts_close <= end.

A timestamp is exact. --date-from T starts with the first bar that closes after T, and --date-to T ends with the bar that closes at T.

A date is a day in the exchange’s time zone, the zone the adapter gives for the symbol (America/Chicago for fut:XCME:ES):

  • Without --session, a date is the whole local day, from the midnight that starts it to the midnight that ends it. Marketfeed cuts a dated series’ daily bars on the same midnights.
  • A continuous series at 1d or 1w (a bare root or :cont, without --continuous-clock epoch) reads the feed’s ETH trading days (How continuous contracts are stitched), so its dates are read under ETH, as with --session eth. The day’s session that is still trading is a bar that closes at its data’s end, on the evening before its trade date: --date-to on the day before ends at that day’s 16:00:01 CT close and leaves it out (GLE-1350). An intraday or epoch-clock continuous series reads whole local days.
  • With --session, --date-from D starts at the session’s open on D and --date-to D ends at its close, so --date-from D --date-to D is that one session. The close includes the session’s closing second, as the exchange calendar defines it: ES’s ETH session that closes at 16:00 CT ends the window at 16:00:01, where the session grid’s last bar closes. A session that opens before the midnight starting the from-date starts the run at that midnight; one that closes after the midnight ending the to-date ends it there. ES’s ETH session for Monday 2 March 2026 opens at 17:00 CT on Sunday 1 March, so --date-from 2026-03-02 --session eth starts at 00:00 CT on 2 March. The sessions come from the exchange calendar (stdio-pb-v1). An adapter that serves none gives the whole local day; so does a date the calendar does not know, and the run says so.
  • --session utc-day reads a date as a UTC day (Intraday grids; at 1d and 1w it needs an adapter that lists it, which marketfeed does not yet, GLE-1347).
  • An adapter that gives no zone for a symbol (file-csv) gives UTC days, and the run says so.

There is no --timezone flag. The same flags and the same calendar revision always give the same window.

Under a session, a date with no session moves. On a weekend or a holiday, --date-from moves forward to the next session and --date-to moves back to the previous one; the run notes each move. It is refused when no session is left. In --date-from 2010-01-01 --date-to 2026-10-31 --session rth on ES, New Year’s Day moves to 4 January 2010 and Saturday 31 October 2026 to Friday 30 October. Without a session a date does not move: a weekend day is a local day with no bars, or with Sunday evening’s.

Each series has its own window. A run over several symbols resolves the range for each series in its own exchange’s zone and session. Anything that needs one window for the whole run, such as the contract expiry at the run’s end, takes the latest start and the latest end.

The run prints the resolved window as instants, with the zone it used, on its window: line, and --verify prints it under each run:

  window:     2010-01-04T14:30:00Z < ts_close <= 2026-10-30T21:00:01Z (2010-01-04 08:30:00 CST to 2026-10-30 16:00:01 CDT, America/Chicago)
              2010-01-01 has no rth session: the range starts on 2010-01-04
              2026-10-31 has no rth session: the range ends on 2026-10-30

result.json records the same in the header’s DateRange: the bounds as given (From, To) and each series’ Start, End, Zone, the dates the bounds resolved to (FromDate, ToDate) and the notes. With neither flag, the run asks for 1970 to 2100.

The engine dates a bar the same way. A bar without a session trade date is dated by the exchange date of its close minus 1 ns, so a daily bar that closes at midnight belongs to the day it ends. The ex-date rule, the GTC expiry deadline and the contract expiry use this date.

--start and --end are removed. Each still parses, so that a script that passes one fails with removed: use --date-from / --date-to rather than an unknown flag. An adapter that does not declare start < ts_close <= end (DataInitAck.bar_membership) is refused at start-up, rather than shift every run by one bar.