hypercall_api/handlers/

account.rs

use std::time::Instant;

use alloy::primitives::U256;
use rust_decimal::Decimal;
use rust_decimal_macros::dec;
use std::str::FromStr;
use utoipa::IntoParams;

use crate::sonic_json::SonicJson;
use crate::{
    error::ApiError,
    middleware::SignerContext,
    models::{
        ApiResponse, FillApiResponse, FillsResponse, Order, OrdersResponse, Pagination, Portfolio,
        RiskGridResponse, RiskGridScenario, TradeApiResponse, TradesResponse,
    },
};
use axum::{
    body::Body,
    extract::{Query, State},
    http::{header, StatusCode},
    response::{IntoResponse, Response},
};
use hypercall_db::{AnalyticsReader, LiquidationReader};
use hypercall_types::position_metrics::{enrich_position_metrics, PositionMarginMetrics};
use hypercall_types::WalletAddress;
use serde::{Deserialize, Serialize};
use tracing::error;

use super::{
    api_error_response, api_json_response, convert_extended_risk_matrix,
    convert_risk_grid_scenarios, normalize_orders_status_filter_input, pm_unavailable_response,
    AppRuntimeConfig, AppState,
};

// ---------------------------------------------------------------------------

#[derive(Debug, Deserialize, IntoParams)]
pub struct TradesQuery {
    /// Maximum number of trades to return (default: 100, max: 1000)
    #[param(maximum = 1000)]
    limit: Option<usize>,
    /// Pagination offset
    offset: Option<usize>,
    /// Filter by specific option symbol
    symbol: Option<String>,
    /// Filter by underlying asset (e.g., "BTC", "ETH")
    underlying: Option<String>,
    /// Filter by wallet address, matching maker or taker.
    account: Option<WalletAddress>,
}

#[derive(Debug, Deserialize, IntoParams)]
pub struct PortfolioQuery {
    /// Wallet address to get portfolio for
    #[param(example = "0x1234567890abcdef1234567890abcdef12345678")]
    pub wallet: WalletAddress,
}

fn portfolio_margin_mode_allowed(config: &AppRuntimeConfig, wallet: &WalletAddress) -> bool {
    config.testnet_mode || config.portfolio_margin_mode_allowlist.contains(wallet)
}

#[derive(Debug, Deserialize)]
pub struct WithdrawOptionRequest {
    pub wallet: WalletAddress,
    pub account: WalletAddress,
    pub symbol: String,
    pub amount: String,
    pub nonce: u64,
    pub signature: String,
}

#[derive(Debug, Deserialize)]
pub struct WithdrawUsdcRequest {
    pub wallet: WalletAddress,
    pub account: WalletAddress,
    pub destination: WalletAddress,
    pub amount: String,
    pub nonce: u64,
    pub signature: String,
}

#[derive(Debug, Serialize)]
pub struct WithdrawOptionResponse {
    pub success: bool,
    pub request_id: String,
    pub directive_id: String,
    pub domain_status: String,
    pub delivery_status: String,
    pub message: String,
}

#[derive(Debug, Serialize)]
pub struct WithdrawUsdcResponse {
    pub success: bool,
    pub request_id: String,
    pub directive_id: String,
    pub domain_status: String,
    pub delivery_status: String,
    pub balance_after: Decimal,
    pub message: String,
}

async fn ensure_cash_withdrawal_safety(
    state: &AppState,
    wallet: &WalletAddress,
    amount: Decimal,
) -> Result<(), ApiError> {
    let snapshot = state
        .portfolio_cache
        .compute_wallet_margin_snapshot(wallet)
        .await
        .map_err(|error| {
            error!(
                "Failed to compute margin snapshot for USDC withdrawal {}: {}",
                wallet, error
            );
            ApiError::internal_error("failed to validate withdrawal margin")
        })?;

    let post_withdraw_equity = snapshot.margin_summary.equity - amount;
    let maintenance_required = snapshot.span_margin.maintenance_margin_required;
    if post_withdraw_equity < maintenance_required {
        return Err(ApiError::bad_request(format!(
            "withdrawal would put account below maintenance margin: post_withdraw_equity={}, maintenance_required={}",
            post_withdraw_equity, maintenance_required
        )));
    }

    if let Some(record) = LiquidationReader::get_liquidation_state(state.db.as_ref(), wallet)
        .await
        .map_err(|error| {
            error!(
                "Failed to load liquidation state for USDC withdrawal {}: {}",
                wallet, error
            );
            ApiError::internal_error("failed to validate withdrawal liquidation state")
        })?
    {
        if matches!(
            record.state.as_str(),
            hypercall_types::liquidation_state::state_str::PRE_LIQUIDATION
                | hypercall_types::liquidation_state::state_str::IN_LIQUIDATION
        ) {
            return Err(ApiError::bad_request(
                "withdrawals are disabled while the account is in liquidation",
            ));
        }
    }

    let exchange_pool_balance = state
        .exchange_pool_liquidity_reader
        .usdc_pool_balance()
        .await?;
    if exchange_pool_balance < amount {
        return Err(ApiError::bad_request(format!(
            "insufficient pool liquidity, please try again later: available={}, requested={}",
            exchange_pool_balance, amount
        )));
    }

    Ok(())
}

async fn cash_withdrawal_request_already_journaled(
    state: &AppState,
    request_id: &str,
) -> Result<bool, ApiError> {
    state
        .db
        .directive_outbox_exists(request_id)
        .await
        .map_err(|error| {
            error!(
                "Failed to query directive outbox for USDC withdrawal retry: {}",
                error
            );
            ApiError::internal_error("failed to validate withdrawal idempotency")
        })
}
/// Get a list of recent trades
#[utoipa::path(
    get,
    path = "/trades",
    params(TradesQuery),
    responses(
        (status = 200, description = "List of trades", body = TradesResponse),
        (status = 500, description = "Internal server error")
    ),
    tag = "Trading"
)]
pub async fn get_trades(
    State(app_state): State<AppState>,
    Query(params): Query<TradesQuery>,
) -> Result<SonicJson<TradesResponse>, StatusCode> {
    let limit = params.limit.unwrap_or(100).min(1000);
    let offset = params.offset.unwrap_or(0);

    let records = if let Some(symbol) = params.symbol {
        AnalyticsReader::get_trades_by_option(app_state.db.as_ref(), &symbol, limit)
            .await
            .map_err(|e| {
                tracing::error!("Failed to get trades by symbol {}: {}", symbol, e);
                StatusCode::INTERNAL_SERVER_ERROR
            })?
    } else if let Some(underlying) = params.underlying {
        AnalyticsReader::get_trades_by_underlying(app_state.db.as_ref(), &underlying, limit, offset)
            .await
            .map_err(|e| {
                tracing::error!("Failed to get trades by underlying {}: {}", underlying, e);
                StatusCode::INTERNAL_SERVER_ERROR
            })?
    } else if let Some(account) = params.account {
        AnalyticsReader::get_trades_by_account(app_state.db.as_ref(), &account, limit, offset)
            .await
            .map_err(|e| {
                tracing::error!("Failed to get trades by account {}: {}", account, e);
                StatusCode::INTERNAL_SERVER_ERROR
            })?
    } else {
        AnalyticsReader::get_all_trades(app_state.db.as_ref(), limit, offset)
            .await
            .map_err(|e| {
                tracing::error!("Failed to get all trades: {}", e);
                StatusCode::INTERNAL_SERVER_ERROR
            })?
    };

    let count = records.len();
    tracing::info!("Returning {} trades", count);

    // Convert trades to API response format (with human-readable sizes)
    let api_trades: Vec<TradeApiResponse> = records.into_iter().map(Into::into).collect();

    Ok(SonicJson(TradesResponse {
        success: true,
        data: api_trades,
        pagination: Pagination {
            limit,
            offset,
            count,
        },
    }))
}

