ctrader-connector 0.3.10

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

ctrader-connector

A Rust library for the cTrader Open API (Protobuf over TLS) and the cTrader FIX 4.4 API: connection and authorisation, market data, trading and account data.

In the typed API prices, volumes and money are exact decimals, never floats; the generated Protobuf messages in open_api::messages keep the types of the wire. An order is written to the wire at most once and is never sent again by the library.

Features

No feature is on by default.

Feature Enables
open-api The Open API client: application and account authorisation, token refresh, symbols, spot quotes, depth, trendbars, ticks, orders and positions, reconcile, execution events, trader details, deal and order history, margin calls and cash flow.
fix The FIX 4.4 client: quote session (security list, spot prices, depth) and trade session (orders, replacement, cancellation, order status, mass status, positions), with reconnection.
logging Diagnostic events of the Open API connection through tracing.

Requirements

  • Rust 1.86 or later (the minimum supported version), edition 2024.
  • A tokio runtime in the calling application.

Use

The crate is a library. Add it to an application with the protocol features needed:

[dependencies]
ctrader-connector = { version = "0.3", features = ["open-api", "fix"] }

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?;
for account in client.accounts().await? {
    client.authorise_account(account.id).await?;
}
client.shutdown().await;

One connection serves the application and every account of the access token. The connection sends heartbeats, keeps within the request limits of the server, reconnects after a loss and restores authorisations and subscriptions.

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?;
quote.logout().await?;

An account has a quote session and a trade session, each a client of its own. A session answers heartbeats, closes gaps in the sequence numbers and logs on again after a loss. What happens to a message it cannot use depends on the case: it is reported or not, counted or not, answered with a reject (3), asked for again or dropped, or the connection ends. The table "Messages that cannot be used" in the module documentation of fix holds every case and the tags of every reject. A business message reject (j) is never sent: the server refuses one with a reject and closes the connection, so FixClient::send refuses one before anything is written.

The module documentation covers configuration, connection lifecycle, error handling, streams, rate limits, logging, testing and protocol facts for each protocol:

cargo doc --all-features --no-deps --open

Environment variables

Both clients can be configured from the environment. Values are secrets or account details and belong in no file under version control.

Variable Required Meaning
BROKER_CLIENT_ID Open API Client identifier of the application.
BROKER_CLIENT_SECRET Open API Client secret of the application.
BROKER_ACCESS_TOKEN Open API Access token that grants the trading accounts.
BROKER_REFRESH_TOKEN no Refresh token; needed to refresh the pair.
BROKER_ENVIRONMENT no demo or live; demo when absent.
BROKER_DEMO_HOST no Host of the demo environment in place of the default one.
BROKER_TOKEN_URL no Token endpoint in place of the default one.
BROKER_FIX_HOST FIX Host of the FIX sessions.
BROKER_FIX_SENDER_COMP_ID FIX Sender identifier of the sessions.
BROKER_FIX_USERNAME FIX User name of the sessions.
BROKER_FIX_PASSWORD FIX Password of the sessions.
BROKER_FIX_QUOTE_PORT no TLS port of the quote session; 5211 when absent.
BROKER_FIX_TRADE_PORT no TLS port of the trade session; 5212 when absent.
BROKER_FIX_TARGET_COMP_ID no Target identifier; CSERVER when absent.
BROKER_ENV_FILE live tests of the Open API Absolute path of the file that holds the token pair as export lines; the live tests that use the Open API (open_api_live, and fix_live_trading for its read-back) read the pair from it, and the refresh test writes the new pair back. fix_live does not use it. The token refresh example needs it when asked to rotate.
BROKER_EXAMPLE_SYMBOL no Symbol the examples work with; BTCUSD when absent.
BROKER_EXAMPLE_QUANTITY no Quantity the FIX trading examples order, in units; 0.01 when absent.
BROKER_EXAMPLE_ROTATE no Set to 1, true or yes to let the token refresh example rotate the pair.
BROKER_EXAMPLE_MARKET no Set to 1, true or yes to let the FIX order example also trade at market.
BROKER_EXAMPLE_ALLOW_LIVE no Lets the examples leave the demo environment: read-only for the examples that place no order, yes for every example and for rotating the token pair. Absent or any other value: demo only.

Examples

One runnable program per group of requests, each behind the feature of its protocol:

