digdigdig3/core/traits/
positions.rs

1//! # Positions — Futures / perpetual position management
2//!
3//! All position mutations go through `modify_position` via `PositionModification` enum.
4
5use async_trait::async_trait;
6
7use crate::core::types::{
8    AccountType, ExchangeResult, FundingRate, Position,
9    PositionModification, PositionQuery,
10    OpenInterest, MarkPrice, ClosedPnlRecord, LongShortRatio,
11};
12
13use super::ExchangeIdentity;
14
15/// Positions — 22/24 exchanges.
16///
17/// Spot-only exchanges (Bitstamp, Gemini) do not implement this trait.
18/// For all others, positions represent open perpetual/futures exposures.
19///
20/// All position mutations are handled through `modify_position` using the
21/// `PositionModification` fat enum. Connectors match only the variants
22/// they support natively.
23///
24/// Authentication is **required** for all methods in this trait.
25#[async_trait]
26pub trait Positions: ExchangeIdentity {
27    /// Get open positions, optionally filtered to a single symbol.
28    ///
29    /// `query.symbol = None` returns all open positions across all symbols.
30    async fn get_positions(&self, query: PositionQuery) -> ExchangeResult<Vec<Position>>;
31
32    /// Get the current funding rate for a perpetual contract symbol.
33    ///
34    /// Returns the current rate, the next funding timestamp, and the
35    /// predicted rate if the exchange provides it.
36    async fn get_funding_rate(
37        &self,
38        symbol: &str,
39        account_type: AccountType,
40    ) -> ExchangeResult<FundingRate>;
41
42    /// Modify a position — leverage, margin mode, add/remove margin,
43    /// TP/SL, or close.
44    ///
45    /// The connector matches the `PositionModification` variant it supports.
46    /// Unsupported variants MUST return `ExchangeError::UnsupportedOperation`.
47    /// Connectors MUST NOT simulate missing features by composing other methods.
48    async fn modify_position(&self, req: PositionModification) -> ExchangeResult<()>;
49
50    /// Get open interest for a perpetual/futures symbol.
51    ///
52    /// Returns the total notional open interest and optionally the USD value.
53    ///
54    /// Default implementation returns `UnsupportedOperation`.
55    ///
56    /// ~18/24: Binance Futures, Bybit, OKX, KuCoin, GateIO, Bitget, BingX,
57    /// Phemex, MEXC, HTX, CryptoCom, Deribit, HyperLiquid, Lighter,
58    /// Paradex, dYdX, Coinglass (data provider).
59    async fn get_open_interest(
60        &self,
61        symbol: &str,
62        account_type: AccountType,
63    ) -> ExchangeResult<OpenInterest> {
64        let _ = (symbol, account_type);
65        Err(crate::core::types::ExchangeError::UnsupportedOperation(
66            "get_open_interest not implemented".into(),
67        ))
68    }
69
70    /// Get the current mark price (and optionally index price + funding rate)
71    /// for a perpetual/futures symbol.
72    ///
73    /// Default implementation returns `UnsupportedOperation`.
74    ///
75    /// ~18/24: all perpetuals-capable exchanges.
76    async fn get_mark_price(
77        &self,
78        symbol: &str,
79    ) -> ExchangeResult<MarkPrice> {
80        let _ = symbol;
81        Err(crate::core::types::ExchangeError::UnsupportedOperation(
82            "get_mark_price not implemented".into(),
83        ))
84    }
85
86    /// Get the closed position P&L history.
87    ///
88    /// Returns realized P&L records for positions that have been closed,
89    /// optionally filtered by symbol and time range.
90    ///
91    /// Default implementation returns `UnsupportedOperation`.
92    ///
93    /// ~12/24: Bybit, OKX, Binance Futures, KuCoin, GateIO, Bitget, BingX,
94    /// Phemex, Deribit, HyperLiquid, Paradex, dYdX.
95    async fn get_closed_pnl(
96        &self,
97        symbol: Option<&str>,
98        start_time: Option<u64>,
99        end_time: Option<u64>,
100        limit: Option<u32>,
101    ) -> ExchangeResult<Vec<ClosedPnlRecord>> {
102        let _ = (symbol, start_time, end_time, limit);
103        Err(crate::core::types::ExchangeError::UnsupportedOperation(
104            "get_closed_pnl not implemented".into(),
105        ))
106    }
107
108    /// Get the long/short account ratio for a symbol.
109    ///
110    /// Returns the proportion of accounts (or notional) that are long vs short
111    /// at the given moment. A market sentiment indicator.
112    ///
113    /// Default implementation returns `UnsupportedOperation`.
114    ///
115    /// ~8/24: Binance Futures, Bybit, OKX, KuCoin Futures, Bitget, BingX,
116    /// GateIO, HTX.
117    async fn get_long_short_ratio(
118        &self,
119        symbol: &str,
120        account_type: AccountType,
121    ) -> ExchangeResult<LongShortRatio> {
122        let _ = (symbol, account_type);
123        Err(crate::core::types::ExchangeError::UnsupportedOperation(
124            "get_long_short_ratio not implemented".into(),
125        ))
126    }
127}
digdigdig3/core/traits/positions.rs

digdigdig3/core/traits/
positions.rs