/// Get portfolio for a wallet
#[utoipa::path(
    get,
    path = "/portfolio",
    params(PortfolioQuery),
    responses(
        (status = 200, description = "Portfolio data", body = Portfolio),
        (status = 503, description = "Portfolio margin data unavailable", body = ApiResponse<Portfolio>),
        (status = 500, description = "Internal server error")
    ),
    security(("wallet_query" = [])),
    tag = "Portfolio"
)]
pub async fn get_portfolio(
    State(app_state): State<AppState>,
    Query(params): Query<PortfolioQuery>,
) -> Response {
    let wallet = params.wallet;
    tracing::info!("GET /portfolio request for wallet: {}", wallet);
    let margin_mode = match app_state.tier_cache.get_margin_mode(&wallet).await {
        Ok(mode) => mode,
        Err(_) => {
            return api_json_response(StatusCode::OK, ApiResponse::<Portfolio>::success_empty());
        }
    };

    let mut portfolio = if matches!(margin_mode, hypercall_types::MarginMode::Portfolio) {
        match app_state
            .portfolio_cache
            .get_portfolio_fail_closed_pm(&wallet)
            .await
        {
            Ok(portfolio) => portfolio,
            Err(error) => {
                return pm_unavailable_response(format!(
                    "Portfolio margin data unavailable for {}: {}",
                    wallet, error
                ));
            }
        }
    } else {
        match app_state.portfolio_cache.get_portfolio(&wallet).await {
            Ok(p) => p,
            Err(error) => {
                tracing::error!(
                    "Failed to fetch standard portfolio for {}: {}",
                    wallet,
                    error
                );
                return api_error_response(
                    StatusCode::INTERNAL_SERVER_ERROR,
                    "Failed to fetch portfolio".to_string(),
                );
            }
        }
    };

    match app_state
        .portfolio_cache
        .compute_wallet_margin_snapshot(&wallet)
        .await
    {
        Ok(margin_snapshot) => {
            let mode = margin_snapshot.mode;
            portfolio.margin_mode = margin_snapshot.mode.as_str().to_string();
            portfolio.margin_summary = Some(margin_snapshot.margin_summary);
            portfolio.span_margin = Some(margin_snapshot.span_margin);
            portfolio.available_balance = margin_snapshot.available_balance;
            portfolio.total_margin_used = margin_snapshot.total_margin_used;

            if let Err(error) = enrich_position_metrics(
                mode,
                margin_snapshot
                    .standard_position_contributions
                    .map(|contributions| {
                        contributions
                            .into_iter()
                            .map(|(symbol, contribution)| {
                                (
                                    symbol,
                                    PositionMarginMetrics {
                                        initial_margin: contribution.initial_margin,
                                        maintenance_margin: contribution.maintenance_margin,
                                    },
                                )
                            })
                            .collect()
                    }),
                margin_snapshot.standard_option_marks,
                &mut portfolio,
            ) {
                if matches!(mode, hypercall_types::MarginMode::Portfolio) {
                    return pm_unavailable_response(format!(
                        "Portfolio margin data unavailable for {}: {}",
                        wallet, error
                    ));
                }
                return api_error_response(StatusCode::INTERNAL_SERVER_ERROR, error.to_string());
            }
        }
        Err(error) => {
            if matches!(margin_mode, hypercall_types::MarginMode::Portfolio) {
                return pm_unavailable_response(format!(
                    "Portfolio margin data unavailable for {}: {}",
                    wallet, error
                ));
            }

            tracing::warn!(
                "Margin snapshot unavailable for {} (serving portfolio without margin summary): {}",
                wallet,
                error
            );
            portfolio.margin_mode = margin_mode.as_str().to_string();
            portfolio.margin_summary = None;
            portfolio.span_margin = None;
        }
    }

    api_json_response(StatusCode::OK, ApiResponse::success(portfolio))
}

pub async fn withdraw_option(
    State(state): State<AppState>,
    signer_ctx: SignerContext,
    SonicJson(request): SonicJson<WithdrawOptionRequest>,
) -> Result<SonicJson<WithdrawOptionResponse>, ApiError> {
    if testnet_withdrawals_disabled(state.runtime_config.testnet_mode) {
        return Err(ApiError::bad_request(
            "withdrawals are not supported in testnet mode",
        ));
    }
    if request.wallet != signer_ctx.wallet_address {
        return Err(ApiError::forbidden(
            "Wallet mismatch: signer does not match request wallet",
        ));
    }

    let manager = state
        .chain_auth
        .get_manager(request.account.inner())
        .await?;
    if manager == alloy::primitives::Address::ZERO {
        return Err(ApiError::unknown_account(format!(
            "Unknown account: {}",
            request.account
        )));
    }
    if manager != request.wallet.inner() {
        return Err(ApiError::forbidden(
            "Account manager does not match request wallet",
        ));
    }

    let quantity = Decimal::from_str(&request.amount)
        .map_err(|_| ApiError::bad_request("amount must be a decimal string"))?;
    if quantity <= Decimal::ZERO {
        return Err(ApiError::bad_request("amount must be positive"));
    }
    let canonical_amount = canonical_decimal_string(quantity);

    let instrument = state
        .instruments_cache
        .get_by_symbol(&request.symbol)
        .await
        .ok_or_else(|| ApiError::bad_request("unknown option symbol"))?;
    let directive = option_withdrawal_directive(&instrument, quantity)?;
    let request_id = option_withdrawal_request_id(
        &request.wallet,
        &request.account,
        &request.symbol,
        &canonical_amount,
        request.nonce,
    );
    let action_bytes = hypercall_runtime_api::encode_credit_option_action(directive)
        .map_err(|error| ApiError::bad_request(format!("invalid withdrawal: {}", error)))?;
    let rsm_signer = rsm_signer_address_from_state(&state).await?;

    let sender = state.option_withdrawal_sender.clone().ok_or_else(|| {
        ApiError::new(
            StatusCode::SERVICE_UNAVAILABLE,
            "service_unavailable",
            "option withdrawal engine path disabled",
        )
    })?;
    let (applied_tx, applied_rx) = tokio::sync::oneshot::channel();
    sender
        .send(hypercall_runtime_api::OptionWithdrawalRequest {
            request_id: request_id.clone(),
            wallet: request.wallet,
            account: request.account,
            signer: signer_ctx.signer_address,
            rsm_signer,
            symbol: request.symbol.clone(),
            quantity,
            nonce: request.nonce,
            action: action_bytes,
            timestamp_ms: hypercall_types::utils::get_timestamp_millis(),
            applied_tx: Some(applied_tx),
        })
        .await
        .map_err(|_| {
            ApiError::new(
                StatusCode::SERVICE_UNAVAILABLE,
                "service_unavailable",
                "option withdrawal engine path closed",
            )
        })?;
    let receipt = applied_rx
        .await
        .map_err(|_| {
            ApiError::new(
                StatusCode::SERVICE_UNAVAILABLE,
                "service_unavailable",
                "option withdrawal apply dropped",
            )
        })?
        .map_err(ApiError::bad_request)?;

    Ok(SonicJson(WithdrawOptionResponse {
        success: true,
        request_id,
        directive_id: receipt.directive_id,
        domain_status: receipt.domain_status.as_str().to_string(),
        delivery_status: receipt.delivery_status.as_str().to_string(),
        message: "Option withdrawal accepted".to_string(),
    }))
}

