exchange_apiws/
lib.rs

1//! `exchange-apiws` — Exchange REST and WebSocket clients.
2//!
3//! Currently supports **KuCoin** (Spot, Futures, Unified).
4//! The crate is designed to be exchange-agnostic: new exchanges implement the
5//! [`actors::ExchangeConnector`] trait and the shared runner drives their feeds.
6//!
7//! # Quick start
8//!
9//! ```no_run
10//! use std::sync::Arc;
11//! use tokio::sync::{mpsc, watch};
12//! use exchange_apiws::client::Credentials;
13//! use exchange_apiws::connectors::KuCoin;
14//! use exchange_apiws::actors::{DataMessage, ExchangeConnector};
15//! use exchange_apiws::ws::{KucoinConnector, WsRunnerConfig, run_feed};
16//!
17//! #[tokio::main]
18//! async fn main() -> exchange_apiws::Result<()> {
19//!     // ── Connect ───────────────────────────────────────────────────────────
20//!     let kucoin = KuCoin::futures(Credentials::from_env()?);
21//!     let client = kucoin.rest_client()?;
22//!
23//!     // ── REST ──────────────────────────────────────────────────────────────
24//!     let bal  = client.get_balance("USDT").await?;
25//!     let pos  = client.get_position("XBTUSDTM").await?;
26//!     let bars = client.fetch_klines("XBTUSDTM", 200, "1").await?;
27//!
28//!     // ── WebSocket (public) ────────────────────────────────────────────────
29//!     let token = client.get_ws_token_public().await?;
30//!     let conn  = Arc::new(KucoinConnector::new(&token, kucoin.env())?);
31//!
32//!     let mut subs = vec![];
33//!     if let Some(s) = conn.trade_subscription("XBTUSDTM")  { subs.push(s); }
34//!     if let Some(s) = conn.ticker_subscription("XBTUSDTM") { subs.push(s); }
35//!
36//!     let (tx, mut rx)    = mpsc::channel::<DataMessage>(1024);
37//!     let (sd_tx, sd_rx)  = watch::channel(false);
38//!     let config = WsRunnerConfig::from_ping_interval(conn.ping_interval_secs);
39//!
40//!     tokio::spawn(run_feed(conn.ws_url().to_string(), subs, conn, tx, config, sd_rx));
41//!
42//!     while let Some(msg) = rx.recv().await {
43//!         println!("{msg:?}");
44//!     }
45//!     Ok(())
46//! }
47//! ```
48//!
49//! # Module layout
50//!
51//! ```text
52//! exchange_apiws
53//! ├── connectors  — exchange-specific config: KucoinEnv, KuCoin builder, ExchangeConfig trait
54//! │                 (extension point — add new exchanges here)
55//! ├── rest/
56//! │   ├── account  — balance, positions, auto-deposit, risk limit, funding history
57//! │   ├── market   — klines, ticker, order book, funding rate, mark price, contracts
58//! │   └── orders   — place, close, cancel, stop orders; fill history; KuCoinClient::calc_contracts
59//! ├── ws/
60//! │   ├── connect  — bullet-private / bullet-public token negotiation
61//! │   ├── feed     — KucoinConnector: subscription builders + frame parser
62//! │   ├── runner   — run_feed: async connect/ping/reconnect loop
63//! │   └── types    — WsToken, WsMessage
64//! ├── actors   — ExchangeConnector trait, DataMessage and all data types
65//! ├── auth     — HMAC-SHA256 signing (key version 2, KuCoin-specific)
66//! ├── client   — KuCoinClient (generic HTTP plumbing), Credentials
67//! ├── error    — ExchangeError, Result
68//! └── types    — Candle, Side, OrderType, TimeInForce, STP
69//! ```
70
71pub mod actors;
72pub mod auth;
73pub mod client;
74pub mod connectors;
75pub mod error;
76pub mod rest;
77pub mod types;
78pub mod ws;
79
80// ── Primary re-exports ────────────────────────────────────────────────────────
81
82pub use client::{Credentials, KuCoinClient};
83pub use connectors::{ExchangeConfig, KuCoin, KucoinEnv};
84pub use error::{ExchangeError, Result};
85pub use types::{Candle, OrderType, STP, Side, TimeInForce};
86
87// ── WS convenience re-exports ─────────────────────────────────────────────────
88
89pub use ws::{KucoinConnector, WsRunnerConfig, run_feed};
exchange_apiws/lib.rs

exchange_apiws/
lib.rs
