nautilus-binance 0.61.0

// -------------------------------------------------------------------------------------------------
//  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.
// -------------------------------------------------------------------------------------------------

//! Binance Spot-specific enumerations.

use nautilus_model::enums::{OrderType, TimeInForce};
use serde::{Deserialize, Serialize};

use crate::common::enums::BinanceTimeInForce;

/// Spot order type enumeration.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum BinanceSpotOrderType {
    /// Limit order.
    Limit,
    /// Market order.
    Market,
    /// Stop loss (triggers market sell when price drops to stop price).
    StopLoss,
    /// Stop loss limit (triggers limit sell when price drops to stop price).
    StopLossLimit,
    /// Take profit (triggers market sell when price rises to stop price).
    TakeProfit,
    /// Take profit limit (triggers limit sell when price rises to stop price).
    TakeProfitLimit,
    /// Limit maker (post-only, rejected if would match immediately).
    LimitMaker,
    /// Unknown or undocumented value.
    #[serde(other)]
    Unknown,
}

/// Spot order response type.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum BinanceOrderResponseType {
    /// Acknowledge only (fastest).
    Ack,
    /// Result with order details.
    Result,
    /// Full response with fills.
    #[default]
    Full,
}

/// Cancel/replace mode for order modification.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum BinanceCancelReplaceMode {
    /// Stop if cancel fails.
    StopOnFailure,
    /// Continue with new order even if cancel fails.
    AllowFailure,
}

/// Spot user data stream event types.
///
/// These are the `"e"` field values on JSON frames emitted by the Spot user
/// data stream and the Spot WebSocket Trading API. The Spot wire format is
/// camelCase throughout; this enum is kept separate from
/// [`crate::common::enums::BinanceWsEventType`], which mixes camelCase
/// market-data events with `SCREAMING_SNAKE_CASE` Futures user-data events.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum BinanceSpotUserDataEventType {
    /// Order execution report (`executionReport`).
    ExecutionReport,
    /// Account position update (`outboundAccountPosition`).
    OutboundAccountPosition,
    /// Balance update (`balanceUpdate`).
    BalanceUpdate,
    /// Server shutdown notice, sent ~10 minutes before disconnection.
    ServerShutdown,
    /// Listen key expired (legacy user data stream session).
    ListenKeyExpired,
    /// External lock update (`externalLockUpdate`).
    ExternalLockUpdate,
    /// Event stream terminated.
    EventStreamTerminated,
    /// Unknown or undocumented event type.
    #[serde(other)]
    Unknown,
}

/// Converts a Nautilus order type to Binance Spot order type.
///
/// # Errors
///
/// Returns an error if the order type is not supported on Binance Spot.
pub fn order_type_to_binance_spot(
    order_type: OrderType,
    post_only: bool,
) -> anyhow::Result<BinanceSpotOrderType> {
    match (order_type, post_only) {
        (OrderType::Market, _) => Ok(BinanceSpotOrderType::Market),
        (OrderType::Limit, true) => Ok(BinanceSpotOrderType::LimitMaker),
        (OrderType::Limit, false) => Ok(BinanceSpotOrderType::Limit),
        (OrderType::StopMarket, _) => Ok(BinanceSpotOrderType::StopLoss),
        (OrderType::StopLimit, _) => Ok(BinanceSpotOrderType::StopLossLimit),
        (OrderType::MarketIfTouched, _) => Ok(BinanceSpotOrderType::TakeProfit),
        (OrderType::LimitIfTouched, _) => Ok(BinanceSpotOrderType::TakeProfitLimit),
        _ => anyhow::bail!("Unsupported order type for Binance Spot: {order_type:?}"),
    }
}

/// Converts a Nautilus time in force to Binance Spot time in force.
///
/// Binance Spot only supports GTC, IOC, and FOK. When native GTD is disabled,
/// GTD maps to GTC so a Nautilus strategy can manage expiry locally.
///
/// # Errors
///
/// Returns an error if the time in force is not supported on Binance Spot.
pub fn time_in_force_to_binance_spot(
    tif: TimeInForce,
    use_gtd: bool,
) -> anyhow::Result<BinanceTimeInForce> {
    match tif {
        TimeInForce::Gtc => Ok(BinanceTimeInForce::Gtc),
        TimeInForce::Ioc => Ok(BinanceTimeInForce::Ioc),
        TimeInForce::Fok => Ok(BinanceTimeInForce::Fok),
        TimeInForce::Gtd if !use_gtd => {
            log::warn!(
                "Binance Spot does not support GTD; submitting as GTC because use_gtd=false. Enable manage_gtd_expiry on the submitting strategy"
            );
            Ok(BinanceTimeInForce::Gtc)
        }
        TimeInForce::Gtd => anyhow::bail!(
            "Binance Spot does not support native GTD; set use_gtd=false and enable manage_gtd_expiry on the submitting strategy"
        ),
        _ => anyhow::bail!("Unsupported time in force for Binance Spot: {tif:?}"),
    }
}

#[cfg(test)]
mod tests {
    use rstest::rstest;

    use super::*;

    #[rstest]
    #[case(OrderType::Market, false, BinanceSpotOrderType::Market)]
    #[case(OrderType::Limit, false, BinanceSpotOrderType::Limit)]
    #[case(OrderType::Limit, true, BinanceSpotOrderType::LimitMaker)]
    #[case(OrderType::StopMarket, false, BinanceSpotOrderType::StopLoss)]
    #[case(OrderType::StopLimit, false, BinanceSpotOrderType::StopLossLimit)]
    #[case(OrderType::MarketIfTouched, false, BinanceSpotOrderType::TakeProfit)]
    #[case(
        OrderType::LimitIfTouched,
        false,
        BinanceSpotOrderType::TakeProfitLimit
    )]
    fn test_order_type_to_binance_spot(
        #[case] order_type: OrderType,
        #[case] post_only: bool,
        #[case] expected: BinanceSpotOrderType,
    ) {
        let result = order_type_to_binance_spot(order_type, post_only).unwrap();
        assert_eq!(result, expected);
    }

    #[rstest]
    #[case(OrderType::TrailingStopMarket)]
    fn test_order_type_to_binance_spot_unsupported(#[case] order_type: OrderType) {
        let result = order_type_to_binance_spot(order_type, false);
        result.unwrap_err();
    }

    #[rstest]
    #[case(TimeInForce::Gtc, BinanceTimeInForce::Gtc)]
    #[case(TimeInForce::Ioc, BinanceTimeInForce::Ioc)]
    #[case(TimeInForce::Fok, BinanceTimeInForce::Fok)]
    fn test_time_in_force_to_binance_spot(
        #[case] tif: TimeInForce,
        #[case] expected: BinanceTimeInForce,
    ) {
        let result = time_in_force_to_binance_spot(tif, true).unwrap();
        assert_eq!(result, expected);
    }

    #[rstest]
    #[case(TimeInForce::Gtd)]
    fn test_time_in_force_to_binance_spot_rejects_gtd(#[case] tif: TimeInForce) {
        let result = time_in_force_to_binance_spot(tif, true);
        result.unwrap_err();
    }

    #[rstest]
    fn test_time_in_force_to_binance_spot_maps_locally_managed_gtd_to_gtc() {
        let result = time_in_force_to_binance_spot(TimeInForce::Gtd, false).unwrap();
        assert_eq!(result, BinanceTimeInForce::Gtc);
    }
}