pub async fn withdraw_usdc(
    State(state): State<AppState>,
    signer_ctx: SignerContext,
    SonicJson(request): SonicJson<WithdrawUsdcRequest>,
) -> Result<SonicJson<WithdrawUsdcResponse>, ApiError> {
    if testnet_withdrawals_disabled(state.runtime_config.testnet_mode) {
        return Err(ApiError::bad_request(
            "withdrawals are not supported in testnet mode",
        ));
    }
    if request.wallet != signer_ctx.wallet_address {
        return Err(ApiError::forbidden(
            "Wallet mismatch: signer does not match request wallet",
        ));
    }

    let margin_mode = state
        .tier_cache
        .get_margin_mode(&request.wallet)
        .await
        .map_err(|_| ApiError::internal_error("failed to determine margin mode for withdrawal"))?;
    if !matches!(margin_mode, hypercall_types::MarginMode::Standard) {
        return Err(ApiError::bad_request(
            "USDC withdrawals are only supported for standard margin accounts",
        ));
    }
    let now_ms = hypercall_types::utils::get_timestamp_millis();
    if !hypercall_engine::nonce_within_time_bounds(request.nonce, now_ms) {
        return Err(ApiError::bad_request(format!(
            "nonce {} is outside acceptable time bounds",
            request.nonce
        )));
    }

    // Validate destination before reserving balance so that an invalid
    // destination (e.g. zero address) cannot leave funds permanently locked
    // in a reserve with no matching outbox row.
    if request.destination == WalletAddress::default() {
        return Err(ApiError::bad_request(
            "withdrawal destination must not be the zero address",
        ));
    }
    if request.account == WalletAddress::default() {
        return Err(ApiError::bad_request(
            "withdrawal account must not be the zero address",
        ));
    }
    if request.account != request.wallet {
        return Err(ApiError::bad_request(
            "standard margin USDC withdrawal account must equal wallet",
        ));
    }

    let amount = Decimal::from_str(&request.amount)
        .map_err(|_| ApiError::bad_request("amount must be a decimal string"))?;
    if amount <= Decimal::ZERO {
        return Err(ApiError::bad_request("amount must be positive"));
    }
    let canonical_amount = canonical_decimal_string(amount);
    let request_id = usdc_withdrawal_request_id(
        &request.wallet,
        &request.account,
        &request.destination,
        &canonical_amount,
        request.nonce,
    );
    if !cash_withdrawal_request_already_journaled(&state, &request_id).await? {
        ensure_cash_withdrawal_safety(&state, &request.wallet, amount).await?;
    }
    let amount_wei = usdc_amount_to_token_amount(amount)?;
    let timestamp_ms = hypercall_types::utils::get_timestamp_millis();
    let rsm_signer = rsm_signer_address_from_state(&state).await?;

    let sender = state.cash_withdrawal_sender.clone().ok_or_else(|| {
        ApiError::new(
            StatusCode::SERVICE_UNAVAILABLE,
            "service_unavailable",
            "cash withdrawal engine path disabled",
        )
    })?;
    let (applied_tx, applied_rx) = tokio::sync::oneshot::channel();
    sender
        .send(hypercall_runtime_api::CashWithdrawalRequest {
            request_id: request_id.clone(),
            wallet: request.wallet,
            account: request.account,
            destination: request.destination,
            signer: signer_ctx.signer_address,
            rsm_signer,
            amount,
            amount_wei,
            nonce: request.nonce,
            timestamp_ms,
            applied_tx: Some(applied_tx),
        })
        .await
        .map_err(|_| {
            ApiError::new(
                StatusCode::SERVICE_UNAVAILABLE,
                "service_unavailable",
                "cash withdrawal engine path closed",
            )
        })?;
    let receipt = applied_rx
        .await
        .map_err(|_| {
            ApiError::new(
                StatusCode::SERVICE_UNAVAILABLE,
                "service_unavailable",
                "cash withdrawal apply dropped",
            )
        })?
        .map_err(ApiError::bad_request)?;

    Ok(SonicJson(WithdrawUsdcResponse {
        success: true,
        request_id: request_id.clone(),
        directive_id: receipt.directive_id,
        domain_status: receipt.domain_status.as_str().to_string(),
        delivery_status: receipt.delivery_status.as_str().to_string(),
        balance_after: receipt.balance_after,
        message: "USDC withdrawal accepted".to_string(),
    }))
}

fn testnet_withdrawals_disabled(testnet_mode: bool) -> bool {
    if !testnet_mode {
        return false;
    }

    #[cfg(feature = "test-endpoints")]
    {
        if std::env::var("ALLOW_TESTNET_WITHDRAWALS").as_deref() == Ok("1") {
            return false;
        }
    }

    true
}

fn option_withdrawal_directive(
    instrument: &hypercall_types::Instrument,
    quantity: Decimal,
) -> Result<hypercall_runtime_api::SystemCreditOptionDirective, ApiError> {
    let option_type = instrument
        .option_type
        .parse::<hypercall_types::OptionType>()
        .map_err(|_| ApiError::bad_request("invalid option_type for instrument"))?;
    let strike_e8 = hypercall_types::utils::strike_to_e8(instrument.strike)
        .map_err(|error| ApiError::bad_request(format!("invalid strike: {}", error)))?;
    let underlying =
        hypercall_types::option_token_address::encode_short_string_bytes32(&instrument.underlying)
            .map_err(|error| ApiError::bad_request(format!("invalid underlying: {}", error)))?;
    let expiry_ts = option_expiry_to_timestamp(&instrument.underlying, instrument.expiry)
        .map_err(|error| ApiError::bad_request(format!("invalid expiry: {}", error)))?;

    Ok(hypercall_runtime_api::SystemCreditOptionDirective {
        underlying: underlying.into(),
        expiry: U256::from(expiry_ts),
        strike: U256::from(strike_e8),
        is_call: option_type.is_call(),
        amount_wei: option_quantity_to_token_amount(quantity)?,
    })
}

fn option_expiry_to_timestamp(underlying: &str, expiry: u64) -> Result<u64, String> {
    if expiry < 100_000_000 {
        hypercall_types::utils::expiry_date_to_timestamp_checked(underlying, expiry)
            .map_err(|error| error.to_string())
    } else {
        Ok(expiry)
    }
}

