Refactor Info and WebsocketManager for improved subscription handling and metadata loading

- Enhanced Info class to include separate methods for populating perpetual and spot metadata.
- Introduced remapping of subscription identifiers in the WebsocketManager to ensure consistency.
- Updated canonical_coin and name_to_asset methods to utilize new metadata structures.
- Added error handling for float serialization in signing utilities to prevent rounding issues.
- Improved unit tests for Info and WebsocketManager to cover new functionality and edge cases.
- Introduced Mock classes for Info and Exchange to facilitate testing without external dependencies.
- Refactored websocket message handling to align with Python SDK semantics for identifier mapping.

Author: kzhdev

CHANGELOG.md

@@ -9,15 +9,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.1.2] - 2026-06-09
 
+### Added
+- **`Exchange`: API-wallet account selection support** — added a constructor overload with optional `account_address` so authenticated flows can query the effective trading account separately from the signing key.
+- **`Info`: canonical asset lookup helpers** — added `name_to_coin`, `name_to_asset`, `asset_to_sz_decimals`, and `canonical_coin()` to resolve human-readable market names to Hyperliquid wire identifiers and asset ids.
+- **`WebsocketManager::message_to_identifier()`** — explicit inbound message routing helper for channel-to-handler lookup.
+- **Offline exchange parity tests** — added `tests/test_exchange.cpp` covering spot/perp mapping, payload shapes, price rounding, and effective-account selection.
+
 ### Fixed
 - **`WebsocketManager`: use-after-free / same-dispatch unsubscribe race** — callbacks now dispatch from a lock-free snapshot of shared handler state instead of copying `std::function`s under a mutex. Each callback entry carries an `active` flag and `in_flight` counter: `unsubscribe()` removes the callback from future snapshots, marks that specific callback inactive, and waits on its per-callback in-flight count with C++20 atomic wait/notify. This prevents a later callback from firing after being removed earlier in the same snapshot while still allowing self-unsubscribe without deadlocking.
+- **`updateIsolatedMargin` payload shape** — exchange requests now send the documented `ntli` field with `isBuy: true` instead of the previous mismatched parameters.
+- **`usdClassTransfer` formatting** — the signed action now uses the SDK-compatible `"amount"` string and appends `" subaccount:<address>"` when trading through a vault.
+- **Effective account selection for `market_close()`** — account state is now queried against `vault_address`, then `account_address`, then the signer wallet, matching Hyperliquid API-wallet semantics.
+- **Vault handling for user-signed transfers** — user-signed exchange payloads now include or omit `vaultAddress` consistently with the current Python SDK behavior.
+- **`basic_order.cpp` default credentials** — the example now uses the Hardhat private key instead of the Hardhat address.
 
 ### Changed
 - **`WebsocketManager`: removed `pending_subs_` pre-connection queue** — the underlying `slick::net::Websocket` already buffers outbound frames until the connection is established, making the manual pending-subscription queue redundant. `subscribe()` and `unsubscribe()` now call `ws_->send()` unconditionally; `flush_pending()`, `writer_mutex_`, and the `pending_subs_` vector are all removed.
+- **Metadata loading now matches the Hyperliquid SDK/docs** — perp assets use `meta` indices, spot assets use `10000 + spotMeta.index`, and spot aliases such as `PURR/USDC` and `@<index>` resolve to canonical wire coins.
+- **REST and WebSocket market-data requests now canonicalize coin names** before sending requests, so spot and perp subscriptions/queries use documented wire names instead of assuming perpetual-only symbols.
+- **Exchange precision handling was tightened to SDK behavior** — `float_to_wire()` and `float_to_usd_int()` now reject silent rounding, and market-order slippage pricing now applies 5 significant figures with max decimals derived from `szDecimals`.
+- **WebSocket routing was rebuilt around explicit message identifiers** — `trades`, `candle`, `activeAssetCtx`, `activeSpotAssetCtx`, `userEvents`, and `orderUpdates` now route using the actual inbound payload shape, with a 50-second heartbeat under the documented idle timeout.
+- **Internal identifier normalization is narrower** — coin-bearing websocket identifiers now preserve canonical coin casing, while address-bearing identifiers still lowercase the user/address portion for stable routing.
+- **Docs and examples were refreshed** — `README.md` now documents the expanded asset lookup maps, `account_address`, and the updated `update_isolated_margin(coin, amount)` signature.
 
 ### Tests
 - **`UnsubscribeBlocksUntilCallbackCompletes`** (integration) — regression test for the above fix; subscribes with a callback that blocks until explicitly released, calls `unsubscribe()` concurrently from a second thread, and asserts that `unsubscribe()` does not return before the in-flight callback has finished.
 - **`CallbackCanRemoveLaterCallbackFromSameDispatch`** (integration) — regression test for the snapshot hazard where callback A unsubscribes callback B on the same channel before the dispatcher reaches B in the already-loaded snapshot.
