hypercall_api/handlers/

mod.rs

pub mod account;
pub mod admin;
pub mod agents;
pub mod bulk_orders;
pub mod candles;
pub mod competition;
pub mod directives;
pub mod gas_provider;
pub mod greeks;
pub mod health;
pub mod historical_pnl;
pub mod historical_theos;
pub mod liquidation;
pub mod market_data;
pub mod notifications;
pub mod options_chain;
pub mod orders;
pub mod profile_image;
pub mod push;
pub mod replace_orders;
pub mod rfq;
#[cfg(feature = "rsm-state")]
pub mod rsm_rpc;
pub mod settlement;
#[cfg(any(feature = "faucet", feature = "test-endpoints"))]
pub mod testnet;
pub mod username;

use rust_decimal::Decimal;
use serde::{Serialize, Serializer};

use super::sonic_json::SonicJson;
use super::{
    error::ApiError,
    models::{
        ApiResponse, ExtendedRiskMatrixResponse, InstrumentRiskRowResponse, InstrumentStatus,
        RiskGridScenario, ScenarioDefinition,
    },
};
pub(crate) use crate::state::{submit_tier_update_command, ENGINE_RESPONSE_TIMEOUT};
pub use crate::state::{AppRuntimeConfig, AppState};
use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
};
use hypercall_types::{Greeks, OrderBookGreeks, CONTRACT_UNIT_MULTIPLIER};

#[cfg(feature = "faucet")]
pub(crate) const FAUCET_LIFETIME_CAP_USDC: i64 = 100_000;
#[cfg(feature = "faucet")]
pub(crate) const MARKET_MAKER_TIER: &str = "market_maker";

// Re-export handler functions so callers can use `handlers::place_order` style.
// These stay until all call sites migrate to direct `handlers::orders::place_order` paths.
pub use account::{
    get_fills, get_markets, get_orders, get_portfolio, get_risk_grid, get_trades, set_margin_mode,
};
#[cfg(feature = "test-endpoints")]
pub use admin::cancel_all_orders;
pub use admin::{
    delete_mmp_config, delete_user_tier, get_mmp_config, get_user_tier, reset_mmp, set_mmp_config,
    set_user_tier,
};
pub use agents::{approve_agent, get_authorized_agents, revoke_agent};
pub use bulk_orders::{
    bulk_cancel_order, bulk_cancel_order_by_cloid, bulk_place_order, BulkOrderResult,
};
pub use health::{health, ready, standby_ready, version};
pub use market_data::{
    get_expiry_summary, get_instrument_specs, get_instruments, get_options_summary,
};
pub use options_chain::{get_options_chain, get_orderbook};
pub use orders::{cancel_order, cancel_order_by_cloid, place_order};
pub use replace_orders::{bulk_replace_order, replace_order};
#[cfg(feature = "test-endpoints")]
pub use testnet::expire_instrument;
#[cfg(feature = "faucet")]
pub use testnet::faucet;
#[cfg(feature = "test-endpoints")]
pub use testnet::{set_option_iv, set_spot_price};

// ---- Shared helper functions used by submodules ----

fn trading_halt_message(reason: &str) -> String {
    format!(
        "{}. Order placement is disabled while trading is halted. Existing orders can still be canceled.",
        reason
    )
}

fn trading_halt_api_error(reason: String) -> ApiError {
    ApiError::new(
        StatusCode::SERVICE_UNAVAILABLE,
        "trading_halted",
        trading_halt_message(&reason),
    )
}

pub(crate) async fn ensure_order_creation_allowed(
    state: &AppState,
    symbol: &str,
) -> Result<(), ApiError> {
    let halt_state = state.trading_halt.read().await;
    if let Some(reason) = halt_state.blocked_reason(symbol) {
        return Err(trading_halt_api_error(reason));
    }
    Ok(())
}

pub fn serialize_f64_as_string<S>(value: &f64, serializer: S) -> Result<S::Ok, S::Error>
where
    S: Serializer,
{
    serializer.serialize_str(&value.to_string())
}

pub fn serialize_option_f64_as_string<S>(
    value: &Option<f64>,
    serializer: S,
) -> Result<S::Ok, S::Error>
where
    S: Serializer,
{
    match value {
        Some(v) => serializer.serialize_str(&v.to_string()),
        None => serializer.serialize_none(),
    }
}