fn option_quantity_to_token_amount(quantity: Decimal) -> Result<U256, ApiError> {
    let scaled = quantity * dec!(1000000);
    if scaled.fract() != Decimal::ZERO {
        return Err(ApiError::bad_request(
            "amount must have at most 6 decimal places",
        ));
    }
    U256::from_str(&scaled.normalize().to_string())
        .map_err(|_| ApiError::bad_request("amount is too large for uint256"))
}

fn usdc_amount_to_token_amount(amount: Decimal) -> Result<u64, ApiError> {
    // HyperCore CoreWriter sendAsset uses 1e8 scaling for all token amounts,
    // regardless of the ERC20's native decimals (USDC ERC20 = 6 decimals,
    // but CoreWriter amountWei = amount * 1e8).
    let scaled = amount * dec!(100000000);
    if scaled.fract() != Decimal::ZERO {
        return Err(ApiError::bad_request(
            "amount must have at most 8 decimal places",
        ));
    }
    u64::from_str(&scaled.normalize().to_string())
        .map_err(|_| ApiError::bad_request("amount is too large for uint64"))
}

fn canonical_decimal_string(amount: Decimal) -> String {
    amount.normalize().to_string()
}

fn option_withdrawal_request_id(
    wallet: &WalletAddress,
    account: &WalletAddress,
    symbol: &str,
    amount: &str,
    nonce: u64,
) -> String {
    let mut material = Vec::with_capacity(20 + symbol.len() + amount.len() + 32);
    material.extend_from_slice(b"hypercall:withdraw-option:v1");
    material.extend_from_slice(wallet.as_bytes());
    material.extend_from_slice(account.as_bytes());
    material.extend_from_slice(symbol.as_bytes());
    material.push(0);
    material.extend_from_slice(amount.as_bytes());
    material.push(0);
    material.extend_from_slice(&nonce.to_be_bytes());

    let hash = alloy::primitives::keccak256(material);
    let mut bytes = [0_u8; 16];
    bytes.copy_from_slice(&hash[..16]);
    bytes[6] = (bytes[6] & 0x0f) | 0x80;
    bytes[8] = (bytes[8] & 0x3f) | 0x80;
    uuid::Uuid::from_bytes(bytes).to_string()
}

async fn rsm_signer_address_from_state(state: &AppState) -> Result<WalletAddress, ApiError> {
    if let Some(address) = state.rsm_signer_address {
        return Ok(address);
    }

    let signer = state.rsm_signer.as_ref().ok_or_else(|| {
        ApiError::new(
            StatusCode::SERVICE_UNAVAILABLE,
            "service_unavailable",
            "RSM signer is not configured",
        )
    })?;
    signer
        .status()
        .await
        .map(|status| status.signer)
        .map_err(|error| {
            ApiError::new(
                StatusCode::SERVICE_UNAVAILABLE,
                "service_unavailable",
                format!("RSM signer is not available: {error}"),
            )
        })
}

fn usdc_withdrawal_request_id(
    wallet: &WalletAddress,
    account: &WalletAddress,
    destination: &WalletAddress,
    amount: &str,
    nonce: u64,
) -> String {
    let mut material = Vec::with_capacity(20 * 3 + amount.len() + 40);
    material.extend_from_slice(b"hypercall:withdraw-usdc:v1");
    material.extend_from_slice(wallet.as_bytes());
    material.extend_from_slice(account.as_bytes());
    material.extend_from_slice(destination.as_bytes());
    material.push(0);
    material.extend_from_slice(amount.as_bytes());
    material.push(0);
    material.extend_from_slice(&nonce.to_be_bytes());

    let hash = alloy::primitives::keccak256(material);
    let mut bytes = [0_u8; 16];
    bytes.copy_from_slice(&hash[..16]);
    bytes[6] = (bytes[6] & 0x0f) | 0x80;
    bytes[8] = (bytes[8] & 0x3f) | 0x80;
    uuid::Uuid::from_bytes(bytes).to_string()
}

#[cfg(test)]
mod portfolio_liquidation_tests {
    use super::*;
    use crate::models::{Portfolio, Position, PositionWithMetrics, SpanMarginSummary};
    use chrono::Utc;
    use std::collections::HashMap;

    fn test_wallet(id: u8) -> WalletAddress {
        let mut bytes = [0u8; 20];
        bytes[19] = id;
        WalletAddress::from(bytes)
    }

    fn test_runtime_config(
        testnet_mode: bool,
        portfolio_margin_mode_allowlist: Vec<WalletAddress>,
    ) -> AppRuntimeConfig {
        AppRuntimeConfig {
            testnet_mode,
            trade_explorer_url_template: None,
            wal_path: std::path::PathBuf::from("/tmp/account-handler-test.wal"),
            db_host: "localhost".to_string(),
            db_name: "hypercall_test".to_string(),
            directive_chain_id: hypercall_types::directives::HYPERCALL_MAINNET_CHAIN_ID,
            signing_chain_id: hypercall_types::directives::HYPERCALL_MAINNET_CHAIN_ID,
            exchange_contract_address: "0x0000000000000000000000000000000000000000".to_string(),
            portfolio_margin_pool_enabled: false,
            portfolio_margin_mode_allowlist,
            portfolio_margin_settlement_allowlist: Vec::new(),
            #[cfg(feature = "rsm-state")]
            rsm_environment: hypercall_db::ValidatorRsmEnvironment::Testnet,
        }
    }

    #[test]
    fn portfolio_margin_mode_allowed_in_testnet() {
        let config = test_runtime_config(true, Vec::new());
        assert!(portfolio_margin_mode_allowed(&config, &test_wallet(1)));
    }

    #[test]
    fn portfolio_margin_mode_allowed_for_allowlisted_wallet_outside_testnet() {
        let wallet = test_wallet(1);
        let config = test_runtime_config(false, vec![wallet]);
        assert!(portfolio_margin_mode_allowed(&config, &wallet));
    }

    #[test]
    fn portfolio_margin_mode_rejected_for_unlisted_wallet_outside_testnet() {
        let config = test_runtime_config(false, vec![test_wallet(1)]);
        assert!(!portfolio_margin_mode_allowed(&config, &test_wallet(2)));
    }

    fn test_position(
        symbol: &str,
        amount: Decimal,
        entry: Decimal,
        upnl: Decimal,
    ) -> PositionWithMetrics {
        PositionWithMetrics {
            position: Position {
                wallet_address: test_wallet(1),
                symbol: symbol.to_string(),
                amount,
                entry_price: entry,
                margin_posted: dec!(0),
                realized_pnl: dec!(0),
                unrealized_pnl: upnl,
                updated_at: Utc::now(),
            },
            notional_value: amount * entry,
            maintenance_margin: dec!(0),
            liquidation_price: dec!(0),
            margin_ratio: dec!(0),
        }
    }

