Skip to main content

nautilus_polymarket/python/
positions.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 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//! Python bindings for Deposit Wallet position operations.
17
18use std::sync::Arc;
19
20use nautilus_core::{env::get_or_env_var, python::to_pyvalue_err, string::secret::SecretString};
21use nautilus_network::websocket::proxy::ProxyUrl;
22use pyo3::prelude::*;
23use rust_decimal::Decimal;
24
25use crate::{
26    common::credential::{EvmPrivateKey, RelayerApiKey, credential_env_vars},
27    positions::{
28        PolymarketPositionClient, PolymarketPositionOutcome, PolymarketPositionTransaction,
29    },
30};
31
32/// Terminal result of a Polymarket split, merge, or redeem operation.
33#[pyclass(
34    module = "nautilus_trader.adapters.polymarket",
35    name = "PolymarketPositionOutcome",
36    frozen
37)]
38#[pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.adapters.polymarket")]
39#[derive(Clone, Debug)]
40pub struct PyPolymarketPositionOutcome {
41    inner: PolymarketPositionOutcome,
42}
43
44#[pymethods]
45#[pyo3_stub_gen::derive::gen_stub_pymethods]
46impl PyPolymarketPositionOutcome {
47    /// Relayer terminal status: `confirmed`, `failed`, or `invalid`.
48    #[getter]
49    fn status(&self) -> &'static str {
50        match self.inner {
51            PolymarketPositionOutcome::Confirmed { .. } => "confirmed",
52            PolymarketPositionOutcome::Failed { .. } => "failed",
53            PolymarketPositionOutcome::Invalid { .. } => "invalid",
54        }
55    }
56
57    /// Relayer transaction identifier.
58    #[getter]
59    fn transaction_id(&self) -> &str {
60        match &self.inner {
61            PolymarketPositionOutcome::Confirmed { transaction_id, .. }
62            | PolymarketPositionOutcome::Failed { transaction_id, .. }
63            | PolymarketPositionOutcome::Invalid { transaction_id, .. } => transaction_id,
64        }
65    }
66
67    /// On-chain transaction hash when the Relayer supplied one.
68    #[getter]
69    fn transaction_hash(&self) -> Option<&str> {
70        match &self.inner {
71            PolymarketPositionOutcome::Confirmed {
72                transaction_hash, ..
73            }
74            | PolymarketPositionOutcome::Failed {
75                transaction_hash, ..
76            } => transaction_hash.as_deref(),
77            PolymarketPositionOutcome::Invalid { .. } => None,
78        }
79    }
80
81    /// Relayer error detail when present.
82    #[getter]
83    fn error_msg(&self) -> Option<&str> {
84        match &self.inner {
85            PolymarketPositionOutcome::Failed { error_msg, .. }
86            | PolymarketPositionOutcome::Invalid { error_msg, .. } => error_msg.as_deref(),
87            PolymarketPositionOutcome::Confirmed { .. } => None,
88        }
89    }
90
91    fn __repr__(&self) -> String {
92        format!(
93            "PolymarketPositionOutcome(status='{}', transaction_id='{}', transaction_hash={:?}, error_msg={:?})",
94            self.status(),
95            self.transaction_id(),
96            self.transaction_hash(),
97            self.error_msg(),
98        )
99    }
100}
101
102/// Submitted position operation that can be polled to a terminal Relayer state.
103#[pyclass(
104    module = "nautilus_trader.adapters.polymarket",
105    name = "PolymarketPositionTransaction"
106)]
107#[pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.adapters.polymarket")]
108#[derive(Debug)]
109pub struct PyPolymarketPositionTransaction {
110    transaction_id: String,
111    inner: Option<PolymarketPositionTransaction>,
112}
113
114#[pymethods]
115#[pyo3_stub_gen::derive::gen_stub_pymethods]
116impl PyPolymarketPositionTransaction {
117    /// Relayer transaction identifier returned at submit time.
118    #[getter]
119    fn transaction_id(&self) -> &str {
120        &self.transaction_id
121    }
122
123    /// Polls the Relayer until the transaction is confirmed, failed, or invalid.
124    fn wait<'py>(&mut self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
125        let inner = self
126            .inner
127            .take()
128            .ok_or_else(|| to_pyvalue_err("transaction wait() has already been consumed"))?;
129        pyo3_async_runtimes::tokio::future_into_py(py, async move {
130            let outcome = inner.wait().await.map_err(to_pyvalue_err)?;
131            Ok(PyPolymarketPositionOutcome { inner: outcome })
132        })
133    }
134
135    fn __repr__(&self) -> String {
136        match &self.inner {
137            Some(inner) => format!(
138                "PolymarketPositionTransaction(transaction_id='{}')",
139                inner.transaction_id()
140            ),
141            None => format!(
142                "PolymarketPositionTransaction(transaction_id='{}', consumed)",
143                self.transaction_id
144            ),
145        }
146    }
147}
148
149impl From<PolymarketPositionTransaction> for PyPolymarketPositionTransaction {
150    fn from(inner: PolymarketPositionTransaction) -> Self {
151        Self {
152            transaction_id: inner.transaction_id().to_string(),
153            inner: Some(inner),
154        }
155    }
156}
157
158/// Deposit Wallet client for split, merge, and redeem position operations.
159#[pyclass(
160    module = "nautilus_trader.adapters.polymarket",
161    name = "PolymarketPositionClient"
162)]
163#[pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.adapters.polymarket")]
164#[derive(Debug)]
165pub struct PyPolymarketPositionClient {
166    inner: Arc<PolymarketPositionClient>,
167}
168
169#[pymethods]
170#[pyo3_stub_gen::derive::gen_stub_pymethods]
171impl PyPolymarketPositionClient {
172    #[new]
173    #[pyo3(signature = (
174        private_key=None,
175        funder=None,
176        relayer_api_key=None,
177        relayer_api_key_address=None,
178        base_url_relayer=None,
179        base_url_clob=None,
180        timeout_secs=None,
181        proxy_url=None,
182        base_url_rpc=None
183    ))]
184    #[allow(
185        clippy::too_many_arguments,
186        reason = "Python constructor mirrors optional credential fields"
187    )]
188    fn py_new(
189        private_key: Option<String>,
190        funder: Option<String>,
191        relayer_api_key: Option<String>,
192        relayer_api_key_address: Option<String>,
193        base_url_relayer: Option<String>,
194        base_url_clob: Option<String>,
195        timeout_secs: Option<u64>,
196        proxy_url: Option<String>,
197        base_url_rpc: Option<String>,
198    ) -> PyResult<Self> {
199        let private_key = private_key.map(SecretString::from);
200        let relayer_api_key = relayer_api_key.map(SecretString::from);
201        let (_, _, _, private_key_var, funder_var) = credential_env_vars();
202
203        let private_key = match private_key.filter(|value| !value.expose_secret().trim().is_empty())
204        {
205            Some(value) => value,
206            None => get_or_env_var(None, private_key_var)
207                .map(SecretString::from)
208                .map_err(to_pyvalue_err)?,
209        };
210
211        let private_key =
212            EvmPrivateKey::new(private_key.expose_secret()).map_err(to_pyvalue_err)?;
213
214        let funder = match funder.filter(|value| !value.trim().is_empty()) {
215            Some(value) => value,
216            None => get_or_env_var(None, funder_var).map_err(to_pyvalue_err)?,
217        };
218
219        let relayer_api_key = RelayerApiKey::resolve(relayer_api_key, relayer_api_key_address)
220            .map_err(to_pyvalue_err)?;
221        let proxy_url = proxy_url
222            .filter(|value| !value.trim().is_empty())
223            .map(ProxyUrl::parse)
224            .transpose()
225            .map_err(to_pyvalue_err)?;
226        let mut inner = PolymarketPositionClient::new(
227            &private_key,
228            &funder,
229            relayer_api_key,
230            base_url_relayer,
231            base_url_clob,
232            timeout_secs,
233            proxy_url,
234        )
235        .map_err(to_pyvalue_err)?;
236
237        if let Some(url) = base_url_rpc {
238            inner = inner.with_rpc_url(url);
239        }
240
241        Ok(Self {
242            inner: Arc::new(inner),
243        })
244    }
245
246    /// Approves ExchangeV3 trading from the Deposit Wallet holding the assets.
247    ///
248    /// `collateral_limit` is an explicit pUSD limit covering BUY spend plus fees. The same batch
249    /// enables ExchangeV3 to transfer V2 positions for SELL orders. It does not redeem positions.
250    /// The Relayer requires unlimited ExchangeV3 approvals and rejects this bounded request.
251    /// V2 trading from a Deposit Wallet therefore requires existing approvals.
252    ///
253    /// # Errors
254    ///
255    /// Returns an error if the limit is invalid, wallet verification fails, or Relayer submission
256    /// is rejected or ambiguous. A pending wallet submission must be reconciled before retrying.
257    #[pyo3(name = "approve_v2_trading")]
258    fn py_approve_v2_trading<'py>(
259        &self,
260        py: Python<'py>,
261        #[pyo3(from_py_with = extract_amount)] collateral_limit: Decimal,
262    ) -> PyResult<Bound<'py, PyAny>> {
263        let inner = self.inner.clone();
264        pyo3_async_runtimes::tokio::future_into_py(py, async move {
265            let tx = inner
266                .approve_v2_trading(collateral_limit)
267                .await
268                .map_err(to_pyvalue_err)?;
269            Ok(PyPolymarketPositionTransaction::from(tx))
270        })
271    }
272
273    /// Splits `amount` pUSD into a complete set of outcome tokens.
274    fn split_position<'py>(
275        &self,
276        py: Python<'py>,
277        condition_id: String,
278        #[pyo3(from_py_with = extract_amount)] amount: Decimal,
279    ) -> PyResult<Bound<'py, PyAny>> {
280        let inner = self.inner.clone();
281        pyo3_async_runtimes::tokio::future_into_py(py, async move {
282            let tx = inner
283                .split_position(&condition_id, amount)
284                .await
285                .map_err(to_pyvalue_err)?;
286            Ok(PyPolymarketPositionTransaction::from(tx))
287        })
288    }
289
290    /// Merges `amount` complete sets of outcome tokens back into pUSD.
291    fn merge_positions<'py>(
292        &self,
293        py: Python<'py>,
294        condition_id: String,
295        #[pyo3(from_py_with = extract_amount)] amount: Decimal,
296    ) -> PyResult<Bound<'py, PyAny>> {
297        let inner = self.inner.clone();
298        pyo3_async_runtimes::tokio::future_into_py(py, async move {
299            let tx = inner
300                .merge_positions(&condition_id, amount)
301                .await
302                .map_err(to_pyvalue_err)?;
303            Ok(PyPolymarketPositionTransaction::from(tx))
304        })
305    }
306
307    /// Redeems an explicit six-decimal share amount of V2 outcome index `0` or `1`.
308    ///
309    /// The index is the position ID's final byte, independent of CLOB token-array order.
310    /// Reverted or unavailable payout reads fail before submission. Zero losing payouts are valid.
311    fn redeem_position<'py>(
312        &self,
313        py: Python<'py>,
314        condition_id: String,
315        outcome_index: u8,
316        #[pyo3(from_py_with = extract_amount)] amount: Decimal,
317    ) -> PyResult<Bound<'py, PyAny>> {
318        let inner = self.inner.clone();
319        pyo3_async_runtimes::tokio::future_into_py(py, async move {
320            let tx = inner
321                .redeem_position(&condition_id, outcome_index, amount)
322                .await
323                .map_err(to_pyvalue_err)?;
324            Ok(PyPolymarketPositionTransaction::from(tx))
325        })
326    }
327
328    /// Redeems both CTF binary outcome balances for a resolved market.
329    fn redeem_positions<'py>(
330        &self,
331        py: Python<'py>,
332        condition_id: String,
333    ) -> PyResult<Bound<'py, PyAny>> {
334        let inner = self.inner.clone();
335        pyo3_async_runtimes::tokio::future_into_py(py, async move {
336            let tx = inner
337                .redeem_positions(&condition_id)
338                .await
339                .map_err(to_pyvalue_err)?;
340            Ok(PyPolymarketPositionTransaction::from(tx))
341        })
342    }
343
344    fn redeem_positions_batch<'py>(
345        &self,
346        py: Python<'py>,
347        condition_ids: Vec<String>,
348    ) -> PyResult<Bound<'py, PyAny>> {
349        let inner = self.inner.clone();
350        pyo3_async_runtimes::tokio::future_into_py(py, async move {
351            let condition_ids = condition_ids.iter().map(String::as_str).collect::<Vec<_>>();
352            let tx = inner
353                .redeem_positions_batch(&condition_ids)
354                .await
355                .map_err(to_pyvalue_err)?;
356            Ok(PyPolymarketPositionTransaction::from(tx))
357        })
358    }
359}
360
361fn extract_amount(value: &Bound<'_, PyAny>) -> PyResult<Decimal> {
362    let amount: Decimal = value.extract()?;
363    if !amount.into_pyobject(value.py())?.eq(value)? {
364        return Err(to_pyvalue_err("amount cannot be represented exactly"));
365    }
366
367    Ok(amount)
368}
369
370#[cfg(test)]
371mod tests {
372    use pyo3::{exceptions::PyValueError, types::PyDict};
373    use rstest::rstest;
374    use rust_decimal_macros::dec;
375
376    use super::*;
377
378    #[rstest]
379    #[case("split_position")]
380    #[case("merge_positions")]
381    #[case("redeem_position")]
382    fn test_position_amount_rejects_rounding(#[case] method: &str) {
383        Python::initialize();
384        Python::attach(|py| {
385            let kwargs = PyDict::new(py);
386            kwargs
387                .set_item(
388                    "private_key",
389                    "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
390                )
391                .unwrap();
392            kwargs
393                .set_item("funder", "0x1111111111111111111111111111111111111111")
394                .unwrap();
395            kwargs
396                .set_item("relayer_api_key", "dummy-relayer-key")
397                .unwrap();
398            kwargs
399                .set_item(
400                    "relayer_api_key_address",
401                    "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
402                )
403                .unwrap();
404            let client = py
405                .get_type::<PyPolymarketPositionClient>()
406                .call((), Some(&kwargs))
407                .unwrap();
408            let amount = py
409                .import("decimal")
410                .unwrap()
411                .getattr("Decimal")
412                .unwrap()
413                .call1(("1.00000000000000000000000000001",))
414                .unwrap();
415            let args = PyDict::new(py);
416            args.set_item(
417                "condition_id",
418                "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
419            )
420            .unwrap();
421            args.set_item("amount", amount).unwrap();
422            if method == "redeem_position" {
423                args.set_item("outcome_index", 1).unwrap();
424            }
425
426            let error = client.call_method(method, (), Some(&args)).unwrap_err();
427            assert!(error.is_instance_of::<PyValueError>(py));
428            assert!(
429                error
430                    .to_string()
431                    .contains("amount cannot be represented exactly")
432            );
433        });
434    }
435
436    #[rstest]
437    #[case("1.234567", dec!(1.234567))]
438    #[case("1.00000000000000000000000000000", dec!(1))]
439    #[case("1E-6", dec!(0.000001))]
440    #[case("1E+20", dec!(100000000000000000000))]
441    fn test_extract_amount_preserves_exact_values(#[case] input: &str, #[case] expected: Decimal) {
442        Python::initialize();
443        Python::attach(|py| {
444            let amount = py
445                .import("decimal")
446                .unwrap()
447                .getattr("Decimal")
448                .unwrap()
449                .call1((input,))
450                .unwrap();
451            assert_eq!(extract_amount(&amount).unwrap(), expected);
452        });
453    }
454}