pub(crate) fn try_decimal_from_f64(value: f64, context: &str) -> Result<Decimal, String> {
    Decimal::from_f64_retain(value).ok_or_else(|| {
        format!(
            "{} value {} is not representable as Decimal",
            context, value
        )
    })
}

fn api_json_response<T: Serialize>(status: StatusCode, payload: ApiResponse<T>) -> Response {
    (status, SonicJson(payload)).into_response()
}

fn api_error_response(status: StatusCode, message: impl Into<String>) -> Response {
    api_json_response(status, ApiResponse::<()>::error(message.into()))
}

fn pm_unavailable_response(message: impl Into<String>) -> Response {
    api_error_response(StatusCode::SERVICE_UNAVAILABLE, message)
}

fn convert_risk_grid_scenarios(
    scenario_pnls: Vec<hypercall_margin::ScenarioPnl>,
) -> Result<Vec<RiskGridScenario>, String> {
    scenario_pnls
        .into_iter()
        .map(|scenario| {
            Ok(RiskGridScenario {
                id: scenario.scenario_id,
                spot_shock_pct: try_decimal_from_f64(
                    scenario.scenario.spot_shock_pct,
                    "risk_grid.scenario.spot_shock_pct",
                )?,
                vol_shock_pct: try_decimal_from_f64(
                    scenario.scenario.vol_shock_pct,
                    "risk_grid.scenario.vol_shock_pct",
                )?,
                pnl_weight: try_decimal_from_f64(
                    scenario.scenario.pnl_weight,
                    "risk_grid.scenario.pnl_weight",
                )?,
                is_tail: scenario.scenario.is_tail,
                total_pnl: try_decimal_from_f64(
                    scenario.total_pnl,
                    "risk_grid.scenario.total_pnl",
                )?,
            })
        })
        .collect()
}

fn convert_extended_risk_matrix(
    extended_grid: hypercall_margin::ExtendedRiskGrid,
) -> Result<Option<ExtendedRiskMatrixResponse>, String> {
    if extended_grid.instruments.is_empty() {
        return Ok(None);
    }

    let scenarios = extended_grid
        .scenarios
        .iter()
        .map(|scenario| {
            Ok(ScenarioDefinition {
                id: scenario.id.clone(),
                spot_shock_pct: try_decimal_from_f64(
                    scenario.spot_shock_pct,
                    "risk_grid.extended.scenario.spot_shock_pct",
                )?,
                vol_shock_pct: try_decimal_from_f64(
                    scenario.vol_shock_pct,
                    "risk_grid.extended.scenario.vol_shock_pct",
                )?,
                pnl_weight: try_decimal_from_f64(
                    scenario.pnl_weight,
                    "risk_grid.extended.scenario.pnl_weight",
                )?,
                is_tail: scenario.is_tail,
            })
        })
        .collect::<Result<Vec<_>, String>>()?;
    let instruments = extended_grid
        .instruments
        .into_iter()
        .map(|instrument| {
            Ok(InstrumentRiskRowResponse {
                symbol: instrument.symbol,
                underlying: instrument.underlying,
                amount: try_decimal_from_f64(
                    instrument.amount,
                    "risk_grid.extended.instrument.amount",
                )?,
                base_amount: try_decimal_from_f64(
                    instrument.base_amount,
                    "risk_grid.extended.instrument.base_amount",
                )?,
                current_value: try_decimal_from_f64(
                    instrument.current_value,
                    "risk_grid.extended.instrument.current_value",
                )?,
                scenario_pnls: instrument
                    .scenario_pnls
                    .into_iter()
                    .map(|pnl| {
                        try_decimal_from_f64(pnl, "risk_grid.extended.instrument.scenario_pnl")
                    })
                    .collect::<Result<Vec<_>, String>>()?,
            })
        })
        .collect::<Result<Vec<_>, String>>()?;
    let total_pnls = extended_grid
        .total_pnls
        .into_iter()
        .map(|pnl| try_decimal_from_f64(pnl, "risk_grid.extended.total_pnl"))
        .collect::<Result<Vec<_>, String>>()?;

    Ok(Some(ExtendedRiskMatrixResponse {
        scenarios,
        instruments,
        total_pnls,
        worst_scenario_index: extended_grid.worst_scenario_index,
        worst_scenario_pnl: try_decimal_from_f64(
            extended_grid.worst_scenario_pnl,
            "risk_grid.extended.worst_scenario_pnl",
        )?,
    }))
}

