Struct Candle 

pub struct Candle {
    pub close_time: DateTime<Utc>,
    pub open: Decimal,
    pub high: Decimal,
    pub low: Decimal,
    pub close: Decimal,
    pub volume: Option<Decimal>,
    pub trade_count: Option<u64>,
}

Normalised Barter OHLCV Candle model.

close_time contract

close_time is the exclusive end-of-period boundary of the candle:

close_time == open_time + interval

A candle aggregates the trades that fall in the half-open interval [close_time − interval, close_time) — i.e. trades with open_time ≤ ts < close_time. A trade landing exactly on close_time belongs to the next candle, so close_time equals the next candle’s open instant.

Two distinct caveats apply to the boundary — do not conflate them:

• Not session-aligned (daily/weekly/monthly): the boundary is the UTC period grid (day → next 00:00 UTC, etc.), not an exchange session close. The library has no session calendar.
• Variable-length calendar arithmetic (month/quarter/year only): these are nominal boundaries computed with calendar months (chrono Months), not fixed Durations. Daily and weekly are exact fixed durations in UTC (no DST), exact to the millisecond. The open_time + N months equality holds only when open_time is calendar-grid-aligned (e.g. a 1M candle opens on the 1st at 00:00 UTC); a non-aligned open day-clamps (Jan 31 + 1 month → Feb 28/29). Venue-supplied open times are always aligned, so clamping never arises in practice, but it is part of the contract for callers computing boundaries from arbitrary instants.

Candle deliberately carries neither open_time nor interval — recover them from the originating fetch request / subscription resolution (open_time ≡ close_time − interval). Range-computing producers derive close_time through close_time_from_open so the boundary is defined in exactly one place (the Massive WS path uses the venue-supplied boundary directly — see close_time_from_open for the full producer list).

Using a Candle with the engine

When wrapping a Candle into a MarketEvent for a consuming engine (live or backtest), set time_exchange to this close_time — it is the period-END instant, the only choice that avoids lookahead (see that field’s contract). The library’s own candle producers already do this.

Fields

close_time: DateTime<Utc>

open: Decimal

high: Decimal

low: Decimal

close: Decimal

volume: Option<Decimal>

Consolidated trade volume over the candle period, or None when the producer carries no volume for this instrument class.

None is a first-class “volume is unknown” fact, not zero: some feeds (e.g. spot FX candles) publish no consolidated volume at all. Encoding that absence as Some(0.0) would be a silent lie — a volume-derived feature would read a real, quiet zero rather than an explicit unknown. aggregate_candles propagates the absence: any None constituent makes the whole aggregated bucket None.

Serde contract

Plain Option semantics, with two consequences worth stating because they changed when this field became optional:

• An absent volume key now deserialises to None. It was previously a hard missing field error, so a truncated or hand-written record that used to be rejected is now accepted as “volume unknown”. Reject it explicitly if a producer of yours must always report one.
• A record persisted before the migration carries the fabricated "volume": 0 verbatim, and reads back as Some(0) — indistinguishable from a genuine zero-volume bar. This type cannot recover the distinction; re-fetch, or track the affected range out-of-band.

None serialises as "volume": null (the key is written, not skipped), so a round trip through JSON preserves absence rather than degrading it into the missing-key case above.

trade_count: Option<u64>

Number of trades in the candle period, or None when the producer does not report a trade count.

Same contract as volume throughout, including serde: None means “unknown”, never zero; any None constituent makes an aggregated bucket None; an absent key deserialises to None; and a pre-migration "trade_count": 0 still reads back as Some(0).

Trait Implementations

impl Clone for Candle

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Candle

impl Debug for Candle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Candle

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for Candle

impl From<Candle> for DataKind

fn from(value: Candle) -> Self

Converts to this type from the input type.

impl Hash for Candle

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Candle

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for Candle

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Candle

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Candle