Class: Hyperliquid::Info

Inherits:
Object
  • Object
show all
Defined in:
lib/hyperliquid/info.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base_url: MAINNET_URL, skip_ws: false) ⇒ Info

Returns a new instance of Info.



7
8
9
10
11
12
13
14
15
16
17
18
 
# File 'lib/hyperliquid/info.rb', line 7

def initialize(base_url: MAINNET_URL, skip_ws: false)
  @transport = Transport.new(base_url: base_url)
  @coin_to_asset = nil
  @spot_coin_to_asset = nil
  @name_to_coin = nil
  @asset_to_sz_decimals = nil
  @ws_manager = nil
  return if skip_ws

  @ws_manager = WebsocketManager.new(base_url)
  @ws_manager.start
end

Instance Attribute Details

#transport ⇒ Object (readonly)

Returns the value of attribute transport.



5
6
7
 
# File 'lib/hyperliquid/info.rb', line 5

def transport
  @transport
end

Instance Method Details

#all_mids(dex: nil) ⇒ Object

Get all mid prices. Returns Hash of coin => mid price string.

Parameters:

  • dex (String, nil) (defaults to: nil) —

    optional dex identifier for builder perp dexs



49
50
51
52
53
54
55
 
# File 'lib/hyperliquid/info.rb', line 49

def all_mids(dex: nil)
  if dex && !dex.empty?
    post("allMids", dex: dex)
  else
    post("allMids")
  end
end

#asset_to_sz_decimals(asset) ⇒ Integer

Get sz decimals for an asset index.

Parameters:

  • asset (Integer) —

    asset index

Returns:

  • (Integer) —

    sz decimals



377
378
379
380
 
# File 'lib/hyperliquid/info.rb', line 377

def asset_to_sz_decimals(asset)
  load_all_mappings! unless @asset_to_sz_decimals
  @asset_to_sz_decimals[asset]
end

#candles_snapshot(coin, interval:, start_time:, end_time:) ⇒ Object

Get candle data.

Parameters:

  • coin (String) —

    e.g. “ETH”

  • interval (String) —

    e.g. “1h”, “1d”, “15m”

  • start_time (Integer) —

    start timestamp in ms

  • end_time (Integer) —

    end timestamp in ms



69
70
71
 
# File 'lib/hyperliquid/info.rb', line 69

def candles_snapshot(coin, interval:, start_time:, end_time:)
  post("candleSnapshot", req: { coin: coin, interval: interval, startTime: start_time, endTime: end_time })
end

#coin_to_asset(coin) ⇒ Integer

Map a coin name to its perpetual asset index.

Parameters:

  • coin (String) —

    e.g. “ETH”

Returns:

  • (Integer) —

    asset index



361
362
363
364
 
# File 'lib/hyperliquid/info.rb', line 361

def coin_to_asset(coin)
  load_coin_mapping! unless @coin_to_asset
  @coin_to_asset[coin] || raise(Error, "Unknown perpetual coin: #{coin}")
end

#delegator_history(address) ⇒ Object

Get comprehensive delegator history.

Parameters:

  • address (String) —

    user address



231
232
233
 
# File 'lib/hyperliquid/info.rb', line 231

def delegator_history(address)
  post("delegatorHistory", user: address)
end

#disconnect_websocket ⇒ Object

Disconnect the WebSocket connection and stop the ping thread.



335
336
337
338
339
 
# File 'lib/hyperliquid/info.rb', line 335

def disconnect_websocket
  raise "Cannot call disconnect_websocket since skip_ws was used" if @ws_manager.nil?

  @ws_manager.stop
end

#extra_agents(address) ⇒ Object

Get extra agents for a user.

Parameters:

  • address (String) —

    user address



306
307
308
 
# File 'lib/hyperliquid/info.rb', line 306

def extra_agents(address)
  post("extraAgents", user: address)
end

#frontend_open_orders(address, dex: nil) ⇒ Object

Get user’s open orders with additional frontend info.

Parameters:

  • address (String) —

    user address

  • dex (String, nil) (defaults to: nil) —

    optional dex identifier



111
112
113
114
115
116
117
 
# File 'lib/hyperliquid/info.rb', line 111

def frontend_open_orders(address, dex: nil)
  if dex && !dex.empty?
    post("frontendOpenOrders", user: address, dex: dex)
  else
    post("frontendOpenOrders", user: address)
  end
end

#funding_history(coin, start_time:, end_time: nil) ⇒ Object

Get funding history for a coin.

Parameters:

  • coin (String) —

    e.g. “ETH”

  • start_time (Integer) —

    start timestamp in ms

  • end_time (Integer) (defaults to: nil) —

    end timestamp in ms (optional)



190
191
192
193
194
 
# File 'lib/hyperliquid/info.rb', line 190