pub(crate) fn order_book_greeks_from(source: &Greeks) -> OrderBookGreeks {
    OrderBookGreeks {
        delta: source.delta,
        gamma: source.gamma,
        vega: source.vega,
        theta: source.theta,
        rho: source.rho,
    }
}

pub(crate) fn raw_contract_units_to_human_contracts(size_contract_units_raw: f64) -> f64 {
    size_contract_units_raw / CONTRACT_UNIT_MULTIPLIER
}

pub(crate) fn quote_levels_to_human_contracts(
    levels_contract_units_raw: &[(f64, f64)],
) -> Vec<[f64; 2]> {
    levels_contract_units_raw
        .iter()
        .map(|(price, size_contract_units_raw)| {
            [
                *price,
                raw_contract_units_to_human_contracts(*size_contract_units_raw),
            ]
        })
        .collect()
}

fn normalize_orders_status_filter_input(status: &str) -> String {
    status.trim().to_ascii_lowercase().replace('-', "_")
}

pub(crate) fn parse_status_filter(raw: Option<&str>) -> Option<Vec<InstrumentStatus>> {
    match raw {
        Some(s) if s.eq_ignore_ascii_case("all") => None,
        Some(statuses) => {
            let parsed: Vec<InstrumentStatus> = statuses
                .split(',')
                .filter_map(|s| InstrumentStatus::from_db_str(s.trim()))
                .collect();
            if parsed.is_empty() {
                Some(vec![InstrumentStatus::Active])
            } else {
                Some(parsed)
            }
        }
        None => Some(vec![InstrumentStatus::Active]),
    }
}

pub(crate) fn parse_requested_underlyings(
    raw: Option<&str>,
    available_underlyings: Vec<String>,
) -> Vec<String> {
    match raw {
        Some(value) => {
            let mut seen = std::collections::HashSet::new();
            let parsed: Vec<String> = value
                .split(',')
                .map(|item| item.trim().to_uppercase())
                .filter(|item| !item.is_empty())
                .filter(|item| seen.insert(item.clone()))
                .collect();
            if parsed.is_empty() || parsed.iter().any(|item| item == "ALL") {
                available_underlyings
            } else {
                parsed
            }
        }
        None => available_underlyings,
    }
}

// ---- Tests for shared helpers ----

#[cfg(test)]
fn matches_status_filter(
    status: &InstrumentStatus,
    filter: &Option<Vec<InstrumentStatus>>,
) -> bool {
    match filter {
        Some(allowed) => allowed.contains(status),
        None => true,
    }
}

#[cfg(test)]
mod status_filter_tests {
    use super::*;

    #[test]
    fn test_parse_default_returns_active_only() {
        let filter = parse_status_filter(None);
        assert_eq!(filter, Some(vec![InstrumentStatus::Active]));
    }

    #[test]
    fn test_parse_all_returns_none() {
        assert_eq!(parse_status_filter(Some("all")), None);
        assert_eq!(parse_status_filter(Some("ALL")), None);
        assert_eq!(parse_status_filter(Some("All")), None);
    }

    #[test]
    fn test_parse_single_status() {
        assert_eq!(
            parse_status_filter(Some("SETTLED")),
            Some(vec![InstrumentStatus::Settled])
        );
        assert_eq!(
            parse_status_filter(Some("EXPIRED_PENDING_PRICE")),
            Some(vec![InstrumentStatus::ExpiredPendingPrice])
        );
    }

    #[test]
    fn test_parse_comma_separated() {
        let filter = parse_status_filter(Some("ACTIVE,EXPIRED_PENDING_PRICE"));
        assert_eq!(
            filter,
            Some(vec![
                InstrumentStatus::Active,
                InstrumentStatus::ExpiredPendingPrice,
            ])
        );
    }

    #[test]
    fn test_parse_with_whitespace() {
        let filter = parse_status_filter(Some(" ACTIVE , SETTLED "));
        assert_eq!(
            filter,
            Some(vec![InstrumentStatus::Active, InstrumentStatus::Settled])
        );
    }

    #[test]
    fn test_parse_invalid_falls_back_to_active() {
        let filter = parse_status_filter(Some("GARBAGE"));
        assert_eq!(filter, Some(vec![InstrumentStatus::Active]));
    }

