ctrader_connector/lib.rs
1//! Client library for the cTrader Open API and the cTrader FIX 4.4 API.
2//!
3//! # Overview
4//!
5//! The crate talks to a cTrader server over either of its two programming interfaces:
6//!
7//! - [`open_api`]: Protobuf messages over TLS. One connection serves an application and
8//! every trading account its access token grants: symbols, prices, depth, bars, ticks,
9//! orders, positions, history and account data.
10//! - [`fix`]: FIX 4.4. One trading account has a quote session for prices and a trade
11//! session for orders, each a connection of its own.
12//!
13//! The [`common`] module holds what both share: [configuration](common::config),
14//! [errors](common::errors), [typed identifiers](common::ids),
15//! [exact prices and volumes](common::decimals) and [timestamps](common::time). Prices,
16//! volumes and money are decimals throughout the typed API, never floats; the generated
17//! Protobuf messages of the Open API keep the types of the wire.
18//!
19//! Both clients are asynchronous and run on a tokio runtime the application provides.
20//!
21//! # Features
22//!
23//! No feature is on by default.
24//!
25//! | Feature | Enables |
26//! |---|---|
27//! | `open-api` | The [`open_api`] module. |
28//! | `fix` | The [`fix`] module. |
29//! | `logging` | Diagnostic events of the Open API connection, emitted through `tracing`. |
30//!
31//! # Quick start
32//!
33//! Both clients are built from a configuration, which is either read from the environment
34//! or put together with a builder. The Open API targets the demo environment unless the
35//! live one is asked for; a FIX configuration names its host. The variables are listed in
36//! the documentation of each protocol module.
37//!
38//! ## Open API
39//!
40//! ```no_run
41//! # #[cfg(feature = "open-api")]
42//! # async fn run() -> Result<(), ctrader_connector::common::errors::ConnectorError> {
43//! use ctrader_connector::common::config::ConfigurationOpenApi;
44//! use ctrader_connector::open_api::client::OpenApiClient;
45//!
46//! let client = OpenApiClient::connect(ConfigurationOpenApi::from_env()?).await?;
47//! client.authorise_application().await?;
48//! let accounts = client.accounts().await?;
49//! if let Some(account) = accounts.iter().find(|account| !account.is_live) {
50//! client.authorise_account(account.id).await?;
51//! let trader = client.trader(account.id).await?;
52//! println!("balance: {} {}", trader.balance, trader.currency);
53//! }
54//! client.shutdown().await;
55//! # Ok(())
56//! # }
57//! ```
58//!
59//! ## FIX
60//!
61//! ```no_run
62//! # #[cfg(feature = "fix")]
63//! # async fn run() -> Result<(), ctrader_connector::common::errors::ConnectorError> {
64//! use ctrader_connector::common::config::ConfigurationFix;
65//! use ctrader_connector::fix::client::FixClient;
66//! use ctrader_connector::fix::session::SessionKind;
67//!
68//! let quote = FixClient::connect(ConfigurationFix::from_env()?, SessionKind::Quote).await?;
69//! let securities = quote.securities().await?;
70//! if let Some(security) = securities.first() {
71//! let mut spots = quote.subscribe_spot(security.id).await?;
72//! let prices = spots.next().await?;
73//! println!("{}: {:?} / {:?}", security.name, prices.bid, prices.offer);
74//! spots.unsubscribe().await?;
75//! }
76//! quote.logout().await?;
77//! # Ok(())
78//! # }
79//! ```
80//!
81//! # Errors
82//!
83//! Every call of a client returns [`ConnectorError`](common::errors::ConnectorError), one
84//! family for both protocols. A configuration or a value that is refused before anything is
85//! sent returns a narrower error, such as
86//! [`ConfigError`](common::errors::ConfigError) or
87//! [`ValueError`](common::errors::ValueError), that converts into it. Each protocol module
88//! explains which of its variants call for
89//! which reaction; the one to know before trading is
90//! [`OutcomeUnknown`](common::errors::ConnectorError::OutcomeUnknown): an order is written
91//! to the wire at most once and is never sent again by this library.
92//!
93//! # Examples
94//!
95//! The `examples` directory of the repository holds one runnable program per group of
96//! requests, `examples/open_api` and `examples/fix`, each behind the feature of its
97//! protocol.
98
99pub mod common;
100
101#[cfg(feature = "fix")]
102pub mod fix;
103
104#[cfg(feature = "open-api")]
105pub mod open_api;
106
107#[cfg(test)]
108mod proto_text;
109
110/// Version of this crate as recorded in its manifest.
111pub const VERSION: &str = env!("CARGO_PKG_VERSION");
112
113#[cfg(test)]
114mod tests {
115 use super::VERSION;
116
117 #[test]
118 fn version_matches_the_manifest() {
119 let manifest = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/Cargo.toml"));
120 assert!(manifest.contains(&format!("version = \"{VERSION}\"")));
121 }
122}