Universe

hl.Universe

Universe(id_to_info: dict[int, AssetInfo] | None = None)

The Universe class provides asset information and metadata for the exchange.

The Universe contains mappings between asset names and IDs, along with detailed information about each asset including decimals, type (SPOT/PERPETUAL), and other metadata. It also provides utility methods for rounding prices and sizes according to each asset's rules.

Warning: Do not instantiate Universe directly. Use Info.get_universe() instead.

Example

Retrieve the universe from the Info class:

api = await Api.create(address="0x...", secret_key="0x...") ... universe = await api.info.get_universe() ... btc_id = universe.name_to_id["BTC"] # Get BTC's asset ID ... btc_info = universe.id_to_info[btc_id] # Get BTC's asset info

Warning: This constructor is for internal use only. Users should not have to instantiate Universe directly. Instead, retrieve the universe using:

universe = await api.info.get_universe()

or

universe = Universe.from_meta_and_spot_meta(meta, spot_meta)

Parameters:

Name	Type	Description	Default
id_to_info	dict[int, AssetInfo] | None	Mapping from asset IDs to asset info.	None

Methods:

Name	Description
from_perpetual_meta_and_spot_meta	Create a Universe instance from perpetual and spot metadata.
round_price	Round price so it satisfies Hyperliquid’s tick-size rules.
round_size	Round a size to an allowed value, respecting the coin's szDecimals.
to_asset_id	Convert an asset ID or name to an asset ID.
to_asset_name	Convert an asset ID or name to an asset name.

Attributes:

Name	Type	Description
id_to_info	dict[int, AssetInfo]	Mapping from asset IDs to detailed asset information including decimals and type.
id_to_name	dict[int, str]	Mapping from asset IDs to their names (e.g. "BTC", "ETH").
name_to_id	dict[str, int]	Mapping from asset names (e.g. "BTC", "ETH") to their numeric asset IDs.

id_to_info instance-attribute

id_to_info: dict[int, AssetInfo] = id_to_info

Mapping from asset IDs to detailed asset information including decimals and type.

id_to_name instance-attribute

id_to_name: dict[int, str] = {
    asset_info["id"]: asset_info["name"]
    for asset_info in values()
}

Mapping from asset IDs to their names (e.g. "BTC", "ETH").

name_to_id instance-attribute

name_to_id: dict[str, int] = {
    asset_info["name"]: asset_info["id"]
    for asset_info in values()
}

Mapping from asset names (e.g. "BTC", "ETH") to their numeric asset IDs.

from_perpetual_meta_and_spot_meta classmethod

from_perpetual_meta_and_spot_meta(
    perpetual_meta: Meta, spot_meta: SpotMeta
) -> Universe

Create a Universe instance from perpetual and spot metadata.

Parameters:

Name	Type	Description	Default
perpetual_meta	Meta	Perpetual assets metadata containing the universe of perpetual trading pairs and their properties.	required
spot_meta	SpotMeta	Spot assets metadata containing the universe of spot trading pairs and token information.	required

Returns:

Type	Description
Universe	A Universe instance with the asset information from the perpetual and spot metadata.

round_price

round_price(
    asset: int | str,
    price: Decimal,
    rounding: str = ROUND_HALF_EVEN,
) -> Decimal

Round price so it satisfies Hyperliquid’s tick-size rules.

Rules (docs): ≤5 sig figs and ≤pxDecimals decimals. Integers are always OK.

Reference: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size

Parameters:

Name	Type	Description	Default
asset	int | str	The asset ID or name to round the price for.	required
price	Decimal	The price to round.	required
rounding	str	The rounding mode to use. Defaults to ROUND_HALF_EVEN.	ROUND_HALF_EVEN

Returns:

Type	Description
Decimal	decimal.Decimal: The rounded price.

round_size

round_size(
    asset: int | str,
    size: Decimal,
    rounding: str = ROUND_HALF_EVEN,
) -> Decimal

Round a size to an allowed value, respecting the coin's szDecimals.

By default, we round to the nearest allowed size with ties going to the nearest even integer.

Parameters:

Name	Type	Description	Default
asset	int | str	The asset ID or name to round the size for.	required
size	Decimal	The size to round.	required
rounding	str	The rounding mode to use. Defaults to ROUND_HALF_EVEN.	ROUND_HALF_EVEN

Returns:

Type	Description
Decimal	decimal.Decimal: The rounded size.

to_asset_id

to_asset_id(asset: int | str) -> int

Convert an asset ID or name to an asset ID.

Parameters:

Name	Type	Description	Default
asset	int | str	The asset ID or name to convert.	required

Returns:

Name	Type	Description
int	int	The asset ID.

to_asset_name

to_asset_name(asset: int | str) -> str

Convert an asset ID or name to an asset name.

Parameters:

Name	Type	Description	Default
asset	int | str	The asset ID or name to convert.	required

Returns:

Name	Type	Description
str	str	The asset name.