# Types Reference
This document provides complete reference for all data types used in the Ostium Rust SDK.
## Core Trading Types
### Network
Represents the blockchain network to connect to.
```rust
pub enum Network {
Mainnet, // Arbitrum One (Chain ID: 42161)
Testnet, // Arbitrum Sepolia (Chain ID: 421614)
}
```
### Trading Pairs
#### `TradingPair`
Complete information about a trading pair.
```rust
pub struct TradingPair {
pub id: String, // Unique identifier
pub base_asset: String, // Base asset (e.g., "BTC")
pub quote_asset: String, // Quote asset (e.g., "USD")
pub symbol: String, // Full symbol (e.g., "BTC/USD")
pub is_active: bool, // Whether trading is active
pub min_position_size: Decimal, // Minimum position size
pub max_position_size: Decimal, // Maximum position size
pub price_precision: u8, // Price decimal places
pub quantity_precision: u8, // Quantity decimal places
}
```
## Position Management
### `PositionSide`
Represents the direction of a trading position.
```rust
pub enum PositionSide {
Long, // Betting price goes up (buy)
Short, // Betting price goes down (sell)
}
```
### `Position`
Complete position information.
```rust
pub struct Position {
pub id: String, // Unique position identifier
pub symbol: String, // Trading pair symbol
pub side: PositionSide, // Long or Short
pub size: Decimal, // Position size
pub entry_price: Decimal, // Average entry price
pub mark_price: Decimal, // Current mark price
pub unrealized_pnl: Decimal, // Unrealized profit/loss
pub realized_pnl: Decimal, // Realized profit/loss
pub margin: Decimal, // Margin used
pub leverage: Decimal, // Position leverage
pub liquidation_price: Option<Decimal>, // Liquidation price
pub take_profit: Option<Decimal>, // Take profit price
pub stop_loss: Option<Decimal>, // Stop loss price
pub created_at: DateTime<Utc>, // Creation timestamp
pub updated_at: DateTime<Utc>, // Last update timestamp
}
```
## Order Management
### `OrderType`
Types of trading orders.
```rust
pub enum OrderType {
Market, // Execute immediately at market price
Limit, // Execute at specified price or better
StopMarket, // Trigger at stop price, execute as market
StopLimit, // Trigger at stop price, execute as limit
}
```
### `OrderStatus`
Current status of an order.
```rust
pub enum OrderStatus {
Pending, // Waiting for execution
PartiallyFilled, // Partially executed
Filled, // Completely executed
Cancelled, // Cancelled by user
Rejected, // Rejected by system
}
```
### `Order`
Complete order information.
```rust
pub struct Order {
pub id: String, // Unique order identifier
pub symbol: String, // Trading pair symbol
pub order_type: OrderType, // Type of order
pub side: PositionSide, // Long or Short
pub size: Decimal, // Order size
pub price: Option<Decimal>, // Order price (for limit orders)
pub stop_price: Option<Decimal>, // Stop price (for stop orders)
pub status: OrderStatus, // Current order status
pub filled_size: Decimal, // Amount already filled
pub avg_fill_price: Option<Decimal>, // Average fill price
pub created_at: DateTime<Utc>, // Creation timestamp
pub updated_at: DateTime<Utc>, // Last update timestamp
}
```
## Market Data Types
### `Price`
Real-time price information for a trading pair.
```rust
pub struct Price {
pub symbol: String, // Trading pair symbol
pub mark_price: Decimal, // Current mark price
pub index_price: Decimal, // Current index price
pub high_24h: Decimal, // 24-hour high
pub low_24h: Decimal, // 24-hour low
pub volume_24h: Decimal, // 24-hour volume
pub timestamp: DateTime<Utc>, // Price timestamp
}
```
### `TradingHours`
Trading schedule information.
```rust
pub struct TradingHours {
pub symbol: String, // Trading pair symbol
pub is_open: bool, // Whether trading is open
pub next_open: Option<DateTime<Utc>>, // Next opening time
pub next_close: Option<DateTime<Utc>>, // Next closing time
}
```
## Account Types
### `Balance`
Account balance information.
```rust
pub struct Balance {
pub asset: String, // Asset symbol (e.g., "USDC")
pub available: Decimal, // Available for trading
pub locked: Decimal, // Locked in orders/positions
pub total: Decimal, // Total balance
}
```
## Trading Parameter Types
### Opening Positions
#### `OpenPositionParams`
Parameters for opening a new position.
```rust
pub struct OpenPositionParams {
pub symbol: String, // Trading pair (e.g., "BTC/USD")
pub side: PositionSide, // Long or Short
pub size: Decimal, // Position size
pub leverage: Decimal, // Leverage multiplier
pub take_profit: Option<Decimal>, // Optional TP price
pub stop_loss: Option<Decimal>, // Optional SL price
pub slippage_tolerance: Decimal, // Max slippage (e.g., 0.01 = 1%)
}
```
### Advanced Orders
#### `AdvancedOrderParams`
Parameters for placing advanced orders (market, limit, stop).
```rust
pub struct AdvancedOrderParams {
pub symbol: String, // Trading pair symbol
pub side: PositionSide, // Position side
pub size: Decimal, // Order size
pub leverage: Decimal, // Leverage to use
pub order_type: OrderExecutionType, // Order execution type
pub price: Option<Decimal>, // Price (for limit/stop)
pub take_profit: Option<Decimal>, // Optional TP
pub stop_loss: Option<Decimal>, // Optional SL
pub slippage_tolerance: Decimal, // Slippage tolerance
}
```
#### `OrderExecutionType`
How an order should be executed.
```rust
pub enum OrderExecutionType {
Market, // Execute immediately at market price
Limit, // Execute at specified price or better
Stop, // Execute when price crosses threshold
}
```
#### `LimitOrderParams`
Specific parameters for limit orders.
```rust
pub struct LimitOrderParams {
pub symbol: String, // Trading pair
pub side: PositionSide, // Position side
pub size: Decimal, // Order size
pub leverage: Decimal, // Leverage
pub limit_price: Decimal, // Execution price
pub take_profit: Option<Decimal>, // Optional TP
pub stop_loss: Option<Decimal>, // Optional SL
}
```
#### `StopOrderParams`
Specific parameters for stop orders.
```rust
pub struct StopOrderParams {
pub symbol: String, // Trading pair
pub side: PositionSide, // Position side
pub size: Decimal, // Order size
pub leverage: Decimal, // Leverage
pub stop_price: Decimal, // Trigger price
pub take_profit: Option<Decimal>, // Optional TP
pub stop_loss: Option<Decimal>, // Optional SL
}
```
### Position Management
#### `ClosePositionParams`
Parameters for closing positions.
```rust
pub struct ClosePositionParams {
pub position_id: String, // Position to close
pub size: Option<Decimal>, // Amount to close (None = all)
pub slippage_tolerance: Decimal, // Max slippage
}
```
#### `UpdateTPSLParams`
Parameters for updating take profit and stop loss.
```rust
pub struct UpdateTPSLParams {
pub position_id: String, // Position to update
pub take_profit: Option<Decimal>, // New TP (None = remove)
pub stop_loss: Option<Decimal>, // New SL (None = remove)
}
```
### Order Management
#### `CancelOrderParams`
Parameters for canceling orders.
```rust
pub struct CancelOrderParams {
pub order_id: String, // Order ID (format: "trader:pair:index")
}
```
#### `UpdateLimitOrderParams`
Parameters for updating limit orders.
```rust
pub struct UpdateLimitOrderParams {
pub order_id: String, // Order to update
pub limit_price: Option<Decimal>, // New price (None = keep)
pub take_profit: Option<Decimal>, // New TP (None = keep)
pub stop_loss: Option<Decimal>, // New SL (None = keep)
}
```
## Unsigned Transaction Types
### `UnsignedTransaction`
Transaction data for frontend signing.
```rust
pub struct UnsignedTransaction {
pub to: Address, // Contract address
pub data: Vec<u8>, // Encoded function call
pub value: U256, // ETH value (usually 0)
pub gas_limit: Option<U256>, // Estimated gas limit
pub gas_price: Option<U256>, // Gas price estimate
pub chain_id: u64, // Network chain ID
pub nonce: Option<u64>, // Transaction nonce
}
```
### `UnsignedTransactionParams`
Configuration for generating unsigned transactions.
```rust
pub struct UnsignedTransactionParams {
pub from: Address, // Signer address
pub include_gas_estimates: bool, // Include gas estimates
pub include_nonce: bool, // Include nonce
}
```
## Contract Types
### `Trade`
Low-level contract trade structure.
```rust
pub struct Trade {
pub collateral: U256, // Collateral (USDC, 6 decimals)
pub open_price: u128, // Open price (18 decimals)
pub tp: u128, // Take profit (18 decimals)
pub sl: u128, // Stop loss (18 decimals)
pub trader: Address, // Trader address
pub leverage: u32, // Leverage (basis points)
pub pair_index: u16, // Trading pair index
pub index: u8, // Position index
pub buy: bool, // True = long, false = short
}
```
### `OpenLimitOrder`
Low-level contract limit order structure.
```rust
pub struct OpenLimitOrder {
pub collateral: U256, // Collateral amount
pub target_price: u128, // Execution price
pub tp: u128, // Take profit
pub sl: u128, // Stop loss
pub trader: Address, // Trader address
pub leverage: u32, // Leverage
pub created_at: u32, // Creation timestamp
pub last_updated: u32, // Update timestamp
pub pair_index: u16, // Pair index
pub order_type: u8, // Order type
pub index: u8, // Order index
pub buy: bool, // Direction
}
```
## Type Aliases
```rust
/// Transaction hash type
pub type TxHash = alloy_primitives::TxHash;
/// Ethereum address type
pub type Address = alloy_primitives::Address;
/// 256-bit unsigned integer
pub type U256 = alloy_primitives::U256;
```
## Utility Types
### Open Interest
#### `OpenInterestInfo`
Information about open interest for a trading pair.
```rust
pub struct OpenInterestInfo {
pub symbol: String, // Trading pair
pub total_open_interest: Decimal, // Total OI in USD
pub long_open_interest: Decimal, // Long OI in USD
pub short_open_interest: Decimal, // Short OI in USD
pub max_open_interest: Decimal, // Maximum allowed OI
pub utilization_percent: Decimal, // Current utilization %
pub is_capped: bool, // Whether new positions blocked
}
```
## Serialization
All public types implement:
- `Serialize` and `Deserialize` (via serde)
- `Debug`, `Clone`, and `PartialEq` where appropriate
- JSON-compatible serialization for frontend integration
## Example Usage
```rust
use ostium_rust_sdk::{
OpenPositionParams, PositionSide, OrderExecutionType,
UnsignedTransactionParams,
};
use rust_decimal_macros::dec;
// Creating trading parameters
let params = OpenPositionParams {
symbol: "BTC/USD".to_string(),
side: PositionSide::Long,
size: dec!(0.01),
leverage: dec!(5.0),
take_profit: Some(dec!(55000)),
stop_loss: Some(dec!(45000)),
slippage_tolerance: dec!(0.01),
};
// Unsigned transaction configuration
let tx_params = UnsignedTransactionParams {
from: trader_address,
include_gas_estimates: true,
include_nonce: true,
};
```
## See Also
- [Client API Reference](client.md) - Main client interface
- [Trading API Reference](trading.md) - Trading operations
- [Market Data API Reference](market-data.md) - Market data types
- [Advanced Orders API Reference](advanced-orders.md) - Order types