nautilus_polymarket/http/

parse.rs

// -------------------------------------------------------------------------------------------------
//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
//  https://nautechsystems.io
//
//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
//  You may not use this file except in compliance with the License.
//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
// -------------------------------------------------------------------------------------------------

//! Instrument parsing for Polymarket markets.

use jiff::Timestamp;
use nautilus_core::{Params, UnixNanos};
use nautilus_model::{
    enums::{AssetClass, CurrencyType},
    identifiers::{InstrumentId, Symbol},
    instruments::{BinaryOption, InstrumentAny},
    types::{Currency, Price, Quantity},
};
use rust_decimal::Decimal;
use rust_decimal_macros::dec;
use serde::{Deserialize, Serialize};
use ustr::Ustr;

use super::models::{CryptoMarketConfig, FeeSchedule, GammaMarket};
use crate::common::{
    consts::{POLYMARKET_PRICE_PRECISION, POLYMARKET_VENUE, PUSD},
    enums::PolymarketOutcome,
};

const DEFAULT_TICK_SIZE: Decimal = dec!(0.001);

/// Normalized instrument definition for a single Polymarket outcome token.
///
/// Each Polymarket market produces two of these (Yes and No).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PolymarketInstrumentDef {
    /// Nautilus symbol: `{conditionId}-{tokenId}`.
    pub symbol: Ustr,
    /// CLOB token ID (ERC1155 token, used for orders/subscriptions).
    pub token_id: Ustr,
    /// On-chain condition ID.
    pub condition_id: Ustr,
    /// Gamma market ID.
    pub market_id: String,
    /// Question ID (resolution hash).
    pub question_id: Option<String>,
    /// Outcome label.
    pub outcome: PolymarketOutcome,
    /// Market question/title.
    pub question: String,
    /// Market description.
    pub description: Option<String>,
    /// Canonical price precision (four decimal places).
    pub price_precision: u8,
    /// Minimum tick size.
    pub tick_size: Decimal,
    /// Minimum order size.
    pub min_size: Option<Decimal>,
    /// Maker fee (decimal, not bps).
    pub maker_fee: Option<Decimal>,
    /// Taker fee (decimal, not bps).
    pub taker_fee: Option<Decimal>,
    /// Market start timestamp (ISO 8601).
    pub start_date: Option<String>,
    /// Event window start timestamp (ISO 8601).
    pub event_start_time: Option<String>,
    /// Market end timestamp (ISO 8601).
    pub end_date: Option<String>,
    /// Whether the market is active and accepting orders.
    pub active: bool,
    /// Whether Gamma reports the market closed.
    #[serde(default)]
    pub closed: bool,
    /// URL slug for the market.
    pub market_slug: Option<String>,
    /// Whether the market uses the neg-risk CTF exchange contract.
    pub neg_risk: Option<bool>,
    /// Source used to resolve the market.
    pub resolution_source: Option<String>,
    /// Crypto market resolution configuration.
    pub crypto_market_config: Option<CryptoMarketConfig>,
    /// Fee schedule for this market.
    pub fee_schedule: Option<FeeSchedule>,
    /// Game ID for sport markets, kept verbatim because Gamma emits both
    /// numeric and composite `<uuid>:<away>:<home>` forms.
    pub game_id: Option<String>,
}

/// Parses a Gamma market response into instrument definitions.
///
/// Each market produces two definitions: one for the Yes outcome
/// and one for the No outcome.
pub fn parse_gamma_market(market: &GammaMarket) -> anyhow::Result<Vec<PolymarketInstrumentDef>> {
    let game_id = market.game_id.clone().or_else(|| {
        market
            .events
            .as_ref()?
            .iter()
            .find_map(|event| event.game_id.clone())
    });

    let token_ids: Vec<String> = serde_json::from_str(&market.clob_token_ids).map_err(|e| {
        anyhow::anyhow!(
            "Failed to parse clob_token_ids '{}': {e}",
            market.clob_token_ids
        )
    })?;

    if token_ids.len() != 2 {
        anyhow::bail!("Expected 2 token IDs, received {}", token_ids.len());
    }

    let outcomes: Vec<String> = serde_json::from_str(&market.outcomes)
        .map_err(|e| anyhow::anyhow!("Failed to parse outcomes '{}': {e}", market.outcomes))?;

    if outcomes.len() != 2 {
        anyhow::bail!("Expected 2 outcomes, received {}", outcomes.len());
    }

    let tick_size = market
        .order_price_min_tick_size
        .unwrap_or(DEFAULT_TICK_SIZE);
    let price_precision = POLYMARKET_PRICE_PRECISION;

    // Polymarket charges fees using `feeSchedule.rate` on the Gamma market.
    // Only takers pay; makers are always zero.
    // Reference: https://docs.polymarket.com/trading/fees
    let maker_fee: Option<Decimal> = market.fee_schedule.as_ref().map(|_| Decimal::ZERO);
    let taker_fee: Option<Decimal> = market.fee_schedule.as_ref().map(|fs| fs.rate);

    let min_size = market.order_min_size;

    let active = market.active.unwrap_or(false)
        && !market.closed.unwrap_or(false)
        && market.accepting_orders.unwrap_or(false);

    let neg_risk = market.neg_risk;

    let mut defs = Vec::with_capacity(2);

    for (token_id, outcome_label) in token_ids.iter().zip(outcomes.iter()) {
        let outcome = PolymarketOutcome::from(outcome_label.as_str());

        let symbol_str = format!("{}-{token_id}", market.condition_id);

        defs.push(PolymarketInstrumentDef {
            symbol: Ustr::from(&symbol_str),
            token_id: Ustr::from(token_id.as_str()),
            condition_id: Ustr::from(market.condition_id.as_str()),
            market_id: market.id.clone(),
            question_id: market.question_id.clone(),
            outcome,
            question: market.question.clone(),
            description: market.description.clone(),
            price_precision,
            tick_size,
            min_size,
            maker_fee,
            taker_fee,
            start_date: market.start_date.clone(),
            event_start_time: market.event_start_time.clone(),
            end_date: market.end_date.clone(),
            active,
            closed: market.closed.unwrap_or(false),
            market_slug: market.market_slug.clone(),
            neg_risk,
            resolution_source: market.resolution_source.clone(),
            crypto_market_config: market.crypto_market_config.clone(),
            fee_schedule: market.fee_schedule.clone(),
            game_id: game_id.clone(),
        });
    }

    Ok(defs)
}

