Skip to content

Execution

Hyperliquid Asset IDs: Spot, Perps and HIP-3

Compute and reverse-check Hyperliquid order asset IDs with a hypothetical metadata fixture, including token-index and builder DEX numbering mistakes.

Three ivory ceramic channels with different recesses and a lime block fitted into the stepped channel.
Illustration for execution; examples in this article are educational.

Hyperliquid order asset IDs come from market metadata: native perps use their zero-based universe position, spot uses 10000 plus the spot market index, and HIP-3 uses 100000 plus the DEX index times 10000 plus the local perp index. Resolve the network, market family and canonical name first; token indices and display tickers cannot replace that mapping.

An integration can preserve a quantity perfectly and sign its request correctly while naming an unintended market. The same short label might refer to a native perpetual, a spot token quoted in USDC, or a builder's perpetual. A routing decision needs enough context to distinguish those markets before any price or size is attached.

The formulas below follow Hyperliquid's official asset ID reference, checked on 29 October 2026. The worked fixture is entirely hypothetical. Its names, indices and market availability are invented for calculation, and the public API mechanisms described here do not establish a trading product's supported markets.

Match the identifier to the operation

The exchange order format puts the integer asset ID in the field a. Cancel-by-order-ID also supplies a alongside the order ID. A token's name or hexadecimal identity belongs to a different field and operation; substituting either for an order asset ID loses that distinction. Official exchange request formats.

Market-data requests use another representation. For perpetuals, coin follows the name in perpetual metadata. Ordinary spot markets generally use @ followed by the spot pair index; the documented special case is PURR/USDC. Thus a spot market can have both a string such as @41 for a data request and an integer such as 10041 for an order. Those values describe related identities in different request schemas. Info endpoint coin conventions.

Keep the canonical API name even when showing a friendlier pair label. Hyperliquid's interface remapping example shows that displayed BTC/USDC corresponds to UBTC/USDC on mainnet HyperCore. A familiar screen label therefore deserves a metadata lookup before routing. The broader symbol and contract identifier guide explains the same identity problem across venues.

Calculate from the unmodified metadata

Read meta for the original perpetual DEX and meta with the chosen dex for a builder DEX. The empty DEX name denotes the original venue. Obtain the DEX index from its zero-based position in the full perpDexs list, including the native entry. A builder's name alone does not supply that position. Official perpetual metadata endpoints.

Market familyInput that identifies the marketOrder asset calculation
Native perpetualZero-based position in the original meta.universeThat position
Ordinary spotThe selected spotMeta.universe object's index10000 + market index
HIP-3 perpetualDEX index and zero-based position in that DEX's universe100000 + DEX index × 10000 + local index

The official Python SDK provides a concrete implementation of these paths. At the pinned 0.24.0 snapshot, it enumerates the raw perpetual universe and adds the relevant offset. For spot, it uses the market object's explicit index, then joins the base and quote references to token records by token index. Pinned SDK metadata mapping.

When perp_dexs is omitted, this SDK loads only the original perp DEX. Builder perps need the intended DEX names included when constructing the client.

These two indexing rules require different handling. A spot row's position in a selected or sorted list is not its explicit market index. For perps, filtering or sorting the raw universe before deriving positions changes the meaning of those positions. Preserve the source ordering and filter only after recording the original index.

A checked fixture: one NOVA label, five routes

Assume one hypothetical environment returns the following selected metadata. Every occurrence of NOVA in this section is fictional:

  • Original perp universe: ALPHA, NOVA, BETA, in that order. ALPHA is marked delisted.
  • Spot tokens: index 0 names USDC, 7 names USDT, and 19 names NOVA.
  • Spot markets: @41 has index: 41 and tokens: [19, 0]; @44 has index: 44 and tokens: [19, 7].
  • Perp DEX list: native placeholder null, then forge, then atlas.
  • Each builder universe has its prefixed ALPHA, BETA and NOVA entries in that order.

The spot token references represent base followed by quote, as used in the inspected SDK mapping. Separate token and market arrays are also visible in the official spot metadata schema. Selecting NOVA as the base still leaves a choice between the two hypothetical quote assets.

Intended routeMetadata evidenceArithmeticOrder asset ID
Native NOVA perpNOVA is at raw position 111
NOVA/USDC spotPair index 41; token references [19, 0]10000 + 4110041
NOVA/USDT spotPair index 44; token references [19, 7]10000 + 4410044
forge:NOVA perpDEX index 1; local position 2100000 + 1 × 10000 + 2110002
atlas:NOVA perpDEX index 2; local position 2100000 + 2 × 10000 + 2120002

All five results were recomputed with local integer arithmetic and inverse lookups. None is a claim about a currently listed instrument.

