Crates.io | xtb-client |
lib.rs | xtb-client |
version | 0.1.3 |
source | src |
created_at | 2024-03-29 11:28:43.717638 |
updated_at | 2024-11-12 17:07:35.768135 |
description | Rust implementation of XTB Broker API connector |
homepage | |
repository | https://github.com/elmordo/xtb-client |
max_upload_size | |
id | 1189876 |
size | 270,108 |
The XTB-Client library provides typed and simple to use implementation of a connector to the API of the XTB broker.
This library is still under development. The library api can be changed and some bugs are maybe living in the code.
The XTB interface is provided by the XtbClient
struct implementing the XtbApi
and XtbStreamApi
traits. The struct
can be created by the XtbClientBuilder
struct and when created, it is automatically connected to the server and
the login
command is performed. If both is success, the XtbClient
instance is returned.
The XtbClient
is configured by the XtbClientBuilder
. The builder has three initialization methods:
new(api_url: &str, stream_api_url: &str)
- create new instance with custom urls.new_real()
- create new instance with real account servers preset.new_demo()
- create new instance with demo account servers preset.new_bare()
- create new instance without any value set.The setters (prefixed by with_
and options are flattened to underlying type) and getters (not prefixed) can be used
to override following attributes:
api_url: Option<String>
- URL of the request/response api server.stream_api_url: Option<String>
- URL of the stream api server.app_id: Option<String>
- optional application id (marked as deprecated in the official documentation).app_name: Option<String>
- optional application name (marked as deprecated in the official documentation).ping_period: Option<u64>
- time period between ping requests (default is 30s)When a builder instance is configured, the build
method can be called. The method accepts two &str
params: username and password.
When the method is called, server connections are created, user is logged in and ping tokio green threads are spawned.
use xtb_client::XtbClientBuilder;
#[tokio::main]
fn main() {
let real_builder = XtbClientBuilder::new_real();
let demo_builder = XtbClientBuilder::new_demo();
let custom_builder = XtbClientBuilder::new("wss://my-server.com/api", "wss://my-server.com/apiStream").with_ping_period(20u64);
let bare_builder = XtbClientBuilder::new_bare().with_api_url("wss://my-server.com/api").with_stream_api_url("wss://my-server.com/apiStream");
let client = custom_builder.build("12345", "reallySecretPassword");
}
The simplest way how to communicate with the server is a request/response API. This api always returns a response to a request.
Methods names corresponds with the command names transformed to snake_case. Examples:
getAllSymbols
-> get_all_symbols
getCalendar
-> get_calendar
getVersion
-> get_version
Several commands are not implemented in public interface of the trait:
login
- performed automatically by XtbClient
creation processlogout
- performed automatically when XtbClient
instance is droppedping
- performed periodically by the XtbClient
instance every 30s (can be configured).The stream api feed a consumer by stream of messages delivered to a consumer by the DataStream
struct. The subscription
is cancelled automatically when a DataStream
instance is dropped.
The stream API implementation uses internal subscription counter so if two subscribers are subscribed for same messages (e.g. USDEUR tick prices), unsubscription of the first one does not cut off the second one from the messages.
Methods names corresponds with the command names transformed to snake_case and with subscribe_
prefix instead
of the get_
prefix. Examples:
getCandles
-> subscribe_candles
getTrades
-> subscribe_trades
getProfits
-> subscribe_profits
Several commands are not implemented in public interface of the trait:
ping
- performed periodically by the XtbClient
instance every 30s (can be configured).The library exposes low level connections too.
The XtbConnection
trait and its implementor BasicXtbConnection
provides low level connection to the XTB server
for the request-response commands.
The trait provides the send_command
method. This method accepts command name (for example getNews
) and payload
used as a command arguments. When the command has no arguments, pass None
.
After the method is called, the ResponsePromise
struct instance is returned. It is awaitable returning response from
the server. The result is Ok(Response)
if command was successful or Err(ErrorResponse)
if command fails.
The XtbStreamConnection
trait and its implementor BasicStreamConnection
provides low level connection to the XTB
stream server for data streaming.
The trait provides subscribe
, unsubscribe
and make_message_stream
methods.
The subscribe
method accepts command name and optional arguments as parameter. The parameter must be None
or Some(serde_json::Value::Null)
for commands without arguments and Some(serde_json::Value::Object)
for commands
with arguments. When command is send successfully, the server should stream requested data.
The unsubscribe
method is similar to the subscribe
but its effect is to stop the data stream.
The make_message_stream
make local subscription for messages delivered from the XTB server. It accepts
DataMessageFilter
enum as parameter and use it to filter incoming messages by given predicate. Available filters are
following:
Always
(default) - all messages are passed to a consumerNever
- no message is passed for consumerCommand(String)
- filter messages by the command
field of data message received from the serverFieldValue { name: String, value: serde_json::Value }
- filter messages by field name of data
field of the data message
received from the server. The filter match if and only if data
contains type of serde_json::Value::Object
and
the object has key named name
and the field contains equal value as value
.Custom(Box<dyn Fn(&StreamDataMessage) -> bool + Send + Sync>)
- custom filter fnAll(Vec<DataMessageFilter>)
- container for none, one or more predicates. Matches if and only if all predicates is
matching. If list of predicates is empty, returns true
.Any(Vec<DataMessageFilter>)
- container for none, one or more predicates. Matches if any predicate is
matching. If list of predicates is empty, returns false
.Note: the Not
is not implemented but the Custom
variant can be used to create it.
The make_message_stream
returns implementor of the MessageStream
trait. This trait provides the next()
method
returning incoming messages matching to the filter.
Simple API call to get all available symbols.
use tracing::Level;
use xtb_client::RequestResponseApi;
use xtb_client::schema::GetAllSymbolsRequest;
#[tokio::main]
async fn main() {
dotenvy::dotenv().unwrap_or_default();
let subscriber = tracing_subscriber::fmt().with_max_level(Level::DEBUG).finish();
tracing::subscriber::set_global_default(subscriber).unwrap();
let username = dotenvy::var("XTB_USERNAME").unwrap();
let password = dotenvy::var("XTB_PASSWORD").unwrap();
let api_server = dotenvy::var("XTB_API_SERVER").unwrap();
let stream_server = dotenvy::var("XTB_STREAM_SERVER").unwrap();
let mut client = xtb_client::XtbClientBuilder::new(&api_server, &stream_server).build(&username, &password).await.unwrap();
let symbols = client.get_all_symbols(GetAllSymbolsRequest::default()).await.unwrap();
println!("{}", serde_json::to_string_pretty(&symbols).unwrap())
}
Subscribe for the keppAlive
messages.
use tracing::Level;
use xtb_client::{StreamApi};
use xtb_client::schema::{StreamGetKeepAliveSubscribe};
#[tokio::main]
async fn main() {
dotenvy::dotenv().unwrap_or_default();
let subscriber = tracing_subscriber::fmt().with_max_level(Level::DEBUG).finish();
tracing::subscriber::set_global_default(subscriber).unwrap();
let username = dotenvy::var("XTB_USERNAME").unwrap();
let password = dotenvy::var("XTB_PASSWORD").unwrap();
let api_server = dotenvy::var("XTB_API_SERVER").unwrap();
let stream_server = dotenvy::var("XTB_STREAM_SERVER").unwrap();
let mut client = xtb_client::XtbClientBuilder::new(&api_server, &stream_server).build(&username, &password).await.unwrap();
let mut listener = client.subscribe_keep_alive(StreamGetKeepAliveSubscribe::default()).await.unwrap();
while let Some(item) = listener.next().await.unwrap() {
println!("Keep alive received: {}", item.timestamp);
}
println!("Stream closed");
}
The library stays in the development (version number starting with 0) until following steps won't be finished.
MarginMode
variant with value 104
and QuoteId
variants with values 5 and 6 are not
mentioned in the official documentation. Meaning of these variants must be known before the library will be stabilized.If you like this library, or you want to support its development, support me by one cold beer. The beer is tasty and full of vitamins :-)