/// Converts a Polymarket instrument definition into a Nautilus `InstrumentAny`.
pub fn create_instrument_from_def(
    def: &PolymarketInstrumentDef,
    ts_init: UnixNanos,
) -> anyhow::Result<InstrumentAny> {
    let symbol = Symbol::new(def.symbol);
    let venue = *POLYMARKET_VENUE;
    let instrument_id = InstrumentId::new(symbol, venue);
    let raw_symbol = Symbol::new(def.token_id);
    let currency = get_currency(PUSD);

    let size_increment = Quantity::from("0.000001");

    let activation_ns = def
        .start_date
        .as_deref()
        .and_then(parse_datetime_to_nanos)
        .unwrap_or_default();
    let expiration_ns = def
        .end_date
        .as_deref()
        .and_then(parse_datetime_to_nanos)
        .unwrap_or_default();

    // Advertise the tradeable range for the current tick so consumers and testers that clamp to
    // these bounds land inside the venue's `[tick, 1 - tick]` range; execution-side validation in
    // `PolymarketOrderBuilder::validate_limit_price` remains the source of truth.
    let (min_price, max_price) = tick_relative_price_bounds(def.tick_size)?;
    let price_increment = min_price;

    // Polymarket exposes `orderMinSize` (limit-order minimum shares) and a separate
    // $1 market-order minimum amount; the instrument model can only carry one
    // `min_quantity`, so leave it unset and let the venue reject out-of-bounds orders.
    let min_quantity: Option<Quantity> = None;

    let info: Params = serde_json::from_value(build_info_json(def))?;

    let binary_option = BinaryOption::builder()
        .instrument_id(instrument_id)
        .raw_symbol(raw_symbol)
        .asset_class(AssetClass::Alternative)
        .currency(currency)
        .activation_ns(activation_ns)
        .expiration_ns(expiration_ns)
        .price_precision(POLYMARKET_PRICE_PRECISION)
        // size_precision: 6-decimal collateral increments
        .size_precision(6)
        .price_increment(price_increment)
        .size_increment(size_increment)
        .outcome(def.outcome.inner())
        .description(Ustr::from(def.question.as_str()))
        .maybe_min_quantity(min_quantity)
        .max_price(max_price)
        .min_price(min_price)
        .maybe_maker_fee(def.maker_fee)
        .maybe_taker_fee(def.taker_fee)
        .info(info)
        .ts_event(ts_init)
        .ts_init(ts_init)
        .build()?;

    Ok(InstrumentAny::BinaryOption(binary_option))
}

/// Converts a collection of definitions into Nautilus instruments.
#[must_use]
pub fn instruments_from_defs(
    defs: &[PolymarketInstrumentDef],
    ts_init: UnixNanos,
) -> Vec<InstrumentAny> {
    defs.iter()
        .filter_map(|def| {
            create_instrument_from_def(def, ts_init)
                .map_err(|e| log::warn!("Failed to create instrument {}: {e}", def.symbol))
                .ok()
        })
        .collect()
}

