ironbeam_rs/lib.rs
1//! [![github]](https://github.com/wboayue/ironbeam-rs) [![crates-io]](https://crates.io/crates/ironbeam-rs) [![license]](https://opensource.org/licenses/MIT)
2//!
3//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
4//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
5//! [license]: https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge&labelColor=555555
6//!
7//! <br>
8//!
9//! An async Rust client for the [Ironbeam](https://www.ironbeam.com/) futures trading API,
10//! providing both REST and WebSocket streaming interfaces for account management,
11//! order execution, and real-time market data.
12//!
13//! # Quick Start
14//!
15//! Connect to the demo environment and query account balances:
16//!
17//! ```no_run
18//! use ironbeam_rs::client::{Client, Credentials};
19//! use ironbeam_rs::types::BalanceType;
20//!
21//! #[tokio::main]
22//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
23//! let client = Client::builder()
24//! .credentials(Credentials {
25//! username: "user".into(),
26//! password: "pass".into(),
27//! api_key: "key".into(),
28//! })
29//! .demo()
30//! .connect()
31//! .await?;
32//!
33//! let accounts = client.all_accounts().await?;
34//! let balance = client.balance(&accounts[0], BalanceType::CurrentOpen).await?;
35//! println!("{balance:?}");
36//!
37//! client.logout().await?;
38//! Ok(())
39//! }
40//! ```
41//!
42//! # Modules
43//!
44//! | Module | Description |
45//! |--------|-------------|
46//! | [`client`] | [`Client`](client::Client) builder, connection, and REST API methods |
47//! | [`client::stream`] | WebSocket streaming for real-time quotes, depth, trades, orders, and indicator bars |
48//! | [`types`] | Domain types — accounts, orders, market data, enums, and serde helpers |
49//! | [`error`] | [`Error`](error::Error) enum and [`Result`](error::Result) alias |
50//!
51//! # REST API
52//!
53//! All REST methods are on [`Client`](client::Client). Authentication is handled
54//! automatically by [`ClientBuilder::connect()`](client::ClientBuilder::connect).
55//!
56//! ```no_run
57//! # use ironbeam_rs::client::{Client, Credentials};
58//! # async fn example() -> ironbeam_rs::error::Result<()> {
59//! # let client = Client::builder()
60//! # .credentials(Credentials { username: "u".into(), password: "p".into(), api_key: "k".into() })
61//! # .demo().connect().await?;
62//! // Account data
63//! let accounts = client.all_accounts().await?;
64//! let positions = client.positions(&accounts[0]).await?;
65//!
66//! // Market data
67//! let quotes = client.quotes(&["ESM5"]).await?;
68//! let depth = client.depth(&["ESM5"]).await?;
69//!
70//! // Orders
71//! use ironbeam_rs::client::OrderBuilder;
72//! use ironbeam_rs::types::{OrderSide, DurationType};
73//! let order = OrderBuilder::limit("ESM5", OrderSide::Buy, 1.0, 5000.0, DurationType::Day);
74//! let receipt = client.place_order(&accounts[0], &order).await?;
75//!
76//! // Reference data
77//! let exchanges = client.exchange_sources().await?;
78//! let info = client.trader_info(None).await?;
79//! # Ok(())
80//! # }
81//! ```
82//!
83//! # Streaming
84//!
85//! Real-time data via WebSocket. Subscribe to quotes, depth, trades, account
86//! updates, and indicator bars (trade/tick/time/volume).
87//!
88//! ```no_run
89//! # use ironbeam_rs::client::{Client, Credentials};
90//! # use ironbeam_rs::client::stream::StreamEvent;
91//! # async fn example() -> ironbeam_rs::error::Result<()> {
92//! # let client = Client::builder()
93//! # .credentials(Credentials { username: "u".into(), password: "p".into(), api_key: "k".into() })
94//! # .demo().connect().await?;
95//! let mut stream = client.stream().start().await?;
96//!
97//! stream.subscribe_quotes(&["ESM5"]).await?;
98//! stream.subscribe_depth(&["ESM5"]).await?;
99//!
100//! while let Some(Ok(event)) = stream.next().await {
101//! match event {
102//! StreamEvent::Quotes(quotes) => println!("{quotes:?}"),
103//! StreamEvent::Depth(depth) => println!("{depth:?}"),
104//! _ => {}
105//! }
106//! }
107//! # Ok(())
108//! # }
109//! ```
110//!
111//! # Error Handling
112//!
113//! All methods return [`error::Result<T>`]. The [`Error`](error::Error) enum
114//! covers HTTP transport, JSON parsing, API-level errors (with status code),
115//! authentication failures, and WebSocket errors.
116//!
117//! ```no_run
118//! # use ironbeam_rs::client::{Client, Credentials};
119//! # use ironbeam_rs::error::Error;
120//! # async fn example() -> ironbeam_rs::error::Result<()> {
121//! # let client = Client::builder()
122//! # .credentials(Credentials { username: "u".into(), password: "p".into(), api_key: "k".into() })
123//! # .demo().connect().await?;
124//! match client.quotes(&["INVALID"]).await {
125//! Ok(quotes) => println!("{quotes:?}"),
126//! Err(Error::Api { status: 429, .. }) => eprintln!("rate limited, back off"),
127//! Err(e) => eprintln!("error: {e}"),
128//! }
129//! # Ok(())
130//! # }
131//! ```
132//!
133//! # Rate Limiting
134//!
135//! The API enforces a hard limit of 10 requests/second. The client has optional
136//! built-in rate limiting via [`ClientBuilder::rate_limit()`](client::ClientBuilder::rate_limit):
137//!
138//! ```no_run
139//! # use ironbeam_rs::client::{Client, Credentials};
140//! # async fn example() -> ironbeam_rs::error::Result<()> {
141//! let client = Client::builder()
142//! .credentials(Credentials {
143//! username: "u".into(),
144//! password: "p".into(),
145//! api_key: "k".into(),
146//! })
147//! .demo()
148//! .rate_limit(8) // stay under the 10/sec hard limit
149//! .connect()
150//! .await?;
151//! # Ok(())
152//! # }
153//! ```
154//!
155//! # Feature Highlights
156//!
157//! - **Async/await** — built on `tokio`, `hyper`, and `fastwebsockets`
158//! - **Unified types** — single structs deserialize from both REST (camelCase) and streaming (abbreviated) wire formats via `serde` aliases
159//! - **Builder pattern** — fluent construction for clients, orders, and queries
160//! - **Typed errors** — no `unwrap()` in library code; all failures surface as [`Error`](error::Error) variants
161//! - **Rate limiting** — optional client-side throttling to avoid 429 cooldowns
162//! - **Secure by default** — TLS via `rustls`, auth headers redacted in `Debug` output
163
164/// Authenticated client, builders, and REST/streaming API methods.
165pub mod client;
166/// Error types and result alias.
167pub mod error;
168/// Domain model — accounts, orders, market data, enums, and serde helpers.
169pub mod types;