polyester/models/
trading.rs

1//! Trading read/write models (Go `models/trading.go` parity).
2
3use crate::types::{AssetAmount, Price, Quantity};
4use buffa_types::google::protobuf::Timestamp;
5
6#[derive(Debug, Clone, PartialEq, Eq)]
7pub struct Order {
8    pub order_id: String,
9    pub symbol_id: u32,
10    pub client_order_id: String,
11    pub side: String,
12    pub status: String,
13    pub order_type: String,
14    pub tif: String,
15    pub orig_qty: Option<Quantity>,
16    pub cum_qty: Option<Quantity>,
17    pub leaves_qty: Option<Quantity>,
18    pub price: Option<Price>,
19    pub avg_px: Option<Price>,
20    pub created_ts_ns: String,
21    pub version: u32,
22    pub post_only: bool,
23    /// Asset selected to pay fees: `quote`, `base`, or an
24    /// `UNKNOWN(<number>)` forward-compatible enum value.
25    pub fee_asset: String,
26    /// Hard all-in quote debit submitted with quote-budget sizing, when used.
27    pub submitted_max_quote_debit_scaled: Option<i64>,
28    /// Attached risk policy when requested via `include_attached_risk`.
29    pub attached_risk: Option<AttachedRisk>,
30}
31
32#[derive(Debug, Clone, PartialEq, Eq)]
33pub struct OrdersList {
34    pub orders: Vec<Order>,
35    pub next_page_token: String,
36}
37
38#[derive(Debug, Clone, PartialEq, Eq)]
39pub struct OrderMutationResult {
40    pub status: String,
41    pub order_id: String,
42    pub client_order_id: String,
43    /// Gross base quantity resolved by the admission service.
44    pub resolved_base_qty: Option<Quantity>,
45    /// Hard all-in quote debit submitted with quote-budget sizing, when used.
46    pub submitted_max_quote_debit_scaled: Option<i64>,
47}
48
49#[derive(Debug, Clone, PartialEq, Eq)]
50pub struct GetOrderResult {
51    pub order: Option<Order>,
52    pub trades: Vec<UserTrade>,
53}
54
55#[derive(Debug, Clone, PartialEq, Eq)]
56pub struct UserTrade {
57    pub symbol_id: u32,
58    pub match_id: String,
59    pub order_id: String,
60    pub side: String,
61    pub is_maker: bool,
62    pub price: Option<Price>,
63    pub qty: Option<Quantity>,
64    pub fee_scaled: String,
65    /// Asset used to pay the fee: `quote`, `base`, or an
66    /// `UNKNOWN(<number>)` forward-compatible enum value.
67    pub fee_asset: String,
68    pub referral_share_scaled: String,
69    pub ts_ns: String,
70}
71
72#[derive(Debug, Clone, PartialEq, Eq)]
73pub struct UserTradesList {
74    pub trades: Vec<UserTrade>,
75    pub next_page_token: String,
76}
77
78#[derive(Debug, Clone, PartialEq, Eq)]
79pub struct ModifyOrderResult {
80    pub action_taken: String,
81    pub old_order_id: String,
82    pub final_order_id: String,
83    pub code: String,
84}
85
86#[derive(Debug, Clone, PartialEq, Eq)]
87pub struct CancelAllOrdersResult {
88    pub status: String,
89    pub matched_orders: u32,
90    pub submitted_cancels: u32,
91    pub failed_cancels: u32,
92}
93
94#[derive(Debug, Clone, PartialEq, Eq)]
95pub struct BatchCreateResultItem {
96    pub status: String,
97    pub order_id: String,
98    pub client_order_id: String,
99    pub code: String,
100}
101
102#[derive(Debug, Clone, PartialEq, Eq)]
103pub struct BatchCreateOrdersResult {
104    pub results: Vec<BatchCreateResultItem>,
105    pub accepted_count: u32,
106    pub rejected_count: u32,
107}
108
109/// Identifies an order by exactly one of exchange order id or client order id.
110///
111/// Matches TypeScript/Go oneOf semantics for get/cancel/modify and batch items.
112#[derive(Debug, Clone, PartialEq, Eq)]
113pub enum OrderKey {
114    OrderId(String),
115    ClientOrderId(String),
116}
117
118#[derive(Debug, Clone, PartialEq, Eq)]
119pub struct BatchCancelItem {
120    pub key: OrderKey,
121    pub symbol_id: Option<u32>,
122}
123
124#[derive(Debug, Clone, PartialEq, Eq)]
125pub struct BatchCancelResultItem {
126    pub status: String,
127    pub order_id: String,
128    pub client_order_id: String,
129    pub code: String,
130}
131
132#[derive(Debug, Clone, PartialEq, Eq)]
133pub struct BatchCancelOrdersResult {
134    pub results: Vec<BatchCancelResultItem>,
135    pub accepted_count: u32,
136    pub rejected_count: u32,
137}
138
139#[derive(Debug, Clone, PartialEq, Eq)]
140pub struct BatchReplaceItem {
141    pub key: OrderKey,
142    pub new_price: Option<Price>,
143    pub new_qty: Option<Quantity>,
144    pub new_attached_risk: Option<AttachedRisk>,
145    pub new_client_order_id: Option<String>,
146}
147
148/// Typed single-order modify params.
149#[derive(Debug, Clone)]
150pub struct ModifyOrderParams {
151    pub symbol: String,
152    pub key: OrderKey,
153    pub subaccount_id: Option<u64>,
154    /// Optional mutation request id (API-required on the wire).
155    ///
156    /// When omitted or blank, the SDK generates a unique id (TypeScript/Go/Python parity).
157    /// Set a stable non-empty value when you may retry the same logical modification after an
158    /// ambiguous failure, and reuse that same value on retry. A blind retry that omits
159    /// `request_id` mints a *new* id and is not an idempotent replay.
160    pub request_id: Option<String>,
161    pub new_price: Option<Price>,
162    pub new_qty: Option<Quantity>,
163    pub new_attached_risk: Option<AttachedRisk>,
164    pub behavior: Option<String>,
165    pub new_client_order_id: Option<String>,
166}
167
168/// Price source requested for trigger evaluation.
169///
170/// Attached order risk currently evaluates against last trade and cannot
171/// encode a caller-selected source. Standalone triggers expose their own
172/// supported semantics.
173#[derive(Debug, Clone, Copy, PartialEq, Eq)]
174pub enum TriggerPriceSourceKind {
175    LastPrice,
176    IndexPrice,
177    MarkPrice,
178}
179
180/// Take-profit or stop-loss leg (trigger + optional LIMIT child).
181#[derive(Debug, Clone, PartialEq, Eq)]
182pub struct RiskLeg {
183    pub trigger_price: Price,
184    /// Deprecated for attached risk: any supplied value is rejected because
185    /// the wire contract always evaluates against last trade.
186    #[deprecated(
187        note = "attached risk always uses last trade; supplying trigger_price_source is rejected"
188    )]
189    pub trigger_price_source: Option<TriggerPriceSourceKind>,
190    pub order_type: Option<CreateOrderType>,
191    pub limit_price: Option<Price>,
192}
193
194/// Trailing-stop distance (exactly one of ticks or bps).
195#[derive(Debug, Clone, Copy, PartialEq, Eq)]
196pub enum TrailingDistance {
197    Ticks(i64),
198    Bps(i32),
199}
200
201/// Optional max slippage for trailing-stop MARKET children.
202#[derive(Debug, Clone, Copy, PartialEq, Eq)]
203pub enum MaxSlippage {
204    /// Quote ticks (proto field is int32).
205    Ticks(i32),
206    Bps(i32),
207}
208
209/// Trailing-stop attached-risk leg.
210#[derive(Debug, Clone, PartialEq, Eq)]
211pub struct TrailingStop {
212    pub distance: TrailingDistance,
213    pub activation_price: Option<Price>,
214    pub trigger_price_source: Option<TriggerPriceSourceKind>,
215    pub order_type: Option<CreateOrderType>,
216    pub max_slippage: Option<MaxSlippage>,
217}
218
219/// Typed attached risk policy for order create/modify (TP/SL/trailing).
220///
221/// Prefer this over raw proto/`map` escape hatches: trigger/limit prices use [`Price`].
222#[derive(Debug, Clone, Default, PartialEq, Eq)]
223pub struct AttachedRisk {
224    pub take_profit: Option<RiskLeg>,
225    pub stop_loss: Option<RiskLeg>,
226    pub trailing_stop: Option<TrailingStop>,
227    /// When true, take-profit and the stop leg form an OCO pair.
228    pub oco: bool,
229}
230
231/// Typed internal-transfer create params.
232#[derive(Debug, Clone)]
233pub struct CreateInternalTransferParams {
234    pub asset_id: u32,
235    pub quantity: AssetAmount,
236    pub idempotency_key: String,
237    pub subaccount_id: Option<u64>,
238    pub destination_account_id: Option<String>,
239    pub destination_subaccount_id: Option<String>,
240    pub destination_smart_account_address: Option<String>,
241    /// Input quantity scale when `quantity` does not carry one. Wire
242    /// `amount_e18` is always rescaled exactly to 18 decimals.
243    pub quantity_scale: Option<u32>,
244}
245
246/// Typed trading-withdraw create params.
247#[derive(Debug, Clone)]
248pub struct CreateTradingWithdrawParams {
249    pub asset_id: u32,
250    pub amount: AssetAmount,
251    pub payload_signature: Vec<u8>,
252    pub destination_address: String,
253    /// Stable key for this logical withdrawal. Persist it and reuse it for
254    /// every retry; generating a new key per attempt defeats deduplication.
255    pub idempotency_key: String,
256    /// Input amount scale when `amount` does not carry one. Wire `amount_e18`
257    /// is always rescaled exactly to 18 decimals.
258    pub amount_scale: Option<u32>,
259    /// Exact deadline covered by `payload_signature`. Required for this
260    /// precomputed-signature path.
261    pub deadline_ts_sec: Option<u64>,
262    /// Non-zero nonce included in the signed withdrawal payload.
263    pub nonce: u128,
264}
265
266/// API-key trading-withdraw params for SDK-owned payload construction/signing.
267#[derive(Debug, Clone)]
268pub struct CreateApiKeyTradingWithdrawParams {
269    pub asset_id: u32,
270    pub amount: AssetAmount,
271    pub destination_address: String,
272    /// Stable key for this logical withdrawal.
273    pub idempotency_key: String,
274    /// Input amount scale when `amount` does not carry one. Wire `amount_e18`
275    /// is always rescaled exactly to 18 decimals.
276    pub amount_scale: Option<u32>,
277    /// Optional explicit deadline. The SDK uses now + five minutes when absent.
278    pub deadline_ts_sec: Option<u64>,
279    /// Optional explicit nonce. The SDK generates a secure non-zero nonce when absent.
280    pub nonce: Option<u128>,
281}
282
283/// Typed wallet trading-withdraw create params.
284#[derive(Debug, Clone)]
285pub struct CreateWalletTradingWithdrawParams {
286    pub action: String,
287    pub asset_id: u32,
288    pub amount: AssetAmount,
289    pub idempotency_key: String,
290    pub payload_signature: Vec<u8>,
291    pub signer_wallet: String,
292    pub destination_chain_id: u64,
293    pub destination_address: String,
294    pub subaccount_id: Option<u64>,
295    /// Input amount scale when `amount` does not carry one. Wire `amount_e18`
296    /// is always rescaled exactly to 18 decimals.
297    pub amount_scale: Option<u32>,
298    /// Exact deadline covered by `payload_signature`. Required for this
299    /// precomputed-signature path.
300    pub deadline_ts_sec: Option<u64>,
301    /// Non-zero nonce included in the signed withdrawal payload.
302    pub nonce: u128,
303}
304
305#[derive(Debug, Clone, PartialEq, Eq)]
306pub struct BatchReplaceAdmissionItem {
307    pub item_index: u32,
308    pub status: String,
309    pub old_order_id: String,
310    pub client_order_id: String,
311    pub replacement_order_id: String,
312    pub code: String,
313}
314
315#[derive(Debug, Clone, PartialEq, Eq)]
316pub struct BatchReplaceOrdersResult {
317    pub batch_request_id: String,
318    pub status: String,
319    pub results: Vec<BatchReplaceAdmissionItem>,
320    pub accepted_count: u32,
321    pub rejected_count: u32,
322    pub accepted_ts_ns: u64,
323}
324
325#[derive(Debug, Clone, PartialEq, Eq)]
326pub struct BatchReplaceStatusItem {
327    pub item_index: u32,
328    pub phase: String,
329    pub old_order_id: String,
330    pub replacement_order_id: String,
331    pub order_status: String,
332    pub code: String,
333    pub updated_ts_ns: u64,
334}
335
336#[derive(Debug, Clone, PartialEq, Eq)]
337pub struct BatchReplaceStatusResult {
338    pub batch_request_id: String,
339    pub admission_status: String,
340    pub items: Vec<BatchReplaceStatusItem>,
341    pub accepted_count: u32,
342    pub rejected_count: u32,
343    pub accepted_ts_ns: u64,
344    pub updated_ts_ns: u64,
345}
346
347impl BatchReplaceStatusResult {
348    /// Returns true once every item has left admission processing.
349    ///
350    /// `working` means the replacement is live, not that it has reached an
351    /// execution terminal state. Continue polling/reconciling order state when
352    /// execution finality is required.
353    pub fn is_settled(&self) -> bool {
354        is_batch_replace_settled(self)
355    }
356}
357
358/// Returns true once every batch-replace item is `working`, `rejected`, or
359/// `terminal`. An empty status is not considered settled.
360pub fn is_batch_replace_settled(status: &BatchReplaceStatusResult) -> bool {
361    !status.items.is_empty()
362        && status
363            .items
364            .iter()
365            .all(|item| matches!(item.phase.as_str(), "working" | "rejected" | "terminal"))
366}
367
368#[derive(Debug, Clone, PartialEq, Eq)]
369pub struct CancelAllAfterResult {
370    pub status: String,
371    pub effective_timeout_sec: u32,
372    pub expires_at_ts_ns: String,
373}
374
375/// Options for [`crate::services::OrdersService::list_open_with`].
376#[derive(Debug, Clone, Default)]
377pub struct ListOpenOrdersOpts {
378    pub subaccount_id: Option<u64>,
379    pub page_token: Option<String>,
380    pub limit: Option<u32>,
381    pub include_attached_risk: bool,
382    pub include_attached_risk_state: bool,
383}
384
385/// Options for [`crate::services::OrdersService::list_history_with`].
386#[derive(Debug, Clone, Default)]
387pub struct ListOrderHistoryOpts {
388    pub subaccount_id: Option<u64>,
389    pub symbol: Option<String>,
390    pub symbol_id: Option<u32>,
391    pub page_token: Option<String>,
392    pub limit: Option<u32>,
393    pub include_attached_risk: bool,
394    pub include_attached_risk_state: bool,
395}
396
397/// Options for [`crate::services::OrdersService::get_with`].
398#[derive(Debug, Clone)]
399pub struct GetOrderOpts {
400    pub key: OrderKey,
401    pub subaccount_id: Option<u64>,
402    pub include_attached_risk: bool,
403    pub include_attached_risk_state: bool,
404}
405
406/// Params for [`crate::services::OrdersService::cancel_with`].
407#[derive(Debug, Clone)]
408pub struct CancelOrderParams {
409    pub key: OrderKey,
410    pub symbol: Option<String>,
411    pub symbol_id: Option<u32>,
412    pub subaccount_id: Option<u64>,
413}
414
415/// Options for [`crate::services::OrdersService::cancel_all_with`].
416#[derive(Debug, Clone, Default)]
417pub struct CancelAllOpts {
418    pub symbol: Option<String>,
419    pub dry_run: bool,
420    pub subaccount_id: Option<u64>,
421    pub side: Option<String>,
422    /// Optional mutation request id (API-required on the wire).
423    ///
424    /// When omitted or blank, the SDK generates a unique id (TypeScript/Go/Python parity).
425    /// Set a stable non-empty value when you may retry the same logical cancel-all after an
426    /// ambiguous failure, and reuse that same value on retry. A blind retry that omits
427    /// `request_id` mints a *new* id and is not an idempotent replay.
428    pub request_id: Option<String>,
429}
430
431#[derive(Debug, Clone)]
432pub struct CreateOrderParams {
433    pub symbol: String,
434    pub side: CreateSide,
435    pub order_type: CreateOrderType,
436    /// Base quantity. Set exactly one of this and `max_quote_debit_scaled`.
437    pub quantity: Option<Quantity>,
438    /// Hard all-in quote debit limit in the pair's quote quantity scale. Set
439    /// exactly one of this and `quantity`.
440    pub max_quote_debit_scaled: Option<i64>,
441    pub price: Option<Price>,
442    pub time_in_force: Option<CreateTimeInForce>,
443    /// Optional client order id (API-optional).
444    ///
445    /// Set a stable non-empty value when you may retry after an ambiguous failure
446    /// (`Error::mutation_outcome_unknown`), and reuse that same value on retry.
447    /// Omit (`None`) for one-shot creates where you will not reconcile by client id.
448    pub client_order_id: Option<String>,
449    pub subaccount_id: Option<u64>,
450    pub post_only: Option<bool>,
451    /// Client reference price for MARKET order reservation (price ticks domain).
452    pub market_client_ref_price: Option<Price>,
453    /// Fee asset. `Base` is valid only for BUY orders; SELL orders use `Quote`.
454    pub fee_asset: Option<FeeAsset>,
455    /// Self-trade prevention policy for this order.
456    pub self_trade_prevention: Option<OrderSelfTradePrevention>,
457    /// Optional market-order slippage guard.
458    pub market_max_slippage: Option<MaxSlippage>,
459    /// Optional TP/SL/trailing controls that arm after the parent fills.
460    pub attached_risk: Option<AttachedRisk>,
461}
462
463#[derive(Debug, Clone, Copy, PartialEq, Eq)]
464pub enum FeeAsset {
465    Quote,
466    Base,
467}
468
469/// Legacy name for [`FeeAsset`].
470///
471/// `Received` was removed by the API contract; use `FeeAsset::Base` for a
472/// BUY fee deducted from received base quantity.
473#[deprecated(note = "renamed to FeeAsset; use FeeAsset::Base instead of the removed Received")]
474pub type OrderFeeSource = FeeAsset;
475
476/// Order inputs accepted by [`crate::services::OrdersService::preview`].
477#[derive(Debug, Clone)]
478pub struct PreviewOrderParams {
479    pub symbol: String,
480    pub side: CreateSide,
481    pub order_type: CreateOrderType,
482    /// Base quantity. Set exactly one of this and `max_quote_debit_scaled`.
483    pub quantity: Option<Quantity>,
484    /// Hard all-in quote debit limit in the pair's quote quantity scale. Set
485    /// exactly one of this and `quantity`.
486    pub max_quote_debit_scaled: Option<i64>,
487    pub price: Option<Price>,
488    pub time_in_force: Option<CreateTimeInForce>,
489    pub subaccount_id: Option<u64>,
490    pub post_only: Option<bool>,
491    pub market_client_ref_price: Option<Price>,
492    pub fee_asset: Option<FeeAsset>,
493    pub market_max_slippage: Option<MaxSlippage>,
494}
495
496#[derive(Debug, Clone, PartialEq, Eq)]
497pub struct PreviewOrderResult {
498    pub resolved_base_qty: Option<Quantity>,
499    pub price_bound: Option<Price>,
500    pub estimated_quote_debit_scaled: i64,
501    pub estimated_fee_scaled: i64,
502    pub estimated_net_base_qty: Option<Quantity>,
503    pub fee_asset: String,
504    pub fresh_at_ts_ns: u64,
505}
506
507#[derive(Debug, Clone, Copy, PartialEq, Eq)]
508pub enum OrderSelfTradePrevention {
509    ExpireTaker,
510    ExpireMaker,
511    ExpireBoth,
512}
513
514#[derive(Debug, Clone, Copy, PartialEq, Eq)]
515pub enum CreateSide {
516    Buy,
517    Sell,
518}
519
520#[derive(Debug, Clone, Copy, PartialEq, Eq)]
521pub enum CreateOrderType {
522    Limit,
523    Market,
524}
525
526#[derive(Debug, Clone, Copy, PartialEq, Eq)]
527pub enum CreateTimeInForce {
528    Gtc,
529    Ioc,
530    Fok,
531}
532
533#[derive(Debug, Clone, PartialEq, Eq)]
534pub struct InternalTransferResult {
535    pub request_id: String,
536    pub transfer_id: String,
537    pub asset_id: u32,
538    pub asset_code: String,
539    pub quantity: Option<AssetAmount>,
540}
541
542#[derive(Debug, Clone, PartialEq, Eq)]
543pub struct DepositAddress {
544    pub chain_id: u32,
545    pub deposit_address: String,
546}
547
548#[derive(Debug, Clone, PartialEq, Eq)]
549pub struct DepositAddressesList {
550    pub addresses: Vec<DepositAddress>,
551}
552
553#[derive(Debug, Clone, PartialEq, Eq)]
554pub struct WithdrawIntentResult {
555    pub intent_id: String,
556    pub status: String,
557    pub flow_id: String,
558}
559
560#[derive(Debug, Clone, PartialEq)]
561pub struct ApiKeySummary {
562    pub key_id: String,
563    pub label: String,
564    pub status: String,
565    pub public_key_ed25519: String,
566    pub created_at: Option<Timestamp>,
567    pub last_used_at: Option<Timestamp>,
568    pub updated_at: Option<Timestamp>,
569    /// Monotonic resource revision for conditional updates.
570    pub revision: u64,
571}
572
573#[derive(Debug, Clone, PartialEq)]
574pub struct ApiKeysList {
575    pub keys: Vec<ApiKeySummary>,
576}
577
578#[derive(Debug, Clone, PartialEq, Eq)]
579pub struct ResolvedAccount {
580    pub account_id: String,
581    pub username: String,
582    pub smart_account_address: String,
583}
584
585#[derive(Debug, Clone, PartialEq, Eq)]
586pub struct ResolvedAccountsList {
587    pub accounts: Vec<ResolvedAccount>,
588}
polyester/models/trading.rs

polyester/models/
trading.rs