/// Rebuilds an instrument with a new active tick size and canonical price precision.
///
/// All other fields are preserved from `existing`. Returns a new `InstrumentAny`.
pub fn rebuild_instrument_with_tick_size(
    existing: &InstrumentAny,
    new_tick_size: &str,
    ts_event: UnixNanos,
    ts_init: UnixNanos,
) -> anyhow::Result<InstrumentAny> {
    let bo = match existing {
        InstrumentAny::BinaryOption(b) => b,
        other => anyhow::bail!("Expected BinaryOption, was {other:?}"),
    };

    let tick_size: Decimal = new_tick_size
        .parse()
        .map_err(|e| anyhow::anyhow!("Failed to parse tick size '{new_tick_size}': {e}"))?;
    let (min_price, max_price) = tick_relative_price_bounds(tick_size)?;
    let price_increment = min_price;

    let rebuilt = BinaryOption::builder()
        .instrument_id(bo.id)
        .raw_symbol(bo.raw_symbol)
        .asset_class(bo.asset_class)
        .currency(bo.currency)
        .activation_ns(bo.activation_ns)
        .expiration_ns(bo.expiration_ns)
        .price_precision(POLYMARKET_PRICE_PRECISION)
        .size_precision(bo.size_precision)
        .price_increment(price_increment)
        .size_increment(bo.size_increment)
        .maybe_outcome(bo.outcome)
        .maybe_description(bo.description)
        .maybe_max_quantity(bo.max_quantity)
        // min_quantity: see `create_instrument_from_def`
        .maybe_max_notional(bo.max_notional)
        .maybe_min_notional(bo.min_notional)
        .max_price(max_price)
        .min_price(min_price)
        .margin_init(bo.margin_init)
        .margin_maint(bo.margin_maint)
        .maker_fee(bo.maker_fee)
        .taker_fee(bo.taker_fee)
        .maybe_info(bo.info.clone())
        .ts_event(ts_event)
        .ts_init(ts_init)
        .build()?;

    Ok(InstrumentAny::BinaryOption(rebuilt))
}

// Returns the tradeable price bounds `[tick_size, 1 - tick_size]` for a Polymarket outcome,
// mirroring the venue range enforced in `PolymarketOrderBuilder::validate_limit_price`.
pub(crate) fn tick_relative_price_bounds(tick_size: Decimal) -> anyhow::Result<(Price, Price)> {
    anyhow::ensure!(
        tick_size > Decimal::ZERO,
        "Tick size {tick_size} must be positive"
    );

    let min_price = Price::from_decimal_dp(tick_size, POLYMARKET_PRICE_PRECISION)?;
    let max_price = Price::from_decimal_dp(Decimal::ONE - tick_size, POLYMARKET_PRICE_PRECISION)?;

    anyhow::ensure!(
        min_price.as_decimal() == tick_size,
        "Tick size {tick_size} is not exactly representable at Polymarket price precision {POLYMARKET_PRICE_PRECISION}"
    );
    Ok((min_price, max_price))
}

fn build_info_json(def: &PolymarketInstrumentDef) -> serde_json::Value {
    let mut map = serde_json::Map::new();
    map.insert(
        "token_id".to_string(),
        serde_json::Value::String(def.token_id.to_string()),
    );
    map.insert(
        "condition_id".to_string(),
        serde_json::Value::String(def.condition_id.to_string()),
    );
    map.insert(
        "market_id".to_string(),
        serde_json::Value::String(def.market_id.clone()),
    );

    if let Some(qid) = &def.question_id {
        map.insert(
            "question_id".to_string(),
            serde_json::Value::String(qid.clone()),
        );
    }

    if let Some(slug) = &def.market_slug {
        map.insert(
            "market_slug".to_string(),
            serde_json::Value::String(slug.clone()),
        );
    }

    if let Some(description) = &def.description {
        map.insert(
            "description".to_string(),
            serde_json::Value::String(description.clone()),
        );
    }

    if let Some(event_start_time) = &def.event_start_time {
        map.insert(
            "event_start_time".to_string(),
            serde_json::Value::String(event_start_time.clone()),
        );
    }

    if let Some(end_date) = &def.end_date {
        map.insert(
            "end_date".to_string(),
            serde_json::Value::String(end_date.clone()),
        );
    }

    if let Some(neg_risk) = def.neg_risk {
        map.insert("neg_risk".to_string(), serde_json::Value::Bool(neg_risk));
    }

    if let Some(resolution_source) = &def.resolution_source {
        map.insert(
            "resolution_source".to_string(),
            serde_json::Value::String(resolution_source.clone()),
        );
    }

    if let Some(crypto_market_config) = &def.crypto_market_config
        && let Ok(value) = serde_json::to_value(crypto_market_config)
    {
        map.insert("crypto_market_config".to_string(), value);
    }

    if let Some(min_size) = def.min_size {
        map.insert(
            "min_order_size".to_string(),
            serde_json::Value::String(min_size.to_string()),
        );
    }

    if let Some(fee_schedule) = &def.fee_schedule
        && let Ok(value) = serde_json::to_value(fee_schedule)
    {
        map.insert("fee_schedule".to_string(), value);
    }

    if let Some(game_id) = &def.game_id {
        map.insert(
            "game_id".to_string(),
            serde_json::Value::String(game_id.clone()),
        );
    }

    serde_json::Value::Object(map)
}