    #[test]
    fn test_parse_mixed_valid_invalid_keeps_valid() {
        let filter = parse_status_filter(Some("ACTIVE,GARBAGE,SETTLED"));
        assert_eq!(
            filter,
            Some(vec![InstrumentStatus::Active, InstrumentStatus::Settled])
        );
    }

    #[test]
    fn test_parse_case_insensitive() {
        let filter = parse_status_filter(Some("active,settled"));
        assert_eq!(
            filter,
            Some(vec![InstrumentStatus::Active, InstrumentStatus::Settled])
        );
    }

    #[test]
    fn test_matches_active_default_filter() {
        let filter = parse_status_filter(None);
        assert!(matches_status_filter(&InstrumentStatus::Active, &filter));
        assert!(!matches_status_filter(&InstrumentStatus::Settled, &filter));
        assert!(!matches_status_filter(
            &InstrumentStatus::ExpiredPendingPrice,
            &filter
        ));
    }

    #[test]
    fn test_matches_all_filter() {
        let filter = parse_status_filter(Some("all"));
        assert!(matches_status_filter(&InstrumentStatus::Active, &filter));
        assert!(matches_status_filter(&InstrumentStatus::Settled, &filter));
        assert!(matches_status_filter(
            &InstrumentStatus::ExpiredPendingPrice,
            &filter
        ));
    }

    #[test]
    fn test_matches_multi_status_filter() {
        let filter = parse_status_filter(Some("ACTIVE,EXPIRED_PENDING_PRICE"));
        assert!(matches_status_filter(&InstrumentStatus::Active, &filter));
        assert!(matches_status_filter(
            &InstrumentStatus::ExpiredPendingPrice,
            &filter
        ));
        assert!(!matches_status_filter(&InstrumentStatus::Settled, &filter));
    }
}

#[cfg(test)]
mod instrument_status_tests {
    use super::*;

    #[test]
    fn test_from_db_str() {
        assert_eq!(
            InstrumentStatus::from_db_str("ACTIVE"),
            Some(InstrumentStatus::Active)
        );
        assert_eq!(
            InstrumentStatus::from_db_str("EXPIRED_PENDING_PRICE"),
            Some(InstrumentStatus::ExpiredPendingPrice)
        );
        assert_eq!(
            InstrumentStatus::from_db_str("SETTLED"),
            Some(InstrumentStatus::Settled)
        );
        assert_eq!(
            InstrumentStatus::from_db_str("active"),
            Some(InstrumentStatus::Active)
        );
        assert_eq!(InstrumentStatus::from_db_str("UNKNOWN"), None);
        assert_eq!(InstrumentStatus::from_db_str(""), None);
    }

    #[test]
    fn test_is_active() {
        assert!(InstrumentStatus::Active.is_active());
        assert!(!InstrumentStatus::ExpiredPendingPrice.is_active());
        assert!(!InstrumentStatus::Settled.is_active());
    }

    #[test]
    fn test_display_roundtrip() {
        for status in [
            InstrumentStatus::Active,
            InstrumentStatus::ExpiredPendingPrice,
            InstrumentStatus::Settled,
        ] {
            let s = status.to_string();
            assert_eq!(InstrumentStatus::from_db_str(&s), Some(status));
        }
    }

    #[test]
    fn test_serde_roundtrip() {
        let status = InstrumentStatus::ExpiredPendingPrice;
        let json = sonic_rs::to_string(&status).unwrap();
        assert_eq!(json, "\"EXPIRED_PENDING_PRICE\"");
        let parsed: InstrumentStatus = sonic_rs::from_str(&json).unwrap();
        assert_eq!(parsed, status);
    }
}

#[cfg(test)]
mod parse_requested_underlyings_tests {
    use super::parse_requested_underlyings;

    #[test]
    fn deduplicates_requested_underlyings_case_insensitively() {
        let parsed = parse_requested_underlyings(
            Some("btc,BTC, eth ,ETH"),
            vec!["BTC".to_string(), "ETH".to_string(), "SOL".to_string()],
        );
        assert_eq!(parsed, vec!["BTC".to_string(), "ETH".to_string()]);
    }

    #[test]
    fn returns_all_available_when_all_requested_after_deduplication() {
        let parsed = parse_requested_underlyings(
            Some("btc,all,BTC"),
            vec!["BTC".to_string(), "ETH".to_string()],
        );
        assert_eq!(parsed, vec!["BTC".to_string(), "ETH".to_string()]);
    }
}

// ---- utoipa path re-exports ----