def funding_history(coin, start_time:, end_time: nil)
  req = { coin: coin, startTime: start_time }
  req[:endTime] = end_time if end_time
  post("fundingHistory", **req)
end

#historical_orders(address) ⇒ Object

Get user’s historical orders (up to 2000 recent).

Parameters:

  • address (String) —

    user address



180
181
182
 
# File 'lib/hyperliquid/info.rb', line 180

def historical_orders(address)
  post("historicalOrders", user: address)
end

#l2_snapshot(coin, n_levels: 10) ⇒ Object

Get L2 order book snapshot.

Parameters:

  • coin (String) —

    e.g. “ETH”

  • n_levels (Integer) (defaults to: 10) —

    number of price levels (default: 10)



60
61
62
 
# File 'lib/hyperliquid/info.rb', line 60

def l2_snapshot(coin, n_levels: 10)
  post("l2Book", coin: coin, nSigFigs: n_levels)
end

#meta(dex: nil) ⇒ Object

Get perpetual metadata (universe, asset info).

Parameters:

  • dex (String, nil) (defaults to: nil) —

    optional dex identifier for builder perp dexs



24
25
26
27
28
29
30
 
# File 'lib/hyperliquid/info.rb', line 24

def meta(dex: nil)
  if dex && !dex.empty?
    post("meta", dex: dex)
  else
    post("meta")
  end
end

#meta_and_asset_ctxs ⇒ Object

Get perpetual metadata with live asset contexts (funding, open interest, etc).



38
39
40
 
# File 'lib/hyperliquid/info.rb', line 38

def meta_and_asset_ctxs
  post("metaAndAssetCtxs")
end

#name_to_asset(name) ⇒ Integer

Map a coin name to its asset index (handles both perp and spot). This is the primary method used by Exchange for resolving coin names.

Parameters:

  • name (String) —

    e.g. “ETH”, “BTC”, “PURR/USDC”

Returns:

  • (Integer) —

    asset index

Raises:



347
348
349
350
351
352
353
354
355
356
 
# File 'lib/hyperliquid/info.rb', line 347

def name_to_asset(name)
  load_all_mappings! unless @name_to_coin
  coin = @name_to_coin[name]
  raise Error, "Unknown coin name: #{name}" unless coin

  asset = @coin_to_asset[coin]
  raise Error, "Unknown coin: #{coin}" unless asset

  asset
end

#name_to_coin(name) ⇒ String

Get the full coin name (with dex prefix if applicable) for a display name.

Parameters:

  • name (String) —

    e.g. “ETH”

Returns:

  • (String) —

    coin name



385
386
387
388
 
# File 'lib/hyperliquid/info.rb', line 385

def name_to_coin(name)
  load_all_mappings! unless @name_to_coin
  @name_to_coin[name] || raise(Error, "Unknown name: #{name}")
end

#open_orders(address, dex: nil) ⇒ Object

Get user’s open orders.

Parameters:

  • address (String) —

    user address

  • dex (String, nil) (defaults to: nil) —

    optional dex identifier



100
101
102
103
104
105
106
 
# File 'lib/hyperliquid/info.rb', line 100

def open_orders(address, dex: nil)
  if dex && !dex.empty?
    post("openOrders", user: address, dex: dex)
  else
    post("openOrders", user: address)
  end
end

#order_status(address, oid) ⇒ Object

Query status of an order by oid or cloid.

Parameters:

  • address (String) —

    user address

  • oid (Integer, String) —

    order id (Integer) or cloid (String)



174
175
176
 
# File 'lib/hyperliquid/info.rb', line 174

def order_status(address, oid)
  post("orderStatus", user: address, oid: oid)
end

#perp_dexs ⇒ Object

Get list of perp dexes.



74
75
76
 
# File 'lib/hyperliquid/info.rb', line 74

def perp_dexs
  post("perpDexs")
end

#portfolio(address) ⇒ Object

Get portfolio performance data.

Parameters:

  • address (String) —

    user address



282
283
284
 
# File 'lib/hyperliquid/info.rb', line 282

def portfolio(address)
  post("portfolio", user: address)
end

#predicted_fundings ⇒ Object

Get predicted funding rates.



197
198
199
 
# File 'lib/hyperliquid/info.rb', line 197

def predicted_fundings
  post("predictedFundings")
end

#query_perp_deploy_auction_status ⇒ Object

Get perp deploy auction status.



254
255
256
 
# File 'lib/hyperliquid/info.rb', line 254

def query_perp_deploy_auction_status
  post("perpDeployAuctionStatus")
end

#query_spot_deploy_auction_status(address) ⇒ Object

Get spot deploy state for a user.

Parameters:

  • address (String) —

    user address



260
261
262
 
# File 'lib/hyperliquid/info.rb', line 260