fn get_currency(code: &str) -> Currency {
    Currency::try_from_str(code).unwrap_or_else(|| {
        let currency = Currency::new(code, 6, 0, code, CurrencyType::Crypto);
        if let Err(e) = Currency::register(currency, false) {
            log::error!("Failed to register currency '{code}': {e}");
        }
        currency
    })
}

fn parse_datetime_to_nanos(s: &str) -> Option<UnixNanos> {
    s.parse::<Timestamp>()
        .ok()
        .and_then(|dt| u64::try_from(dt.as_nanosecond()).ok())
        .map(UnixNanos::from)
}

#[cfg(test)]
mod tests {
    use nautilus_core::UUID4;
    use nautilus_model::{
        enums::{OrderSide, TimeInForce},
        identifiers::{ClientOrderId, StrategyId, TraderId},
        instruments::Instrument,
        orders::{LimitOrder, OrderAny},
    };
    use rstest::rstest;
    use rust_decimal_macros::dec;

    use super::*;
    use crate::execution::order_builder::PolymarketOrderBuilder;

    const UNSUPPORTED_TICK_SIZE: &str = "0.0000000000000000001";

    fn load_gamma_market(filename: &str) -> GammaMarket {
        let path = format!("test_data/{filename}");
        let content = std::fs::read_to_string(path).expect("Failed to read test data");
        serde_json::from_str(&content).expect("Failed to parse test data")
    }

    fn limit_order_at(price: Price) -> OrderAny {
        OrderAny::Limit(LimitOrder::new(
            TraderId::from("TESTER-001"),
            StrategyId::from("S-001"),
            InstrumentId::from("TEST.POLYMARKET"),
            ClientOrderId::from("O-001"),
            OrderSide::Buy,
            Quantity::from("10"),
            price,
            TimeInForce::Gtc,
            None,
            false,
            false,
            false,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            UUID4::new(),
            UnixNanos::default(),
        ))
    }

    #[rstest]
    fn test_parse_gamma_market_produces_two_defs() {
        let market = load_gamma_market("gamma_market.json");
        let defs = parse_gamma_market(&market).unwrap();

        assert_eq!(defs.len(), 2);
        assert_eq!(defs[0].outcome, PolymarketOutcome::from("Up"));
        assert_eq!(defs[1].outcome, PolymarketOutcome::from("Down"));
    }

    #[rstest]
    fn test_parse_gamma_market_fields() {
        let market = load_gamma_market("gamma_market.json");
        let defs = parse_gamma_market(&market).unwrap();
        let yes_def = &defs[0];

        assert_eq!(
            yes_def.condition_id.as_str(),
            "0x78443f961b9a65869dcb39359de9960165c7e5cbad0904eac7f29cd77872a63b"
        );
        assert_eq!(yes_def.market_id, "1557558");
        assert_eq!(
            yes_def.question_id.as_deref(),
            Some("0x15813764bba41cfb5f99e2e649cfbae7a121a9f8f91ed47ca261aab95e9729de")
        );
        assert_eq!(
            yes_def.question,
            "Bitcoin Up or Down - March 12, 5:20AM-5:25AM ET"
        );
        assert_eq!(yes_def.tick_size, dec!(0.01));
        assert_eq!(yes_def.price_precision, POLYMARKET_PRICE_PRECISION);
        assert_eq!(yes_def.min_size, Some(dec!(5.0)));
        assert!(yes_def.maker_fee.is_none());
        assert!(yes_def.taker_fee.is_none());
        assert!(yes_def.active);
        assert_eq!(
            yes_def.market_slug.as_deref(),
            Some("btc-updown-5m-1773307200")
        );
        assert_eq!(yes_def.game_id, None);
    }

    #[rstest]
    fn test_parse_gamma_market_sports_game_id_and_fee_schedule() {
        let money_line = load_gamma_market("gamma_market_sports_market_money_line.json");
        let map_handicap = load_gamma_market("gamma_market_sports_market_map_handicap.json");

        let money_line_defs = parse_gamma_market(&money_line).unwrap();
        let map_handicap_defs = parse_gamma_market(&map_handicap).unwrap();

        assert_eq!(money_line_defs[0].game_id.as_deref(), Some("1427074"));
        assert_eq!(map_handicap_defs[0].game_id.as_deref(), Some("1427074"));
        assert_eq!(money_line_defs[0].fee_schedule, money_line.fee_schedule);
        assert_eq!(map_handicap_defs[0].fee_schedule, map_handicap.fee_schedule);

        // Maker fee is always zero for feeSchedule-backed markets
        assert_eq!(money_line_defs[0].maker_fee, Some(Decimal::ZERO));
        // Taker fee comes from feeSchedule.rate (sports rate = 0.03)
        assert_eq!(money_line_defs[0].taker_fee, Some(dec!(0.03)));
    }