For the atlas route, first subtract 100000 from 120002, leaving 20002. Dividing that remainder into blocks of 10000 gives DEX index 2 and local index 2. Raw DEX position 2 names atlas, whose local position 2 contains atlas:NOVA. The round trip returns the originally selected canonical name.

For spot asset 10041, subtracting 10000 gives market index 41. Find the market whose index equals 41, read its [19, 0] references, and join them to NOVA and USDC. Searching the token table directly for 41 would skip the market relationship that proves the quote asset.

Compare the reconstructed identity with the requested family, DEX and token pair. Reversing an integer without this comparison only checks the arithmetic.

Plausible integers can still identify the wrong market

Using NOVA's token index 19 to build a spot order produces 10019. The intended NOVA/USDC route requires 10041. The fixture supplies no market with index 19, so a resolver should return an unresolved match. A real environment could contain some other pair at that index; integer validity alone would still be insufficient.

Removing delisted ALPHA from the native universe before enumeration moves NOVA to position 0 in the filtered list. Raw asset 0 still belongs to ALPHA in this fixture. Preserve that raw identity while separately deciding whether an instrument is eligible for a new order.

A builder off-by-one error is more subtle. After dropping the native placeholder, atlas appears at position 1 in the shortened DEX list. Inserting that position into the documented formula gives 110002, which reverses to forge:NOVA here. The pinned SDK avoids this numbering mismatch by starting its post-placeholder builder offsets at 110000. SDK DEX offset construction.

Stripping atlas: creates a different failure: a name lookup for plain NOVA can select the native perpetual, asset 1. Store the full canonical name with its DEX context. A display abbreviation should never overwrite the identifier carried through an execution record.

Outcome identifiers need a separate path

Current documentation also defines outcomes, whose order representation differs from ordinary spot despite shared trading implementation details. With outcome ID o and side s, the encoding is 10 × o + s; only sides 0 and 1 are valid. The coin form uses #, the token-name form uses +, and the order asset adds 100000000. Official outcome identifier rules.

For a separate hypothetical outcome 27, side 1 produces encoding 271, coin #271, token name +271, and order asset 100000271. Applying ordinary spot arithmetic would instead produce 10271. The computed digits would be correct for the wrong representation.

Resolve the ID and side against outcomeMeta, including its side names and event description. An ID does not describe the event's meaning or resolution terms by itself. Outcome metadata response. A resolver designed around the older spot/perp paths needs explicit outcome handling before accepting this family. Documentation coverage alone does not establish its availability in every environment or client version.

Carry the environment and numerical rules with the match

Mainnet and testnet have separate API hosts in the pinned SDK constants. The official asset reference also documents different indices across those environments. Rebuild the mapping from the intended host when moving between them; an integer contains no independent assurance about which network supplied its metadata.

Likewise, a spot token's numeric index, hexadecimal tokenId and optional EVM contract metadata are distinct fields in the pinned SDK token definition. Retain each with its documented purpose. An order asset ID should not become a substitute for a token-transfer or contract identity.

After identity is settled, validate the proposed size and price against that resolved market's rules. The Hyperliquid size and price decimal guide handles that next step, while the API decimal-precision guide explains preserving the original numerical value. The SDK's order serializer places the asset, price and size in separate wire fields.

Keep subsequent accounting attached to the same identity too. A perpetual's funding observations belong with its canonical market and DEX context; the Hyperliquid funding-rate and payment guide develops that separate reconciliation.

Validate the full route before constructing an order

Use this sequence as a resolver acceptance check:

  1. Record the API environment, intended market family and metadata retrieval time. Preserve the source arrays with their original positions.
  2. Select exactly one market. Require both base and quote for spot, and the full DEX-prefixed name for HIP-3. Treat multiple candidates as unresolved.
  3. Calculate the integer from that record. Store its source indices and canonical name alongside the result.
  4. Reverse the calculation against the same snapshot. Confirm the DEX and local record, or the spot market and both token references, agree with the original selection.
  5. Apply market status, numerical constraints and account permissions separately. Preserve the resolved identity with subsequent order and fill records.

These checks describe a proposed application boundary. The inspected SDK establishes client-side mapping and serialization, without proving the matching engine's internal implementation. Correct routing also leaves separate questions about collateral, liquidity and execution.

For the fictional atlas request, the acceptance record must retain the environment, HIP-3 family, atlas:NOVA, DEX index 2, local index 2 and asset 120002. If any component disagrees with the inverse lookup, stop construction and resolve that discrepancy before attaching a price or quantity.

Keep the context with the example.

Each worked example is illustrative, with its sources and assumptions in the article. Read our editorial standards for authorship, verification and corrections.