nautilus-hyperliquid 0.55.0

Hyperliquid integration adapter for the Nautilus trading engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

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

use std::fmt::Display;

use serde::{Deserialize, Serialize};

/// Represents an asset ID for Hyperliquid.
///
/// Asset IDs follow Hyperliquid's convention:
/// - Perps: raw index into meta.universe
/// - Spot: 10000 + index in spotMeta.universe
/// - Builder perps: 100000 + dex_index * 10000 + meta_index
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct HyperliquidAssetId(pub u32);

impl HyperliquidAssetId {
    /// Creates a perpetual asset ID from raw index.
    pub fn perp(index: u32) -> Self {
        Self(index)
    }

    /// Creates a spot asset ID (10000 + index).
    pub fn spot(index: u32) -> Self {
        Self(10_000 + index)
    }

    /// Creates a builder perpetual asset ID.
    pub fn builder_perp(dex_index: u32, meta_index: u32) -> Self {
        Self(100_000 + dex_index * 10_000 + meta_index)
    }

    /// Checks if this is a spot asset (>= 10000).
    pub fn is_spot(self) -> bool {
        self.0 >= 10_000 && self.0 < 100_000
    }

    /// Checks if this is a builder perp (>= 100000).
    pub fn is_builder_perp(self) -> bool {
        self.0 >= 100_000
    }

    /// Gets the base index for spot assets (asset_id - 10000).
    /// For perps, returns the raw index.
    pub fn base_index(self) -> u32 {
        if self.is_spot() {
            self.0 - 10_000
        } else if self.is_builder_perp() {
            // For builder perps, return the meta_index
            (self.0 - 100_000) % 10_000
        } else {
            self.0
        }
    }

    /// Gets the raw asset ID value.
    pub fn to_raw(self) -> u32 {
        self.0
    }
}

impl Display for HyperliquidAssetId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0)
    }
}

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

    use super::*;

    #[rstest]
    fn test_asset_id_perp() {
        let asset_id = HyperliquidAssetId::perp(7);
        assert_eq!(asset_id.to_raw(), 7);
        assert!(!asset_id.is_spot());
        assert!(!asset_id.is_builder_perp());
        assert_eq!(asset_id.base_index(), 7);
    }

    #[rstest]
    fn test_asset_id_spot() {
        let asset_id = HyperliquidAssetId::spot(7);
        assert_eq!(asset_id.to_raw(), 10_007);
        assert!(asset_id.is_spot());
        assert!(!asset_id.is_builder_perp());
        assert_eq!(asset_id.base_index(), 7);
    }

    #[rstest]
    fn test_asset_id_builder_perp() {
        let asset_id = HyperliquidAssetId::builder_perp(1, 7);
        assert_eq!(asset_id.to_raw(), 110_007);
        assert!(!asset_id.is_spot());
        assert!(asset_id.is_builder_perp());
        assert_eq!(asset_id.base_index(), 7);
    }
}