    #[rstest]
    fn test_parse_gamma_market_symbol_format() {
        let market = load_gamma_market("gamma_market.json");
        let defs = parse_gamma_market(&market).unwrap();

        assert_eq!(
            defs[0].symbol.as_str(),
            "0x78443f961b9a65869dcb39359de9960165c7e5cbad0904eac7f29cd77872a63b-104239898038807136052399800151408521467737075933964991162589336683346093173875"
        );
        assert_eq!(
            defs[1].symbol.as_str(),
            "0x78443f961b9a65869dcb39359de9960165c7e5cbad0904eac7f29cd77872a63b-71183960810705820955071415844881728181970340514894896943812046065452395013351"
        );
    }

    #[rstest]
    fn test_parse_gamma_market_token_ids() {
        let market = load_gamma_market("gamma_market.json");
        let defs = parse_gamma_market(&market).unwrap();

        assert_eq!(
            defs[0].token_id.as_str(),
            "104239898038807136052399800151408521467737075933964991162589336683346093173875"
        );
        assert_eq!(
            defs[1].token_id.as_str(),
            "71183960810705820955071415844881728181970340514894896943812046065452395013351"
        );
    }

    #[rstest]
    fn test_parse_gamma_market_derives_outcome_from_label() {
        let mut market = load_gamma_market("gamma_market.json");

        // Reverse the outcomes order so No comes first
        market.outcomes = r#"["No", "Yes"]"#.to_string();

        let defs = parse_gamma_market(&market).unwrap();

        assert_eq!(defs[0].outcome, PolymarketOutcome::no());
        assert_eq!(defs[1].outcome, PolymarketOutcome::yes());
    }

    #[rstest]
    fn test_parse_gamma_market_accepts_arbitrary_outcome_label() {
        let mut market = load_gamma_market("gamma_market.json");
        market.outcomes = r#"["Maybe", "No"]"#.to_string();

        let defs = parse_gamma_market(&market).unwrap();

        assert_eq!(defs[0].outcome, PolymarketOutcome::from("Maybe"));
        assert_eq!(defs[1].outcome, PolymarketOutcome::no());
    }

    #[rstest]
    fn test_parse_gamma_market_null_tick_size_uses_default() {
        let mut market = load_gamma_market("gamma_market.json");
        market.order_price_min_tick_size = None;

        let defs = parse_gamma_market(&market).unwrap();

        assert_eq!(defs[0].tick_size, dec!(0.001));
        assert_eq!(defs[0].price_precision, POLYMARKET_PRICE_PRECISION);
    }

    #[rstest]
    fn test_parse_gamma_market_closed_is_inactive() {
        let mut market = load_gamma_market("gamma_market.json");
        market.closed = Some(true);

        let defs = parse_gamma_market(&market).unwrap();

        assert!(!defs[0].active);
        assert!(!defs[1].active);
    }

    #[rstest]
    fn test_create_instrument_from_def() {
        let market = load_gamma_market("gamma_market.json");
        let defs = parse_gamma_market(&market).unwrap();
        let ts_init = UnixNanos::from(1_000_000_000u64);

        let instrument = create_instrument_from_def(&defs[0], ts_init).unwrap();

        let binary = match &instrument {
            InstrumentAny::BinaryOption(b) => b,
            other => panic!("Expected BinaryOption, was {other:?}"),
        };

        assert_eq!(
            binary.id.to_string(),
            "0x78443f961b9a65869dcb39359de9960165c7e5cbad0904eac7f29cd77872a63b-104239898038807136052399800151408521467737075933964991162589336683346093173875.POLYMARKET"
        );
        assert_eq!(binary.outcome, Some(Ustr::from("Up")));
        assert_eq!(binary.asset_class, AssetClass::Alternative);
        assert_eq!(binary.currency.code.as_str(), "pUSD");
        assert_eq!(binary.price_precision, POLYMARKET_PRICE_PRECISION);
        assert_eq!(binary.size_precision, 6);
        assert_eq!(binary.price_increment(), Price::from("0.01"));
        assert_eq!(binary.size_increment(), Quantity::from("0.000001"));
    }

    #[rstest]
    fn test_create_instrument_info_params() {
        let market = load_gamma_market("gamma_market.json");
        let defs = parse_gamma_market(&market).unwrap();
        let ts_init = UnixNanos::from(1_000_000_000u64);

        let instrument = create_instrument_from_def(&defs[0], ts_init).unwrap();

        let binary = match &instrument {
            InstrumentAny::BinaryOption(b) => b,
            other => panic!("Expected BinaryOption, was {other:?}"),
        };

        let info = binary.info.as_ref().expect("info should be Some");
        assert_eq!(
            info.get_str("token_id"),
            Some("104239898038807136052399800151408521467737075933964991162589336683346093173875")
        );
        assert_eq!(
            info.get_str("condition_id"),
            Some("0x78443f961b9a65869dcb39359de9960165c7e5cbad0904eac7f29cd77872a63b")
        );
        assert_eq!(info.get_str("market_id"), Some("1557558"));
        assert_eq!(
            info.get_str("question_id"),
            Some("0x15813764bba41cfb5f99e2e649cfbae7a121a9f8f91ed47ca261aab95e9729de")
        );
        assert_eq!(
            info.get_str("market_slug"),
            Some("btc-updown-5m-1773307200")
        );
        assert_eq!(
            info.get_str("event_start_time"),
            Some("2026-03-12T09:20:00Z")
        );
        assert_eq!(info.get_str("game_id"), None);
        assert_eq!(info.get_str("min_order_size"), Some("5"));
        assert_eq!(info.get_bool("neg_risk"), Some(false));
        assert_eq!(info.get("fee_schedule"), None);
    }