+- **Signing regressions** — added tests asserting that `float_to_wire()` and `float_to_usd_int()` throw when serialization would require rounding.
+- **WebSocket routing regressions** — extended channel-identifier tests to cover inbound routing, snapshot-safe channel naming, spot/perp active-asset messages, address normalization, and preserved coin casing.
 
 ## [0.1.1] - 2026-06-08
 

CMakeLists.txt

@@ -64,6 +64,7 @@ if(HYPERLIQUID_BUILD_TESTS)
         tests/test_keccak.cpp
         tests/test_types.cpp
         tests/test_signing.cpp
+        tests/test_exchange.cpp
         tests/test_websocket_utils.cpp
     )
 

README.md

@@ -232,9 +232,10 @@ Candle `interval` values: `"1m"` `"5m"` `"15m"` `"30m"` `"1h"` `"4h"` `"8h"` `"1
 |--------|-------------|
 | `subscribe(sub_json, callback)` | Subscribe to a channel; returns `subscription_id` (positive int) |
 | `unsubscribe(sub_json, subscription_id)` | Remove one callback; double-unsubscribe is a no-op |
-| `load_meta()` | Populate `coin_to_asset` (called automatically by `Exchange`) |
+| `load_meta()` | Populate `coin_to_asset`, `name_to_coin`, and `asset_to_sz_decimals` (called automatically by `Exchange`) |
 
-`coin_to_asset` is a public `std::unordered_map<std::string, int>` mapping coin names to 0-based asset indices.
+`coin_to_asset` maps canonical wire coins to asset ids. Perps are 0-based; spot assets use `10000 + spot index`.
+`name_to_coin` maps human-readable names such as `PURR/USDC` back to canonical wire coins.
 
 ---
 
@@ -247,7 +248,8 @@ hyperliquid::Exchange exchange(
     private_key_hex,    // "0x..." or bare 64 hex chars
     base_url,           // MAINNET_API_URL or TESTNET_API_URL
     info,               // shared_ptr<Info>
-    vault_address);     // optional sub-account address
+    vault_address,      // optional sub-account address
+    account_address);   // optional account queried when using an API wallet
 ```
 
 The constructor derives `wallet_address()` from the private key and calls `info->load_meta()`.
@@ -285,7 +287,7 @@ All methods return `nlohmann::json` with the raw Hyperliquid API response.
 | Method | Description |
 |--------|-------------|
 | `update_leverage(coin, is_cross, leverage)` | Set cross or isolated leverage |
-| `update_isolated_margin(coin, is_buy, ntl)` | Add/remove USD from an isolated position |
+| `update_isolated_margin(coin, amount)` | Add/remove USD from an isolated position |
 
 ### Transfers (EIP-712 user-signed)
 

examples/basic_order.cpp

@@ -7,7 +7,7 @@
 #include <string>
 
 static constexpr const char* kDefaultKey =
