nautilus_execution/client/mod.rs
1// -------------------------------------------------------------------------------------------------
2// Copyright (C) 2015-2025 Nautech Systems Pty Ltd. All rights reserved.
3// https://nautechsystems.io
4//
5// Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6// You may not use this file except in compliance with the License.
7// You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Execution client implementations for trading venue connectivity.
17
18use nautilus_common::messages::execution::{
19 BatchCancelOrders, CancelAllOrders, CancelOrder, GenerateFillReports,
20 GenerateOrderStatusReport, GeneratePositionReports, ModifyOrder, QueryAccount, QueryOrder,
21 SubmitOrder, SubmitOrderList,
22};
23use nautilus_core::UnixNanos;
24use nautilus_model::{
25 accounts::AccountAny,
26 enums::OmsType,
27 identifiers::{AccountId, ClientId, Venue},
28 reports::{ExecutionMassStatus, FillReport, OrderStatusReport, PositionStatusReport},
29 types::{AccountBalance, MarginBalance},
30};
31
32pub mod base;
33
34pub trait ExecutionClient {
35 fn is_connected(&self) -> bool;
36 fn client_id(&self) -> ClientId;
37 fn account_id(&self) -> AccountId;
38 fn venue(&self) -> Venue;
39 fn oms_type(&self) -> OmsType;
40 fn get_account(&self) -> Option<AccountAny>;
41
42 /// Generates and publishes the account state event.
43 ///
44 /// # Errors
45 ///
46 /// Returns an error if generating the account state fails.
47 fn generate_account_state(
48 &self,
49 balances: Vec<AccountBalance>,
50 margins: Vec<MarginBalance>,
51 reported: bool,
52 ts_event: UnixNanos,
53 ) -> anyhow::Result<()>;
54
55 /// Starts the execution client.
56 ///
57 /// # Errors
58 ///
59 /// Returns an error if the client fails to start.
60 fn start(&mut self) -> anyhow::Result<()>;
61
62 /// Stops the execution client.
63 ///
64 /// # Errors
65 ///
66 /// Returns an error if the client fails to stop.
67 fn stop(&mut self) -> anyhow::Result<()>;
68
69 /// Submits a single order command to the execution venue.
70 ///
71 /// # Errors
72 ///
73 /// Returns an error if submission fails.
74 fn submit_order(&self, cmd: &SubmitOrder) -> anyhow::Result<()>;
75
76 /// Submits a list of orders to the execution venue.
77 ///
78 /// # Errors
79 ///
80 /// Returns an error if submission fails.
81 fn submit_order_list(&self, cmd: &SubmitOrderList) -> anyhow::Result<()>;
82
83 /// Modifies an existing order.
84 ///
85 /// # Errors
86 ///
87 /// Returns an error if modification fails.
88 fn modify_order(&self, cmd: &ModifyOrder) -> anyhow::Result<()>;
89
90 /// Cancels a specific order.
91 ///
92 /// # Errors
93 ///
94 /// Returns an error if cancellation fails.
95 fn cancel_order(&self, cmd: &CancelOrder) -> anyhow::Result<()>;
96
97 /// Cancels all orders.
98 ///
99 /// # Errors
100 ///
101 /// Returns an error if cancellation fails.
102 fn cancel_all_orders(&self, cmd: &CancelAllOrders) -> anyhow::Result<()>;
103
104 /// Cancels a batch of orders.
105 ///
106 /// # Errors
107 ///
108 /// Returns an error if batch cancellation fails.
109 fn batch_cancel_orders(&self, cmd: &BatchCancelOrders) -> anyhow::Result<()>;
110
111 /// Queries the status of an account.
112 ///
113 /// # Errors
114 ///
115 /// Returns an error if the query fails.
116 fn query_account(&self, cmd: &QueryAccount) -> anyhow::Result<()>;
117
118 /// Queries the status of an order.
119 ///
120 /// # Errors
121 ///
122 /// Returns an error if the query fails.
123 fn query_order(&self, cmd: &QueryOrder) -> anyhow::Result<()>;
124}
125
126pub trait LiveExecutionClient: ExecutionClient {
127 /// Establishes a connection for live execution.
128 ///
129 /// # Errors
130 ///
131 /// Returns an error if connection fails.
132 fn connect(&mut self) -> anyhow::Result<()>;
133
134 /// Disconnects the live execution client.
135 ///
136 /// # Errors
137 ///
138 /// Returns an error if disconnection fails.
139 fn disconnect(&mut self) -> anyhow::Result<()>;
140
141 /// Generates a single order status report.
142 ///
143 /// # Errors
144 ///
145 /// Returns an error if report generation fails.
146 fn generate_order_status_report(
147 &self,
148 cmd: &GenerateOrderStatusReport,
149 ) -> anyhow::Result<Option<OrderStatusReport>>;
150
151 /// Generates multiple order status reports.
152 ///
153 /// # Errors
154 ///
155 /// Returns an error if report generation fails.
156 fn generate_order_status_reports(
157 &self,
158 cmd: &GenerateOrderStatusReport,
159 ) -> anyhow::Result<Vec<OrderStatusReport>>;
160
161 /// Generates fill reports based on execution results.
162 ///
163 /// # Errors
164 ///
165 /// Returns an error if fill report generation fails.
166 fn generate_fill_reports(&self, report: GenerateFillReports)
167 -> anyhow::Result<Vec<FillReport>>;
168
169 /// Generates position status reports.
170 ///
171 /// # Errors
172 ///
173 /// Returns an error if generation fails.
174 fn generate_position_status_reports(
175 &self,
176 cmd: &GeneratePositionReports,
177 ) -> anyhow::Result<Vec<PositionStatusReport>>;
178
179 /// Generates mass status for executions.
180 ///
181 /// # Errors
182 ///
183 /// Returns an error if status generation fails.
184 fn generate_mass_status(
185 &self,
186 lookback_mins: Option<u64>,
187 ) -> anyhow::Result<Option<ExecutionMassStatus>>;
188}