626 lines
21 KiB
Python
626 lines
21 KiB
Python
from hyperliquid.api import API
|
|
from hyperliquid.utils.types import (
|
|
Any,
|
|
Callable,
|
|
Cloid,
|
|
List,
|
|
Meta,
|
|
Optional,
|
|
SpotMeta,
|
|
SpotMetaAndAssetCtxs,
|
|
Subscription,
|
|
cast,
|
|
)
|
|
from hyperliquid.websocket_manager import WebsocketManager
|
|
|
|
|
|
class Info(API):
|
|
def __init__(
|
|
self,
|
|
base_url: Optional[str] = None,
|
|
skip_ws: Optional[bool] = False,
|
|
meta: Optional[Meta] = None,
|
|
spot_meta: Optional[SpotMeta] = None,
|
|
# Note that when perp_dexs is None, then "" is used as the perp dex. "" represents
|
|
# the original dex.
|
|
perp_dexs: Optional[List[str]] = None,
|
|
): # pylint: disable=too-many-locals
|
|
super().__init__(base_url)
|
|
self.ws_manager: Optional[WebsocketManager] = None
|
|
if not skip_ws:
|
|
self.ws_manager = WebsocketManager(self.base_url)
|
|
self.ws_manager.start()
|
|
|
|
if spot_meta is None:
|
|
spot_meta = self.spot_meta()
|
|
|
|
self.coin_to_asset = {}
|
|
self.name_to_coin = {}
|
|
self.asset_to_sz_decimals = {}
|
|
|
|
# spot assets start at 10000
|
|
for spot_info in spot_meta["universe"]:
|
|
asset = spot_info["index"] + 10000
|
|
self.coin_to_asset[spot_info["name"]] = asset
|
|
self.name_to_coin[spot_info["name"]] = spot_info["name"]
|
|
base, quote = spot_info["tokens"]
|
|
base_info = spot_meta["tokens"][base]
|
|
quote_info = spot_meta["tokens"][quote]
|
|
self.asset_to_sz_decimals[asset] = base_info["szDecimals"]
|
|
name = f'{base_info["name"]}/{quote_info["name"]}'
|
|
if name not in self.name_to_coin:
|
|
self.name_to_coin[name] = spot_info["name"]
|
|
|
|
perp_dex_to_offset = {"": 0}
|
|
if perp_dexs is None:
|
|
perp_dexs = [""]
|
|
else:
|
|
for i, perp_dex in enumerate(self.perp_dexs()[1:]):
|
|
# builder-deployed perp dexs start at 110000
|
|
perp_dex_to_offset[perp_dex["name"]] = 110000 + i * 10000
|
|
|
|
for perp_dex in perp_dexs:
|
|
offset = perp_dex_to_offset[perp_dex]
|
|
if perp_dex == "" and meta is not None:
|
|
self.set_perp_meta(meta, 0)
|
|
else:
|
|
fresh_meta = self.meta(dex=perp_dex)
|
|
self.set_perp_meta(fresh_meta, offset)
|
|
|
|
def set_perp_meta(self, meta: Meta, offset: int) -> Any:
|
|
for asset, asset_info in enumerate(meta["universe"]):
|
|
asset += offset
|
|
self.coin_to_asset[asset_info["name"]] = asset
|
|
self.name_to_coin[asset_info["name"]] = asset_info["name"]
|
|
self.asset_to_sz_decimals[asset] = asset_info["szDecimals"]
|
|
|
|
def disconnect_websocket(self):
|
|
if self.ws_manager is None:
|
|
raise RuntimeError("Cannot call disconnect_websocket since skip_ws was used")
|
|
else:
|
|
self.ws_manager.stop()
|
|
|
|
def user_state(self, address: str, dex: str = "") -> Any:
|
|
"""Retrieve trading details about a user.
|
|
|
|
POST /info
|
|
|
|
Args:
|
|
address (str): Onchain address in 42-character hexadecimal format;
|
|
e.g. 0x0000000000000000000000000000000000000000.
|
|
Returns:
|
|
{
|
|
assetPositions: [
|
|
{
|
|
position: {
|
|
coin: str,
|
|
entryPx: Optional[float string]
|
|
leverage: {
|
|
type: "cross" | "isolated",
|
|
value: int,
|
|
rawUsd: float string # only if type is "isolated"
|
|
},
|
|
liquidationPx: Optional[float string]
|
|
marginUsed: float string,
|
|
positionValue: float string,
|
|
returnOnEquity: float string,
|
|
szi: float string,
|
|
unrealizedPnl: float string
|
|
},
|
|
type: "oneWay"
|
|
}
|
|
],
|
|
crossMarginSummary: MarginSummary,
|
|
marginSummary: MarginSummary,
|
|
withdrawable: float string,
|
|
}
|
|
|
|
where MarginSummary is {
|
|
accountValue: float string,
|
|
totalMarginUsed: float string,
|
|
totalNtlPos: float string,
|
|
totalRawUsd: float string,
|
|
}
|
|
"""
|
|
return self.post("/info", {"type": "clearinghouseState", "user": address, "dex": dex})
|
|
|
|
def spot_user_state(self, address: str) -> Any:
|
|
return self.post("/info", {"type": "spotClearinghouseState", "user": address})
|
|
|
|
def open_orders(self, address: str, dex: str = "") -> Any:
|
|
"""Retrieve a user's open orders.
|
|
|
|
POST /info
|
|
|
|
Args:
|
|
address (str): Onchain address in 42-character hexadecimal format;
|
|
e.g. 0x0000000000000000000000000000000000000000.
|
|
Returns: [
|
|
{
|
|
coin: str,
|
|
limitPx: float string,
|
|
oid: int,
|
|
side: "A" | "B",
|
|
sz: float string,
|
|
timestamp: int
|
|
}
|
|
]
|
|
"""
|
|
return self.post("/info", {"type": "openOrders", "user": address, "dex": dex})
|
|
|
|
def frontend_open_orders(self, address: str, dex: str = "") -> Any:
|
|
"""Retrieve a user's open orders with additional frontend info.
|
|
|
|
POST /info
|
|
|
|
Args:
|
|
address (str): Onchain address in 42-character hexadecimal format;
|
|
e.g. 0x0000000000000000000000000000000000000000.
|
|
Returns: [
|
|
{
|
|
children:
|
|
[
|
|
dict of frontend orders
|
|
]
|
|
coin: str,
|
|
isPositionTpsl: bool,
|
|
isTrigger: bool,
|
|
limitPx: float string,
|
|
oid: int,
|
|
orderType: str,
|
|
origSz: float string,
|
|
reduceOnly: bool,
|
|
side: "A" | "B",
|
|
sz: float string,
|
|
tif: str,
|
|
timestamp: int,
|
|
triggerCondition: str,
|
|
triggerPx: float str
|
|
}
|
|
]
|
|
"""
|
|
return self.post("/info", {"type": "frontendOpenOrders", "user": address, "dex": dex})
|
|
|
|
def all_mids(self, dex: str = "") -> Any:
|
|
"""Retrieve all mids for all actively traded coins.
|
|
|
|
POST /info
|
|
|
|
Returns:
|
|
{
|
|
ATOM: float string,
|
|
BTC: float string,
|
|
any other coins which are trading: float string
|
|
}
|
|
"""
|
|
return self.post("/info", {"type": "allMids", "dex": dex})
|
|
|
|
def user_fills(self, address: str) -> Any:
|
|
"""Retrieve a given user's fills.
|
|
|
|
POST /info
|
|
|
|
Args:
|
|
address (str): Onchain address in 42-character hexadecimal format;
|
|
e.g. 0x0000000000000000000000000000000000000000.
|
|
|
|
Returns:
|
|
[
|
|
{
|
|
closedPnl: float string,
|
|
coin: str,
|
|
crossed: bool,
|
|
dir: str,
|
|
hash: str,
|
|
oid: int,
|
|
px: float string,
|
|
side: str,
|
|
startPosition: float string,
|
|
sz: float string,
|
|
time: int
|
|
},
|
|
...
|
|
]
|
|
"""
|
|
return self.post("/info", {"type": "userFills", "user": address})
|
|
|
|
def user_fills_by_time(self, address: str, start_time: int, end_time: Optional[int] = None) -> Any:
|
|
"""Retrieve a given user's fills by time.
|
|
|
|
POST /info
|
|
|
|
Args:
|
|
address (str): Onchain address in 42-character hexadecimal format;
|
|
e.g. 0x0000000000000000000000000000000000000000.
|
|
start_time (int): Unix timestamp in milliseconds
|
|
end_time (Optional[int]): Unix timestamp in milliseconds
|
|
|
|
Returns:
|
|
[
|
|
{
|
|
closedPnl: float string,
|
|
coin: str,
|
|
crossed: bool,
|
|
dir: str,
|
|
hash: str,
|
|
oid: int,
|
|
px: float string,
|
|
side: str,
|
|
startPosition: float string,
|
|
sz: float string,
|
|
time: int
|
|
},
|
|
...
|
|
]
|
|
"""
|
|
return self.post(
|
|
"/info", {"type": "userFillsByTime", "user": address, "startTime": start_time, "endTime": end_time}
|
|
)
|
|
|
|
def meta(self, dex: str = "") -> Meta:
|
|
"""Retrieve exchange perp metadata
|
|
|
|
POST /info
|
|
|
|
Returns:
|
|
{
|
|
universe: [
|
|
{
|
|
name: str,
|
|
szDecimals: int
|
|
},
|
|
...
|
|
]
|
|
}
|
|
"""
|
|
return cast(Meta, self.post("/info", {"type": "meta", "dex": dex}))
|
|
|
|
def meta_and_asset_ctxs(self) -> Any:
|
|
"""Retrieve exchange MetaAndAssetCtxs
|
|
|
|
POST /info
|
|
|
|
Returns:
|
|
[
|
|
{
|
|
universe: [
|
|
{
|
|
'name': str,
|
|
'szDecimals': int
|
|
'maxLeverage': int,
|
|
'onlyIsolated': bool,
|
|
},
|
|
...
|
|
]
|
|
},
|
|
[
|
|
{
|
|
"dayNtlVlm": float string,
|
|
"funding": float string,
|
|
"impactPxs": Optional([float string, float string]),
|
|
"markPx": Optional(float string),
|
|
"midPx": Optional(float string),
|
|
"openInterest": float string,
|
|
"oraclePx": float string,
|
|
"premium": Optional(float string),
|
|
"prevDayPx": float string
|
|
},
|
|
...
|
|
]
|
|
"""
|
|
return self.post("/info", {"type": "metaAndAssetCtxs"})
|
|
|
|
def perp_dexs(self) -> Any:
|
|
return self.post("/info", {"type": "perpDexs"})
|
|
|
|
def spot_meta(self) -> SpotMeta:
|
|
"""Retrieve exchange spot metadata
|
|
|
|
POST /info
|
|
|
|
Returns:
|
|
{
|
|
universe: [
|
|
{
|
|
tokens: [int, int],
|
|
name: str,
|
|
index: int,
|
|
isCanonical: bool
|
|
},
|
|
...
|
|
],
|
|
tokens: [
|
|
{
|
|
name: str,
|
|
szDecimals: int,
|
|
weiDecimals: int,
|
|
index: int,
|
|
tokenId: str,
|
|
isCanonical: bool
|
|
},
|
|
...
|
|
]
|
|
}
|
|
"""
|
|
return cast(SpotMeta, self.post("/info", {"type": "spotMeta"}))
|
|
|
|
def spot_meta_and_asset_ctxs(self) -> SpotMetaAndAssetCtxs:
|
|
"""Retrieve exchange spot asset contexts
|
|
POST /info
|
|
Returns:
|
|
[
|
|
{
|
|
universe: [
|
|
{
|
|
tokens: [int, int],
|
|
name: str,
|
|
index: int,
|
|
isCanonical: bool
|
|
},
|
|
...
|
|
],
|
|
tokens: [
|
|
{
|
|
name: str,
|
|
szDecimals: int,
|
|
weiDecimals: int,
|
|
index: int,
|
|
tokenId: str,
|
|
isCanonical: bool
|
|
},
|
|
...
|
|
]
|
|
},
|
|
[
|
|
{
|
|
dayNtlVlm: float string,
|
|
markPx: float string,
|
|
midPx: Optional(float string),
|
|
prevDayPx: float string,
|
|
circulatingSupply: float string,
|
|
coin: str
|
|
}
|
|
...
|
|
]
|
|
]
|
|
"""
|
|
return cast(SpotMetaAndAssetCtxs, self.post("/info", {"type": "spotMetaAndAssetCtxs"}))
|
|
|
|
def funding_history(self, name: str, startTime: int, endTime: Optional[int] = None) -> Any:
|
|
"""Retrieve funding history for a given coin
|
|
|
|
POST /info
|
|
|
|
Args:
|
|
name (str): Coin to retrieve funding history for.
|
|
startTime (int): Unix timestamp in milliseconds.
|
|
endTime (int): Unix timestamp in milliseconds.
|
|
|
|
Returns:
|
|
[
|
|
{
|
|
coin: str,
|
|
fundingRate: float string,
|
|
premium: float string,
|
|
time: int
|
|
},
|
|
...
|
|
]
|
|
"""
|
|
coin = self.name_to_coin[name]
|
|
if endTime is not None:
|
|
return self.post(
|
|
"/info", {"type": "fundingHistory", "coin": coin, "startTime": startTime, "endTime": endTime}
|
|
)
|
|
return self.post("/info", {"type": "fundingHistory", "coin": coin, "startTime": startTime})
|
|
|
|
def user_funding_history(self, user: str, startTime: int, endTime: Optional[int] = None) -> Any:
|
|
"""Retrieve a user's funding history
|
|
POST /info
|
|
Args:
|
|
user (str): Address of the user in 42-character hexadecimal format.
|
|
startTime (int): Start time in milliseconds, inclusive.
|
|
endTime (int, optional): End time in milliseconds, inclusive. Defaults to current time.
|
|
Returns:
|
|
List[Dict]: A list of funding history records, where each record contains:
|
|
- user (str): User address.
|
|
- type (str): Type of the record, e.g., "userFunding".
|
|
- startTime (int): Unix timestamp of the start time in milliseconds.
|
|
- endTime (int): Unix timestamp of the end time in milliseconds.
|
|
"""
|
|
if endTime is not None:
|
|
return self.post("/info", {"type": "userFunding", "user": user, "startTime": startTime, "endTime": endTime})
|
|
return self.post("/info", {"type": "userFunding", "user": user, "startTime": startTime})
|
|
|
|
def l2_snapshot(self, name: str) -> Any:
|
|
"""Retrieve L2 snapshot for a given coin
|
|
|
|
POST /info
|
|
|
|
Args:
|
|
name (str): Coin to retrieve L2 snapshot for.
|
|
|
|
Returns:
|
|
{
|
|
coin: str,
|
|
levels: [
|
|
[
|
|
{
|
|
n: int,
|
|
px: float string,
|
|
sz: float string
|
|
},
|
|
...
|
|
],
|
|
...
|
|
],
|
|
time: int
|
|
}
|
|
"""
|
|
return self.post("/info", {"type": "l2Book", "coin": self.name_to_coin[name]})
|
|
|
|
def candles_snapshot(self, name: str, interval: str, startTime: int, endTime: int) -> Any:
|
|
"""Retrieve candles snapshot for a given coin
|
|
|
|
POST /info
|
|
|
|
Args:
|
|
name (str): Coin to retrieve candles snapshot for.
|
|
interval (str): Candlestick interval.
|
|
startTime (int): Unix timestamp in milliseconds.
|
|
endTime (int): Unix timestamp in milliseconds.
|
|
|
|
Returns:
|
|
[
|
|
{
|
|
T: int,
|
|
c: float string,
|
|
h: float string,
|
|
i: str,
|
|
l: float string,
|
|
n: int,
|
|
o: float string,
|
|
s: string,
|
|
t: int,
|
|
v: float string
|
|
},
|
|
...
|
|
]
|
|
"""
|
|
req = {"coin": self.name_to_coin[name], "interval": interval, "startTime": startTime, "endTime": endTime}
|
|
return self.post("/info", {"type": "candleSnapshot", "req": req})
|
|
|
|
def user_fees(self, address: str) -> Any:
|
|
"""Retrieve the volume of trading activity associated with a user.
|
|
POST /info
|
|
Args:
|
|
address (str): Onchain address in 42-character hexadecimal format;
|
|
e.g. 0x0000000000000000000000000000000000000000.
|
|
Returns:
|
|
{
|
|
activeReferralDiscount: float string,
|
|
dailyUserVlm: [
|
|
{
|
|
date: str,
|
|
exchange: str,
|
|
userAdd: float string,
|
|
userCross: float string
|
|
},
|
|
],
|
|
feeSchedule: {
|
|
add: float string,
|
|
cross: float string,
|
|
referralDiscount: float string,
|
|
tiers: {
|
|
mm: [
|
|
{
|
|
add: float string,
|
|
makerFractionCutoff: float string
|
|
},
|
|
],
|
|
vip: [
|
|
{
|
|
add: float string,
|
|
cross: float string,
|
|
ntlCutoff: float string
|
|
},
|
|
]
|
|
}
|
|
},
|
|
userAddRate: float string,
|
|
userCrossRate: float string
|
|
}
|
|
"""
|
|
return self.post("/info", {"type": "userFees", "user": address})
|
|
|
|
def user_staking_summary(self, address: str) -> Any:
|
|
"""Retrieve the staking summary associated with a user.
|
|
POST /info
|
|
Args:
|
|
address (str): Onchain address in 42-character hexadecimal format;
|
|
e.g. 0x0000000000000000000000000000000000000000.
|
|
Returns:
|
|
{
|
|
delegated: float string,
|
|
undelegated: float string,
|
|
totalPendingWithdrawal: float string,
|
|
nPendingWithdrawals: int
|
|
}
|
|
"""
|
|
return self.post("/info", {"type": "delegatorSummary", "user": address})
|
|
|
|
def user_staking_delegations(self, address: str) -> Any:
|
|
"""Retrieve the user's staking delegations.
|
|
POST /info
|
|
Args:
|
|
address (str): Onchain address in 42-character hexadecimal format;
|
|
e.g. 0x0000000000000000000000000000000000000000.
|
|
Returns:
|
|
[
|
|
{
|
|
validator: string,
|
|
amount: float string,
|
|
lockedUntilTimestamp: int
|
|
},
|
|
]
|
|
"""
|
|
return self.post("/info", {"type": "delegations", "user": address})
|
|
|
|
def user_staking_rewards(self, address: str) -> Any:
|
|
"""Retrieve the historic staking rewards associated with a user.
|
|
POST /info
|
|
Args:
|
|
address (str): Onchain address in 42-character hexadecimal format;
|
|
e.g. 0x0000000000000000000000000000000000000000.
|
|
Returns:
|
|
[
|
|
{
|
|
time: int,
|
|
source: string,
|
|
totalAmount: float string
|
|
},
|
|
]
|
|
"""
|
|
return self.post("/info", {"type": "delegatorRewards", "user": address})
|
|
|
|
def query_order_by_oid(self, user: str, oid: int) -> Any:
|
|
return self.post("/info", {"type": "orderStatus", "user": user, "oid": oid})
|
|
|
|
def query_order_by_cloid(self, user: str, cloid: Cloid) -> Any:
|
|
return self.post("/info", {"type": "orderStatus", "user": user, "oid": cloid.to_raw()})
|
|
|
|
def query_referral_state(self, user: str) -> Any:
|
|
return self.post("/info", {"type": "referral", "user": user})
|
|
|
|
def query_sub_accounts(self, user: str) -> Any:
|
|
return self.post("/info", {"type": "subAccounts", "user": user})
|
|
|
|
def query_user_to_multi_sig_signers(self, multi_sig_user: str) -> Any:
|
|
return self.post("/info", {"type": "userToMultiSigSigners", "user": multi_sig_user})
|
|
|
|
def _remap_coin_subscription(self, subscription: Subscription) -> None:
|
|
if (
|
|
subscription["type"] == "l2Book"
|
|
or subscription["type"] == "trades"
|
|
or subscription["type"] == "candle"
|
|
or subscription["type"] == "bbo"
|
|
):
|
|
subscription["coin"] = self.name_to_coin[subscription["coin"]]
|
|
|
|
def subscribe(self, subscription: Subscription, callback: Callable[[Any], None]) -> int:
|
|
self._remap_coin_subscription(subscription)
|
|
if self.ws_manager is None:
|
|
raise RuntimeError("Cannot call subscribe since skip_ws was used")
|
|
else:
|
|
return self.ws_manager.subscribe(subscription, callback)
|
|
|
|
def unsubscribe(self, subscription: Subscription, subscription_id: int) -> bool:
|
|
self._remap_coin_subscription(subscription)
|
|
if self.ws_manager is None:
|
|
raise RuntimeError("Cannot call unsubscribe since skip_ws was used")
|
|
else:
|
|
return self.ws_manager.unsubscribe(subscription, subscription_id)
|
|
|
|
def name_to_asset(self, name: str) -> int:
|
|
return self.coin_to_asset[self.name_to_coin[name]]
|