Skip to main content

nautilus_hyperliquid/websocket/
enums.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16use serde::{Deserialize, Serialize};
17use strum::{AsRefStr, Display, EnumIter, EnumString};
18
19/// WebSocket channel names for Hyperliquid.
20#[derive(
21    Clone,
22    Debug,
23    Display,
24    PartialEq,
25    Eq,
26    Hash,
27    AsRefStr,
28    EnumIter,
29    EnumString,
30    Serialize,
31    Deserialize,
32)]
33pub enum HyperliquidWsChannel {
34    #[serde(rename = "subscriptionResponse")]
35    SubscriptionResponse,
36    #[serde(rename = "trades")]
37    Trades,
38    #[serde(rename = "l2Book")]
39    L2Book,
40    #[serde(rename = "l2")]
41    L2,
42    #[serde(rename = "bbo")]
43    Bbo,
44    #[serde(rename = "candle")]
45    Candle,
46    #[serde(rename = "allMids")]
47    AllMids,
48    #[serde(rename = "allDexsAssetCtxs")]
49    AllDexsAssetCtxs,
50    #[serde(rename = "notification")]
51    Notification,
52    #[serde(rename = "orderUpdates")]
53    OrderUpdates,
54    #[serde(rename = "userEvents")]
55    UserEvents,
56    #[serde(rename = "userFills")]
57    UserFills,
58    #[serde(rename = "userFundings")]
59    UserFundings,
60    #[serde(rename = "userNonFundingLedgerUpdates")]
61    UserNonFundingLedgerUpdates,
62    #[serde(rename = "activeAssetCtx")]
63    ActiveAssetCtx,
64    #[serde(rename = "activeSpotAssetCtx")]
65    ActiveSpotAssetCtx,
66    #[serde(rename = "activeAssetData")]
67    ActiveAssetData,
68    #[serde(rename = "userTwapSliceFills")]
69    UserTwapSliceFills,
70    #[serde(rename = "userTwapHistory")]
71    UserTwapHistory,
72    #[serde(rename = "webData2")]
73    WebData2,
74    /// Generic user channel - Hyperliquid sends fills/events on this channel.
75    #[serde(rename = "user")]
76    User,
77    #[serde(rename = "post")]
78    Post,
79    #[serde(rename = "pong")]
80    Pong,
81    #[serde(rename = "error")]
82    Error,
83    #[serde(rename = "clearinghouseState")]
84    ClearinghouseState,
85    #[serde(rename = "spotState")]
86    SpotState,
87}
88
89impl HyperliquidWsChannel {
90    /// Returns the string representation of the channel.
91    pub fn as_str(&self) -> &'static str {
92        match self {
93            Self::SubscriptionResponse => "subscriptionResponse",
94            Self::Trades => "trades",
95            Self::L2Book => "l2Book",
96            Self::L2 => "l2",
97            Self::Bbo => "bbo",
98            Self::Candle => "candle",
99            Self::AllMids => "allMids",
100            Self::AllDexsAssetCtxs => "allDexsAssetCtxs",
101            Self::Notification => "notification",
102            Self::OrderUpdates => "orderUpdates",
103            Self::UserEvents => "userEvents",
104            Self::UserFills => "userFills",
105            Self::UserFundings => "userFundings",
106            Self::UserNonFundingLedgerUpdates => "userNonFundingLedgerUpdates",
107            Self::ActiveAssetCtx => "activeAssetCtx",
108            Self::ActiveSpotAssetCtx => "activeSpotAssetCtx",
109            Self::ActiveAssetData => "activeAssetData",
110            Self::UserTwapSliceFills => "userTwapSliceFills",
111            Self::UserTwapHistory => "userTwapHistory",
112            Self::WebData2 => "webData2",
113            Self::User => "user",
114            Self::Post => "post",
115            Self::Pong => "pong",
116            Self::Error => "error",
117            Self::ClearinghouseState => "clearinghouseState",
118            Self::SpotState => "spotState",
119        }
120    }
121
122    /// Returns true if this is a public channel (does not require authentication).
123    pub fn is_public(&self) -> bool {
124        matches!(
125            self,
126            Self::SubscriptionResponse
127                | Self::Trades
128                | Self::L2Book
129                | Self::L2
130                | Self::Bbo
131                | Self::Candle
132                | Self::AllMids
133                | Self::AllDexsAssetCtxs
134                | Self::ActiveAssetCtx
135                | Self::ActiveSpotAssetCtx
136                | Self::Notification
137                | Self::Pong
138                | Self::Error
139        )
140    }
141
142    /// Returns true if this is a private channel (requires authentication).
143    pub fn is_private(&self) -> bool {
144        !self.is_public()
145    }
146
147    /// Parses a channel from its wire-format string (e.g., "allMids").
148    pub fn from_wire_str(s: &str) -> Option<Self> {
149        serde_json::from_value(serde_json::Value::String(s.to_string())).ok()
150    }
151}
152
153#[cfg(test)]
154mod tests {
155    use std::str::FromStr;
156
157    use rstest::rstest;
158    use serde_json;
159    use strum::IntoEnumIterator;
160
161    use super::*;
162
163    #[rstest]
164    #[case(HyperliquidWsChannel::Trades, r#""trades""#)]
165    #[case(HyperliquidWsChannel::L2Book, r#""l2Book""#)]
166    #[case(HyperliquidWsChannel::UserFills, r#""userFills""#)]
167    #[case(HyperliquidWsChannel::Bbo, r#""bbo""#)]
168    #[case(
169        HyperliquidWsChannel::SubscriptionResponse,
170        r#""subscriptionResponse""#
171    )]
172    fn test_channel_serialization(#[case] channel: HyperliquidWsChannel, #[case] expected: &str) {
173        assert_eq!(serde_json::to_string(&channel).unwrap(), expected);
174    }
175
176    #[rstest]
177    #[case(r#""trades""#, HyperliquidWsChannel::Trades)]
178    #[case(r#""l2Book""#, HyperliquidWsChannel::L2Book)]
179    #[case(r#""userEvents""#, HyperliquidWsChannel::UserEvents)]
180    #[case(r#""bbo""#, HyperliquidWsChannel::Bbo)]
181    #[case(r#""pong""#, HyperliquidWsChannel::Pong)]
182    fn test_channel_deserialization(#[case] json: &str, #[case] expected: HyperliquidWsChannel) {
183        assert_eq!(
184            serde_json::from_str::<HyperliquidWsChannel>(json).unwrap(),
185            expected
186        );
187    }
188
189    #[rstest]
190    #[case(HyperliquidWsChannel::Trades, "trades")]
191    #[case(HyperliquidWsChannel::L2Book, "l2Book")]
192    #[case(HyperliquidWsChannel::UserFills, "userFills")]
193    #[case(
194        HyperliquidWsChannel::UserNonFundingLedgerUpdates,
195        "userNonFundingLedgerUpdates"
196    )]
197    #[case(HyperliquidWsChannel::Bbo, "bbo")]
198    fn test_as_str_method(#[case] channel: HyperliquidWsChannel, #[case] expected: &str) {
199        assert_eq!(channel.as_str(), expected);
200    }
201
202    #[rstest]
203    fn test_display_trait() {
204        assert_eq!(format!("{}", HyperliquidWsChannel::Trades), "Trades");
205        assert_eq!(format!("{}", HyperliquidWsChannel::L2Book), "L2Book");
206        assert_eq!(format!("{}", HyperliquidWsChannel::UserFills), "UserFills");
207    }
208
209    #[rstest]
210    fn test_is_public_channel() {
211        assert!(HyperliquidWsChannel::Trades.is_public());
212        assert!(HyperliquidWsChannel::L2Book.is_public());
213        assert!(HyperliquidWsChannel::Bbo.is_public());
214        assert!(HyperliquidWsChannel::SubscriptionResponse.is_public());
215        assert!(HyperliquidWsChannel::Pong.is_public());
216
217        assert!(!HyperliquidWsChannel::OrderUpdates.is_public());
218        assert!(!HyperliquidWsChannel::UserEvents.is_public());
219        assert!(!HyperliquidWsChannel::UserFills.is_public());
220        assert!(!HyperliquidWsChannel::UserFundings.is_public());
221        assert!(!HyperliquidWsChannel::UserNonFundingLedgerUpdates.is_public());
222        assert!(!HyperliquidWsChannel::Post.is_public());
223    }
224
225    #[rstest]
226    fn test_is_private_channel() {
227        assert!(!HyperliquidWsChannel::Trades.is_private());
228        assert!(!HyperliquidWsChannel::L2Book.is_private());
229        assert!(!HyperliquidWsChannel::Bbo.is_private());
230
231        assert!(HyperliquidWsChannel::OrderUpdates.is_private());
232        assert!(HyperliquidWsChannel::UserEvents.is_private());
233        assert!(HyperliquidWsChannel::UserFills.is_private());
234        assert!(HyperliquidWsChannel::UserFundings.is_private());
235        assert!(HyperliquidWsChannel::UserNonFundingLedgerUpdates.is_private());
236        assert!(HyperliquidWsChannel::Post.is_private());
237    }
238
239    #[rstest]
240    fn test_enum_iter() {
241        let channels: Vec<HyperliquidWsChannel> = HyperliquidWsChannel::iter().collect();
242        assert_eq!(channels.len(), 26);
243        assert!(channels.contains(&HyperliquidWsChannel::Trades));
244        assert!(channels.contains(&HyperliquidWsChannel::L2Book));
245        assert!(channels.contains(&HyperliquidWsChannel::L2));
246        assert!(channels.contains(&HyperliquidWsChannel::UserFills));
247        assert!(channels.contains(&HyperliquidWsChannel::Candle));
248        assert!(channels.contains(&HyperliquidWsChannel::AllMids));
249        assert!(channels.contains(&HyperliquidWsChannel::AllDexsAssetCtxs));
250        assert!(channels.contains(&HyperliquidWsChannel::Notification));
251        assert!(channels.contains(&HyperliquidWsChannel::ClearinghouseState));
252        assert!(channels.contains(&HyperliquidWsChannel::SpotState));
253    }
254
255    #[rstest]
256    fn test_from_str() {
257        assert_eq!(
258            HyperliquidWsChannel::from_str("Trades").unwrap(),
259            HyperliquidWsChannel::Trades
260        );
261        assert_eq!(
262            HyperliquidWsChannel::from_str("L2Book").unwrap(),
263            HyperliquidWsChannel::L2Book
264        );
265        assert_eq!(
266            HyperliquidWsChannel::from_str("UserFills").unwrap(),
267            HyperliquidWsChannel::UserFills
268        );
269
270        assert!(HyperliquidWsChannel::from_str("InvalidChannel").is_err());
271    }
272}