def query_spot_deploy_auction_status(address)
  post("spotDeployState", user: address)
end

#query_user_abstraction_state(address) ⇒ Object

Get user abstraction state.

Parameters:

  • address (String) —

    user address



274
275
276
 
# File 'lib/hyperliquid/info.rb', line 274

def query_user_abstraction_state(address)
  post("userAbstraction", user: address)
end

#query_user_dex_abstraction_state(address) ⇒ Object

Get dex abstraction state for a user.

Parameters:

  • address (String) —

    user address



268
269
270
 
# File 'lib/hyperliquid/info.rb', line 268

def query_user_dex_abstraction_state(address)
  post("userDexAbstraction", user: address)
end

#query_user_to_multi_sig_signers(address) ⇒ Object

Get multi-sig signers for a user.

Parameters:

  • address (String) —

    multi-sig user address



247
248
249
 
# File 'lib/hyperliquid/info.rb', line 247

def query_user_to_multi_sig_signers(address)
  post("userToMultiSigSigners", user: address)
end

#referral(address) ⇒ Object

Get referral state for an address.

Parameters:

  • address (String) —

    user address



239
240
241
 
# File 'lib/hyperliquid/info.rb', line 239

def referral(address)
  post("referral", user: address)
end

#refresh_coin_mappings! ⇒ Object

Reset cached coin mappings (e.g. after new listings).



391
392
393
394
395
396
 
# File 'lib/hyperliquid/info.rb', line 391

def refresh_coin_mappings!
  @coin_to_asset = nil
  @spot_coin_to_asset = nil
  @name_to_coin = nil
  @asset_to_sz_decimals = nil
end

#spot_coin_to_asset(coin) ⇒ Integer

Map a coin name to its spot asset index (10000 + index).

Parameters:

  • coin (String) —

    e.g. “PURR/USDC”

Returns:

  • (Integer) —

    asset index



369
370
371
372
 
# File 'lib/hyperliquid/info.rb', line 369

def spot_coin_to_asset(coin)
  load_spot_coin_mapping! unless @spot_coin_to_asset
  @spot_coin_to_asset[coin] || raise(Error, "Unknown spot coin: #{coin}")
end

#spot_meta ⇒ Object

Get spot metadata.



33
34
35
 
# File 'lib/hyperliquid/info.rb', line 33

def spot_meta
  post("spotMeta")
end

#spot_meta_and_asset_ctxs ⇒ Object

Get spot metadata with live asset contexts.



43
44
45
 
# File 'lib/hyperliquid/info.rb', line 43

def spot_meta_and_asset_ctxs
  post("spotMetaAndAssetCtxs")
end

#spot_user_state(address) ⇒ Object

Get user’s spot account state.

Parameters:

  • address (String) —

    user address



93
94
95
 
# File 'lib/hyperliquid/info.rb', line 93

def spot_user_state(address)
  post("spotClearinghouseState", user: address)
end

#sub_accounts(address) ⇒ Object

Get sub-accounts for an address.

Parameters:

  • address (String) —

    user address



205
206
207
 
# File 'lib/hyperliquid/info.rb', line 205

def sub_accounts(address)
  post("subAccounts", user: address)
end

#subscribe(subscription, callback) ⇒ Integer

Subscribe to a WebSocket channel.

Parameters:

  • subscription (Hash) —

    e.g. { “type” => “allMids” } or { “type” => “l2Book”, “coin” => “ETH” }

  • callback (Proc) —

    called with each message hash

Returns:

  • (Integer) —

    subscription_id for unsubscribing



316
317
318
319
320
321
 
# File 'lib/hyperliquid/info.rb', line 316

def subscribe(subscription, callback)
  remap_coin_subscription(subscription)
  raise "Cannot call subscribe since skip_ws was used" if @ws_manager.nil?

  @ws_manager.subscribe(subscription, callback)
end

#unsubscribe(subscription, subscription_id) ⇒ Boolean

Unsubscribe from a WebSocket channel.

Parameters:

  • subscription (Hash) —

    same hash used to subscribe

  • subscription_id (Integer) —

    returned by subscribe

Returns:

  • (Boolean) —

    true if subscription was found and removed



327
328
329
330
331
332
 
# File 'lib/hyperliquid/info.rb', line 327

def unsubscribe(subscription, subscription_id)
  remap_coin_subscription(subscription)
  raise "Cannot call unsubscribe since skip_ws was used" if @ws_manager.nil?

  @ws_manager.unsubscribe(subscription, subscription_id)
end

#user_fees(address) ⇒ Object

Get user’s fee rates.

Parameters:

  • address (String) —

    user address



139
140
141
 
# File 'lib/hyperliquid/info.rb', line 139

def user_fees(address)
  post("userFees", user: address)