    fn base_portfolio(positions: Vec<PositionWithMetrics>) -> Portfolio {
        Portfolio {
            wallet_address: test_wallet(1),
            positions,
            total_margin_used: dec!(0),
            available_balance: dec!(0),
            span_margin: Some(SpanMarginSummary {
                equity: dec!(10000),
                initial_margin_required: dec!(0),
                maintenance_margin_required: dec!(9000),
                open_orders_initial_margin: dec!(0),
                option_margin_required: dec!(0),
                scanning_risk: dec!(0),
                option_floor: dec!(0),
                gamma_overlay: dec!(0),
                hypercore_margin_required: dec!(0),
            }),
            margin_mode: "standard".to_string(),
            margin_summary: None,
        }
    }

    #[test]
    fn test_compute_short_option_liquidation_mark() {
        let liq = hypercall_types::position_metrics::compute_short_option_liquidation_mark(
            dec!(10000),
            dec!(9000),
            dec!(-2),
            dec!(100),
        )
        .expect("liq mark should compute");
        assert_eq!(liq, dec!(600));
    }

    #[test]
    fn test_compute_short_option_liquidation_mark_already_liquidating() {
        let liq = hypercall_types::position_metrics::compute_short_option_liquidation_mark(
            dec!(8000),
            dec!(9000),
            dec!(-1),
            dec!(50),
        )
        .expect("liq mark should compute");
        assert_eq!(liq, dec!(50));
    }

    #[test]
    fn test_enrich_position_metrics_standard_mode() {
        let mut portfolio = base_portfolio(vec![
            test_position("BTC-20260213-70000-C", dec!(-2), dec!(100), dec!(-20)),
            test_position("BTC-20260213-80000-C", dec!(1), dec!(30), dec!(5)),
        ]);

        let mut contributions = HashMap::new();
        contributions.insert(
            "BTC-20260213-70000-C".to_string(),
            hypercall_types::position_metrics::PositionMarginMetrics {
                initial_margin: dec!(1500),
                maintenance_margin: dec!(900),
            },
        );

        let mut marks = HashMap::new();
        marks.insert("BTC-20260213-70000-C".to_string(), dec!(110));
        marks.insert("BTC-20260213-80000-C".to_string(), dec!(30));

        enrich_position_metrics(
            hypercall_types::MarginMode::Standard,
            Some(contributions),
            Some(marks),
            &mut portfolio,
        )
        .expect("enrichment should succeed");

        let short = portfolio
            .positions
            .iter()
            .find(|p| p.position.symbol == "BTC-20260213-70000-C")
            .expect("short position exists");
        assert_eq!(short.position.margin_posted, dec!(1500));
        assert_eq!(short.maintenance_margin, dec!(900));
        assert!(short.liquidation_price > dec!(0));

        let long = portfolio
            .positions
            .iter()
            .find(|p| p.position.symbol == "BTC-20260213-80000-C")
            .expect("long position exists");
        assert_eq!(long.liquidation_price, dec!(0));
    }

    #[test]
    fn test_enrich_position_metrics_portfolio_mode_uses_position_derived_mark() {
        let mut portfolio = base_portfolio(vec![test_position(
            "BTC-20260213-70000-C",
            dec!(-2),
            dec!(100),
            dec!(-20),
        )]);
        if let Some(ref mut span) = portfolio.span_margin {
            span.equity = dec!(9800);
            span.maintenance_margin_required = dec!(9000);
        }

        enrich_position_metrics(
            hypercall_types::MarginMode::Portfolio,
            None,
            None,
            &mut portfolio,
        )
        .expect("enrichment should succeed");

        let short = &portfolio.positions[0];
        // Derived mark = entry + upnl/amount = 100 + (-20/-2) = 110
        // liq = 110 + ((9000-9800)/-2) = 510
        assert_eq!(short.liquidation_price, dec!(510));
    }

    #[test]
    fn test_option_withdrawal_request_id_is_nonce_idempotent() {
        let wallet = test_wallet(1);
        let account = test_wallet(2);
        let first =
            option_withdrawal_request_id(&wallet, &account, "BTC-20260130-100000-C", "1.25", 42);
        let retry =
            option_withdrawal_request_id(&wallet, &account, "BTC-20260130-100000-C", "1.25", 42);
        let different_nonce =
            option_withdrawal_request_id(&wallet, &account, "BTC-20260130-100000-C", "1.25", 43);

        assert_eq!(first, retry);
        assert_ne!(first, different_nonce);
        uuid::Uuid::parse_str(&first).expect("request id should be a UUID");
    }

    #[test]
    fn test_option_withdrawal_request_id_uses_canonical_amount() {
        let wallet = test_wallet(1);
        let account = test_wallet(2);
        let canonical = canonical_decimal_string(Decimal::from_str("1.000000").unwrap());
        let retry = canonical_decimal_string(Decimal::from_str("01.0").unwrap());

        assert_eq!(canonical, "1");
        assert_eq!(retry, "1");

        let first = option_withdrawal_request_id(
            &wallet,
            &account,
            "BTC-20260130-100000-C",
            &canonical,
            42,
        );
        let second =
            option_withdrawal_request_id(&wallet, &account, "BTC-20260130-100000-C", &retry, 42);
        let different_nonce = option_withdrawal_request_id(
            &wallet,
            &account,
            "BTC-20260130-100000-C",
            &canonical,
            43,
        );

        assert_eq!(first, second);
        assert_ne!(first, different_nonce);
        uuid::Uuid::parse_str(&first).expect("request id should be a UUID");
    }

    #[test]
    fn test_usdc_withdrawal_request_id_uses_canonical_amount() {
        let wallet = test_wallet(1);
        let account = test_wallet(2);
        let destination = test_wallet(3);
        let canonical = canonical_decimal_string(Decimal::from_str("1.00000000").unwrap());
        let retry = canonical_decimal_string(Decimal::from_str("01.0").unwrap());

        assert_eq!(canonical, "1");
        assert_eq!(retry, "1");

        let first = usdc_withdrawal_request_id(&wallet, &account, &destination, &canonical, 42);
        let second = usdc_withdrawal_request_id(&wallet, &account, &destination, &retry, 42);
        let different_nonce =
            usdc_withdrawal_request_id(&wallet, &account, &destination, &canonical, 43);

        assert_eq!(first, second);
        assert_ne!(first, different_nonce);
        uuid::Uuid::parse_str(&first).expect("request id should be a UUID");
    }

    #[test]
    fn test_parse_exchange_pool_balance_parser() {
        let json = serde_json::json!({
            "marginSummary": {
                "accountValue": "41316.993784",
                "totalNtlPos": "0.0",
                "totalRawUsd": "41316.993784",
                "totalMarginUsed": "0.0"
            },
            "withdrawable": "41316.993784",
            "assetPositions": [],
            "time": 1781200688450_u64
        });

        assert_eq!(
            crate::state::parse_hypercore_withdrawable_balance(&json).unwrap(),
            dec!(41316.993784)
        );
    }

    #[test]
    fn test_parse_exchange_pool_balance_allows_zero_withdrawable() {
        let json = serde_json::json!({
            "withdrawable": "0.0",
        });

        assert_eq!(
            crate::state::parse_hypercore_withdrawable_balance(&json).unwrap(),
            Decimal::ZERO
        );
    }

    #[test]
    fn test_parse_exchange_pool_balance_missing_withdrawable_errors() {
        let json = serde_json::json!({
            "marginSummary": {},
        });

        assert!(crate::state::parse_hypercore_withdrawable_balance(&json).is_err());
    }

