ostium_rust_sdk/
types.rs

1//! Common types used throughout the Ostium SDK
2//!
3//! This module defines the core data structures for trading, market data,
4//! and account management.
5
6use alloy_primitives::{Address, U256};
7use chrono::{DateTime, Utc};
8use rust_decimal::Decimal;
9use serde::{Deserialize, Serialize};
10
11/// Trading pair information
12#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
13pub struct TradingPair {
14    /// Unique identifier for the pair
15    pub id: String,
16    /// Base asset symbol (e.g., "BTC")
17    pub base_asset: String,
18    /// Quote asset symbol (e.g., "USD")
19    pub quote_asset: String,
20    /// Full pair symbol (e.g., "BTC/USD")
21    pub symbol: String,
22    /// Whether the pair is currently active for trading
23    pub is_active: bool,
24    /// Minimum position size
25    pub min_position_size: Decimal,
26    /// Maximum position size
27    pub max_position_size: Decimal,
28    /// Price precision (decimal places)
29    pub price_precision: u8,
30    /// Quantity precision (decimal places)
31    pub quantity_precision: u8,
32}
33
34/// Price information for a trading pair
35#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
36pub struct Price {
37    /// Trading pair symbol
38    pub symbol: String,
39    /// Current mark price
40    pub mark_price: Decimal,
41    /// Current index price
42    pub index_price: Decimal,
43    /// 24h high price
44    pub high_24h: Decimal,
45    /// 24h low price
46    pub low_24h: Decimal,
47    /// 24h volume in quote currency
48    pub volume_24h: Decimal,
49    /// Timestamp of the price update
50    pub timestamp: DateTime<Utc>,
51}
52
53/// Trading hours information
54#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
55pub struct TradingHours {
56    /// Trading pair symbol
57    pub symbol: String,
58    /// Whether trading is currently open
59    pub is_open: bool,
60    /// Next opening time (if currently closed)
61    pub next_open: Option<DateTime<Utc>>,
62    /// Next closing time (if currently open)
63    pub next_close: Option<DateTime<Utc>>,
64}
65
66/// Position side (Long or Short)
67#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
68pub enum PositionSide {
69    /// Long position (buy)
70    Long,
71    /// Short position (sell)
72    Short,
73}
74
75/// Order type
76#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
77pub enum OrderType {
78    /// Market order
79    Market,
80    /// Limit order
81    Limit,
82    /// Stop market order
83    StopMarket,
84    /// Stop limit order
85    StopLimit,
86}
87
88/// Order status
89#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
90pub enum OrderStatus {
91    /// Order is pending execution
92    Pending,
93    /// Order is partially filled
94    PartiallyFilled,
95    /// Order is completely filled
96    Filled,
97    /// Order was cancelled
98    Cancelled,
99    /// Order was rejected
100    Rejected,
101}
102
103/// Trading position
104#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
105pub struct Position {
106    /// Unique position ID
107    pub id: String,
108    /// Trading pair symbol
109    pub symbol: String,
110    /// Position side (Long/Short)
111    pub side: PositionSide,
112    /// Position size
113    pub size: Decimal,
114    /// Average entry price
115    pub entry_price: Decimal,
116    /// Current mark price
117    pub mark_price: Decimal,
118    /// Unrealized PnL
119    pub unrealized_pnl: Decimal,
120    /// Realized PnL
121    pub realized_pnl: Decimal,
122    /// Margin used
123    pub margin: Decimal,
124    /// Leverage
125    pub leverage: Decimal,
126    /// Liquidation price
127    pub liquidation_price: Option<Decimal>,
128    /// Take profit price
129    pub take_profit: Option<Decimal>,
130    /// Stop loss price
131    pub stop_loss: Option<Decimal>,
132    /// Position creation timestamp
133    pub created_at: DateTime<Utc>,
134    /// Last update timestamp
135    pub updated_at: DateTime<Utc>,
136}
137
138/// Trading order
139#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
140pub struct Order {
141    /// Unique order ID
142    pub id: String,
143    /// Trading pair symbol
144    pub symbol: String,
145    /// Order type
146    pub order_type: OrderType,
147    /// Position side
148    pub side: PositionSide,
149    /// Order size
150    pub size: Decimal,
151    /// Order price (for limit orders)
152    pub price: Option<Decimal>,
153    /// Stop price (for stop orders)
154    pub stop_price: Option<Decimal>,
155    /// Order status
156    pub status: OrderStatus,
157    /// Filled size
158    pub filled_size: Decimal,
159    /// Average fill price
160    pub avg_fill_price: Option<Decimal>,
161    /// Order creation timestamp
162    pub created_at: DateTime<Utc>,
163    /// Last update timestamp
164    pub updated_at: DateTime<Utc>,
165}
166
167/// Account balance information
168#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
169pub struct Balance {
170    /// Asset symbol (e.g., "USDC")
171    pub asset: String,
172    /// Available balance
173    pub available: Decimal,
174    /// Balance locked in orders/positions
175    pub locked: Decimal,
176    /// Total balance (available + locked)
177    pub total: Decimal,
178}
179
180/// Open interest information for a trading pair
181#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
182pub struct OpenInterestInfo {
183    /// Trading pair symbol
184    pub symbol: String,
185    /// Current total open interest in USD
186    pub total_open_interest: Decimal,
187    /// Current long open interest in USD
188    pub long_open_interest: Decimal,
189    /// Current short open interest in USD
190    pub short_open_interest: Decimal,
191    /// Maximum allowed open interest in USD
192    pub max_open_interest: Decimal,
193    /// Current utilization percentage (0-100)
194    pub utilization_percent: Decimal,
195    /// Whether new positions are currently blocked
196    pub is_capped: bool,
197}
198
199/// Open interest cap validation result
200#[derive(Debug, Clone)]
201pub struct OpenInterestCapResult {
202    /// Whether the position would exceed the cap
203    pub would_exceed_cap: bool,
204    /// Current utilization before the trade
205    pub current_utilization: Decimal,
206    /// Projected utilization after the trade
207    pub projected_utilization: Decimal,
208    /// Available capacity in USD
209    pub available_capacity: Decimal,
210    /// Recommended maximum position size
211    pub max_recommended_size: Decimal,
212}
213
214/// Transaction hash type
215pub type TxHash = alloy_primitives::TxHash;
216
217/// Parameters for opening a new position
218#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
219pub struct OpenPositionParams {
220    /// Trading pair symbol
221    pub symbol: String,
222    /// Position side
223    pub side: PositionSide,
224    /// Position size
225    pub size: Decimal,
226    /// Leverage to use
227    pub leverage: Decimal,
228    /// Optional take profit price
229    pub take_profit: Option<Decimal>,
230    /// Optional stop loss price
231    pub stop_loss: Option<Decimal>,
232    /// Slippage tolerance (as decimal, e.g., 0.01 for 1%)
233    pub slippage_tolerance: Decimal,
234}
235
236/// Advanced parameters for opening positions with specific order types
237#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
238pub struct AdvancedOrderParams {
239    /// Trading pair symbol
240    pub symbol: String,
241    /// Position side
242    pub side: PositionSide,
243    /// Position size
244    pub size: Decimal,
245    /// Leverage to use
246    pub leverage: Decimal,
247    /// Order type to use
248    pub order_type: OrderExecutionType,
249    /// Price for limit/stop orders
250    pub price: Option<Decimal>,
251    /// Optional take profit price
252    pub take_profit: Option<Decimal>,
253    /// Optional stop loss price
254    pub stop_loss: Option<Decimal>,
255    /// Slippage tolerance (as decimal, e.g., 0.01 for 1%)
256    pub slippage_tolerance: Decimal,
257}
258
259/// Order execution type for advanced orders
260#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
261pub enum OrderExecutionType {
262    /// Market order - execute immediately at current market price
263    Market,
264    /// Limit order - execute when price reaches or is better than specified price
265    Limit,
266    /// Stop order - execute when price crosses the stop level
267    Stop,
268}
269
270/// Parameters for placing a limit order
271#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
272pub struct LimitOrderParams {
273    /// Trading pair symbol
274    pub symbol: String,
275    /// Position side
276    pub side: PositionSide,
277    /// Position size
278    pub size: Decimal,
279    /// Leverage to use
280    pub leverage: Decimal,
281    /// Limit price for execution
282    pub limit_price: Decimal,
283    /// Optional take profit price
284    pub take_profit: Option<Decimal>,
285    /// Optional stop loss price
286    pub stop_loss: Option<Decimal>,
287}
288
289/// Parameters for placing a stop order
290#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
291pub struct StopOrderParams {
292    /// Trading pair symbol
293    pub symbol: String,
294    /// Position side
295    pub side: PositionSide,
296    /// Position size
297    pub size: Decimal,
298    /// Leverage to use
299    pub leverage: Decimal,
300    /// Stop price that triggers the order
301    pub stop_price: Decimal,
302    /// Optional take profit price
303    pub take_profit: Option<Decimal>,
304    /// Optional stop loss price
305    pub stop_loss: Option<Decimal>,
306}
307
308/// Parameters for canceling an order
309#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
310pub struct CancelOrderParams {
311    /// Order ID to cancel (format: "trader:pair_index:index")
312    pub order_id: String,
313}
314
315/// Parameters for updating an existing limit order
316#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
317pub struct UpdateLimitOrderParams {
318    /// Order ID to update (format: "trader:pair_index:index")
319    pub order_id: String,
320    /// New limit price (None = keep current)
321    pub limit_price: Option<Decimal>,
322    /// New take profit price (None = keep current)
323    pub take_profit: Option<Decimal>,
324    /// New stop loss price (None = keep current)
325    pub stop_loss: Option<Decimal>,
326}
327
328/// Parameters for closing a position
329#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
330pub struct ClosePositionParams {
331    /// Position ID to close
332    pub position_id: String,
333    /// Size to close (None = close entire position)
334    pub size: Option<Decimal>,
335    /// Slippage tolerance (as decimal, e.g., 0.01 for 1%)
336    pub slippage_tolerance: Decimal,
337}
338
339/// Parameters for updating take profit and stop loss
340#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
341pub struct UpdateTPSLParams {
342    /// Position ID to update
343    pub position_id: String,
344    /// New take profit price (None = remove TP)
345    pub take_profit: Option<Decimal>,
346    /// New stop loss price (None = remove SL)
347    pub stop_loss: Option<Decimal>,
348}
349
350/// Type of order being placed
351#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
352pub enum OpenOrderType {
353    /// Market order
354    Market,
355    /// Limit order
356    Limit,
357    /// Stop order
358    Stop,
359}
360
361/// Trade information for opening a position
362#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
363pub struct Trade {
364    /// Collateral amount in USDC (with 6 decimals)
365    pub collateral: U256,
366    /// Open price (with 18 decimals)
367    pub open_price: u128,
368    /// Take profit price (with 18 decimals)
369    pub tp: u128,
370    /// Stop loss price (with 18 decimals)
371    pub sl: u128,
372    /// Trader address
373    pub trader: Address,
374    /// Leverage (with 2 decimals, e.g., 500 = 5x)
375    pub leverage: u32,
376    /// Pair index
377    pub pair_index: u16,
378    /// Position index
379    pub index: u8,
380    /// True for long, false for short
381    pub buy: bool,
382}
383
384/// Open limit order information
385#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
386pub struct OpenLimitOrder {
387    /// Collateral amount in USDC (with 6 decimals)
388    pub collateral: U256,
389    /// Target price to execute at (with 18 decimals)
390    pub target_price: u128,
391    /// Take profit price (with 18 decimals)
392    pub tp: u128,
393    /// Stop loss price (with 18 decimals)
394    pub sl: u128,
395    /// Trader address
396    pub trader: Address,
397    /// Leverage (with 2 decimals, e.g., 500 = 5x)
398    pub leverage: u32,
399    /// Creation timestamp
400    pub created_at: u32,
401    /// Last update timestamp
402    pub last_updated: u32,
403    /// Pair index
404    pub pair_index: u16,
405    /// Order type (0 = market, 1 = limit, 2 = stop)
406    pub order_type: u8,
407    /// Position index
408    pub index: u8,
409    /// True for long, false for short
410    pub buy: bool,
411}
412
413/// Unsigned transaction data that can be sent to frontend for signing
414#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
415pub struct UnsignedTransaction {
416    /// Contract address to call
417    pub to: Address,
418    /// Transaction data (encoded function call)
419    pub data: Vec<u8>,
420    /// Value to send (usually 0 for contract calls)
421    pub value: U256,
422    /// Estimated gas limit
423    pub gas_limit: Option<U256>,
424    /// Gas price estimate
425    pub gas_price: Option<U256>,
426    /// Chain ID
427    pub chain_id: u64,
428    /// Nonce (if known)
429    pub nonce: Option<u64>,
430}
431
432/// Parameters for building unsigned transactions
433#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
434pub struct UnsignedTransactionParams {
435    /// Address that will sign and send the transaction
436    pub from: Address,
437    /// Whether to include gas estimates
438    pub include_gas_estimates: bool,
439    /// Whether to include nonce
440    pub include_nonce: bool,
441}
ostium_rust_sdk/types.rs

ostium_rust_sdk/
types.rs
