Skip to main content

nautilus_polymarket/http/
data_api.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//! Provides the HTTP client for the Polymarket Data API v2.
17
18use std::{collections::HashMap, result::Result as StdResult};
19
20use anyhow::Context;
21use nautilus_core::{UnixNanos, time::get_atomic_clock_realtime};
22use nautilus_model::{
23    data::TradeTick,
24    enums::AggressorSide,
25    identifiers::{InstrumentId, TradeId},
26    types::{Price, Quantity},
27};
28use nautilus_network::{
29    http::{HttpClient, HttpClientError, Method, create_standard_nautilus_headers},
30    websocket::proxy::ProxyUrl,
31};
32use rust_decimal::Decimal;
33
34use crate::{
35    common::{enums::PolymarketOrderSide, urls::data_api_url},
36    http::{
37        error::{Error, Result, decode_response},
38        models::{DataApiPage, DataApiPosition, DataApiTrade},
39        pagination::{
40            CollectAll, Completion, CursorProtocol, FetchOutcome, PageReducer, Paginator,
41        },
42    },
43};
44
45const PATH_POSITIONS: &str = "/v2/positions";
46const PATH_TRADES: &str = "/v2/trades";
47
48// Bounds retained trades when neither `start` nor `limit` is supplied; matches the
49// 10,000 rows the v1 offset ceiling served for the same request shape.
50const MAX_UNBOUNDED_WALK_ROWS: usize = 10_000;
51
52// Approximate venue retention horizon for diagnostics only
53const TRADE_RETENTION_SECONDS: i64 = 3 * 365 * 86_400;
54
55// Composite key for stabilizing same-second trades across paginated responses
56fn data_api_trade_sort_key(t: &DataApiTrade) -> (i64, &str, &str, &'static str, Decimal, Decimal) {
57    (
58        t.timestamp,
59        t.transaction_hash.as_str(),
60        t.asset.as_str(),
61        match t.side {
62            PolymarketOrderSide::Buy => "BUY",
63            PolymarketOrderSide::Sell => "SELL",
64        },
65        t.price,
66        t.size,
67    )
68}
69
70// Composite TradeId: tx hashes recur across multi-fill swaps, so a per-(tx,
71// asset) sequence is appended to disambiguate fills that would otherwise
72// collide on the last 36 chars of the transaction hash.
73pub(crate) fn build_polymarket_trade_id(transaction_hash: &str, asset: &str, seq: u32) -> String {
74    let hash_suffix = if transaction_hash.len() > 24 {
75        &transaction_hash[transaction_hash.len() - 24..]
76    } else {
77        transaction_hash
78    };
79    let asset_suffix = if asset.len() > 4 {
80        &asset[asset.len() - 4..]
81    } else {
82        asset
83    };
84    format!("{hash_suffix}-{asset_suffix}-{seq:06}")
85}
86
87fn validate_trade_page_scope(
88    rows: Vec<DataApiTrade>,
89    expected_condition_id: &str,
90) -> anyhow::Result<Vec<DataApiTrade>> {
91    match rows.iter().find(|trade| {
92        !trade
93            .condition_id
94            .eq_ignore_ascii_case(expected_condition_id)
95    }) {
96        Some(trade) => anyhow::bail!(
97            "Polymarket Data API returned trade for condition {} while requesting {expected_condition_id}",
98            trade.condition_id
99        ),
100        None => Ok(rows),
101    }
102}
103
104#[derive(Clone, Debug, Eq, PartialEq)]
105enum TradeTickStop {
106    CallerCapped,
107    OlderThanStart,
108    PageCapReached,
109}
110
111struct TradeTickReducer {
112    rows: Vec<DataApiTrade>,
113    instrument_id: InstrumentId,
114    condition_id: String,
115    token_id: String,
116    price_precision: u8,
117    size_precision: u8,
118    start: Option<UnixNanos>,
119    end: Option<UnixNanos>,
120    limit: Option<usize>,
121}
122
123impl PageReducer<DataApiTrade, anyhow::Error> for TradeTickReducer {
124    type Output = Vec<TradeTick>;
125    type Stop = TradeTickStop;
126
127    fn consume(&mut self, rows: Vec<DataApiTrade>) -> anyhow::Result<Option<Self::Stop>> {
128        // The v2 condition feed ignores start/end bounds and is served
129        // newest-first, so once an entire page precedes the requested start
130        // the remaining pages cannot contain matching rows.
131        let older_than_start = self.start.is_some_and(|start| {
132            let start_secs = (start.as_u64() / 1_000_000_000) as i64;
133            !rows.is_empty() && rows.iter().all(|trade| trade.timestamp < start_secs)
134        });
135
136        let end_secs = self.end.map(|end| (end.as_u64() / 1_000_000_000) as i64);
137        self.rows.extend(rows.into_iter().filter(|trade| {
138            trade.asset == self.token_id && end_secs.is_none_or(|end| trade.timestamp <= end)
139        }));
140
141        if older_than_start {
142            return Ok(Some(TradeTickStop::OlderThanStart));
143        }
144
145        let capped =
146            self.start.is_none() && self.limit.is_some_and(|target| self.rows.len() >= target);
147        if capped {
148            return Ok(Some(TradeTickStop::CallerCapped));
149        }
150
151        // End-only requests must traverse newer pages first, so this bounds
152        // retained history, not the number of requests.
153        let unbounded_capped = self.start.is_none()
154            && self.limit.is_none()
155            && self.rows.len() >= MAX_UNBOUNDED_WALK_ROWS;
156        Ok(unbounded_capped.then_some(TradeTickStop::PageCapReached))
157    }
158
159    fn finish(self, completion: &Completion<Self::Stop>) -> anyhow::Result<Self::Output> {
160        if let Some(start) = self.start
161            && matches!(completion, Completion::WireExhausted)
162            && start_predates_retention_window(
163                (start.as_u64() / 1_000_000_000) as i64,
164                (get_atomic_clock_realtime().get_time_ns().as_u64() / 1_000_000_000) as i64,
165            )
166        {
167            log::warn!(
168                "Polymarket Data API trades start predates the approximate three-year retention window for condition {}; results may be incomplete",
169                self.condition_id
170            );
171        }
172
173        let start_secs = self
174            .start
175            .map(|value| (value.as_u64() / 1_000_000_000) as i64);
176        let end_secs = self
177            .end
178            .map(|value| (value.as_u64() / 1_000_000_000) as i64);
179        let mut trades = parse_trade_ticks(
180            self.rows,
181            self.instrument_id,
182            &self.token_id,
183            self.price_precision,
184            self.size_precision,
185        )?;
186        trades.retain(|trade| {
187            let event_secs = trade.ts_event.as_u64() / 1_000_000_000;
188            start_secs.is_none_or(|start| event_secs >= start as u64)
189                && end_secs.is_none_or(|end| event_secs <= end as u64)
190        });
191
192        if let Some(target) = self.limit
193            && trades.len() > target
194        {
195            if self.start.is_some() {
196                trades.truncate(target);
197            } else {
198                trades.drain(..trades.len() - target);
199            }
200        }
201
202        Ok(trades)
203    }
204}
205
206/// Provides an unauthenticated HTTP client for the Polymarket Data API.
207///
208/// Used for fetching historical trade data from `GET /v2/trades`.
209#[derive(Debug, Clone)]
210pub struct PolymarketDataApiHttpClient {
211    client: HttpClient,
212    base_url: String,
213}
214
215impl PolymarketDataApiHttpClient {
216    /// Creates a new [`PolymarketDataApiHttpClient`].
217    ///
218    /// # Errors
219    ///
220    /// Returns an error if the HTTP client cannot be created.
221    pub fn new(base_url: Option<String>, timeout_secs: u64) -> StdResult<Self, HttpClientError> {
222        Self::new_with_proxy(base_url, timeout_secs, None)
223    }
224
225    /// Creates a new client with an optional validated proxy URL.
226    ///
227    /// # Errors
228    ///
229    /// Returns an error if the HTTP client cannot be created.
230    pub fn new_with_proxy(
231        base_url: Option<String>,
232        timeout_secs: u64,
233        proxy_url: Option<ProxyUrl>,
234    ) -> StdResult<Self, HttpClientError> {
235        let mut headers: HashMap<String, String> =
236            create_standard_nautilus_headers().into_iter().collect();
237        headers.insert("Content-Type".to_string(), "application/json".to_string());
238
239        Ok(Self {
240            client: HttpClient::builder()
241                .headers(headers)
242                .timeout_secs(timeout_secs)
243                .maybe_proxy_url(proxy_url.map(|url| url.expose().to_string()))
244                .build()?,
245            base_url: base_url
246                .unwrap_or_else(|| data_api_url().to_string())
247                .trim_end_matches('/')
248                .to_string(),
249        })
250    }
251
252    /// Fetches all positions for a user from the Data API v2.
253    ///
254    /// Walks `GET /v2/positions?user={address}` by cursor until the venue
255    /// reports no further pages. A short page never ends the walk; only a
256    /// `null` `next_cursor` does.
257    pub async fn get_positions(&self, user_address: &str) -> Result<Vec<DataApiPosition>> {
258        // v2 caps `limit` at 1000 and it only sizes the first page; the cursor
259        // carries the page size onward.
260        const PAGE_SIZE: u32 = 500;
261
262        let protocol = CursorProtocol::gamma(PATH_POSITIONS);
263        let paginator = Paginator::new(PATH_POSITIONS, protocol, CollectAll::new());
264        let completed = paginator
265            .run(
266                |position| async move {
267                    let page = self
268                        .get_positions_page(
269                            user_address,
270                            PAGE_SIZE,
271                            position.as_ref().map(|cursor| cursor.as_ref()),
272                        )
273                        .await?;
274                    Ok(FetchOutcome {
275                        rows: page.data,
276                        wire: page.pagination.next_cursor,
277                    })
278                },
279                |e| Error::decode(e.to_string()),
280            )
281            .await?;
282
283        match completed.completion {
284            Completion::WireExhausted => Ok(completed.output),
285            Completion::Stopped(never) => match never {},
286        }
287    }
288
289    async fn get_positions_page(
290        &self,
291        user_address: &str,
292        limit: u32,
293        cursor: Option<&str>,
294    ) -> Result<DataApiPage<DataApiPosition>> {
295        let mut params = vec![
296            ("user".to_string(), user_address.to_string()),
297            ("limit".to_string(), limit.to_string()),
298            ("filter_type".to_string(), "TOKENS".to_string()),
299            ("filter_amount".to_string(), "0".to_string()),
300            ("sort_by".to_string(), "TOKENS".to_string()),
301            ("sort_direction".to_string(), "DESC".to_string()),
302        ];
303
304        if let Some(cursor) = cursor {
305            params.push(("cursor".to_string(), cursor.to_string()));
306        }
307
308        let url = format!("{}{PATH_POSITIONS}", self.base_url);
309        let response = self
310            .client
311            .request_with_params(Method::GET, url, Some(&params), None, None, None, None)
312            .await
313            .map_err(Error::from_http_client)?;
314
315        decode_response(&response)
316    }
317
318    /// Fetches a single page of trades from the Data API v2 for the given
319    /// condition ID.
320    pub async fn get_trades(
321        &self,
322        condition_id: &str,
323        limit: Option<u32>,
324    ) -> Result<Vec<DataApiTrade>> {
325        Ok(self.get_trades_page(condition_id, limit, None).await?.data)
326    }
327
328    /// Fetches trades and converts them to [`TradeTick`] for the given instrument.
329    ///
330    /// Automatically walks all pages by cursor (up to `limit` if specified).
331    /// Filters by `token_id` (since the API returns trades for all outcomes of
332    /// the condition) and returns results in chronological order.
333    ///
334    /// The v2 condition feed serves a fixed three-year window and ignores
335    /// `start`/`end` bounds, so window filtering happens locally and the walk
336    /// stops as soon as an entire page precedes `start` (the feed is served
337    /// newest-first).
338    #[expect(clippy::too_many_arguments)]
339    pub async fn request_trade_ticks(
340        &self,
341        instrument_id: InstrumentId,
342        condition_id: &str,
343        token_id: &str,
344        price_precision: u8,
345        size_precision: u8,
346        start: Option<UnixNanos>,
347        end: Option<UnixNanos>,
348        limit: Option<u32>,
349    ) -> anyhow::Result<Vec<TradeTick>> {
350        // v2 caps `limit` at 1000; it sizes the first page and the cursor
351        // carries that size onward.
352        const PAGE_SIZE: u32 = 1000;
353
354        if let (Some(start), Some(end)) = (start, end)
355            && start > end
356        {
357            anyhow::bail!("start must not be later than end");
358        }
359
360        if limit == Some(0) {
361            anyhow::bail!("limit must be greater than zero");
362        }
363
364        let protocol = CursorProtocol::gamma(PATH_TRADES);
365
366        let reducer = TradeTickReducer {
367            rows: Vec::new(),
368            instrument_id,
369            condition_id: condition_id.to_string(),
370            token_id: token_id.to_string(),
371            price_precision,
372            size_precision,
373            start,
374            end,
375            limit: limit.map(|value| value as usize),
376        };
377        let paginator = Paginator::new(PATH_TRADES, protocol, reducer);
378        let completed = paginator
379            .run(
380                |position| async move {
381                    let page = self
382                        .get_trades_page(
383                            condition_id,
384                            Some(PAGE_SIZE),
385                            position.as_ref().map(|cursor| cursor.as_ref()),
386                        )
387                        .await
388                        .map_err(anyhow::Error::new)?;
389                    let rows = validate_trade_page_scope(page.data, condition_id)?;
390                    Ok::<_, anyhow::Error>(FetchOutcome {
391                        rows,
392                        wire: page.pagination.next_cursor,
393                    })
394                },
395                anyhow::Error::new,
396            )
397            .await?;
398
399        match completed.completion {
400            Completion::WireExhausted
401            | Completion::Stopped(TradeTickStop::CallerCapped | TradeTickStop::OlderThanStart) => {
402                Ok(completed.output)
403            }
404            Completion::Stopped(TradeTickStop::PageCapReached) => {
405                log::warn!(
406                    "Polymarket Data API trades walk for condition {condition_id} capped at {MAX_UNBOUNDED_WALK_ROWS} rows; returning newest partial results, bound the request with start or limit for more",
407                );
408                Ok(completed.output)
409            }
410        }
411    }
412
413    async fn get_trades_page(
414        &self,
415        condition_id: &str,
416        limit: Option<u32>,
417        cursor: Option<&str>,
418    ) -> Result<DataApiPage<DataApiTrade>> {
419        let mut params = vec![("condition".to_string(), condition_id.to_string())];
420
421        if let Some(limit) = limit {
422            params.push(("limit".to_string(), limit.to_string()));
423        }
424
425        if let Some(cursor) = cursor {
426            params.push(("cursor".to_string(), cursor.to_string()));
427        }
428
429        let url = format!("{}{PATH_TRADES}", self.base_url);
430        let response = self
431            .client
432            .request_with_params(Method::GET, url, Some(&params), None, None, None, None)
433            .await
434            .map_err(Error::from_http_client)?;
435
436        decode_response(&response)
437    }
438}
439
440fn start_predates_retention_window(start_secs: i64, now_secs: i64) -> bool {
441    start_secs < now_secs - TRADE_RETENTION_SECONDS
442}
443
444// Extracted from `request_trade_ticks` so the parse behavior can be
445// unit-tested without HTTP
446fn parse_trade_ticks(
447    mut data_api_trades: Vec<DataApiTrade>,
448    instrument_id: InstrumentId,
449    token_id: &str,
450    price_precision: u8,
451    size_precision: u8,
452) -> anyhow::Result<Vec<TradeTick>> {
453    // Composite sort to stabilize same-second trades across pages
454    data_api_trades.sort_by(|a, b| data_api_trade_sort_key(a).cmp(&data_api_trade_sort_key(b)));
455
456    let mut timestamp_counts: HashMap<u64, u32> = HashMap::new();
457    let mut tx_asset_counts: HashMap<(String, String), u32> = HashMap::new();
458    let mut trades: Vec<TradeTick> = Vec::new();
459
460    for t in data_api_trades {
461        if t.asset != token_id {
462            continue;
463        }
464
465        let price = Price::from_decimal_dp(t.price, price_precision).with_context(|| {
466            format!(
467                "failed to convert Data API trade price {} with precision {price_precision}",
468                t.price
469            )
470        })?;
471        let size = Quantity::from_decimal_dp(t.size, size_precision).with_context(|| {
472            format!(
473                "failed to convert Data API trade size {} with precision {size_precision}",
474                t.size
475            )
476        })?;
477        let aggressor_side = AggressorSide::from(t.side);
478
479        let base_ns = (t.timestamp as u64) * 1_000_000_000;
480        let occurrence = timestamp_counts.entry(base_ns).or_insert(0);
481        let tiebreaker = (*occurrence).min(999_999_999) as u64;
482        *occurrence += 1;
483        let ts_event = nautilus_core::UnixNanos::from(base_ns + tiebreaker);
484
485        let key = (t.transaction_hash.clone(), t.asset.clone());
486        let seq = *tx_asset_counts
487            .entry(key)
488            .and_modify(|n| *n += 1)
489            .or_insert(0);
490        let trade_id = TradeId::new(build_polymarket_trade_id(
491            &t.transaction_hash,
492            &t.asset,
493            seq,
494        ));
495
496        trades.push(TradeTick::new(
497            instrument_id,
498            price,
499            size,
500            aggressor_side,
501            trade_id,
502            ts_event,
503            ts_event,
504        ));
505    }
506
507    Ok(trades)
508}
509
510#[cfg(test)]
511mod tests {
512    use nautilus_model::{enums::AggressorSide, identifiers::InstrumentId};
513    use rstest::rstest;
514    use rust_decimal_macros::dec;
515
516    use super::*;
517    use crate::http::models::{DataApiPosition, DataApiTrade};
518
519    fn load_positions() -> Vec<DataApiPosition> {
520        let path = "test_data/data_api_positions_response.json";
521        let content = std::fs::read_to_string(path).expect("Failed to read test data");
522        let page: DataApiPage<DataApiPosition> =
523            serde_json::from_str(&content).expect("Failed to parse test data");
524        page.data
525    }
526
527    fn load_trades() -> Vec<DataApiTrade> {
528        // Constructed fixture retained for conversion, filtering, and ordering tests
529        let path = "test_data/data_api_trades_response.json";
530        let content = std::fs::read_to_string(path).expect("Failed to read test data");
531        let page: DataApiPage<DataApiTrade> =
532            serde_json::from_str(&content).expect("Failed to parse test data");
533        page.data
534    }
535
536    #[rstest]
537    #[case::before(99, true)]
538    #[case::at(100, false)]
539    #[case::after(101, false)]
540    fn test_start_predates_retention_window(#[case] start: i64, #[case] expected: bool) {
541        assert_eq!(
542            start_predates_retention_window(start, TRADE_RETENTION_SECONDS + 100),
543            expected,
544        );
545    }
546
547    #[rstest]
548    #[case::caller_limit(Some(2), TradeTickStop::CallerCapped)]
549    #[case::retained_cap(None, TradeTickStop::PageCapReached)]
550    fn test_trade_reducer_discards_irrelevant_rows(
551        #[case] limit: Option<usize>,
552        #[case] expected_stop: TradeTickStop,
553    ) {
554        let mut reducer = TradeTickReducer {
555            rows: Vec::new(),
556            instrument_id: test_instrument_id(),
557            condition_id: "0xcond".to_string(),
558            token_id: "token_aaa".to_string(),
559            price_precision: 2,
560            size_precision: 2,
561            start: None,
562            end: Some(UnixNanos::from(100_000_000_000_u64)),
563            limit,
564        };
565        let matching = make_trade(
566            100,
567            "0xmatch",
568            "token_aaa",
569            PolymarketOrderSide::Buy,
570            0.5,
571            2.0,
572        );
573        let newer = make_trade(
574            101,
575            "0xnew",
576            "token_aaa",
577            PolymarketOrderSide::Buy,
578            0.6,
579            3.0,
580        );
581        let other = make_trade(
582            99,
583            "0xother",
584            "token_bbb",
585            PolymarketOrderSide::Sell,
586            0.4,
587            4.0,
588        );
589
590        for _ in 0..12 {
591            let stop = reducer.consume(vec![newer.clone(); 1_000]).unwrap();
592            assert_eq!(stop, None);
593            assert_eq!(reducer.rows.len(), 0);
594        }
595
596        let stop = reducer
597            .consume(vec![newer, other, matching.clone()])
598            .unwrap();
599        assert_eq!(stop, None);
600        assert_eq!(reducer.rows.len(), 1);
601        assert_eq!(reducer.rows[0].transaction_hash, "0xmatch");
602
603        let target = limit.unwrap_or(MAX_UNBOUNDED_WALK_ROWS);
604        let stop = reducer.consume(vec![matching; target - 1]).unwrap();
605        assert_eq!(stop, Some(expected_stop));
606        assert_eq!(reducer.rows.len(), target);
607    }
608
609    #[rstest]
610    #[case::start_after_end(
611        Some(nautilus_core::UnixNanos::from(2_u64)),
612        Some(nautilus_core::UnixNanos::from(1_u64)),
613        None,
614        "start must not be later than end"
615    )]
616    #[case::zero_limit(None, None, Some(0), "limit must be greater than zero")]
617    #[tokio::test]
618    async fn test_request_trade_ticks_rejects_invalid_arguments(
619        #[case] start: Option<UnixNanos>,
620        #[case] end: Option<UnixNanos>,
621        #[case] limit: Option<u32>,
622        #[case] expected_error: &str,
623    ) {
624        let client = PolymarketDataApiHttpClient::new(None, 5).unwrap();
625
626        let error = client
627            .request_trade_ticks(
628                test_instrument_id(),
629                "0xcondition_test",
630                "token_aaa",
631                2,
632                2,
633                start,
634                end,
635                limit,
636            )
637            .await
638            .expect_err("invalid arguments must fail before any request");
639
640        assert_eq!(error.to_string(), expected_error);
641    }
642
643    #[rstest]
644    fn test_data_api_position_deserialization() {
645        let positions = load_positions();
646
647        assert_eq!(positions.len(), 4);
648        assert_eq!(positions[0].size, dec!(150.5));
649        assert_eq!(positions[0].avg_price, Some(dec!(0.55)));
650        assert_eq!(
651            positions[0].condition_id,
652            "0xc8f1cf5d4f26e0fd9c8fe89f2a7b3263b902cf14fde7bfccef525753bb492e47"
653        );
654    }
655
656    #[rstest]
657    fn test_data_api_trade_deserialization() {
658        let trades = load_trades();
659
660        assert_eq!(trades.len(), 3);
661
662        assert_eq!(
663            trades[0].asset,
664            "71321045863084981365469005770620412523470745398083994982746259498689308907982"
665        );
666        assert_eq!(
667            trades[0].condition_id,
668            "0xc8f1cf5d4f26e0fd9c8fe89f2a7b3263b902cf14fde7bfccef525753bb492e47"
669        );
670        assert_eq!(trades[0].price, dec!(0.55));
671        assert_eq!(trades[0].size, dec!(100.0));
672        assert_eq!(trades[0].timestamp, 1710000000);
673        assert_eq!(
674            trades[0].transaction_hash,
675            "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456"
676        );
677    }
678
679    #[rstest]
680    fn test_data_api_trade_ignores_extra_fields() {
681        let trades = load_trades();
682        // proxy_wallet, title, slug should be silently ignored
683        assert_eq!(trades.len(), 3);
684    }
685
686    #[rstest]
687    fn test_build_trade_ticks_filters_by_token_id() {
688        let trades = load_trades();
689        let instrument_id = InstrumentId::from(
690            "0xc8f1cf5d4f26e0fd9c8fe89f2a7b3263b902cf14fde7bfccef525753bb492e47-71321045863084981365469005770620412523470745398083994982746259498689308907982.POLYMARKET",
691        );
692        let token_id =
693            "71321045863084981365469005770620412523470745398083994982746259498689308907982";
694        let price_precision = 2u8;
695        let size_precision = 2u8;
696
697        let ticks: Vec<TradeTick> = trades
698            .into_iter()
699            .filter(|t| t.asset == token_id)
700            .map(|t| {
701                let price = Price::from_decimal_dp(t.price, price_precision).unwrap();
702                let size = Quantity::from_decimal_dp(t.size, size_precision).unwrap();
703                let aggressor_side = AggressorSide::from(t.side);
704                // TradeId max length is 36; tx hash is 66 chars, take last 36
705                let hash = &t.transaction_hash;
706                let trade_id_str = if hash.len() > 36 {
707                    &hash[hash.len() - 36..]
708                } else {
709                    hash.as_str()
710                };
711                let trade_id = TradeId::new(trade_id_str);
712                let ts_event = nautilus_core::UnixNanos::from(t.timestamp as u64 * 1_000_000_000);
713
714                TradeTick::new(
715                    instrument_id,
716                    price,
717                    size,
718                    aggressor_side,
719                    trade_id,
720                    ts_event,
721                    ts_event,
722                )
723            })
724            .collect();
725
726        // Should filter out the third trade (different asset)
727        assert_eq!(ticks.len(), 2);
728        assert_eq!(ticks[0].aggressor_side, AggressorSide::Buy);
729        assert_eq!(ticks[1].aggressor_side, AggressorSide::Sell);
730    }
731
732    #[rstest]
733    fn test_build_trade_ticks_chronological_order() {
734        let trades = load_trades();
735        let instrument_id = InstrumentId::from(
736            "0xc8f1cf5d4f26e0fd9c8fe89f2a7b3263b902cf14fde7bfccef525753bb492e47-71321045863084981365469005770620412523470745398083994982746259498689308907982.POLYMARKET",
737        );
738        let token_id =
739            "71321045863084981365469005770620412523470745398083994982746259498689308907982";
740
741        let mut ticks: Vec<TradeTick> = trades
742            .into_iter()
743            .filter(|t| t.asset == token_id)
744            .map(|t| {
745                let price = Price::from_decimal_dp(t.price, 2).unwrap();
746                let size = Quantity::from_decimal_dp(t.size, 2).unwrap();
747                let aggressor_side = AggressorSide::from(t.side);
748                // TradeId max length is 36; tx hash is 66 chars, take last 36
749                let hash = &t.transaction_hash;
750                let trade_id_str = if hash.len() > 36 {
751                    &hash[hash.len() - 36..]
752                } else {
753                    hash.as_str()
754                };
755                let trade_id = TradeId::new(trade_id_str);
756                let ts_event = nautilus_core::UnixNanos::from(t.timestamp as u64 * 1_000_000_000);
757
758                TradeTick::new(
759                    instrument_id,
760                    price,
761                    size,
762                    aggressor_side,
763                    trade_id,
764                    ts_event,
765                    ts_event,
766                )
767            })
768            .collect();
769
770        // Reverse to get chronological order (API returns newest-first)
771        ticks.reverse();
772
773        assert_eq!(ticks.len(), 2);
774        // First tick should be the older one (lower timestamp)
775        assert!(ticks[0].ts_event < ticks[1].ts_event);
776    }
777
778    fn make_trade(
779        timestamp: i64,
780        transaction_hash: &str,
781        asset: &str,
782        side: PolymarketOrderSide,
783        price: f64,
784        size: f64,
785    ) -> DataApiTrade {
786        DataApiTrade {
787            proxy_wallet: None,
788            asset: asset.to_string(),
789            condition_id: "0xcond".to_string(),
790            side,
791            price: Decimal::from_str_exact(&price.to_string()).unwrap(),
792            size: Decimal::from_str_exact(&size.to_string()).unwrap(),
793            timestamp,
794            title: None,
795            slug: None,
796            icon: None,
797            event_slug: None,
798            outcome: None,
799            outcome_index: None,
800            name: None,
801            pseudonym: None,
802            bio: None,
803            profile_image: None,
804            profile_image_optimized: None,
805            transaction_hash: transaction_hash.to_string(),
806        }
807    }
808
809    fn test_instrument_id() -> InstrumentId {
810        InstrumentId::from(
811            "0xc8f1cf5d4f26e0fd9c8fe89f2a7b3263b902cf14fde7bfccef525753bb492e47-71321045863084981365469005770620412523470745398083994982746259498689308907982.POLYMARKET",
812        )
813    }
814
815    #[rstest]
816    fn test_data_api_trade_sort_key_orders_pages_deterministically() {
817        let mut trades = [
818            make_trade(1729000005, "0xZ", "T", PolymarketOrderSide::Buy, 0.5, 1.0),
819            make_trade(1729000000, "0xC", "T", PolymarketOrderSide::Buy, 0.5, 1.0),
820            make_trade(1729000000, "0xA", "T", PolymarketOrderSide::Sell, 0.5, 1.0),
821            make_trade(1729000000, "0xB", "T", PolymarketOrderSide::Buy, 0.5, 1.0),
822        ];
823
824        trades.sort_by(|a, b| data_api_trade_sort_key(a).cmp(&data_api_trade_sort_key(b)));
825
826        let order: Vec<&str> = trades.iter().map(|t| t.transaction_hash.as_str()).collect();
827        assert_eq!(order, ["0xA", "0xB", "0xC", "0xZ"]);
828    }
829
830    #[rstest]
831    fn test_data_api_trade_sort_key_uses_full_composite_for_inner_ties() {
832        // Locks ordering on the (asset, side, price, size) tail of the key
833        let mut trades = [
834            // (ts, hash) all equal; tail differs across asset/side/price/size
835            make_trade(1, "0xH", "Tb", PolymarketOrderSide::Buy, 0.5, 1.0),
836            make_trade(1, "0xH", "Ta", PolymarketOrderSide::Sell, 0.5, 1.0),
837            make_trade(1, "0xH", "Ta", PolymarketOrderSide::Buy, 0.6, 1.0),
838            make_trade(1, "0xH", "Ta", PolymarketOrderSide::Buy, 0.5, 2.0),
839            make_trade(1, "0xH", "Ta", PolymarketOrderSide::Buy, 0.5, 1.0),
840        ];
841
842        trades.sort_by(|a, b| data_api_trade_sort_key(a).cmp(&data_api_trade_sort_key(b)));
843
844        // Sort key composite: (ts, hash, asset, side, price, size)
845        // Expected ordering across the five trades:
846        //   1. asset=Ta side=BUY  price=0.5 size=1.0 (lex-min on side first)
847        //   2. asset=Ta side=BUY  price=0.5 size=2.0 (size breaks tie)
848        //   3. asset=Ta side=BUY  price=0.6 size=1.0 (price breaks tie)
849        //   4. asset=Ta side=SELL price=0.5 size=1.0 (side breaks tie)
850        //   5. asset=Tb side=BUY  price=0.5 size=1.0 (asset breaks tie)
851        let key: Vec<(String, String, Decimal, Decimal)> = trades
852            .iter()
853            .map(|t| (t.asset.clone(), t.side.to_string(), t.price, t.size))
854            .collect();
855        assert_eq!(key[0], ("Ta".into(), "BUY".into(), dec!(0.5), dec!(1.0)));
856        assert_eq!(key[1], ("Ta".into(), "BUY".into(), dec!(0.5), dec!(2.0)));
857        assert_eq!(key[2], ("Ta".into(), "BUY".into(), dec!(0.6), dec!(1.0)));
858        assert_eq!(key[3], ("Ta".into(), "SELL".into(), dec!(0.5), dec!(1.0)));
859        assert_eq!(key[4], ("Tb".into(), "BUY".into(), dec!(0.5), dec!(1.0)));
860    }
861
862    #[rstest]
863    fn test_parse_trade_ticks_filters_other_tokens() {
864        let token_id = "T_KEEP";
865        let trades = vec![
866            make_trade(
867                1729000000,
868                "0xa",
869                token_id,
870                PolymarketOrderSide::Buy,
871                0.5,
872                1.0,
873            ),
874            make_trade(
875                1729000000,
876                "0xb",
877                "T_DROP",
878                PolymarketOrderSide::Sell,
879                0.5,
880                1.0,
881            ),
882        ];
883
884        let trades = parse_trade_ticks(trades, test_instrument_id(), token_id, 2, 2).unwrap();
885
886        assert_eq!(trades.len(), 1);
887        assert_eq!(trades[0].aggressor_side, AggressorSide::Buy);
888    }
889
890    #[rstest]
891    fn test_parse_trade_ticks_disambiguates_multi_fill_transaction() {
892        // Two fills sharing tx + asset must produce distinct TradeIds
893        let token_id = "12345token";
894        let same_hash = "0x000000000000000000000000000000000000000000000000000000000000abcdef";
895        let trades = vec![
896            make_trade(
897                1729000000,
898                same_hash,
899                token_id,
900                PolymarketOrderSide::Buy,
901                0.5,
902                1.0,
903            ),
904            make_trade(
905                1729000000,
906                same_hash,
907                token_id,
908                PolymarketOrderSide::Sell,
909                0.5,
910                1.0,
911            ),
912        ];
913
914        let trades = parse_trade_ticks(trades, test_instrument_id(), token_id, 2, 2).unwrap();
915
916        assert_eq!(trades.len(), 2);
917        assert_ne!(trades[0].trade_id, trades[1].trade_id);
918        // ts_event monotonic: same epoch second + nanosecond tiebreaker
919        assert!(trades[0].ts_event < trades[1].ts_event);
920        assert_eq!(
921            u64::from(trades[1].ts_event) - u64::from(trades[0].ts_event),
922            1
923        );
924        // ID format ends with the per-(tx, asset) sequence
925        assert!(trades[0].trade_id.to_string().ends_with("-000000"));
926        assert!(trades[1].trade_id.to_string().ends_with("-000001"));
927    }
928
929    #[rstest]
930    fn test_parse_trade_ticks_distinct_tx_share_timestamp() {
931        // Different transactions in the same epoch second still get distinct
932        // ts_event values (the tiebreaker is per-second, not per-transaction).
933        let token_id = "T";
934        let trades = vec![
935            make_trade(
936                1729000000,
937                "0xtx1",
938                token_id,
939                PolymarketOrderSide::Buy,
940                0.5,
941                1.0,
942            ),
943            make_trade(
944                1729000000,
945                "0xtx2",
946                token_id,
947                PolymarketOrderSide::Buy,
948                0.5,
949                1.0,
950            ),
951            make_trade(
952                1729000000,
953                "0xtx3",
954                token_id,
955                PolymarketOrderSide::Buy,
956                0.5,
957                1.0,
958            ),
959        ];
960
961        let trades = parse_trade_ticks(trades, test_instrument_id(), token_id, 2, 2).unwrap();
962
963        assert_eq!(trades.len(), 3);
964        // Strictly increasing ts_event
965        assert!(trades[0].ts_event < trades[1].ts_event);
966        assert!(trades[1].ts_event < trades[2].ts_event);
967        // Each trade is the first fill on its (tx, asset) so all have seq 0
968        for trade in &trades {
969            assert!(trade.trade_id.to_string().ends_with("-000000"));
970        }
971    }
972
973    #[rstest]
974    fn test_parse_trade_ticks_assigns_per_second_tiebreakers() {
975        // Same-second fills get strictly increasing nanosecond tiebreakers
976        // starting at zero, all bounded below 1 second.
977        let token_id = "T";
978        let mut trades = Vec::new();
979
980        for i in 0..3 {
981            let hash = format!("0x{i:064x}");
982            trades.push(make_trade(
983                1729000000,
984                &hash,
985                token_id,
986                PolymarketOrderSide::Buy,
987                0.5,
988                1.0,
989            ));
990        }
991
992        let trades = parse_trade_ticks(trades, test_instrument_id(), token_id, 2, 2).unwrap();
993
994        assert_eq!(trades.len(), 3);
995        let base_ns = 1_729_000_000u64 * 1_000_000_000;
996
997        for (i, trade) in trades.iter().enumerate() {
998            assert!(u64::from(trade.ts_event) - base_ns < 1_000_000_000);
999            assert_eq!(u64::from(trade.ts_event) - base_ns, i as u64);
1000        }
1001    }
1002
1003    #[rstest]
1004    fn test_parse_trade_ticks_sorts_inputs_by_composite_key() {
1005        // Mirror what the API may return: same-second fills delivered out
1006        // of order. parse_trade_ticks must produce a deterministic stream.
1007        let token_id = "T";
1008        let trades = vec![
1009            make_trade(
1010                1729000005,
1011                "0xZ",
1012                token_id,
1013                PolymarketOrderSide::Buy,
1014                0.5,
1015                1.0,
1016            ),
1017            make_trade(
1018                1729000000,
1019                "0xC",
1020                token_id,
1021                PolymarketOrderSide::Buy,
1022                0.5,
1023                1.0,
1024            ),
1025            make_trade(
1026                1729000000,
1027                "0xA",
1028                token_id,
1029                PolymarketOrderSide::Sell,
1030                0.5,
1031                1.0,
1032            ),
1033            make_trade(
1034                1729000000,
1035                "0xB",
1036                token_id,
1037                PolymarketOrderSide::Buy,
1038                0.5,
1039                1.0,
1040            ),
1041        ];
1042
1043        let trades = parse_trade_ticks(trades, test_instrument_id(), token_id, 2, 2).unwrap();
1044
1045        assert_eq!(trades.len(), 4);
1046
1047        // Strictly non-decreasing ts_event
1048        for i in 1..trades.len() {
1049            assert!(trades[i - 1].ts_event <= trades[i].ts_event);
1050        }
1051
1052        // Composite tiebreaker: same-second trades order by transaction_hash
1053        let trade_ids: Vec<String> = trades.iter().map(|t| t.trade_id.to_string()).collect();
1054        assert!(trade_ids[0].contains("0xA"));
1055        assert!(trade_ids[1].contains("0xB"));
1056        assert!(trade_ids[2].contains("0xC"));
1057        assert!(trade_ids[3].contains("0xZ"));
1058    }
1059
1060    #[rstest]
1061    fn test_parse_trade_ticks_propagates_invalid_price() {
1062        let token_id = "T";
1063        let mut trade = make_trade(
1064            1729000000,
1065            "0xtx",
1066            token_id,
1067            PolymarketOrderSide::Buy,
1068            0.5,
1069            1.0,
1070        );
1071        trade.price = Decimal::from_str_exact("99999999999999999999.99").unwrap();
1072
1073        let error = parse_trade_ticks(vec![trade], test_instrument_id(), token_id, 2, 2)
1074            .expect_err("out-of-range price should fail");
1075
1076        assert_eq!(
1077            error.to_string(),
1078            "failed to convert Data API trade price 99999999999999999999.99 with precision 2"
1079        );
1080        assert_eq!(error.chain().count(), 2);
1081    }
1082
1083    #[rstest]
1084    fn test_parse_trade_ticks_propagates_invalid_size() {
1085        let token_id = "T";
1086        let trade = make_trade(
1087            1729000000,
1088            "0xtx",
1089            token_id,
1090            PolymarketOrderSide::Buy,
1091            0.5,
1092            -1.5,
1093        );
1094
1095        let error = parse_trade_ticks(vec![trade], test_instrument_id(), token_id, 2, 2)
1096            .expect_err("negative size should fail");
1097
1098        assert_eq!(
1099            error.to_string(),
1100            "failed to convert Data API trade size -1.5 with precision 2"
1101        );
1102        assert_eq!(error.chain().count(), 2);
1103    }
1104}