    #[test]
    fn test_parse_exchange_pool_balance_invalid_withdrawable_errors() {
        let json = serde_json::json!({
            "withdrawable": "not-a-number",
        });

        assert!(crate::state::parse_hypercore_withdrawable_balance(&json).is_err());
    }

    #[test]
    fn test_option_quantity_to_token_amount_accepts_decimal_contracts() {
        assert_eq!(
            option_quantity_to_token_amount(dec!(1.25)).expect("valid option quantity"),
            U256::from(1_250_000_u64)
        );
        assert_eq!(
            option_quantity_to_token_amount(dec!(1.0)).expect("valid option quantity"),
            U256::from(1_000_000_u64)
        );
        assert!(option_quantity_to_token_amount(dec!(0.0000001)).is_err());
    }

    #[test]
    fn test_option_expiry_to_timestamp_accepts_date_code_and_timestamp() {
        let converted =
            option_expiry_to_timestamp("BTC", 20260130).expect("date code should convert");
        assert!(converted > 1_700_000_000);

        assert_eq!(
            option_expiry_to_timestamp("BTC", converted).expect("timestamp should pass through"),
            converted
        );
    }
}

#[cfg(test)]
mod options_chain_handler_tests {
    use crate::handlers::options_chain::insert_options_chain_leg_for_strike;
    use crate::models::{OptionsChainGreeksAbs, OptionsChainLeg};
    use crate::options_chain::{
        apply_side_filter_to_leg, compute_cash_greeks, OptionsChainSideFilter,
    };
    use rust_decimal_macros::dec;
    use std::collections::BTreeMap;

    fn test_leg(symbol: &str) -> OptionsChainLeg {
        OptionsChainLeg {
            symbol: symbol.to_string(),
            option_token_address: None,
            bid_price_usd: Some(100.0),
            bid_iv: Some(0.5),
            bid_size_contracts: Some(1.0),
            bid_size_usd_notional: Some(100.0),
            ask_price_usd: Some(101.0),
            ask_iv: Some(0.51),
            ask_size_contracts: Some(2.0),
            ask_size_usd_notional: Some(202.0),
            greeks_abs: None,
            greeks_cash: None,
        }
    }

    #[test]
    fn test_insert_options_chain_leg_groups_call_and_put_same_strike() {
        let mut grouped = BTreeMap::new();
        insert_options_chain_leg_for_strike(
            &mut grouped,
            dec!(50000),
            "call",
            test_leg("BTC-20260331-50000-C"),
        )
        .expect("call should insert");
        insert_options_chain_leg_for_strike(
            &mut grouped,
            dec!(50000),
            "put",
            test_leg("BTC-20260331-50000-P"),
        )
        .expect("put should insert");

        assert_eq!(grouped.len(), 1, "both legs should share one strike row");
        let row = grouped.get(&dec!(50000)).expect("strike row should exist");
        assert!(row.call.is_some(), "call leg should be present");
        assert!(row.put.is_some(), "put leg should be present");
    }

    #[test]
    fn test_side_filter_buy_hides_bid_fields() {
        let mut leg = test_leg("BTC-20260331-50000-C");
        apply_side_filter_to_leg(&mut leg, OptionsChainSideFilter::Buy);
        assert!(leg.bid_price_usd.is_none());
        assert!(leg.bid_iv.is_none());
        assert!(leg.bid_size_contracts.is_none());
        assert!(leg.bid_size_usd_notional.is_none());
        assert!(leg.ask_price_usd.is_some());
        assert!(leg.ask_size_contracts.is_some());
    }

    #[test]
    fn test_cash_greeks_formula_uses_pnl_style_convention() {
        let abs = OptionsChainGreeksAbs {
            delta: 0.4,
            gamma: 0.002,
            theta: -1.5,
            vega: 75.0,
        };
        let spot = 50_000.0;
        let cash = compute_cash_greeks(&abs, spot).expect("cash greeks should compute");

        assert!((cash.delta_1pct_usd - 200.0).abs() < 1e-9);
        assert!((cash.gamma_1pct_usd - 250.0).abs() < 1e-9);
        assert!((cash.theta_1d_usd + 1.5).abs() < 1e-9);
        assert!((cash.vega_1vol_usd - 75.0).abs() < 1e-9);
    }
}

#[derive(Debug, Deserialize, IntoParams)]
pub struct RiskGridQuery {
    /// Wallet address to get risk grid for
    #[param(example = "0x1234567890abcdef1234567890abcdef12345678")]
    pub wallet: WalletAddress,
}

/// Get extended risk grid for a wallet.
///
/// Returns detailed margin breakdown and scenario P&L for risk analysis.
/// This is similar to Deribit's risk grid endpoint.
///
/// The response includes:
/// - `equity`: Executed PM equity = cash + executed option UPNL + executed perp UPNL
/// - `position_initial_margin`: IM from executed positions only
/// - `position_maintenance_margin`: MM threshold for liquidation
/// - `open_orders_initial_margin`: Additional IM from open orders
/// - `scenarios`: P&L under each SPAN scenario
#[utoipa::path(
    get,
    path = "/risk/grid",
    params(RiskGridQuery),
    responses(
        (status = 200, description = "Risk grid response", body = ApiResponse<RiskGridResponse>),
        (status = 503, description = "Portfolio margin data unavailable", body = ApiResponse<RiskGridResponse>)
    ),
    tag = "Risk"
)]
pub async fn get_risk_grid(
    State(app_state): State<AppState>,
    Query(params): Query<RiskGridQuery>,
) -> Response {
    let wallet = params.wallet;
    tracing::info!("GET /risk/grid request for wallet: {}", wallet);

    // Risk grid (SPAN scenarios) is only available for portfolio margin accounts
    let margin_mode = match app_state.tier_cache.get_margin_mode(&wallet).await {
        Ok(mode) => mode,
        Err(error) => {
            return api_error_response(
                StatusCode::SERVICE_UNAVAILABLE,
                format!("Margin mode unavailable for {}: {}", wallet, error),
            );
        }
    };
    if matches!(margin_mode, hypercall_types::MarginMode::Standard) {
        return api_error_response(
            StatusCode::OK,
            "Risk grid is only available for portfolio margin accounts. This account uses standard margin.".to_string(),
        );
    }

    let grid_data = match app_state
        .portfolio_cache
        .compute_pm_risk_grid_data(&wallet)
        .await
    {
        Ok(data) => data,
        Err(e) => {
            tracing::warn!("Failed to compute PM risk grid for {}: {}", wallet, e);
            return pm_unavailable_response(format!("Failed to compute PM risk grid: {}", e));
        }
    };

    let position_im = grid_data.position_details.initial_margin_required;
    let open_orders_im =
        (grid_data.margin_details.initial_margin_required - position_im).max(Decimal::ZERO);
    let position_mm = grid_data.position_details.maintenance_margin_required;

    let scenarios: Vec<RiskGridScenario> =
        match convert_risk_grid_scenarios(grid_data.scenario_pnls) {
            Ok(scenarios) => scenarios,
            Err(error) => {
                return pm_unavailable_response(format!("Failed to serialize risk grid: {}", error))
            }
        };

    let extended_risk_matrix = match convert_extended_risk_matrix(grid_data.extended_grid) {
        Ok(m) => m,
        Err(error) => {
            return pm_unavailable_response(format!(
                "Failed to serialize extended risk grid: {}",
                error
            ))
        }
    };

    api_json_response(
        StatusCode::OK,
        ApiResponse::success(RiskGridResponse {
            equity: grid_data.margin_details.equity,
            position_initial_margin: position_im,
            position_maintenance_margin: position_mm,
            open_orders_initial_margin: open_orders_im,
            total_initial_margin: position_im + open_orders_im,
            scanning_risk: grid_data.margin_details.scanning_risk,
            option_floor: grid_data.margin_details.option_floor,
            gamma_overlay: grid_data.margin_details.gamma_overlay,
            scenarios,
            extended_risk_matrix,
        }),
    )
}