-    "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266";
+    "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
 
 int main(int argc, char* argv[]) {
     const std::string private_key = (argc >= 2) ? argv[1] : kDefaultKey;

include/hyperliquid/api.hpp

@@ -16,7 +16,7 @@ class Api {
 
     // POST `endpoint` (e.g. "/info" or "/exchange") with `payload` as JSON body.
     // Throws std::runtime_error on HTTP 4xx/5xx.
-    nlohmann::json post(std::string_view endpoint, const nlohmann::json& payload);
+    virtual nlohmann::json post(std::string_view endpoint, const nlohmann::json& payload);
 
     struct HttpError : std::runtime_error {
         int status_code;

include/hyperliquid/exchange.hpp

@@ -21,12 +21,18 @@ namespace hyperliquid {
 // base_url: MAINNET_API_URL or TESTNET_API_URL.
 // info: shared Info instance for asset-index lookups and market data.
 // vault_address: optional sub-account / vault address; signs on behalf of it.
+// account_address: optional sub-account address; signs on behalf of it.
 class Exchange : public Api {
 public:
     Exchange(std::string private_key_hex,
              std::string_view base_url,
              std::shared_ptr<Info> info,
              std::optional<std::string> vault_address = {});
+    Exchange(std::string private_key_hex,
+             std::string_view base_url,
+             std::shared_ptr<Info> info,
+             std::optional<std::string> vault_address,
+             std::optional<std::string> account_address);
 
     // Ethereum address derived from private_key_hex.
     const std::string& wallet_address() const noexcept { return wallet_; }
@@ -75,9 +81,8 @@ class Exchange : public Api {
 
     nlohmann::json update_leverage(std::string_view coin, bool is_cross, int leverage);
 
-    // ntl: notional USD amount for isolated margin adjustment.
-    nlohmann::json update_isolated_margin(std::string_view coin, bool is_buy,
-                                           double ntl);
+    // amount: signed USD amount for isolated margin adjustment.
+    nlohmann::json update_isolated_margin(std::string_view coin, double amount);
 
     // ── Transfers (user-signed) ───────────────────────────────────────────────
 
@@ -113,23 +118,33 @@ class Exchange : public Api {
     std::string private_key_;
     std::string wallet_;
     std::optional<std::string> vault_address_;
+    std::optional<std::string> account_address_;
     std::shared_ptr<Info> info_;
     bool is_mainnet_;
 
     int asset_index(std::string_view coin);
+    std::string effective_account_address() const;
 
     // Sign an L1 action and POST to /exchange.
+    nlohmann::json post_action(nlohmann::ordered_json action);
     nlohmann::json post_action(nlohmann::ordered_json action,
-                                std::optional<std::string> vault_override = {});
+                               std::optional<std::string> signing_vault_address,
+                               std::optional<std::string> payload_vault_address);
 
     // Sign a user-signed action and POST to /exchange.
     nlohmann::json post_user_signed_action(
         nlohmann::ordered_json action,
         const std::vector<std::pair<std::string, std::string>>& payload_types,
         std::string_view primary_type);
+    nlohmann::json post_user_signed_action(
+        nlohmann::ordered_json action,
+        const std::vector<std::pair<std::string, std::string>>& payload_types,
+        std::string_view primary_type,
+        std::optional<std::string> payload_vault_address);
 
     // Apply slippage to mid-price and round to asset precision.
-    double slippage_price(std::string_view coin, bool is_buy, double slippage);
+    double slippage_price(std::string_view coin, bool is_buy, double slippage,
+                          std::optional<double> px = {});
 };
 
 } // namespace hyperliquid

include/hyperliquid/info.hpp

@@ -92,16 +92,33 @@ class Info : public Api {
 
     // ── Asset index lookup ────────────────────────────────────────────────────
 
-    // coin name → perpetual asset index (0-based). Populated on first call to meta().
+    // Canonical coin string -> asset index. Perp assets are 0-based; spot assets
+    // use 10000 + spot index to match the official Python SDK.
     std::unordered_map<std::string, int> coin_to_asset;
 
-    // Ensure coin_to_asset is populated (call before using Exchange).
+    // Human-readable name -> canonical coin string (e.g. "PURR/USDC" -> "@0").
+    std::unordered_map<std::string, std::string> name_to_coin;
+
+    // Asset index -> size decimals.
+    std::unordered_map<int, int> asset_to_sz_decimals;
+
+    // Resolve a human-readable market name or canonical coin string to the wire coin.
+    std::string canonical_coin(std::string_view coin_or_name);
+
+    // Resolve a human-readable market name or canonical coin string to an asset id.
+    int name_to_asset(std::string_view coin_or_name);
+
+    // Ensure all asset lookup maps are populated (call before using Exchange).
     void load_meta();
 
 private:
     nlohmann::json info_post(const nlohmann::json& payload);
+    void populate_perp_meta(const nlohmann::json& meta);
+    void populate_spot_meta(const nlohmann::json& spot_meta);
+    nlohmann::json remap_subscription(const nlohmann::json& subscription);
 
-    bool meta_loaded_ = false;
+    bool perp_meta_loaded_ = false;
+    bool spot_meta_loaded_ = false;
     std::unique_ptr<WebsocketManager> ws_;
 };
 

include/hyperliquid/websocket_manager.hpp

@@ -3,6 +3,7 @@
 #include <atomic>
 #include <functional>
 #include <memory>
+#include <optional>
 #include <string>
 #include <string_view>
 #include <thread>
@@ -39,6 +40,9 @@ class WebsocketManager {
     // e.g. l2Book+ETH → "l2Book:ETH", candle+BTC+5m → "candle:BTC,5m"
     static std::string to_identifier(const nlohmann::json& sub);
 
+    // Build a channel identifier string from an inbound WebSocket message.
+    static std::optional<std::string> message_to_identifier(const nlohmann::json& msg);
+
     // Convert "https://..." → "wss://.../ws"
     static std::string http_to_ws_url(std::string_view http_url);