examples/
├── open_api/
│   ├── connect.rs         connect and authorise
│   ├── token_refresh.rs   token pair; rotates only when asked to
│   ├── symbols.rs         assets, symbols and trading details
│   ├── quotes.rs          spot quotes
│   ├── depth.rs           market depth
│   ├── trendbars.rs       historical and live bars
│   ├── ticks.rs           tick history
│   ├── trading.rs         market, limit, stop, stop-limit, amend, cancel, close
│   ├── reconcile.rs       open positions and waiting orders
│   ├── executions.rs      execution events
│   ├── trader.rs          account details
│   ├── history.rs         deal and order history
│   └── margin.rs          margin calls and cash flow
├── fix/
│   ├── spot.rs            spot prices of the quote session
│   ├── depth.rs           depth of the quote session
│   ├── securities.rs      security list
│   ├── orders.rs          limit order: place, replace, cancel; market on request
│   ├── reports.rs         order status, mass status and positions
│   └── reconnect.rs       recovery after a lost connection
└── support/               pieces the examples share; guard.rs is the demo guard

An example is named after its protocol and its file:

cargo run --example open_api_connect --features open-api
cargo run --example fix_spot --features fix

Every example reads its configuration from the environment, prints a short result without secrets and exits with a non-zero status and a message that names the cause on failure, with the kind of the error when the library reported it. The trading examples run against a demo account, order the smallest volume, place waiting orders far from the market and remove what they created.

Every example, the read-only ones included, takes its configuration and its client from one guard, examples/support/guard.rs, which checks the configuration before any connection is opened. The guard is an allowlist:

  • an Open API example runs when BROKER_ENVIRONMENT is demo or absent and the host is demo.ctraderapi.com;
  • a FIX example runs when BROKER_FIX_SENDER_COMP_ID starts with demo., one label of BROKER_FIX_HOST has the part demo and no label has a part that starts with live; the parts of a label are separated by -, demo is matched in lower case only and live in any case.

Anything else is refused unless BROKER_EXAMPLE_ALLOW_LIVE permits it: read-only lets the examples that place no order leave demo, yes lets every example leave it, the trading ones included, and any other value permits nothing. Outside demo the token refresh example rotates the pair only under yes; read-only lets it check the pair and no more. Outside demo an Open API example works with the first account of the environment it connects to.

The manifest lists every example and turns the discovery of examples off. A test walks every .rs file under examples/, at any depth: a file outside examples/support has to be the file of a listed example whose access level the test pins, and any other file fails the test. The test scans the sources of the examples and holds each of them to an allowlist: of the library an example imports only the items the test lists, by a use that neither renames nor globs, and names the library nowhere else; of the guard it imports only the access level; and it names nothing that builds a configuration, opens a connection or a transport, names a host, exchanges a token pair or changes the environment. The same test pins the access level every example asks for, and an example pinned read-only names nothing of the library that places, changes, cancels or closes an order or a position.

Known limitations

  • The guard of the examples checks neither the ports nor the token endpoint: BROKER_FIX_QUOTE_PORT, BROKER_FIX_TRADE_PORT and BROKER_TOKEN_URL are used as given.
  • The guard matches demo in BROKER_FIX_HOST in lower case only, so it refuses a demo host written in another case; it fails closed.
  • A FIX reconnect delay above one hour is shortened to one hour without a message; a heartbeat interval above one hour is refused instead. The delay is the pause before the first of at most five attempts and the pause before the n-th attempt is n times the delay, so a session pauses for up to five hours before its last attempt.

Build

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo build --all-features
cargo build --all-features --examples

Test

cargo test --all-features
cargo llvm-cov --all-features --fail-under-lines 85
  • Unit tests and the tests against scripted mock servers need no credentials and no network beyond the loopback interface.
  • Live tests need the variables above and refuse a configuration that is not a demo one: open_api_live and fix_live_trading check the environment of the Open API, fix_live and fix_live_trading check that the sender identifier starts with demo.. open_api_live and fix_live_trading also need BROKER_ENV_FILE; fix_live needs the variables of the FIX sessions only. open_api_live and fix_live_trading trade the smallest volume, label what they create and remove it afterwards; fix_live places no order.
  • The live test of the token refresh rotates the pair and writes the new one to the file BROKER_ENV_FILE names; the old pair stops working at once.

Changes

CHANGELOG.adoc lists what each version added, changed and fixed.

Licence

This library is free software: it can be redistributed and modified under the terms of the GNU Lesser General Public License, version 3 or (at your option) any later version. See COPYING.LESSER and COPYING.