#[derive(Debug, Deserialize, IntoParams)]
pub struct FillsQuery {
    /// Wallet address to get fills for
    #[param(example = "0x1234567890abcdef1234567890abcdef12345678")]
    pub wallet: WalletAddress,
    /// Maximum number of fills to return (default: 100, max: 1000)
    #[param(maximum = 1000)]
    pub limit: Option<usize>,
    /// Pagination offset
    pub offset: Option<usize>,
}

#[derive(Debug, Deserialize, IntoParams)]
pub struct OrdersQuery {
    /// Wallet address to get orders for
    #[param(example = "0x1234567890abcdef1234567890abcdef12345678")]
    pub wallet: WalletAddress,
    /// Filter by order status
    pub status: Option<String>,
    /// Maximum number of orders to return (default: 50, max: 50)
    #[param(maximum = 50)]
    pub limit: Option<usize>,
    /// Pagination offset
    pub offset: Option<usize>,
}

#[derive(Debug, Deserialize, IntoParams)]
pub struct MarketsQuery {
    /// Whether to include individual instruments in the response. Defaults to true.
    #[param(example = "false")]
    include_instruments: Option<bool>,
}

/// Get all available markets with their instruments
#[utoipa::path(
    get,
    path = "/markets",
    params(MarketsQuery),
    responses(
        (status = 200, description = "List of markets", body = MarketsResponse),
        (status = 500, description = "Internal server error")
    ),
    tag = "Markets"
)]
pub async fn get_markets(
    State(app_state): State<AppState>,
    Query(params): Query<MarketsQuery>,
) -> Response {
    let started = Instant::now();
    let include_instruments = params.include_instruments.unwrap_or(true);
    let (body, built_at) = if include_instruments {
        app_state.markets_snapshot_cache.response()
    } else {
        app_state.markets_snapshot_cache.response_slim()
    };
    let last_modified = httpdate::fmt_http_date(built_at);
    // Cache-Control max-age=1 matches the MarketsSnapshotCache refresh interval (1s).
    // The response is already a pre-built snapshot so it won't change faster than that;
    // this lets CDNs/proxies absorb repeated hits within the same refresh window.
    let response = (
        StatusCode::OK,
        [
            (header::CONTENT_TYPE, "application/json".to_string()),
            (header::LAST_MODIFIED, last_modified),
            (header::CACHE_CONTROL, "public, max-age=1".to_string()),
        ],
        Body::from(body),
    )
        .into_response();
    let elapsed = started.elapsed().as_secs_f64();
    metrics::histogram!("ht_markets_handler_seconds").record(elapsed);
    metrics::histogram!("ht_http_request_seconds", "endpoint" => "/markets").record(elapsed);
    response
}

/// Get fills for a wallet
#[utoipa::path(
    get,
    path = "/fills",
    params(FillsQuery),
    responses(
        (status = 200, description = "List of fills", body = FillsResponse),
        (status = 500, description = "Internal server error")
    ),
    security(("wallet_query" = [])),
    tag = "Portfolio"
)]
pub async fn get_fills(
    State(app_state): State<AppState>,
    Query(params): Query<FillsQuery>,
) -> Result<SonicJson<FillsResponse>, StatusCode> {
    let limit = params.limit.unwrap_or(100).min(1000);
    let offset = params.offset.unwrap_or(0);

    tracing::info!(
        "GET /fills request for wallet: {}, limit: {}, offset: {}",
        params.wallet,
        limit,
        offset
    );

    match AnalyticsReader::get_fills_by_account(
        app_state.db.as_ref(),
        &params.wallet,
        limit,
        offset,
    )
    .await
    {
        Ok(records) => {
            let count = records.len();
            // Convert fills to API response format (with human-readable sizes)
            let api_fills: Vec<FillApiResponse> = records.into_iter().map(Into::into).collect();
            Ok(SonicJson(FillsResponse {
                success: true,
                data: api_fills,
                pagination: Pagination {
                    limit,
                    offset,
                    count,
                },
            }))
        }
        Err(e) => {
            error!("Failed to get fills: {}", e);
            Err(StatusCode::INTERNAL_SERVER_ERROR)
        }
    }
}

/// Get orders for a wallet
#[utoipa::path(
    get,
    path = "/orders",
    params(OrdersQuery),
    responses(
        (status = 200, description = "List of orders", body = OrdersResponse),
        (status = 500, description = "Internal server error")
    ),
    security(("wallet_query" = [])),
    tag = "Trading"
)]
pub async fn get_orders(
    State(app_state): State<AppState>,
    Query(params): Query<OrdersQuery>,
) -> Result<SonicJson<OrdersResponse>, StatusCode> {
    let limit = params.limit.unwrap_or(50).min(200); // Default to 50, max 200
    let offset = params.offset.unwrap_or(0);
    let normalized_status = params
        .status
        .as_deref()
        .map(normalize_orders_status_filter_input);
    let status = normalized_status.as_deref();

    let wallet = params.wallet;
    tracing::info!(
        "GET /orders request for wallet: {}, status: {:?}, limit: {}, offset: {}",
        wallet,
        status,
        limit,
        offset
    );

    // Default (no status) and open/active statuses read from engine snapshot (engine truth).
    let is_open_status = matches!(
        status,
        None | Some("open") | Some("acked") | Some("partially_filled")
    );

    let orders = if is_open_status {
        let summaries = app_state.order_snapshot.get_open_orders_for_wallet(&wallet);
        let mut api_orders: Vec<Order> = summaries
            .into_iter()
            .filter(|s| match status {
                Some("partially_filled") => s.remaining_size < s.original_size,
                Some("acked") | Some("open") => s.remaining_size == s.original_size,
                _ => true,
            })
            .map(|s| {
                let filled = s.original_size - s.remaining_size;
                let status_str = if s.remaining_size < s.original_size {
                    "partially_filled"
                } else {
                    "open"
                };
                Order {
                    order_id: i64::try_from(s.order_id).expect("Engine order_id exceeded i64::MAX"),
                    wallet_address: wallet,
                    symbol: s.symbol,
                    side: format!("{:?}", s.side),
                    price: s.price,
                    size: s.original_size,
                    tif: "gtc".to_string(),
                    status: Some(status_str.to_string()),
                    created_at: s.created_at,
                    updated_at: None,
                    filled_size: Some(filled),
                    mmp_enabled: s.mmp_enabled,
                }
            })
            .collect();
        // Apply pagination
        api_orders.sort_by_key(|o| std::cmp::Reverse(o.created_at));
        api_orders
            .into_iter()
            .skip(offset)
            .take(limit)
            .collect::<Vec<_>>()
    } else {
        let records = AnalyticsReader::get_orders_by_account(
            app_state.db.as_ref(),
            &wallet,
            status,
            limit,
            offset,
        )
        .await
        .map_err(|e| {
            error!("Failed to get orders from DB for {}: {}", wallet, e);
            StatusCode::INTERNAL_SERVER_ERROR
        })?;
        records.into_iter().map(Into::into).collect()
    };
    let count = orders.len();

    Ok(SonicJson(OrdersResponse {
        success: true,
        data: orders,
        pagination: Pagination {
            limit,
            offset,
            count,
        },
    }))
}

