nautilus_okx/common/

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

//! Core constants shared across the OKX adapter components.

use std::sync::LazyLock;

use ahash::AHashSet;
use nautilus_model::{
    enums::{OrderType, TimeInForce},
    identifiers::{ClientId, Venue},
};
use ustr::Ustr;

use super::enums::{OKXBookChannel, OKXInstrumentType, OKXVipLevel};

/// Venue identifier string.
pub const OKX: &str = "OKX";

/// Static venue instance.
pub static OKX_VENUE: LazyLock<Venue> = LazyLock::new(|| Venue::new(Ustr::from(OKX)));

/// Static client ID instance.
pub static OKX_CLIENT_ID: LazyLock<ClientId> = LazyLock::new(|| ClientId::new(Ustr::from(OKX)));

/// See <https://www.okx.com/docs-v5/en/#overview-broker-program> for further details.
pub const OKX_NAUTILUS_BROKER_ID: &str = "5328c82e5542BCDE";

/// Default lookback for terminal orders and fills during reconciliation.
///
/// Active orders and current positions are requested independently of this window. The three-day
/// default matches the retention of `GET /api/v5/trade/fills`.
pub const OKX_RECONCILIATION_LOOKBACK_DEFAULT_MINS: u64 = 3 * 24 * 60;

/// Maximum lookback for terminal orders and fills during reconciliation.
///
/// Seven days is the longest complete window across the regular order history and spread trade
/// history endpoints used for reconciliation.
pub const OKX_RECONCILIATION_LOOKBACK_MAX_MINS: u64 = 7 * 24 * 60;

// Use the canonical host with www to avoid cross-domain redirects which may
// strip authentication headers in some HTTP clients and middleboxes.
pub const OKX_HTTP_URL: &str = "https://www.okx.com";
pub const OKX_WS_PUBLIC_URL: &str = "wss://ws.okx.com:8443/ws/v5/public";
pub const OKX_WS_PRIVATE_URL: &str = "wss://ws.okx.com:8443/ws/v5/private";
pub const OKX_WS_BUSINESS_URL: &str = "wss://ws.okx.com:8443/ws/v5/business";
pub const OKX_WS_DEMO_PUBLIC_URL: &str = "wss://wspap.okx.com:8443/ws/v5/public";
pub const OKX_WS_DEMO_PRIVATE_URL: &str = "wss://wspap.okx.com:8443/ws/v5/private";
pub const OKX_WS_DEMO_BUSINESS_URL: &str = "wss://wspap.okx.com:8443/ws/v5/business";

pub const OKX_WS_TOPIC_DELIMITER: char = ':';

/// WebSocket heartbeat (ping/pong) interval in seconds.
pub const OKX_WS_HEARTBEAT_SECS: u64 = 20;

/// OKX success response code for WebSocket operations.
pub const OKX_SUCCESS_CODE: &str = "0";

/// OKX WebSocket code indicating a service upgrade and required reconnect.
pub const OKX_SERVICE_UPGRADE_RECONNECT_CODE: &str = "64008";

/// JSON field key for sub-error code in order operation responses.
pub const OKX_FIELD_SCODE: &str = "sCode";

/// JSON field key for sub-error message in order operation responses.
pub const OKX_FIELD_SMSG: &str = "sMsg";

/// JSON field key for detailed sub-error code in order operation responses.
pub const OKX_FIELD_SUBCODE: &str = "subCode";

/// JSON field key for client order ID in order operation responses.
pub const OKX_FIELD_CLORDID: &str = "clOrdId";

/// Maximum length of a `clOrdId` accepted by OKX.
///
/// OKX requires `clOrdId` to be 1-32 case-sensitive alphanumeric characters.
/// See <https://www.okx.com/docs-v5/en/#order-book-trading-trade>.
pub const OKX_MAX_CLORDID_LEN: usize = 32;

/// Validates a `clOrdId` against OKX's length and charset rules.
///
/// # Errors
///
/// Returns a human-readable reason when the ID exceeds
/// [`OKX_MAX_CLORDID_LEN`] characters or contains non-alphanumeric characters
/// (such as hyphens or underscores).
pub fn validate_okx_client_order_id(cl_ord_id: &str) -> Result<(), String> {
    let len = cl_ord_id.len();
    if len > OKX_MAX_CLORDID_LEN {
        return Err(format!(
            "OKX requires clOrdId to be at most {OKX_MAX_CLORDID_LEN} characters, was {len} ({cl_ord_id:?}); \
             set `use_uuid_client_order_ids=True` and `use_hyphens_in_client_order_ids=False` on the strategy config"
        ));
    }

    if !cl_ord_id.bytes().all(|b| b.is_ascii_alphanumeric()) {
        return Err(format!(
            "OKX requires clOrdId to be alphanumeric only, was {cl_ord_id:?}; \
             set `use_hyphens_in_client_order_ids=False` on the strategy config"
        ));
    }

    Ok(())
}

