Skip to main content

Crate ctrader_connector

Crate ctrader_connector 

Source
Expand description

Client library for the cTrader Open API and the cTrader FIX 4.4 API.

§Overview

The crate talks to a cTrader server over either of its two programming interfaces:

  • open_api: Protobuf messages over TLS. One connection serves an application and every trading account its access token grants: symbols, prices, depth, bars, ticks, orders, positions, history and account data.
  • fix: FIX 4.4. One trading account has a quote session for prices and a trade session for orders, each a connection of its own.

The common module holds what both share: configuration, errors, typed identifiers, exact prices and volumes and timestamps. Prices, volumes and money are decimals throughout the typed API, never floats; the generated Protobuf messages of the Open API keep the types of the wire.

Both clients are asynchronous and run on a tokio runtime the application provides.

§Features

No feature is on by default.

FeatureEnables
open-apiThe open_api module.
fixThe fix module.
loggingDiagnostic events of the Open API connection, emitted through tracing.

§Quick start

Both clients are built from a configuration, which is either read from the environment or put together with a builder. The Open API targets the demo environment unless the live one is asked for; a FIX configuration names its host. The variables are listed in the documentation of each protocol module.

§Open API

use ctrader_connector::common::config::ConfigurationOpenApi;
use ctrader_connector::open_api::client::OpenApiClient;

let client = OpenApiClient::connect(ConfigurationOpenApi::from_env()?).await?;
client.authorise_application().await?;
let accounts = client.accounts().await?;
if let Some(account) = accounts.iter().find(|account| !account.is_live) {
    client.authorise_account(account.id).await?;
    let trader = client.trader(account.id).await?;
    println!("balance: {} {}", trader.balance, trader.currency);
}
client.shutdown().await;

§FIX

use ctrader_connector::common::config::ConfigurationFix;
use ctrader_connector::fix::client::FixClient;
use ctrader_connector::fix::session::SessionKind;

let quote = FixClient::connect(ConfigurationFix::from_env()?, SessionKind::Quote).await?;
let securities = quote.securities().await?;
if let Some(security) = securities.first() {
    let mut spots = quote.subscribe_spot(security.id).await?;
    let prices = spots.next().await?;
    println!("{}: {:?} / {:?}", security.name, prices.bid, prices.offer);
    spots.unsubscribe().await?;
}
quote.logout().await?;

§Errors

Every call of a client returns ConnectorError, one family for both protocols. A configuration or a value that is refused before anything is sent returns a narrower error, such as ConfigError or ValueError, that converts into it. Each protocol module explains which of its variants call for which reaction; the one to know before trading is OutcomeUnknown: an order is written to the wire at most once and is never sent again by this library.

§Examples

The examples directory of the repository holds one runnable program per group of requests, examples/open_api and examples/fix, each behind the feature of its protocol.

Modules§

common
Pieces shared by every protocol: configuration, errors, typed identifiers, exact values and timestamps.
fix
Client for the cTrader FIX 4.4 API.
open_api
Client for the cTrader Open API, which exchanges Protobuf messages over TLS.

Constants§

VERSION
Version of this crate as recorded in its manifest.