// =============================================================================
// Margin Mode Endpoint
// =============================================================================

/// Set margin mode for a wallet (requires zero open positions)
#[utoipa::path(
    post,
    path = "/margin-mode",
    request_body = SetMarginModeRequest,
    responses(
        (status = 200, description = "Margin mode updated", body = hypercall_types::api_models::MarginModeApiResponse),
        (status = 400, description = "Invalid margin mode or has open positions"),
        (status = 503, description = "Margin mode service unavailable"),
        (status = 500, description = "Internal server error")
    ),
    security(("eip712_signature" = [])),
    tag = "Account"
)]
pub async fn set_margin_mode(
    State(state): State<AppState>,
    signer_ctx: SignerContext,
    SonicJson(request): SonicJson<crate::models::SetMarginModeRequest>,
) -> Result<SonicJson<crate::models::ApiResponse<crate::models::MarginModeResponse>>, ApiError> {
    // Ensure the caller is acting on their own wallet
    if request.wallet != signer_ctx.wallet_address {
        tracing::warn!(
            "Margin mode wallet mismatch: request_wallet={}, signer_wallet={}, signer={}",
            request.wallet,
            signer_ctx.wallet_address,
            signer_ctx.signer_address
        );
        return Err(ApiError::forbidden(
            "Wallet mismatch: signer does not match request wallet",
        ));
    }

    let wallet = request.wallet;

    tracing::info!(
        "Setting margin mode for wallet: {} to {} (signed by: {})",
        wallet,
        request.margin_mode,
        signer_ctx.signer_address
    );

    // Validate margin mode value
    let new_mode = match request.margin_mode.to_lowercase().as_str() {
        "standard" => hypercall_types::MarginMode::Standard,
        "portfolio" if portfolio_margin_mode_allowed(&state.runtime_config, &wallet) => {
            hypercall_types::MarginMode::Portfolio
        }
        "portfolio" => {
            return Ok(SonicJson(ApiResponse {
                success: false,
                data: None,
                error: Some(
                    "Portfolio margin is not yet available on this environment.".to_string(),
                ),
            }));
        }
        _ => {
            tracing::warn!("Invalid margin mode: {}", request.margin_mode);
            return Ok(SonicJson(ApiResponse {
                success: false,
                data: None,
                error: Some(format!(
                    "Invalid margin mode '{}'. Must be 'standard' or 'portfolio'.",
                    request.margin_mode
                )),
            }));
        }
    };

    // Get the current margin mode if a row already exists. A missing row is
    // allowed here because this endpoint creates the explicit requested mode.
    let current_mode = state
        .tier_cache
        .get_existing_margin_mode(&wallet)
        .await
        .map_err(|error| {
            ApiError::new(
                StatusCode::SERVICE_UNAVAILABLE,
                "service_unavailable",
                format!("Margin mode unavailable for {}: {}", wallet, error),
            )
        })?;

    // Check if already in requested mode
    if current_mode == Some(new_mode) {
        return Ok(SonicJson(ApiResponse {
            success: false,
            data: None,
            error: Some(format!(
                "Account is already in {} margin mode.",
                new_mode.as_str()
            )),
        }));
    }

    // Check for open positions from canonical in-memory state (no repricing path).
    let position_count = state.portfolio_cache.open_position_count(&wallet).await;
    let has_positions = position_count > 0;

    if has_positions {
        return Ok(SonicJson(ApiResponse {
            success: false,
            data: None,
            error: Some(format!(
                "Cannot change margin mode with {} open position(s). Close all positions first.",
                position_count
            )),
        }));
    }

    // Check for open orders using engine-truth snapshot
    let open_orders = state.order_snapshot.get_open_orders_for_wallet(&wallet);
    if !open_orders.is_empty() {
        return Ok(SonicJson(ApiResponse {
            success: false,
            data: None,
            error: Some(format!(
                "Cannot change margin mode with {} open order(s). Cancel all orders first.",
                open_orders.len()
            )),
        }));
    }

    // Set the new margin mode (returns the new version for event ordering)
    let new_version = match state.tier_cache.set_margin_mode(&wallet, new_mode).await {
        Ok(version) => version,
        Err(e) => {
            tracing::error!("Failed to set margin mode for {}: {}", wallet, e);
            return Err(ApiError::internal_error("Failed to set margin mode"));
        }
    };

    if let Err(e) = super::submit_tier_update_command(&state, wallet).await {
        tracing::error!("Failed to apply margin mode update in engine: {}", e);
        if let Some(previous_mode) = current_mode {
            if let Err(rollback_err) = state
                .tier_cache
                .set_margin_mode(&wallet, previous_mode)
                .await
            {
                tracing::error!(
                    "Failed to roll back margin mode for {} after engine apply failure: {}",
                    wallet,
                    rollback_err
                );
            }
        } else {
            if let Err(delete_err) = state.tier_cache.delete_tier(&wallet).await {
                tracing::error!(
                    "Failed to delete newly created margin mode row for {} after engine apply failure: {}",
                    wallet,
                    delete_err
                );
            } else {
                tracing::warn!(
                    "Deleted newly created margin mode row for {} after engine apply failure",
                    wallet
                );
            }
        }
        return Err(ApiError::internal_error(
            "Failed to apply margin mode update",
        ));
    }

    // Publish TierUpdate message for cross-process cache synchronization
    let tier_update =
        hypercall_types::EngineMessage::TierUpdate(hypercall_types::TierUpdateMessage {
            wallet,
            margin_mode: new_mode.as_str().to_string(),
            version: new_version,
            timestamp: chrono::Utc::now().timestamp() as u64,
        });
    if let Err(e) = state.event_bus_sender.send(tier_update) {
        // Log but don't fail - local cache is already updated
        tracing::warn!("Failed to publish TierUpdate for cross-process sync: {}", e);
    }

    let previous_mode = current_mode.map(|mode| mode.as_str()).unwrap_or("unset");

    tracing::info!(
        "Margin mode changed for wallet {}: {} -> {}",
        wallet,
        previous_mode,
        new_mode.as_str()
    );

    Ok(SonicJson(ApiResponse::success(
        crate::models::MarginModeResponse {
            wallet: wallet.to_string(),
            margin_mode: new_mode.as_str().to_string(),
            previous_mode: previous_mode.to_string(),
        },
    )))
}