    #[rstest]
    #[case(
        Some("Detailed resolution rules with https://example.com/source"),
        Some("Detailed resolution rules with https://example.com/source")
    )]
    #[case(None, None)]
    fn test_create_instrument_info_description(
        #[case] description: Option<&str>,
        #[case] expected: Option<&str>,
    ) {
        let mut market = load_gamma_market("gamma_market.json");
        market.description = description.map(str::to_string);
        market.resolution_source = None;
        let defs = parse_gamma_market(&market).unwrap();

        let instrument =
            create_instrument_from_def(&defs[0], UnixNanos::from(1_000_000_000u64)).unwrap();
        let InstrumentAny::BinaryOption(binary) = instrument else {
            panic!("Expected BinaryOption");
        };
        let info = binary.info.as_ref().expect("info should be Some");

        assert_eq!(info.get_str("description"), expected);
        assert_eq!(info.contains_key("description"), expected.is_some());
        assert_eq!(info.get_str("resolution_source"), None);
    }

    #[rstest]
    fn test_create_instrument_info_includes_resolution_and_crypto_market_config() {
        let market = load_gamma_market("gamma_market_crypto_twap.json");

        let defs = parse_gamma_market(&market).unwrap();
        assert_eq!(defs[0].end_date.as_deref(), Some("2026-08-22T16:05:00Z"));
        let instrument =
            create_instrument_from_def(&defs[0], UnixNanos::from(1_000_000_000u64)).unwrap();
        let InstrumentAny::BinaryOption(binary) = instrument else {
            panic!("Expected BinaryOption");
        };
        let info = binary.info.as_ref().expect("info should be Some");

        assert_eq!(info.get_str("end_date"), Some("2026-08-22T16:05:00Z"));
        assert_eq!(
            info.get_str("resolution_source"),
            Some("https://data.chain.link/streams/btc-usd-twap-60s-streams")
        );
        assert_eq!(
            info.get("crypto_market_config"),
            Some(&serde_json::json!({
                "id": "btc-5m-twap-60",
                "asset": "btc",
                "duration": "5m",
                "twapEnabled": true,
                "twapLookbackSeconds": 60,
            }))
        );
    }

    #[rstest]
    fn test_create_instrument_info_omits_missing_neg_risk() {
        let mut market = load_gamma_market("gamma_market.json");
        market.neg_risk = None;
        let defs = parse_gamma_market(&market).unwrap();

        let instrument =
            create_instrument_from_def(&defs[0], UnixNanos::from(1_000_000_000u64)).unwrap();
        let InstrumentAny::BinaryOption(binary) = instrument else {
            panic!("Expected BinaryOption");
        };
        let info = binary.info.as_ref().expect("info should be Some");

        assert_eq!(info.get_bool("neg_risk"), None);
    }

    #[rstest]
    fn test_past_end_market_carries_closure_state_on_the_definition_only() {
        let mut market = load_gamma_market("gamma_market_past_end_date_open.json");
        let defs = parse_gamma_market(&market).unwrap();

        assert!(!defs[0].closed);

        market.closed = Some(true);
        let closed_defs = parse_gamma_market(&market).unwrap();

        assert!(closed_defs[0].closed);

        // `create_instrument_from_def` is shared with the historical loader, which keeps terminal
        // state in `resolution_metadata`. Closure is stamped on the live Gamma path instead.
        for def in [&defs[0], &closed_defs[0]] {
            let instrument =
                create_instrument_from_def(def, UnixNanos::from(1_000_000_000u64)).unwrap();
            let binary = match &instrument {
                InstrumentAny::BinaryOption(binary) => binary,
                other => panic!("Expected BinaryOption, was {other:?}"),
            };
            let info = binary.info.as_ref().expect("info should be present");

            assert_eq!(info.get_bool("closed"), None);
        }
    }

    #[rstest]
    fn test_create_instrument_info_params_includes_game_id_and_fee_schedule() {
        let market = load_gamma_market("gamma_market_sports_market_money_line.json");
        let defs = parse_gamma_market(&market).unwrap();
        let ts_init = UnixNanos::from(1_000_000_000u64);

        let instrument = create_instrument_from_def(&defs[0], ts_init).unwrap();

        let binary = match &instrument {
            InstrumentAny::BinaryOption(b) => b,
            other => panic!("Expected BinaryOption, was {other:?}"),
        };

        let info = binary.info.as_ref().expect("info should be Some");
        assert_eq!(info.get_str("game_id"), Some("1427074"));
        assert!(info.get("fee_schedule").is_some());
    }

    #[rstest]
    fn test_instruments_from_defs_batch() {
        let market = load_gamma_market("gamma_market.json");
        let defs = parse_gamma_market(&market).unwrap();
        let ts_init = UnixNanos::from(1_000_000_000u64);

        let instruments = instruments_from_defs(&defs, ts_init);

        assert_eq!(instruments.len(), 2);
    }

    #[rstest]
    fn test_instruments_from_defs_skips_unsupported_tick_precision() {
        let mut market = load_gamma_market("gamma_market.json");
        let valid_defs = parse_gamma_market(&market).unwrap();
        market.order_price_min_tick_size = Some(UNSUPPORTED_TICK_SIZE.parse().unwrap());
        let invalid_defs = parse_gamma_market(&market).unwrap();
        let ts_init = UnixNanos::from(1_000_000_000u64);
        let expected = create_instrument_from_def(&valid_defs[1], ts_init).unwrap();
        let defs = [invalid_defs[0].clone(), valid_defs[1].clone()];

        let instruments = instruments_from_defs(&defs, ts_init);

        assert_eq!(instruments.len(), 1);
        assert_eq!(instruments[0].id(), expected.id());
        assert_eq!(instruments[0].price_increment(), expected.price_increment());
        assert_eq!(instruments[0].min_price(), expected.min_price());
        assert_eq!(instruments[0].max_price(), expected.max_price());
    }

    #[rstest]
    #[case::zero("0")]
    #[case::negative("-0.005")]
    fn test_tick_relative_price_bounds_rejects_non_positive(#[case] tick_size: &str) {
        let tick_size: Decimal = tick_size.parse().unwrap();

        let error = tick_relative_price_bounds(tick_size).unwrap_err();

        assert_eq!(
            error.to_string(),
            format!("Tick size {tick_size} must be positive")
        );
    }

    #[rstest]
    #[case("0.1", "0.1", "0.9", 1)]
    #[case("0.01", "0.01", "0.99", 2)]
    #[case("0.005", "0.005", "0.995", 3)]
    #[case("0.0025", "0.0025", "0.9975", 4)]
    #[case("0.001", "0.001", "0.999", 3)]
    #[case("0.0001", "0.0001", "0.9999", 4)]
    fn test_create_instrument_tick_relative_price_bounds(
        #[case] tick_size: &str,
        #[case] expected_min: &str,
        #[case] expected_max: &str,
        #[case] expected_tick_decimals: u8,
    ) {
        let mut market = load_gamma_market("gamma_market.json");
        market.order_price_min_tick_size = Some(tick_size.parse().unwrap());
        let defs = parse_gamma_market(&market).unwrap();
        let ts_init = UnixNanos::from(1_000_000_000u64);

        let instrument = create_instrument_from_def(&defs[0], ts_init).unwrap();

        let binary = match &instrument {
            InstrumentAny::BinaryOption(b) => b,
            other => panic!("Expected BinaryOption, was {other:?}"),
        };

        assert_eq!(binary.price_precision, POLYMARKET_PRICE_PRECISION);
        assert_eq!(binary.price_increment.precision, POLYMARKET_PRICE_PRECISION);
        assert_eq!(
            binary.min_price.unwrap().precision,
            POLYMARKET_PRICE_PRECISION
        );
        assert_eq!(
            binary.max_price.unwrap().precision,
            POLYMARKET_PRICE_PRECISION
        );
        assert_eq!(
            binary.min_price_increment_precision(),
            expected_tick_decimals
        );
        assert_eq!(binary.min_price, Some(Price::from(expected_min)));
        assert_eq!(binary.max_price, Some(Price::from(expected_max)));
        // The lower bound is exactly the price increment (one tick)
        assert_eq!(binary.min_price, Some(binary.price_increment));
    }

    #[rstest]
    fn test_instrument_bounds_agree_with_execution_validation() {
        // On a 0.01-tick market, clamping to the advertised bounds must land inside the
        // venue's [tick, 1 - tick] range that `validate_limit_price` enforces, and the old
        // static 0.001/0.999 bounds must be rejected by that same validation.
        let mut market = load_gamma_market("gamma_market.json");
        market.order_price_min_tick_size = Some(dec!(0.01));
        let defs = parse_gamma_market(&market).unwrap();
        let ts_init = UnixNanos::from(1_000_000_000u64);

        let instrument = create_instrument_from_def(&defs[0], ts_init).unwrap();
        let tick = instrument.price_increment();
        let min_price = instrument.min_price().expect("min_price");
        let max_price = instrument.max_price().expect("max_price");

        assert_eq!(min_price, Price::from("0.01"));
        assert_eq!(max_price, Price::from("0.99"));

        let at_min = limit_order_at(min_price);
        let at_max = limit_order_at(max_price);
        assert!(PolymarketOrderBuilder::validate_limit_price(&at_min, tick).is_ok());
        assert!(PolymarketOrderBuilder::validate_limit_price(&at_max, tick).is_ok());

        let at_old_min = limit_order_at(Price::from("0.001"));
        let at_old_max = limit_order_at(Price::from("0.999"));
        assert!(PolymarketOrderBuilder::validate_limit_price(&at_old_min, tick).is_err());
        assert!(PolymarketOrderBuilder::validate_limit_price(&at_old_max, tick).is_err());
    }

    #[rstest]
    fn test_rebuild_instrument_with_tick_size() {
        let market = load_gamma_market("gamma_market.json");
        let defs = parse_gamma_market(&market).unwrap();
        let ts_init = UnixNanos::from(1_000_000_000u64);

        // The active tick changes independently of canonical price precision
        let instrument = create_instrument_from_def(&defs[0], ts_init).unwrap();
        assert_eq!(instrument.price_precision(), POLYMARKET_PRICE_PRECISION);

        let ts_event = UnixNanos::from(2_000_000_000u64);
        let rebuilt =
            rebuild_instrument_with_tick_size(&instrument, "0.001", ts_event, ts_event).unwrap();

        assert_eq!(rebuilt.price_precision(), POLYMARKET_PRICE_PRECISION);
        assert_eq!(
            rebuilt.price_increment().precision,
            POLYMARKET_PRICE_PRECISION
        );
        assert_eq!(rebuilt.min_price_increment_precision(), 3);
        assert_eq!(rebuilt.price_increment(), Price::from("0.001"));
        // Bounds reflect the new tick, not the pre-change 0.01-tick range
        assert_eq!(rebuilt.min_price(), Some(Price::from("0.001")));
        assert_eq!(rebuilt.max_price(), Some(Price::from("0.999")));
    }

    #[rstest]
    #[case("0.005", "0.0025", 4, "0.9975")]
    #[case("0.0025", "0.005", 3, "0.995")]
    fn test_rebuild_instrument_between_non_power_ticks(
        #[case] old_tick: &str,
        #[case] new_tick: &str,
        #[case] expected_tick_decimals: u8,
        #[case] expected_max: &str,
    ) {
        let market = load_gamma_market("gamma_market.json");
        let defs = parse_gamma_market(&market).unwrap();
        let ts_init = UnixNanos::from(1_000_000_000u64);
        let instrument = create_instrument_from_def(&defs[0], ts_init).unwrap();
        let instrument =
            rebuild_instrument_with_tick_size(&instrument, old_tick, ts_init, ts_init).unwrap();

        let rebuilt =
            rebuild_instrument_with_tick_size(&instrument, new_tick, ts_init, ts_init).unwrap();

        assert_eq!(instrument.price_increment(), Price::from(old_tick));
        assert_eq!(rebuilt.price_precision(), POLYMARKET_PRICE_PRECISION);
        assert_eq!(
            rebuilt.price_increment().precision,
            POLYMARKET_PRICE_PRECISION
        );
        assert_eq!(
            rebuilt.min_price_increment_precision(),
            expected_tick_decimals
        );
        assert_eq!(rebuilt.price_increment(), Price::from(new_tick));
        assert_eq!(rebuilt.min_price(), Some(Price::from(new_tick)));
        assert_eq!(rebuilt.max_price(), Some(Price::from(expected_max)));
    }

    #[rstest]
    fn test_rebuild_instrument_with_tick_size_rejects_unsupported_tick_precision() {
        let market = load_gamma_market("gamma_market.json");
        let defs = parse_gamma_market(&market).unwrap();
        let ts_init = UnixNanos::from(1_000_000_000u64);
        let instrument = create_instrument_from_def(&defs[0], ts_init).unwrap();
        let error =
            rebuild_instrument_with_tick_size(&instrument, UNSUPPORTED_TICK_SIZE, ts_init, ts_init)
                .unwrap_err();

        assert_eq!(
            error.to_string(),
            format!(
                "Tick size {UNSUPPORTED_TICK_SIZE} is not exactly representable at Polymarket price precision {POLYMARKET_PRICE_PRECISION}"
            )
        );
    }

    #[rstest]
    fn test_rebuild_instrument_preserves_fields() {
        let market = load_gamma_market("gamma_market.json");
        let defs = parse_gamma_market(&market).unwrap();
        let ts_init = UnixNanos::from(1_000_000_000u64);

        let instrument = create_instrument_from_def(&defs[0], ts_init).unwrap();
        let ts_event = UnixNanos::from(2_000_000_000u64);
        let rebuilt =
            rebuild_instrument_with_tick_size(&instrument, "0.01", ts_event, ts_event).unwrap();

        assert_eq!(rebuilt.id(), instrument.id());
        assert_eq!(rebuilt.raw_symbol(), instrument.raw_symbol());
        assert_eq!(rebuilt.size_precision(), instrument.size_precision());

        let orig_bo = match &instrument {
            InstrumentAny::BinaryOption(b) => b,
            _ => panic!(),
        };
        let new_bo = match &rebuilt {
            InstrumentAny::BinaryOption(b) => b,
            _ => panic!(),
        };
        assert_eq!(new_bo.outcome, orig_bo.outcome);
        assert_eq!(new_bo.currency, orig_bo.currency);
    }
}