/// OKX supported order time in force.
///
/// # Notes
///
/// - OKX implements IOC and FOK as order types rather than separate time-in-force parameters.
/// - FOK is only supported with Limit orders (Market + FOK is not supported).
/// - IOC with Market orders uses OptimalLimitIoc, with Limit orders uses Ioc.
/// - GTD is supported via expire_time parameter.
pub const OKX_SUPPORTED_TIME_IN_FORCE: &[TimeInForce] = &[
    TimeInForce::Gtc, // Good Till Cancel (default)
    TimeInForce::Ioc, // Immediate or Cancel (mapped to OKXOrderType::Ioc or OptimalLimitIoc)
    TimeInForce::Fok, // Fill or Kill (only with Limit orders, mapped to OKXOrderType::Fok)
];

/// OKX supported order types.
///
/// # Notes
///
/// - PostOnly is supported as a flag on limit orders.
/// - Conditional orders (stop/trigger) are supported via algo orders.
pub const OKX_SUPPORTED_ORDER_TYPES: &[OrderType] = &[
    OrderType::Market,
    OrderType::Limit,
    OrderType::MarketToLimit,   // Mapped to IOC when no price is specified
    OrderType::StopMarket,      // Supported via algo order API
    OrderType::StopLimit,       // Supported via algo order API
    OrderType::MarketIfTouched, // Supported via algo order API
    OrderType::LimitIfTouched,  // Supported via algo order API
    OrderType::TrailingStopMarket, // Supported via algo order API (move_order_stop)
];

/// Conditional order types that require the OKX algo order API.
pub const OKX_CONDITIONAL_ORDER_TYPES: &[OrderType] = &[
    OrderType::StopMarket,
    OrderType::StopLimit,
    OrderType::MarketIfTouched,
    OrderType::LimitIfTouched,
    OrderType::TrailingStopMarket,
];

/// Advance algo order types that require `cancel-advance-algos` for cancellation.
/// These cannot be cancelled via the standard `cancel-algos` endpoint.
pub const OKX_ADVANCE_ALGO_ORDER_TYPES: &[OrderType] = &[OrderType::TrailingStopMarket];

/// OKX error codes that should trigger retries.
///
/// Only retry on temporary network/system issues. Retries never apply to
/// order submission POSTs: OKX rejects a duplicate `clOrdId` only while the
/// first order rests open, so a submit whose response was lost can already
/// have filled, and retrying could place a second live order. Submits are
/// sent once, and an ambiguous outcome resolves through stream updates and
/// reconciliation.
///
/// # References
///
/// Based on OKX API documentation: <https://www.okx.com/docs-v5/en/#error-codes>
pub static OKX_RETRY_ERROR_CODES: LazyLock<AHashSet<&'static str>> = LazyLock::new(|| {
    let mut codes = AHashSet::new();

    // Temporary system errors
    codes.insert("50001"); // Service temporarily unavailable
    codes.insert("50004"); // API endpoint request timeout (does not mean that the request was successful or failed, please check the request result)
    codes.insert("50005"); // API is offline or unavailable
    codes.insert("50013"); // System busy, please try again later
    codes.insert("50026"); // System error, please try again later

    // Rate limit errors (temporary)
    codes.insert("50011"); // Request too frequent
    codes.insert("50113"); // API requests exceed the limit

    // WebSocket connection issues (temporary)
    codes.insert("60001"); // OK not received in time
    codes.insert("60005"); // Connection closed as there was no data transmission in the last 30 seconds
    codes.insert(OKX_SERVICE_UPGRADE_RECONNECT_CODE); // Service upgrade, please reconnect

    codes
});

/// Determines if an OKX error code should trigger a retry.
pub fn should_retry_error_code(error_code: &str) -> bool {
    OKX_RETRY_ERROR_CODES.contains(error_code)
}

/// OKX error code returned when an order request timed out and the outcome is unknown.
pub const OKX_ORDER_REQUEST_TIMEOUT_CODE: &str = "51149";

/// OKX error code returned when a post-only order would immediately take liquidity.
pub const OKX_POST_ONLY_ERROR_CODE: &str = "51019";

/// OKX cancel source code used when a post-only order is auto-cancelled for taking liquidity.
pub const OKX_POST_ONLY_CANCEL_SOURCE: &str = "31";

/// Human-readable reason used when a post-only order is auto-cancelled for taking liquidity.
pub const OKX_POST_ONLY_CANCEL_REASON: &str = "POST_ONLY would take liquidity";

/// OKX error code returned when a market order's `slippagePct` would be exceeded by the
/// projected fill, so the order is rejected.
pub const OKX_SLIPPAGE_EXCEEDED_ERROR_CODE: &str = "54084";

/// OKX error code returned when the supplied `slippagePct` value is outside the
/// venue-permitted range.
pub const OKX_SLIPPAGE_INVALID_ERROR_CODE: &str = "54085";

/// Returns `true` if the OKX `sCode` identifies a slippage-related rejection emitted
/// in response to the `slippagePct` parameter on market orders.
#[must_use]
pub fn is_slippage_rejection(error_code: &str) -> bool {
    matches!(
        error_code,
        OKX_SLIPPAGE_EXCEEDED_ERROR_CODE | OKX_SLIPPAGE_INVALID_ERROR_CODE
    )
}