end

#user_fills(address) ⇒ Object

Get user’s trade fills.

Parameters:

  • address (String) —

    user address



121
122
123
 
# File 'lib/hyperliquid/info.rb', line 121

def user_fills(address)
  post("userFills", user: address)
end

#user_fills_by_time(address, start_time:, end_time: nil, aggregate_by_time: nil) ⇒ Object

Get user’s trade fills in a time range.

Parameters:

  • address (String) —

    user address

  • start_time (Integer) —

    start timestamp in ms

  • end_time (Integer) (defaults to: nil) —

    end timestamp in ms (optional)

  • aggregate_by_time (Boolean) (defaults to: nil) —

    aggregate fills by time (optional)



130
131
132
133
134
135
 
# File 'lib/hyperliquid/info.rb', line 130

def user_fills_by_time(address, start_time:, end_time: nil, aggregate_by_time: nil)
  req = { user: address, startTime: start_time }
  req[:endTime] = end_time if end_time
  req[:aggregateByTime] = aggregate_by_time unless aggregate_by_time.nil?
  post("userFillsByTime", **req)
end

#user_funding(address, start_time:, end_time: nil) ⇒ Object

Get user’s funding history.

Parameters:

  • address (String) —

    user address

  • start_time (Integer) —

    start timestamp in ms

  • end_time (Integer) (defaults to: nil) —

    end timestamp in ms (optional)



147
148
149
150
151
 
# File 'lib/hyperliquid/info.rb', line 147

def user_funding(address, start_time:, end_time: nil)
  req = { user: address, startTime: start_time }
  req[:endTime] = end_time if end_time
  post("userFunding", **req)
end

#user_non_funding_ledger_updates(address, start_time:, end_time: nil) ⇒ Object

Get user’s non-funding ledger updates.

Parameters:

  • address (String) —

    user address

  • start_time (Integer) —

    start timestamp in ms

  • end_time (Integer) (defaults to: nil) —

    end timestamp in ms (optional)



157
158
159
160
161
 
# File 'lib/hyperliquid/info.rb', line 157

def user_non_funding_ledger_updates(address, start_time:, end_time: nil)
  req = { user: address, startTime: start_time }
  req[:endTime] = end_time if end_time
  post("userNonFundingLedgerUpdates", **req)
end

#user_rate_limit(address) ⇒ Object

Get user’s rate limits.

Parameters:

  • address (String) —

    user address



165
166
167
 
# File 'lib/hyperliquid/info.rb', line 165

def user_rate_limit(address)
  post("userRateLimit", user: address)
end

#user_role(address) ⇒ Object

Get user’s role and account type.

Parameters:

  • address (String) —

    user address



300
301
302
 
# File 'lib/hyperliquid/info.rb', line 300

def user_role(address)
  post("userRole", user: address)
end

#user_staking_delegations(address) ⇒ Object

Get user’s staking delegations per validator.

Parameters:

  • address (String) —

    user address



219
220
221
 
# File 'lib/hyperliquid/info.rb', line 219

def user_staking_delegations(address)
  post("delegations", user: address)
end

#user_staking_rewards(address) ⇒ Object

Get user’s historic staking rewards.

Parameters:

  • address (String) —

    user address



225
226
227
 
# File 'lib/hyperliquid/info.rb', line 225

def user_staking_rewards(address)
  post("delegatorRewards", user: address)
end

#user_staking_summary(address) ⇒ Object

Get user’s staking summary (delegated, undelegated, pending).

Parameters:

  • address (String) —

    user address



213
214
215
 
# File 'lib/hyperliquid/info.rb', line 213

def user_staking_summary(address)
  post("delegatorSummary", user: address)
end

#user_state(address, dex: nil) ⇒ Object

Get user’s perpetual account state (positions, margin, etc).

Parameters:

  • address (String) —

    user address

  • dex (String, nil) (defaults to: nil) —

    optional dex identifier



83
84
85
86
87
88
89
 
# File 'lib/hyperliquid/info.rb', line 83

def user_state(address, dex: nil)
  if dex && !dex.empty?
    post("clearinghouseState", user: address, dex: dex)
  else
    post("clearinghouseState", user: address)
  end
end

#user_twap_slice_fills(address) ⇒ Object

Get user’s TWAP slice fills.

Parameters:

  • address (String) —

    user address



288
289
290
 
# File 'lib/hyperliquid/info.rb', line 288

def user_twap_slice_fills(address)
  post("userTwapSliceFills", user: address)
end

#user_vault_equities(address) ⇒ Object

Get user’s vault equity positions.

Parameters:

  • address (String) —

    user address



294
295
296
 
# File 'lib/hyperliquid/info.rb', line 294

def user_vault_equities(address)
  post("userVaultEquities", user: address)
end