Skip to main content

ctrader_connector/open_api/
history.rs

1//! Deals, orders and changes of the balance of an account inside a range of time.
2//!
3//! ```no_run
4//! use std::time::Duration;
5//!
6//! use ctrader_connector::common::config::ConfigurationOpenApi;
7//! use ctrader_connector::common::time::{TimeRange, Timestamp};
8//! use ctrader_connector::open_api::client::OpenApiClient;
9//!
10//! # async fn run() -> Result<(), ctrader_connector::common::errors::ConnectorError> {
11//! let client = OpenApiClient::connect(ConfigurationOpenApi::from_env()?).await?;
12//! client.authorise_application().await?;
13//! let account = client.accounts().await?[0].id;
14//! client.authorise_account(account).await?;
15//! let day = TimeRange::ending_at(Timestamp::now(), Duration::from_secs(86_400));
16//! for deal in client.deal_history(account, day).await? {
17//!     println!("{} {:?} {}", deal.id, deal.side, deal.filled_volume);
18//! }
19//! # Ok(())
20//! # }
21//! ```
22
23use std::collections::BTreeMap;
24use std::time::Duration;
25
26use rust_decimal::Decimal;
27
28use crate::common::errors::{ConnectorError, ValueError};
29use crate::common::ids::{AccountId, CashFlowId};
30use crate::common::time::{TimeRange, Timestamp};
31use crate::open_api::client::OpenApiClient;
32use crate::open_api::messages::{
33    ProtoOaCashFlowHistoryListReq, ProtoOaChangeBalanceType, ProtoOaDealListReq,
34    ProtoOaDepositWithdraw, ProtoOaOrderListReq,
35};
36use crate::open_api::trading::{Deal, Order, money};
37
38const MAX_RANGE_MILLIS: i64 = 604_800_000;
39
40const HISTORY_TIMESTAMP: &str = "end of the range of history";
41const CASH_FLOW_KIND: &str = "kind of cash flow";
42
43/// Longest range of time the server accepts in one request for deals, orders or cash flow.
44pub const MAX_HISTORY_RANGE: Duration = Duration::from_millis(MAX_RANGE_MILLIS.unsigned_abs());
45
46/// Parts of a range of time still to be asked for, each short enough for one request.
47///
48/// The server includes both ends of a request and refuses one whose ends are the same
49/// millisecond, so a part that is a single millisecond is asked for together with the
50/// millisecond before it, or after it at the Unix epoch.
51#[derive(Debug)]
52pub(crate) struct Windows {
53    pending: Vec<(i64, i64)>,
54}
55
56impl Windows {
57    /// Cuts the range into parts of at most [`MAX_HISTORY_RANGE`], latest first.
58    pub(crate) fn new(range: TimeRange) -> Result<Self, ValueError> {
59        let (from, to) = (range.from().as_millis(), range.to().as_millis());
60        let mut pending = Vec::new();
61        let mut start = from;
62        loop {
63            let end = start.saturating_add(MAX_RANGE_MILLIS).min(to);
64            pending.push(widened(start, end)?);
65            if end >= to {
66                break;
67            }
68            start = end.saturating_add(1);
69        }
70        Ok(Self { pending })
71    }
72
73    /// Returns the next part to ask for, as the two timestamps of the request.
74    pub(crate) fn next(&mut self) -> Option<(i64, i64)> {
75        self.pending.pop()
76    }
77
78    /// Replaces a part the server did not answer whole by its two halves, which share their
79    /// middle millisecond.
80    ///
81    /// Fails with [`ConnectorError::Incomplete`] when the part is too short to be halved.
82    pub(crate) fn split(&mut self, (from, to): (i64, i64)) -> Result<(), ConnectorError> {
83        let middle = to
84            .checked_sub(from)
85            .map(|length| length / 2)
86            .and_then(|half| from.checked_add(half))
87            .filter(|middle| from < *middle && *middle < to);
88        let Some(middle) = middle else {
89            return Err(ConnectorError::Incomplete {
90                from: Timestamp::from_millis(from)?,
91                to: Timestamp::from_millis(to)?,
92            });
93        };
94        self.pending.push((from, middle));
95        self.pending.push((middle, to));
96        Ok(())
97    }
98}
99
100/// Tells whether a moment of last update, when the server states one, lies inside the range.
101fn inside(range: TimeRange, updated: Option<i64>) -> bool {
102    updated.is_none_or(|at| range.from().as_millis() <= at && at <= range.to().as_millis())
103}
104
105fn widened(start: i64, end: i64) -> Result<(i64, i64), ValueError> {
106    if start < end {
107        return Ok((start, end));
108    }
109    match start.checked_sub(1).filter(|before| *before >= 0) {
110        Some(before) => Ok((before, end)),
111        None => end
112            .checked_add(1)
113            .map(|after| (start, after))
114            .ok_or(ValueError::OutOfRange {
115                kind: HISTORY_TIMESTAMP,
116            }),
117    }
118}
119
120macro_rules! cash_flow_kinds {
121    ($($(#[$doc:meta])* $name:ident => $wire:ident, $deposit:literal;)*) => {
122        /// Reason the balance of an account changed outside of trading.
123        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
124        #[non_exhaustive]
125        pub enum CashFlowKind {
126            $($(#[$doc])* $name,)*
127        }
128
129        impl CashFlowKind {
130            fn from_wire(raw: i32) -> Result<Self, ValueError> {
131                match ProtoOaChangeBalanceType::try_from(raw) {
132                    $(Ok(ProtoOaChangeBalanceType::$wire) => Ok(Self::$name),)*
133                    Err(_) => Err(ValueError::OutOfRange { kind: CASH_FLOW_KIND }),
134                }
135            }
136
137            /// Tells whether the change adds money to the account; otherwise it takes money
138            /// from it.
139            #[must_use]
140            pub const fn is_deposit(self) -> bool {
141                match self {
142                    $(Self::$name => $deposit,)*
143                }
144            }
145        }
146    };
147}
148
149cash_flow_kinds! {
150    /// Money paid in.
151    Deposit => BalanceDeposit, true;
152    /// Money paid out.
153    Withdraw => BalanceWithdraw, false;
154    /// Commission of a strategy received from an account of the same broker.
155    DepositStrategyCommissionInner => BalanceDepositStrategyCommissionInner, true;
156    /// Commission of a strategy paid to an account of the same broker.
157    WithdrawStrategyCommissionInner => BalanceWithdrawStrategyCommissionInner, false;
158    /// Commissions received as an introducing broker.
159    DepositIbCommissions => BalanceDepositIbCommissions, true;
160    /// Share of commissions passed on by an introducing broker.
161    WithdrawIbSharedPercentage => BalanceWithdrawIbSharedPercentage, false;
162    /// Share of commissions received from a sub introducing broker.
163    DepositIbSharedPercentageFromSubIb => BalanceDepositIbSharedPercentageFromSubIb, true;
164    /// Share of commissions received from the broker.
165    DepositIbSharedPercentageFromBroker => BalanceDepositIbSharedPercentageFromBroker, true;
166    /// Rebate received.
167    DepositRebate => BalanceDepositRebate, true;
168    /// Rebate taken back.
169    WithdrawRebate => BalanceWithdrawRebate, false;
170    /// Commission of a strategy received from an account of another broker.
171    DepositStrategyCommissionOuter => BalanceDepositStrategyCommissionOuter, true;
172    /// Commission of a strategy paid to an account of another broker.
173    WithdrawStrategyCommissionOuter => BalanceWithdrawStrategyCommissionOuter, false;
174    /// Compensation of a bonus taken from the account.
175    WithdrawBonusCompensation => BalanceWithdrawBonusCompensation, false;
176    /// Share of commissions passed on to the broker.
177    WithdrawIbSharedPercentageToBroker => BalanceWithdrawIbSharedPercentageToBroker, false;
178    /// Dividends received.
179    DepositDividends => BalanceDepositDividends, true;
180    /// Dividends charged.
181    WithdrawDividends => BalanceWithdrawDividends, false;
182    /// Charge for a guaranteed stop loss.
183    WithdrawGslCharge => BalanceWithdrawGslCharge, false;
184    /// Charge for holding a position over the rollover.
185    WithdrawRollover => BalanceWithdrawRollover, false;
186    /// Bonus that cannot be paid out, added.
187    DepositNonwithdrawableBonus => BalanceDepositNonwithdrawableBonus, true;
188    /// Bonus that cannot be paid out, removed.
189    WithdrawNonwithdrawableBonus => BalanceWithdrawNonwithdrawableBonus, false;
190    /// Swap received.
191    DepositSwap => BalanceDepositSwap, true;
192    /// Swap charged.
193    WithdrawSwap => BalanceWithdrawSwap, false;
194    /// Management fee received.
195    DepositManagementFee => BalanceDepositManagementFee, true;
196    /// Management fee paid.
197    WithdrawManagementFee => BalanceWithdrawManagementFee, false;
198    /// Performance fee received.
199    DepositPerformanceFee => BalanceDepositPerformanceFee, true;
200    /// Money moved out for a subaccount.
201    WithdrawForSubaccount => BalanceWithdrawForSubaccount, false;
202    /// Money moved in to a subaccount.
203    DepositToSubaccount => BalanceDepositToSubaccount, true;
204    /// Money moved out of a subaccount.
205    WithdrawFromSubaccount => BalanceWithdrawFromSubaccount, false;
206    /// Money moved in from a subaccount.
207    DepositFromSubaccount => BalanceDepositFromSubaccount, true;
208    /// Fee for copying a strategy.
209    WithdrawCopyFee => BalanceWithdrawCopyFee, false;
210    /// Fee for an account that does not trade.
211    WithdrawInactivityFee => BalanceWithdrawInactivityFee, false;
212    /// Transfer received from another account.
213    DepositTransfer => BalanceDepositTransfer, true;
214    /// Transfer sent to another account.
215    WithdrawTransfer => BalanceWithdrawTransfer, false;
216    /// Bonus turned into money of the account.
217    DepositConvertedBonus => BalanceDepositConvertedBonus, true;
218    /// Money added to bring a negative balance back to zero.
219    DepositNegativeBalanceProtection => BalanceDepositNegativeBalanceProtection, true;
220}
221
222/// One change of the balance of an account outside of trading, such as a deposit or a
223/// withdrawal.
224#[derive(Debug, Clone, PartialEq, Eq, Hash)]
225#[non_exhaustive]
226pub struct CashFlow {
227    /// Identifier of the change in the history of the balance.
228    pub id: CashFlowId,
229    /// Reason of the change.
230    pub kind: CashFlowKind,
231    /// Size of the change in the deposit currency; [`CashFlowKind::is_deposit`] tells its
232    /// direction.
233    pub amount: Decimal,
234    /// Balance after the change, in the deposit currency.
235    pub balance: Decimal,
236    /// Equity after the change, in the deposit currency.
237    pub equity: Option<Decimal>,
238    /// Moment of the change.
239    pub at: Timestamp,
240    /// Note the broker attached.
241    pub note: Option<String>,
242    /// Version of the balance after the change.
243    pub balance_version: Option<i64>,
244}
245
246impl TryFrom<ProtoOaDepositWithdraw> for CashFlow {
247    type Error = ValueError;
248
249    fn try_from(change: ProtoOaDepositWithdraw) -> Result<Self, Self::Error> {
250        let digits = change.money_digits;
251        Ok(Self {
252            id: CashFlowId::new(change.balance_history_id)?,
253            kind: CashFlowKind::from_wire(change.operation_type)?,
254            amount: money(change.delta, digits)?,
255            balance: money(change.balance, digits)?,
256            equity: change.equity.map(|raw| money(raw, digits)).transpose()?,
257            at: Timestamp::from_millis(change.change_balance_timestamp)?,
258            note: change.external_note,
259            balance_version: change.balance_version,
260        })
261    }
262}
263
264impl OpenApiClient {
265    /// Fetches the deals of an authorised account inside a range of time, oldest first.
266    ///
267    /// The server selects a deal by the moment it was last updated, which for a deal is the
268    /// moment it was created, and includes both ends of the range. The server refuses a request
269    /// whose ends are the same, so a single millisecond is asked for together with the one
270    /// before it, and what belongs to that other millisecond is left out.
271    ///
272    /// A range longer than [`MAX_HISTORY_RANGE`] is fetched with several requests, each of
273    /// which counts against the limit for historical data. The server sends a limited number
274    /// of deals per request; a part of the range it reports to hold more is halved and asked
275    /// for again, until every part is answered whole. Every deal of the range is thus
276    /// returned, and returned once.
277    ///
278    /// # Errors
279    ///
280    /// Returns [`ConnectorError::Server`] when the server refuses a request,
281    /// [`ConnectorError::Value`] when a deal carries a value out of range,
282    /// [`ConnectorError::Incomplete`] when the server reports more deals than it sends for a
283    /// part too short to be halved, in which case no part of the range is returned, and the
284    /// errors of [`Connection::request`](crate::open_api::connection::Connection::request)
285    /// otherwise.
286    pub async fn deal_history(
287        &self,
288        account: AccountId,
289        range: TimeRange,
290    ) -> Result<Vec<Deal>, ConnectorError> {
291        let mut windows = Windows::new(range)?;
292        let mut deals = BTreeMap::new();
293        while let Some((from, to)) = windows.next() {
294            let request = ProtoOaDealListReq {
295                payload_type: None,
296                ctid_trader_account_id: account.get(),
297                from_timestamp: from,
298                to_timestamp: to,
299                max_rows: None,
300            };
301            let response = self.connection().request(&request).await?;
302            if response.has_more {
303                windows.split((from, to))?;
304                continue;
305            }
306            for deal in response.deal {
307                let updated = deal.utc_last_update_timestamp;
308                let deal = Deal::try_from(deal)?;
309                if inside(range, updated) {
310                    deals.insert(deal.id, deal);
311                }
312            }
313        }
314        let mut deals: Vec<Deal> = deals.into_values().collect();
315        deals.sort_by_key(|deal| (deal.executed, deal.id));
316        Ok(deals)
317    }
318
319    /// Fetches the orders of an authorised account that were last updated inside a range of
320    /// time, in the order of their last update, oldest first.
321    ///
322    /// The orders are the ones in force and the ones that are filled, cancelled, expired or
323    /// refused. Both ends of the range are included, and the range is cut into requests and
324    /// answered whole as described for [`OpenApiClient::deal_history`].
325    ///
326    /// # Errors
327    ///
328    /// Fails like [`OpenApiClient::deal_history`].
329    pub async fn order_history(
330        &self,
331        account: AccountId,
332        range: TimeRange,
333    ) -> Result<Vec<Order>, ConnectorError> {
334        let mut windows = Windows::new(range)?;
335        let mut orders = BTreeMap::new();
336        while let Some((from, to)) = windows.next() {
337            let request = ProtoOaOrderListReq {
338                payload_type: None,
339                ctid_trader_account_id: account.get(),
340                from_timestamp: from,
341                to_timestamp: to,
342            };
343            let response = self.connection().request(&request).await?;
344            if response.has_more {
345                windows.split((from, to))?;
346                continue;
347            }
348            for order in response.order {
349                let updated = order.utc_last_update_timestamp;
350                let order = Order::try_from(order)?;
351                if inside(range, updated) {
352                    orders.insert(order.id, order);
353                }
354            }
355        }
356        let mut orders: Vec<Order> = orders.into_values().collect();
357        orders.sort_by_key(|order| (order.updated, order.id));
358        Ok(orders)
359    }
360
361    /// Fetches the deposits, withdrawals and other changes of the balance of an authorised
362    /// account outside of trading that were made inside a range of time, oldest first.
363    ///
364    /// A range longer than [`MAX_HISTORY_RANGE`] is fetched with several requests, each of
365    /// which counts against the limit for historical data. A single millisecond is asked for
366    /// together with the one before it, and what belongs to that other millisecond is left
367    /// out.
368    ///
369    /// # Errors
370    ///
371    /// Returns [`ConnectorError::Server`] when the server refuses a request,
372    /// [`ConnectorError::Value`] when a change carries a value out of range, in which case no
373    /// part of the range is returned, and the errors of
374    /// [`Connection::request`](crate::open_api::connection::Connection::request) otherwise.
375    pub async fn cash_flow_history(
376        &self,
377        account: AccountId,
378        range: TimeRange,
379    ) -> Result<Vec<CashFlow>, ConnectorError> {
380        let mut windows = Windows::new(range)?;
381        let mut changes = BTreeMap::new();
382        while let Some((from, to)) = windows.next() {
383            let request = ProtoOaCashFlowHistoryListReq {
384                payload_type: None,
385                ctid_trader_account_id: account.get(),
386                from_timestamp: from,
387                to_timestamp: to,
388            };
389            let response = self.connection().request(&request).await?;
390            for change in response.deposit_withdraw {
391                let change = CashFlow::try_from(change)?;
392                if inside(range, Some(change.at.as_millis())) {
393                    changes.insert(change.id, change);
394                }
395            }
396        }
397        let mut changes: Vec<CashFlow> = changes.into_values().collect();
398        changes.sort_by_key(|change| (change.at, change.id));
399        Ok(changes)
400    }
401}
402
403#[cfg(test)]
404mod tests {
405    use std::time::Duration;
406
407    use super::{CashFlow, CashFlowKind, MAX_HISTORY_RANGE, MAX_RANGE_MILLIS, Windows, widened};
408    use crate::common::errors::{ConnectorError, ValueError};
409    use crate::common::time::{TimeRange, Timestamp};
410    use crate::open_api::messages::{
411        ProtoOaChangeBalanceType, ProtoOaDepositWithdraw, ProtoOaExecutionEvent,
412    };
413    use crate::open_api::trading::{Execution, ExecutionType};
414
415    fn range(from: i64, to: i64) -> TimeRange {
416        let at = |millis| Timestamp::from_millis(millis).expect("timestamp");
417        TimeRange::new(at(from), at(to)).expect("range")
418    }
419
420    fn all(mut windows: Windows) -> Vec<(i64, i64)> {
421        std::iter::from_fn(|| windows.next()).collect()
422    }
423
424    #[test]
425    fn range_is_cut_into_parts_the_server_accepts_latest_first() {
426        assert_eq!(MAX_HISTORY_RANGE, Duration::from_secs(7 * 86_400));
427        let week = MAX_RANGE_MILLIS;
428        assert_eq!(
429            all(Windows::new(range(10, 20)).expect("windows")),
430            [(10, 20)]
431        );
432        assert_eq!(
433            all(Windows::new(range(10, 10 + week)).expect("windows")),
434            [(10, 10 + week)]
435        );
436        assert_eq!(
437            all(Windows::new(range(10, 12 + 2 * week)).expect("windows")),
438            [
439                (11 + 2 * week, 12 + 2 * week),
440                (11 + week, 11 + 2 * week),
441                (10, 10 + week)
442            ]
443        );
444    }
445
446    #[test]
447    fn part_of_one_millisecond_is_widened_to_two() {
448        let week = MAX_RANGE_MILLIS;
449        assert_eq!(
450            all(Windows::new(range(10, 10)).expect("windows")),
451            [(9, 10)]
452        );
453        assert_eq!(all(Windows::new(range(0, 0)).expect("windows")), [(0, 1)]);
454        assert_eq!(
455            all(Windows::new(range(10, 11 + week)).expect("windows")),
456            [(10 + week, 11 + week), (10, 10 + week)]
457        );
458        assert_eq!(
459            widened(-5, -5),
460            Ok((-5, -4)),
461            "a moment before the epoch is widened forwards"
462        );
463        assert_eq!(
464            widened(i64::MAX, i64::MAX).map_err(|error| error.to_string()),
465            Ok((i64::MAX - 1, i64::MAX))
466        );
467        assert_eq!(
468            widened(-1, i64::MAX).map_err(|error| error.to_string()),
469            Ok((-1, i64::MAX))
470        );
471        assert!(matches!(
472            widened(i64::MIN, i64::MIN),
473            Ok((i64::MIN, end)) if end == i64::MIN + 1
474        ));
475    }
476
477    #[test]
478    fn part_is_halved_until_it_is_too_short() {
479        let mut windows = Windows::new(range(10, 20)).expect("windows");
480        let whole = windows.next().expect("window");
481        windows.split(whole).expect("halves");
482        assert_eq!(windows.next(), Some((15, 20)));
483        assert_eq!(windows.next(), Some((10, 15)));
484        windows.split((10, 12)).expect("halves");
485        assert_eq!(all(windows), [(11, 12), (10, 11)]);
486        let mut windows = Windows::new(range(10, 11)).expect("windows");
487        let at = |millis| Timestamp::from_millis(millis).expect("timestamp");
488        assert_eq!(
489            windows.split((10, 11)),
490            Err(ConnectorError::Incomplete {
491                from: at(10),
492                to: at(11)
493            })
494        );
495        assert!(windows.split((i64::MIN, i64::MAX)).is_err());
496    }
497
498    #[test]
499    fn every_kind_of_cash_flow_of_the_wire_is_known_with_its_direction() {
500        let mut known = 0;
501        for raw in -1..=64 {
502            match ProtoOaChangeBalanceType::try_from(raw) {
503                Ok(wire) => {
504                    let kind = CashFlowKind::from_wire(raw).expect("kind");
505                    assert_eq!(
506                        kind.is_deposit(),
507                        wire.as_str_name().starts_with("BALANCE_DEPOSIT"),
508                        "{}",
509                        wire.as_str_name()
510                    );
511                    known += 1;
512                }
513                Err(_) => assert_eq!(
514                    CashFlowKind::from_wire(raw),
515                    Err(ValueError::OutOfRange {
516                        kind: "kind of cash flow"
517                    })
518                ),
519            }
520        }
521        assert_eq!(known, 35);
522        assert_eq!(CashFlowKind::from_wire(1), Ok(CashFlowKind::Withdraw));
523    }
524
525    #[test]
526    fn execution_event_carries_the_cash_flow_it_reports() {
527        let change = ProtoOaDepositWithdraw {
528            operation_type: 0,
529            balance_history_id: 77,
530            balance: 150_000,
531            delta: 100_000,
532            change_balance_timestamp: 1_000,
533            external_note: Some("first deposit".to_owned()),
534            balance_version: Some(3),
535            equity: Some(150_100),
536            money_digits: Some(2),
537        };
538        let event = ProtoOaExecutionEvent {
539            ctid_trader_account_id: 101,
540            execution_type: 10,
541            deposit_withdraw: Some(change.clone()),
542            ..ProtoOaExecutionEvent::default()
543        };
544        let execution = Execution::try_from(event).expect("execution");
545        assert_eq!(execution.kind, ExecutionType::DepositWithdraw);
546        let flow = execution.cash_flow.expect("cash flow");
547        assert_eq!(flow.id.get(), 77);
548        assert_eq!(flow.kind, CashFlowKind::Deposit);
549        assert_eq!(flow.amount.to_string(), "1000.00");
550        assert_eq!(flow.balance.to_string(), "1500.00");
551        assert_eq!(
552            flow.equity.map(|equity| equity.to_string()).as_deref(),
553            Some("1501.00")
554        );
555        assert_eq!(flow.at.as_millis(), 1_000);
556        assert_eq!(flow.note.as_deref(), Some("first deposit"));
557        assert_eq!(flow.balance_version, Some(3));
558        assert!(
559            CashFlow::try_from(ProtoOaDepositWithdraw {
560                balance_history_id: 0,
561                ..change
562            })
563            .is_err()
564        );
565    }
566}