/// Target currency literal for base currency.
pub const OKX_TARGET_CCY_BASE: &str = "base_ccy";

/// Target currency literal for quote currency.
pub const OKX_TARGET_CCY_QUOTE: &str = "quote_ccy";

/// Resolves instrument families for a given instrument type.
///
/// Returns `Some(families)` when the type supports family filtering, or `None`
/// to skip the instrument type entirely (Option without configured families).
/// An empty vec means no family filter is needed (Spot, Margin), or all
/// discoverable families should be loaded (Events).
pub fn resolve_instrument_families(
    configured: &Option<Vec<String>>,
    inst_type: OKXInstrumentType,
) -> Option<Vec<String>> {
    match (configured, inst_type) {
        (Some(families), OKXInstrumentType::Option) => Some(families.clone()),
        (
            Some(families),
            OKXInstrumentType::Futures | OKXInstrumentType::Swap | OKXInstrumentType::Events,
        ) => Some(families.clone()),
        (None, OKXInstrumentType::Option) => {
            log::warn!("Skipping OPTION type: instrument_families required but not configured");
            None
        }
        _ => Some(vec![]),
    }
}

/// Clamps a requested book depth to the nearest OKX-supported value.
///
/// OKX WebSocket channels support depths of 50 and 400. Depth 0 means
/// auto-select based on VIP level. Any other value rounds up to the nearest
/// supported depth so the subscription succeeds and the data engine can
/// truncate to the originally requested depth.
pub fn resolve_book_depth(raw_depth: usize) -> usize {
    match raw_depth {
        0 | 400 => raw_depth,
        1..=50 => 50,
        _ => 400,
    }
}

pub(crate) fn select_book_channel(depth: usize, vip: OKXVipLevel) -> OKXBookChannel {
    match depth {
        50 if vip >= OKXVipLevel::Vip4 => OKXBookChannel::Books50L2Tbt,
        0 | 400 if vip >= OKXVipLevel::Vip5 => OKXBookChannel::BookL2Tbt,
        0 | 50 | 400 => OKXBookChannel::Book,
        _ => unreachable!("book depth must be resolved before channel selection"),
    }
}

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

    use super::*;

    #[rstest]
    #[case::auto_default(0, OKXVipLevel::Vip0, OKXBookChannel::Book)]
    #[case::auto_vip4(0, OKXVipLevel::Vip4, OKXBookChannel::Book)]
    #[case::auto_vip5(0, OKXVipLevel::Vip5, OKXBookChannel::BookL2Tbt)]
    #[case::depth_50_vip3(50, OKXVipLevel::Vip3, OKXBookChannel::Book)]
    #[case::depth_50_vip4(50, OKXVipLevel::Vip4, OKXBookChannel::Books50L2Tbt)]
    #[case::depth_400_vip4(400, OKXVipLevel::Vip4, OKXBookChannel::Book)]
    #[case::depth_400_vip5(400, OKXVipLevel::Vip5, OKXBookChannel::BookL2Tbt)]
    fn test_select_book_channel(
        #[case] depth: usize,
        #[case] vip: OKXVipLevel,
        #[case] expected: OKXBookChannel,
    ) {
        assert_eq!(select_book_channel(depth, vip), expected);
    }

    #[rstest]
    #[case("54084", true)]
    #[case("54085", true)]
    #[case("51019", false)]
    #[case("", false)]
    fn test_is_slippage_rejection(#[case] code: &str, #[case] expected: bool) {
        assert_eq!(is_slippage_rejection(code), expected);
    }

    #[rstest]
    #[case("50001", true)]
    #[case("60005", true)]
    #[case(OKX_SERVICE_UPGRADE_RECONNECT_CODE, true)]
    #[case("60012", false)]
    fn test_should_retry_error_code(#[case] code: &str, #[case] expected: bool) {
        assert_eq!(should_retry_error_code(code), expected);
    }

    #[rstest]
    #[case("O20260101000000ABC1", true)]
    #[case("aB9", true)]
    #[case("abcdefghij0123456789ABCDEFGHIJ12", true)] // exactly 32 chars
    #[case("abcdefghij0123456789ABCDEFGHIJ123", false)] // 33 chars
    #[case("O-20260101-000000-001-001-1", false)] // hyphens
    #[case("O_20260101_000000", false)] // underscores
    #[case("", true)] // empty: OKX rejects, but core ClientOrderId never produces empty
    fn test_validate_okx_client_order_id(#[case] cl_ord_id: &str, #[case] expected_ok: bool) {
        assert_eq!(validate_okx_client_order_id(cl_ord_id).is_ok(), expected_ok);
    }

    #[rstest]
    fn test_validate_okx_client_order_id_length_message() {
        // 35-char compact ID (the shape reported in the original bug report).
        let cl_ord_id = "O20260522145501532392555aceLTCUSDT5";
        let err = validate_okx_client_order_id(cl_ord_id).unwrap_err();
        assert!(err.contains("at most 32"));
        assert!(err.contains("was 35"));
        assert!(err.contains("use_uuid_client_order_ids"));
    }
}