exchange-hours
A Rust library that knows when exchanges are open — and where sessions and chart bars begin and end.
Accuracy: best effort, not a guarantee. Schedules are built from operator publications (rulebooks, notices, archived calendars) and re-verified on a review cadence, but exchanges change hours without notice and sources go dark. Where evidence is missing the library refuses with an explicit typed error rather than guessing — but a covered answer is best-effort research, not a guarantee of the venue's actual behavior. Verify against the operator before acting on it.
Give it a UTC timestamp (chrono::DateTime<Utc>) and an exchange, and it answers three
questions:
- Is the market open right now? — regular hours, extended hours, or either.
- When does the current session start and end? — and if the market is closed, when the next session opens.
- Where do chart bars begin and end? — intraday, daily, weekly, and monthly bar boundaries that follow the exchange's real sessions, so a bar never spans a closed period and a daily bar closes at the session close, not at midnight.
Everything is a pure function over a MarketHours snapshot, date-aware
ExchangeCalendar, or caller-overlaid PolicyCalendar: no state, no I/O, no
clock reads, no floats, and #![forbid(unsafe_code)]. Timestamps go in as UTC
and come out as UTC — each exchange's local time zone, including its DST
quirks, is handled internally.
The internal ownership and extension model is documented in
ARCHITECTURE.md.
Coverage: the target is complete served calendars from the permanent 2010-01-01 floor. Actual sourced ranges, special sessions and typed coverage errors are recorded below. The dated current OANDA release-scope exception permits 1.1.0 activation with historical gaps retained in #332; it does not certify those gaps as ordinary trading.
- 96 source-backed market identities, plus the synthetic
Exchange::Unknownfallback (97Exchangevariants total) — covering US equities/options, US and international futures, EU and Asia-Pacific equities, other major global cash markets, always-open crypto, and operator CFD/FX books, with independently fenced point-in-time revisions wherever primary evidence states an unconditional day-level boundary. - Session queries — open/closed by regular/extended/both, session bounds, next open, gaps.
- Product-family calendars — all 51 operator-derived
MarketHoursKeyvalues have fixed, point-in-time, and date-aware query surfaces. - Caller-supplied day policy — whole trade-date closures, early final
closes, and late first opens can be overlaid on any built-in profile, for the
dates the crate does not yet carry.
StaticDayPolicyprovides a validated hard-coded table format for these boundary-level exceptions. - Caller-supplied exception sessions — a trade date that pauses and
reopens, ends regular trading while extended continues, or spans several
civil dates is replaced outright by an ordered
ExceptionBlockset.StaticSessionExceptionsis the validated table format; the crate ships zero exception data. - Calendar-aware bar boundaries — intraday bars clamp to the session close so no bar spans a closed period; the day's last bar ends at the daily close itself (CME 16:00 CT, never the later Pre-Open or matching restart), and daily/weekly/monthly bars close at real session closes, not midnight.
- DST correctness by construction — local seconds-since-midnight rules, resolved to instants with an explicit, asymmetric bias (opens earliest, closes latest).
Installation
exchange-hours 1.0 requires Rust 1.95 or newer. The Quick start constructs
timestamps directly, so its complete dependency set is:
[]
= "1"
= "0.4"
= "0.10"
Quick start
This is the compiled doctest in src/lib.rs, copied verbatim. CME equity-index futures match
17:00→16:00 CT and accept weekday orders from 16:45; RTH runs 08:30–15:15 CT:
use ;
use US;
use ;
let ct = ;
// Every snapshot request carries the caller's instant: the crate never reads
// a clock, so a backtest and a live query run identical code. A live caller
// passes their own `Utc::now()` at the application edge.
let hours = hours_for_exchange;
// Monday mid-morning sits inside the regular session. Boundary queries
// return `Option`: `None` means no matching session exists in the bounded
// search horizon (for example, on a pre-go-live date).
let monday_10am = ct;
assert!;
let = session_bounds.expect;
assert_eq!;
assert_eq!; // end-exclusive
// 16:30 CT is the daily maintenance break: closed, inside an inter-trade-date
// gap (16:00→16:45) no longer than the documented four-hour bound.
let monday_evening = ct;
assert!;
assert!;
// After Friday's close the next accepted-order phase is Sunday's 16:00
// Pre-Open, not Saturday. Matching resumes at 17:00.
let friday_after_close = ct;
let = next_session_after.expect;
assert_eq!;
// Bar boundaries follow the same rules: a daily bar closes at the venue's
// session close, not at midnight.
let daily_close = candle_end;
assert_eq!;
For a venue whose grid can change between dates, keep an ExchangeCalendar
instead of carrying one fixed snapshot:
use ;
use ;
let bmv = calendar_for_exchange;
// All predicates, session scans, and candle methods take UTC instants and
// reselect BMV's normal/early grid for each candidate trading date.
let instant = Utc.with_ymd_and_hms
.single
.expect;
let snapshot_for_one_instant = bmv.hours_at;
assert_eq!;
Product-family calendars use the same date-aware surface. Their identity is a
MarketHoursKey, exposed through CalendarSource, rather than a venue:
use ;
let calendar = calendar_for_market_hours_key;
assert_eq!;
assert_eq!;
Coverage
| Family | Market identities | Local zone | Session shape |
|---|---|---|---|
| US equities and ATS | 19 | America/New_York |
09:30–16:00 regular on matching venues; modeled accepted-order envelopes differ by venue. The set includes LTSE (08:00–17:00), 24X's live daytime service (04:00–20:00), and TXSE (08:00–17:00), each closed before its sourced production launch. Announced overnight expansions remain monitored and unencoded until their readiness conditions and live days are confirmed. |
| FINRA TRFs | 3 | America/New_York |
09:30–16:00 regular; outside-RTH reporting is extended under the sourced 04:00–20:00 system envelope from 2026-03-30. FINRA's announced overnight expansion remains unencoded while its date depends on the SIP rollout. |
| US options | 18 | America/New_York |
Ordinary individual-stock options trade 09:30–16:00 regular. Seventeen venues also expose their current generic order-acceptance queue as extended (06:00, 07:00, or 07:30 by operator); MEMX rejects orders before 09:30. Product-specific ETF, ETN, index, FLEX, floor-only, and designated sessions remain outside scope. Exact launch history is retained, while an unknown historical queue-onset day is disclosed as Partial rather than invented. |
| CME Globex futures | 4 | US/Central |
The count is four compatibility Exchange identities (CME, CBOT, COMEX, NYMEX); nineteen product-family keys cover scoped U.S. equity indexes, NYMEX energy/PGM and COMEX metals, standard-size CBOT grains, mini-sized CBOT grains, Rough Rice, standard-grid CME FX, CBOT/CME interest rates, CME livestock, Nikkei 225 Dollar, CME weather temperature-index futures, CME non-spot-quoted cryptocurrency futures, CME/CBOT Spot-Quoted Futures, CME Group event contracts, Event Contracts on Bitcoin Futures, and the five metals Trading at Settlement books (COMEX gold, silver and copper; NYMEX platinum and palladium). Fixed-current profiles include the published Pre-Open/order-entry and PCP phases. Dated selectors retain only source-dated phase changes, so eighteen of the nineteen key histories—and the four venue defaults that reuse the standard grids—are Partial where an older phase-onset day or a carried-back boundary is unavailable; globex_spot_quoted is the exception. Weather futures have no regular session and closed 15:15 CT until CME SER-9519 expanded them to 16:00 CT on 2025-04-13. Cryptocurrency moved from the five-day 17:00→16:00 grid to 24/7 trading on 2026-05-29. Its weekday maintenance is 16:00–16:02 with Pre-Open from 16:01; Saturday maintenance is 02:00–04:00 with Pre-Open from 03:45. Event Contracts on Bitcoin Futures moved to 24/7 the same day on the sourced intersection of two CME statements that disagree by an hour on the weekday close: open 16:02→15:00 CT, the 15:00–16:00 hour withheld, Saturday 02:00–04:00 with Pre-Open from 03:45. The five metals TAS keys run Sunday–Thursday 17:00 CT to their own closes (12:30, 12:25, 12:00, 12:05 and 12:00 CT) with no Friday-evening reopen and no regular session; none has an executable revision since its 2010–2018 launch, and the COMEX three withhold the Sunday 16:00–16:15 CT quarter-hour that the 2012 queue move leaves undated. |
| Cboe Futures (CFE) | 1 | US/Central |
RTH 08:30–15:00 flows into post-settlement 15:00–16:00; conservative latest queue-acceptance edges are Sunday 16:00:06 and Monday–Thursday 16:45:06 before the 17:00→08:30 overnight wrap. |
| Other U.S. futures venues | 2 | America/Chicago |
Coinbase Derivatives (FairX until 2022) defaults to its 23x5 grid, Sunday–Friday 17:00→16:00 CT, from its exact 2021-06-28 08:00 CT launch, with its undated 16:50 Pre-Open from the 2026-09-11 knowledge-bound row; most of its futures moved to a separate 24x7 family by 2026-05-04. Small Exchange traded 07:00–16:00 CT from its 2020-05-18 launch and 08:30–15:00 CT from November 2024, and is closed from 2025-03-24, after it delisted every contract. |
| EU equities | 14 | 11 European zones | 09:00–17:30 continuous as the continental default, with venue-owned phases: Xetra's DAX-share envelope includes participant-restricted Extended Retail from 07:00 to 22:00; LSE SETS includes 07:00 pre-trading, randomized opening/noon auctions, and CPX to 16:40; central Euronext profiles use the published nominal phase boundaries and exclude per-security randomized uncross seconds; SIX, BME, Vienna, and Nasdaq Nordic books keep their own phases and clocks. |
| Asia-Pacific equities | 17 | 14 IANA zones | ASX, TMX Australia, NZX, TSE, NSE India, BSE India, HKEX, SGX Securities, Bursa Malaysia, SET, IDX, PSE, HOSE, SSE, SZSE, KRX, and TWSE. Venue unions include accepted block/crossing phases; SET also includes the sourced 2025 DR night session. Security eligibility may be narrower than the exchange envelope. |
| Other major global equities | 6 | Toronto / Istanbul / Johannesburg / Riyadh / São Paulo / Mexico City | TSX, Borsa Istanbul, JSE's main/liquid ZA01 segment, Tadawul, B3, and BMV, including their pre-open, closing, trade-at-last, and accepted post-close order phases. B3/BMV grids are date-aware because they follow New York's offset relationship. |
| ICE complex & European energy | 9 | London / Amsterdam / Berlin / Dubai / New York / Winnipeg | Named product-family profiles: Eurex FESX/FDAX/FDXM, EEX Nordic Zonal Power, ICE FANG+, Brent, FTSE 100, Dutch TTF, Murban, and legacy Canola. Date-aware profiles preserve product launches, FTSE extensions, Eurex's fixed-UTC Asian pre-trading/auction and continuous phases, Endex's 2026 extension/DST rule, Murban's New-York-locked grid, and Canola's sourced 2010–2018 eras. |
| Asia-Pacific futures (SGX) | 1 | Asia/Singapore |
Three-Month SORA Futures: continuous 07:25–17:55 and 18:15→05:15, with opening/closing phases and a 18:00–18:05 gap. Closed before the 2024-07-29 launch. |
| Always-open crypto | 1 | UTC |
Binance USDⓈ-M perpetuals are normally 24×7 after their exact 2019-09-13 04:00 UTC launch. |
The supplied Databento catalog is covered explicitly: all 50 distinct venue
labels across equities, equity options, futures, and options on futures map to
non-Unknown identities. See the checked
Databento venue crosswalk for exact vendor
labels, stable enum variants, canonical wire names, and each ledger basis.
Futures hours track the product family, not merely the listing venue.
MarketHoursKey has 52 variants—51 operator-derived product-family keys plus
the synthetic AlwaysOpen key. They reuse profiles and are not additional
venues. session_profile exposes each family's fixed-current static table;
hours_for_market_hours_key selects the sourced snapshot at the caller's
instant; calendar_for_market_hours_key reselects the dated profile while
scanning sessions and candles.
Every key's snake_case name is a stable persisted wire identity shared by
as_str, Display, FromStr, and Serde. Renaming one is a breaking change.
The crate deliberately does not map symbols, roots, product codes, or MICs
to keys: the caller's sourced instrument catalog must make that selection.
The venue-keyed API retains these explicit defaults for compatibility:
| Venue identity | Default family profile |
|---|---|
cme |
globex_equity_index |
cbot |
globex_grains |
comex, nymex |
globex_energy |
cfe |
cfe_vix |
coinbase_derivatives |
23x5 futures venue default |
small_exchange |
Venue history; closed since 2025-03-24 |
eurex |
eurex |
iceus |
ice_us |
sgx |
sgx |
Those defaults are the wrong choice for any product outside the named family.
CME interest-rate, livestock, and cryptocurrency products must use their family
keys rather than Exchange::Cme or Exchange::Cbot. Exchange::Cbot resolves
to the standard grain and oilseed grid, so Rough Rice (ZR/OZR) must select
globex_rough_rice: its extended session was cut to Sunday-Thursday
19:00-21:00 CT on 2018-01-21 and no longer wraps past midnight. The mini-sized
grains (XC/XK/XW/MKC) must likewise select globex_mini_grains: their
day session closed 30 minutes after the standard grid from before the
January-2010 floor until the grids converged on 2022-10-02, and they skipped
the standard grid's 2015-07-05 close change entirely. CME weather
temperature-index futures must select globex_weather rather than
Exchange::Cme: they have no regular session and closed 15:15 CT until
2025-04-13, so their history matches neither globex_fx nor globex_energy
despite sharing the same envelope today. CME/CBOT Spot-Quoted Futures
(QSPX/QNDX/QDOW/QRTY/QBTC/QETH/QSOL/QXRP) must select
globex_spot_quoted: they have no regular session, they launched only on
2025-06-29, and CME kept them on the five-day grid when the cryptocurrency
family moved to 24/7 trading on 2026-05-29, so neither
globex_equity_index nor globex_cryptocurrency answers for them. CME Group
event contracts (ECES/ECNQ/ECRTY/ECYM/EC6E/ECCL/ECNG/ECGC/ECSI/ECHG
and the hourly Chapter 23A roots) must select globex_event_contracts: their
per-root Termination of Trading times are stated expiration times, not session
closes, so all of them run one 17:00→16:00 CT grid rather than the six their
published hours cells appear to describe. ECBTC must select
globex_event_contracts_btc in every era: it rode the shared grid from
2023-03-12 to 2026-05-28, and from 2026-05-29 that key serves a 24/7 grid on
the sourced intersection of the two CME statements of its weekday close, which
disagree by an hour. The same applies to the
two venues whose default now covers only a small slice of what they list:
Exchange::Iceus resolves to NYSE FANG+, so Sugar No. 11, Coffee "C", Cocoa,
Cotton No. 2, FCOJ-A and the U.S. Dollar Index must select ice_us_sugar,
ice_us_coffee, ice_us_cocoa, ice_us_cotton, ice_us_orange_juice or
ice_us_dollar_index; Exchange::Sgx resolves to Three-Month SORA, so SGX
equity-index products must select the matching grid: sgx_equity_index_japan,
sgx_equity_index_china, sgx_equity_index_singapore,
sgx_equity_index_taiwan, or sgx_equity_index_ntr_usd. Eurex
fixed income likewise has its own eurex_fixed_income key, distinct from the
eurex index-futures default, and Nikkei 225 Dollar uses
globex_nikkei_225_dollar rather than globex_equity_index.
Family selection is exact: consumers must never substitute the nearest venue
or product-family key when a product is outside that key's documented scope.
Nikkei 225 Dollar futures (NKD), the six ICE Futures U.S. families, CBOT
mini-sized grains, CBOT Rough Rice, CME weather temperature-index futures, CME/CBOT
Spot-Quoted Futures, CME Group event contracts, Event Contracts on Bitcoin Futures, and Eurex fixed income all ship as
sourced keys.
All eight spot-quoted roots share one key because their normal week and dated
history are identical; their holiday half-day closes are not, so a caller
attaching date exceptions to globex_spot_quoted must build them separately
for the equity and cryptocurrency roots. Options on weather futures are not in
globex_weather: they traded on the CME floor for most of the audited history
and the day they moved to CME Globex is unsourced, so they stay caller catalog
data. SGX equity-index products do not
share one grid, so they ship as five separate keys and the ambiguous name
sgx_equity_index stays rejected rather than resolving to one venue-wide clock.
See
Ambiguous futures families.
The table contains 95 source-backed market identities. Exchange::Unknown is
an additional synthetic 24×7 UTC fallback and is not counted as an exchange or
trading venue.
Schedule assurance
Repository-wide review completed: 2026-08-22
That is the 93-identity ledger cutoff. Product-family keys were reviewed in the same pass and carry their own basis labels in the ledger.
Hours verified against the exchange at the review date: 96 of 96 non-synthetic
Exchange identities, within each row's documented normal-week scope.
The broker-native oanda_china50_cfd and oanda_singapore30_cfd keys expose
the published Singapore day/night grids, witnessed from 2024-02-21, with
current holiday coverage from 2026-10-10 through 2026-10-30; earlier history
remains disclosed in #332. The last Friday night session retains its full
running bounds into local October 31, when queried on Friday. Its closing
trade-date classification and instant queries from Singapore midnight on the
unaudited Saturday refuse beyond the holiday horizon.
OANDA profiles describe the published trading windows and timed session
phases. OANDA also permits customers to store or modify pending orders while
markets are closed. is_accepting_orders does not describe that broker-side
facility or the availability of its order-placement API. The NZD-specific
06:59–07:05 Auckland break requires a caller overlay. The OANDA rows remain
partial. The nine reached book keys are served and reviewed monthly; the
broad OANDA venue remains dormant. Native current holiday coverage ends at
trade date 2026-10-30; later unpublished arrangements remain refused.
Equivalent-calendar inheritance is disclosed consumer user policy, with
explicit OANDA exceptions taking precedence. These keys do not certify
complete coverage of every OANDA listing or the six planned derivatives
families; historical gaps remain #332.
Date-aware queries answer or refuse explicitly — never a silent guess.
The normal-week grid is either sourced (dated primary sources run the whole
way back to January 2010) or verified carried (the operator's own archived
pages and notices were swept across the interval and show no change, so the
sourced state demonstrably held — the sweep record lives in the scope's
evidence file). Where a phase's endpoints are sourced at two values and only
the changeover day is undated, the crate serves the window that holds under
every sourced state and discloses the disputed margin; where a scope's evidence
runs out entirely, the crate refuses with an explicit typed error rather than
claiming hours it cannot support. 29 of 96 exchange rows still name a Basis
gap in the ledger, each with its disclosed residual or external closer.
Which window a gap sits in decides what it costs you. A gap in a phase where
trades print — the regular or extended session — would change whether the crate
reports a market as tradeable. A gap in an order-entry window only changes
whether orders could be queued ahead of an open that is itself modelled
correctly; no trade can print in one of those windows on any venue in this crate.
Every Partial row states which kind it is in its Basis cell, and the split is
37 order-entry to 36 executable across the 73 rows in the ledger. The order-entry majority is
the exact day an older queue or post-close phase started, with the trading
session itself sourced. The executable thirty-six — the ICE Futures U.S. keys,
the SGX equity-index keys, nyse and nyse_american,
whose January-2010 off-hours crossing phase was reclassified from order-entry on
2026-09-02, globex_event_contracts, whose daily close is carried back to its
2022 launch, globex_event_contracts_btc, whose 24/7 weekday close is the
intersection of two CME statements that disagree by an hour,
small_exchange, whose 2024 move to 08:30–15:00 CT is undated inside
2024-11-04..2024-11-21, and the five metals TAS keys — globex_gold_tas,
globex_silver_tas and globex_copper_tas, whose closes are carried across the
2015–2019 exhaustion of CME's metals hours page, and globex_platinum_tas and
globex_palladium_tas, whose windows rest on one archived capture each between
2021 and 2026 — plus oanda_china50_cfd and oanda_singapore30_cfd, whose current grids are witnessed from 2024-02-21 but whose holiday audit starts on 2026-10-10, euronext_index_futures, whose 08:00–22:00 grid is witnessed only by the 2026-10-11 contract pages so dates below the retrieval refuse as carried, and the eight earlier OANDA book rows — oanda, oanda_fx, oanda_try_fx,
oanda_metals, oanda_us_index_cfd, oanda_us_bond_cfd, oanda_us_commodity_cfd and
oanda_brent, whose pre-2024 history carries an earlier grid with an
undated changeover — and bme_ibex and ice_europe_gilts, whose floor grids
are carried below their earliest witnessing captures with the intervening
changeovers served as sourced intersections, and asx_spi_200, whose 2016
night-open witness is confined to two holiday rows of one capture, and
hkex_index_futures, whose after-hours cutovers are bracketed by the
operator's own page stamps — are each served
conservatively, erring toward closed rather than
claiming hours they cannot support. A recent executable-only audit of all
sixteen US futures product families found none of them withholding executable
time that the current grid serves. Rows carry this distinction in the ledger, so
check there before treating a Partial label as a reason to hesitate.
Where a residual uncertainty survives, it is instant-level and disclosed, not
a withheld day: the ledger's Basis cell states what is uncertain (typically the
exact day an operator system setting changed, where every other fact is sourced)
and the crate serves the window that holds under every sourced state around it.
Per-family holiday and early-close tables ship for 66 of the 149 ledger rows,
each over its own audited trade-date window; scopes without a built-in table
reach holidays through the caller's DayPolicy.
Every non-synthetic identity was compared with its official current-hours or
rulebook material and its notice/evidence channel. All 96 current profiles are
primary-supported within their stated scope. The 67 Primary rows have no
known modeled-history gap since January 2010 or their sourced launch; 29
Partial rows name an older queue, PCP phase, or exact onset that available
primary evidence cannot date. The basis vocabulary is closed at four values —
Primary, Partial / executable, Partial / order-entry and
Synthetic — so a row that cannot be sourced at the operator's own tier is a
defect to fix, not a weaker label to wear. Exchange::Unknown is synthetic and
is not one of the 96 source-backed identities.
Every row also states its service tier (LAW-SERVICE-TIERS): 58 of the 149
rows are served — a consumer instrument can reach them, so they owe dated
history to the January-2010 floor and a monthly or quarterly review, with
the dated current OANDA scope exception retaining historical gaps in #332 — and 91 are dormant, kept correct as of their last review and re-reviewed on demand.
Each row carries its evidence tier, the horizon below which its grid is carried
rather than sourced, its review cadence, and a link to the evidence file holding
the quotations and URLs behind it.
The key surface was audited separately:
Hours verified at the review date for each product family: 51 of 51 operator-derived
MarketHoursKey values. The key API provides fixed-current snapshots, an
as_of selector, and a date-aware calendar for sourced histories. Seven key
rows are Primary and forty-four are Partial, because a named historical
queue, PCP amendment day, or undated venue transition cannot be dated from a
primary source.
Queries before January 2010 fall outside all of this. The crate records amendment history back to January 2010 by design, and an instant before that floor resolves to that venue's oldest profile on record rather than to an absence — its pre-launch closure where the venue launched later, or its earliest grid otherwise. It is not a reviewed answer, and nothing below the floor is covered by the counts above.
These are backward-looking evidence statements, not promises that an exchange
will remain unchanged after the review date. They cover recurring weekday
phases, time zones, lunch and maintenance gaps, and weekend boundaries. They
exclude holidays, half-days, one-off closures or halts, severe-weather
exceptions, and product-specific variations outside a row's stated scope:
per-family holiday and early-close tables ship for 66 of the 149 ledger rows,
each over the trade-date window its Holidays cell names, and none of that data
is included in the counts above, which are about normal weeks. A change confined to a
single trade date — an early final close, a late first open, or a full
calendar-day closure — is always a holiday, never a normal-week template
change: the normal-week tables and their dated revisions encode only real,
recurring exchange behavior. Callers can apply their own sourced closed-day,
early-close, and late-open boundary data through DayPolicy, above whatever
the built-in tables carry, and holiday arrangements that replace or split
phases through SessionExceptionSource.
An early close or a late open is exactly a clipped boundary on an otherwise
normal session, which is what DayPolicy applies. An arrangement that
replaces or splits phases is not, and is never approximated by clipping: it
states its own blocks through SessionExceptionSource. Neither mechanism
ships with data. The full method, corrections, exclusions, and confidence
levels are recorded in the
2026-08-22 schedule audit.
The guarantee is exchange/segment/product-family level, never ticker-level microstructure. When an auction uncross is randomized per security, the row states whether the deterministic profile uses the operator's nominal phase boundary or a conservative venue envelope; it does not predict that day's per-security uncross second.
CME's post-2026-05-29 cryptocurrency weekend is stored as one-midnight
SessionRule pieces, but the identity-aware
calendar_for_market_hours_key(GlobexCryptocurrency) joins adjacent pieces
into CME's exact multi-day bounds. Both blocks around Saturday maintenance
carry the following open business date: normally Monday, with a daily bar from
Friday 16:01 Pre-Open through Monday 16:00 CT. If a caller's DayPolicy closes Monday,
the weekend trading remains open, rolls to Tuesday, and the daily bar closes
Tuesday at 16:00. Its key calendar also retains the real Friday 16:00 final
weekly close before the next trade-date week enters Pre-Open at 16:01. A fixed
MarketHours snapshot has no family identity: its open/closed state is exact,
but its bounds retain the one-midnight storage pieces and its generic weekly
candle and trade-date queries are unavailable. Use the key-backed calendar for
those family-specific results. Product-specific listing dates after the family
began remain instrument-catalog data.
The source-set registry records the stable official pages and notice/evidence entry points to check for each exchange. The repeatable process is in Updating exchange schedules. Exact historical notices remain cited beside the Rust table they support.
Historical amendments
hours_for_exchange and hours_for_market_hours_key return fixed-current
snapshots, while their _as_of counterparts select the fixed snapshot at a
UTC instant. For queries that span dates, use calendar_for_exchange or
calendar_for_market_hours_key: their session and candle methods resolve the
applicable profile again for every candidate trading day.
- Recorded changes only. A venue gets a historical cutover only when a primary source
(exchange notice, rulebook amendment, press release) states a day-level effective date.
Real changes without a sourced date are documented as Partial gaps rather than given
invented dates. A fixed current snapshot includes a source-verified current phase;
an
as_ofselector adds it only from a source-stated effective day. Consequently a Partial row's dated history can conservatively omit an undated queue even when its date-free current snapshot is exact. The verification ledger names every such interval. For Paris, Amsterdam, Brussels, and Lisbon, Euronext's per-security 0–30-second auction uncross delay is outside the exchange-level schedule, so those profiles use the operator's published nominal phase boundaries. Dublin and Milan retain their documented conservative latest-edge envelopes. Every choice preserves the exact venue-wide open/closed envelope. IEX and Blue Ocean have sourced production launch boundaries, and B3's explicit older grids are fully recorded to January 2010. - Conditional future changes are not schedules yet. Nasdaq, EDGX, NYSE Arca, MEMX, 24X, and the three FINRA TRFs have official future-session plans that still depend on readiness, SIP, clearing, or later filings. MX2 Options, IEX Options, MRX's additional sessions, and GIX are also watched as future identities/phases. They remain deliberately absent from runtime selectors until every condition and actual production day is confirmed.
- Cutover semantics. Date-only changes are compared in the venue's own local zone. The new profile applies from venue-local midnight on its session opening day—often Sunday for a Monday trade-date change. When a primary source states an exact intraday instant, that instant is preserved rather than rounded to midnight; one nanosecond before it sees the old profile.
- How far back. The aim is to record every session-defining amendment back to
January 2010; changes before that are out of scope by design. Below a venue's oldest
recorded profile,
hours_for_exchangekeeps returning that oldest profile at earlier instants — it does not manufacture an older row or change. Venues with no recorded change return their one grid at every instant.
B3 and BMV use recurring cross-zone selection. B3 chooses its short or long cash-equity
grid from the New York−São Paulo UTC-offset difference; BMV chooses its early or normal
grid from the New York−Mexico City difference. This covers the mismatch weeks created by
the countries' former DST calendars and the post-abolition rules without hard-coding yearly
US transition dates. A MarketHours returned for one date remains a fixed
snapshot, so use the appropriate date-aware calendar rather than carrying it
across a transition.
Trade dates, state, and caller day policies
On ExchangeCalendar and PolicyCalendar, trade_date(instant) returns the
venue-local trade date of the containing session, or None while closed.
Wrapped sessions use the date of the trading day's final close, so a normal
Sunday-evening Globex instant maps to Monday. An always-open profile has no
final close, so its trade date is always None; consequently
is_closed_trade_date is true for every date because no session is assigned to
one. Use is_closed_all_day_on or is_closed_all_day_in_calendar for
civil-day availability.
session_state(instant) returns exactly one of OpenRegular, OpenExtended,
Maintenance, or Closed. Maintenance is normally an inter-trade-date gap no
longer than four elapsed hours within one ISO week. A profile explicitly marked
as having no weekend close also retains an operator-designated short maintenance
gap inside one trade date; this covers CME cryptocurrency's Saturday 02:00–03:45
CT closed interval before its 03:45–04:00 Pre-Open. Same-trade-date gaps (a
scheduled lunch break, for example), longer afternoon gaps, closed days, and
weekends are closed — the crate models scheduled hours only and has no halt
concept.
is_maintenance is exactly the maintenance-state predicate.
The built-in profiles are normal-week schedules. Per-family holiday and
early-close tables sit underneath the caller's overlays for the 26 identities
whose ledger rows name a Holidays window; read one with
ExchangeCalendar::holiday_on(trade_date) and its audited window with
ExchangeCalendar::holiday_coverage(), or detach the layer entirely with the
const ExchangeCalendar::without_holidays(). DayPolicy remains the caller's
overlay above whatever a table carries, and it composes by tightening: a caller
can always make a trading day shorter and never longer. Implement DayPolicy, or construct a validated StaticDayPolicy from
hard-coded DayOverride records, then call
ExchangeCalendar::with_day_policy to create a PolicyCalendar. It applies
closed trade dates, early final closes, and late first opens to every
predicate, scan, trade-date, state, and candle query.
Policy dates are trade dates: for an ordinary wrapped session, closing Monday
removes the trading day that would have opened Sunday evening. CME's continuous
cryptocurrency weekend follows the operator's next-open-business-day rule
instead: closing Monday leaves the weekend trading open and assigns it to
Tuesday. Profiles without a final daily close—such as AlwaysOpen—have no
trade date and ignore the day-policy overlay rather than inventing one.
PolicyCalendar::hours_at intentionally returns the unmodified
sourced snapshot because the policy is a query overlay, not another static
profile.
For a small caller-owned table, no custom trait implementation is needed:
use NaiveDate;
use ;
let closed_date = from_ymd_opt.expect;
let overrides = ;
let policy = new.expect;
let calendar = calendar_for_market_hours_key
.with_day_policy;
The date above is an API example, not bundled operator data; callers remain responsible for the source and exact family/venue scope of every record.
Boundary clipping is not a complete holiday-session model. It cannot insert an
intraday pause/reopen or close only regular trading while an extended phase
continues. Those arrangements go through the exception-session layer, which
ships for caller-owned data alongside DayPolicy. Implement
SessionExceptionSource, or build a validated StaticSessionExceptions table,
then call ExchangeCalendar::with_session_exceptions:
use NaiveDate;
use ;
// A regular-only early close: extended trading continues past 13:00 local.
static BLOCKS: = ;
let half_day = from_ymd_opt.expect;
let first = from_ymd_opt.expect;
let last = from_ymd_opt.expect;
let records = ;
let table = new
.expect;
let calendar = calendar_for_exchange
.with_session_exceptions
.expect;
Each record is one venue-local trade date and is exactly one of known normal,
closed, or replaced — never two at once. Blocks state venue-local
seconds-since-midnight with end-exclusive closes, the same asymmetric DST bias
as normal profiles, and an explicit opening-day offset, so a Globex-style day
that opens the previous evening uses -1. A table publishes its audited
first/last trade dates, and a date outside that window reports
DateException::OutOfCoverage rather than silently reading as an ordinary
weekday. A table scoped to another CalendarSource is refused, not applied.
Precedence is fixed: the exception layer resolves the trading day, then a
DayPolicy overlays it exactly as it overlays a normal week. Two replacement
layers never compose. The contract, the coverage and finality requirements, and
the maintenance checklist for any exception dataset are in
Date exceptions and holiday calendars.
Best effort — validate before production use
Primary-sourced tables and dated revisions carry their citations beside the data and are
pinned by tests. Every non-synthetic current profile is source-supported within the product or
segment scope stated in the ledger. Rows labeled Primary have complete
January-2010-or-launch history at that scope; Partial rows explicitly identify the older
phase or onset that could not be dated. This crate is a best-effort model, not an authority:
exchanges amend hours on short notice, publish product-level exceptions, and run holiday
and half-day schedules; the built-in holiday tables carry those only for the
identities and windows the ledger's Holidays column names.
Supply boundary-level exceptions through DayPolicy when it can represent
them exactly, and multi-phase holiday schedules through
SessionExceptionSource; do not reduce a multi-phase holiday schedule to one
cutoff.
Before trading on
any venue's hours in production, have a human verify the profile against the exchange's
currently published schedule and the relevant contract specifications.
Design
This is a foundational leaf crate. It depends only on chrono + chrono-tz
(instant/zone arithmetic and the DST resolver) and serde (canonical string
serialization of public identities)—no logging facade, engine, transport,
adapter, async runtime, credential crate, or tokio.
Built-in MarketHours status/bound/candle queries and ExchangeCalendar
status/bound/trade-date/candle queries allocate nothing. is_open is
O(rules) for a fixed snapshot and O(rules + log revisions) for a
date-aware calendar. Session-bound, forward, candle, and trade-date queries
multiply that work by their documented bounded day scans; identity-aware
coalescing may inspect adjacent rule pieces.
ExchangeCalendar is Copy + Send + Sync + 'static; work performed inside a
caller's DayPolicy is outside that guarantee. The Criterion
calendar_queries benchmark records is_open, session_bounds, daily
candle_end, trade_date, and closed-gap session_state costs for
GlobexEquityIndex.
Boundaries & invariants
- UTC in, UTC out. Every timestamp argument and timestamp result is
DateTime<Utc>; the exchangeTzis an internal detail and callers never pass or receive local times. - Closes are end-exclusive. An instant equal to a close is closed. Relaxing this makes adjacent sessions overlap and every duration double-count at its boundary.
open_ssm >= close_ssmmeans the session wraps into the next local day. Equal endpoints encode one complete local-day span, so a Sunday18:00→18:00rule is one continuous session through Monday 18:00. Omit the rule to express no session. Any "is it open?" answer must therefore consult yesterday's rules as well as today's.- Opens bias earliest, closes bias latest. On an ambiguous fall-back hour both mappings are valid; the asymmetry keeps a session inclusive while its end-exclusive close lands on the true boundary, and a spring-forward gap snaps to the first instant after it. This is the one place a maintainer must not "simplify" to a single bias.
- Calendar bar starts come from sessions, not durations.
candle_startpairs a daily/weekly/monthly close with the first session open in that period, so a start can fall on the preceding civil day, month, or year. Probe a provider close marker atclose - 1ns. - The
Exchangematches are exhaustive inside the crate.hours_for_exchangeandExchange::as_strhave no catch-all arms, so a new variant forces a profile decision and a canonical name instead of silently inheriting defaults. The enum itself is#[non_exhaustive](likeMarketHoursKey), so venue additions are not breaking changes for dependents — match it with a wildcard arm, and enumerate viaExchange::ALL. - Always-open venues stay categorically separate. A 24×7 venue is a single
0..86400rule on all seven days withhas_daily_close/has_weekend_closebothfalse; it is never folded into the CME-style daily-break profiles. - One canonical name per identity, and it is stable.
ExchangeandMarketHoursKeyserialize assnake_casestrings in every Serde format and expose the same names throughas_str,Display, andFromStr; each also has anALLenumeration. String-keyed callers parse instead of pattern-matching ("nyse_arca".parse::<Exchange>()). Unrecognized input returnsParseExchangeErrororParseMarketHoursKeyError, never a silentExchange::Unknown. A rename that changes one of these strings breaks persisted data. Neither identity enum uses variant ordinals, so adding or removing a row cannot silently reinterpret another identity. - Normal week plus explicit overlays. The normal-week tables carry no
holiday, half-day, or product-level exception data; per-family holiday and
early-close tables carry it separately, as static date tables keyed by the
crate's own venue-local trade date, for the identities whose ledger rows name
a Holidays window.
DayPolicyand the validatedStaticDayPolicyhelper let a caller overlay sourced closed trade dates, early final closes, and late first opens above whatever those tables carry, without changinghours_at. Multi-phase exceptions are not approximated by that boundary API: they go throughSessionExceptionSourceandStaticSessionExceptions, which replace a whole trade date with an ordered block set and publish their own audited coverage window. Both overlay layers are caller-owned; verify contract specs before trading on a profile outside its explicitly stated scope. - No panics, and absence is
None. The public surface is total, and boundary queries (session_bounds*,next_session_after*,candle_start*/candle_end*,time_end_of_day) returnOption: a profile with no session of the requested kind in the bounded search horizon (a venue before its go-live date), or a zero-duration candle resolution, isNone— never a fabricated degenerate pair that could leak downstream as a real session. Predicates report closed/not-in-maintenance/closed-all-day. SessionRulehas a stated domain.SessionRule::new/validateenforceopen_ssm < 86_400,close_ssm <= 86_400, and at least one enabled weekday; every shipped table is fence-checked against the same domain. Equal endpoints are intentional complete-local-day rules, not empty intervals.
Testing
Pure and stateless, so the validation class is property/deterministic-fixture, not workload. Every test is an integration test over the public surface: the crate exposes nothing to tests that callers do not also get (see Architecture: Tests).
tests/venue_sessions.rsandtests/venue_sessions/— a thin harness over focused futures, equities, candle, wrap, bounds, and correction modules. Together they pin published opens, end-exclusive closes, overnight wraps, maintenance gaps, weekend boundaries, always-open venues, serde forms, and source-cited data corrections.tests/futures_family_boundaries.rsandtests/futures_family_boundaries/— a thin harness over dated-boundary fixtures split by venue family (CME Nikkei, CME family queues, ICE, SGX equity index). Each assertion probes an instant on one side of a sourced cutover, at venue-local midnight for the revision and to the second for the session open, so a mis-keyed revision or a one-minute encoding slip fails here.tests/apac_equities.rsandtests/apac_equities/— a thin integration harness with separate modules for current boundaries, regional amendment history, and APAC bulk/name contracts across all 17 cash-equity venues.tests/global_equities.rsandtests/global_equities/— a thin harness over current baselines, amendment history, and the global bulk/name contract for TSX, Borsa Istanbul, JSE, Tadawul, B3, and BMV.tests/schedule_documentation.rsandtests/schedule_documentation/— a thin harness over contracts that keep all 97Exchangerows (96 non-synthetic plusUnknown) and 52MarketHoursKeyrows (51 operator-derived plusAlwaysOpen) in canonical order; validates their review metadata and owner/source links; requires both current and notice/evidence channels for every source set; rejects orphaned source sets; and prevents the README freshness date from drifting from the ledger.tests/seasonal_calendars.rsandtests/seasonal_calendars/— a thin integration harness split into B3, BMV, transition-scan, candle/weekend, Chrono-edge, and compatibility-contract modules. The contracts include all-fixed-venueMarketHours/ExchangeCalendarparity and a daily history scan proving venue time zones remain stable.tests/calendar_policies.rsandtests/calendar_value_traits.rs— pin date-aware key parity, trade-date/state classification, caller policy overlays, bounded all-closed scans, and the calendar's value/thread traits.tests/support/— fixture construction shared by integration targets; it uses only the public crate surface and provides no test-only access to production internals.tests/no_session_contract.rs— theNonecontract for profiles with no rules.tests/rule_validation.rs— theSessionRuledomain: whatnew/validateaccept and reject.tests/contract/session_invariants.rsandtests/contract/session_invariants/— a thin, explicitly configured harness over handwritten identity/history expectations and focused property modules. A fixed-seedsplitmix64sweep plus pinned DST fixtures cover totality, determinism, maintenance, ordered bounds, advancing session walks, and the all-venue cross-query fence. The production tables are never imported into these expectations.src/lib.rsdoctest — the Quick start example above.
The CI gate, in order — cargo fmt --all --check, cargo clippy --all-targets -- -D warnings
(clippy pedantic plus the panic-family and determinism restriction lints, configured in
Cargo.toml and clippy.toml), cargo nextest run, cargo test --doc, cargo doc with
warnings denied, and cargo deny check for dependency licences and advisories. A second job
builds on the declared MSRV so that floor is exercised rather than asserted. The build
toolchain is pinned in rust-toolchain.toml. Run everything the quality job runs:
&& && && && RUSTDOCFLAGS="-D warnings" &&
The MSRV job needs a second toolchain, so it is a separate command:
License
MIT-0 (MIT No Attribution): use, copy, modify, and redistribute freely, with no attribution required and no warranty of any kind — see the best-effort disclaimer above before trading on these tables.