Deploying a spot token (HIP-1 and HIP-2)

Only the first of the 5 actions is on a clock. registerToken2 pays the auction and locks the token’s name and decimals; nothing after it is refunded. Deployments can also get stuck, for example on Hyperliquidity incompatible with total supply; the docs say to rehearse the exact deployment on testnet.

Say the last auction cleared at 1,000 HYPE. The next opens at 2,000 HYPE and falls linearly over 31 hours to the 500 HYPE floor, passing 1,250 HYPE halfway.

The 5 required actions, in order

Each is an L1 spotDeploy action with one variant key:

1. registerToken2: name and decimals; pays the auction.
2. userGenesis, repeatable: balances for addresses and for holders of existing tokens; can blacklist addresses from anchor-token genesis.
3. genesis: fixes maxSupply; noHyperliquidity: true zeroes the Hyperliquidity balance.
4. registerSpot: the pair [base token index, quote token index], USDC for a new token.
5. registerHyperliquidity: the ladder on that pair.

Read the auction before you bid

{ "type": "spotDeployState", "user": "0x..." }

The response holds your deployments under states (token, spec, spots, maxSupply, genesis balances) and the auction under gasAuction (startTimeSeconds, durationSeconds, startGas, currentGas, endGas). Pairs between two existing tokens use registerSpot with a separate auction, reported by {"type": "spotPairDeployAuctionStatus"}.

The quote asset changes the economics

Hyperliquidity runs only on the USDC pair every new token gets. Other pairs go through the pair auction:

Pair type	Effect
Base against USDC	standard spot fees; Hyperliquidity available
Base against another quote asset	fees collected in that quote token go to the Assistance Fund
Pair between two quote assets	taker fees, maker rebates and volume contribution 80% lower
Aligned quote asset (AQAv1)	taker fees 20% lower, maker rebates 50% better, volume contribution 20% higher

A token becomes a quote asset through enableQuoteToken, irreversible and free, with weiDecimals 8, szDecimals 2, a zero deployer fee share and the quote asset stake, slashable by validator vote if peg or liquidity conditions fail (quote assets).

Bridged tokens start at their system address

A token from elsewhere is normally deployed with noHyperliquidity and its whole supply, or 2^64 - 1, credited at genesis to its system address (0x20 then the token index as 19 big-endian bytes). Once linked to its HyperEVM contract, transfers to that address move balances across.

The numbers

Parameter	Value
Required actions	5, in order
Auction duration	31 hours (111600 s)
Auction floor	500 HYPE
Auction starting price	500 HYPE if the previous auction failed to complete, otherwise 2x the last winning price
name	at most 6 characters
szDecimals, weiDecimals	frontend checks allow 0 to 2 and 0 to 8; szDecimals + 5 <= weiDecimals
Genesis amount per entry	at most 19 digits (frontend check)
Total genesis supply	at most u64::MAX / 2 wei (frontend check)
Total genesis balance	at least 100,000,000 lots (frontend check)
Allocation to an anchor token’s holders	at least 100,000 of the new token (frontend check)
Hyperliquidity levels	at least 10; each 0.3% above the last
Hyperliquidity share	more than 1% of total supply
First Hyperliquidity order	at least 1 USDC
Market cap at startPx	at most 10M USDC
Market cap at the top level	1B to 100B USDC
Deployer fee share	0% to 100%, default 100%, decrease-only
Token annotation	changeable at most once per day
Deployer label	2 to 4 lowercase characters, set once
Quote asset stake	200k HYPE for 3 years (50 HYPE on testnet)

Frontend checks are client-side validations for deployment tools, not all the protocol enforces. With the top price computed as startPx * ceil(1.003 ** nOrders), the two market cap checks require at least 1,535 levels.

The actions on the wire

Lists of tuples are signed in the order given; wei amounts are decimal strings:

{ "type": "spotDeploy", "registerToken2": {
    "spec": { "name": "ABC", "szDecimals": 2, "weiDecimals": 8 },
    "maxGas": 100000000000, "fullName": "ABC token" } }

{ "type": "spotDeploy", "userGenesis": {
    "token": 1234,
    "userAndWei": [["0xabc...", "100000000000000"]],
    "existingTokenAndWei": [] } }

{ "type": "spotDeploy", "genesis": { "token": 1234, "maxSupply": "200000000000000" } }

{ "type": "spotDeploy", "registerSpot": { "tokens": [1234, 0] } }

{ "type": "spotDeploy", "registerHyperliquidity": {
    "spot": 987, "startPx": "0.5", "orderSz": "10000", "nOrders": 400, "nSeededLevels": 5 } }

• maxGas caps what you pay. The HIP-1 docs give no unit; the HIP-3 docs use native token wei (HYPE, 1e8 per HYPE). Read currentGas first.
• userGenesis: userAndWei is [address, wei], existingTokenAndWei is [token index, total wei for its holders], and blacklistUsers ([address, bool]) is sent alone.
• registerHyperliquidity: spot is the spot pair index from registerSpot, not the token index; startPx and orderSz are human-unit decimal strings; with noHyperliquidity, nOrders is 0. Seeded levels cost px * sz USDC each, checked against the deployer’s perp USDC balance by the docs’ client.

Optional actions, any time after registerToken2:

Action	Shape	Rule
setDeployerTradingFeeShare	{token, share}, share like "99.4%"	0% to 100%, never increasing
setTokenAnnotation	{token, annotation: {category, description, displayName, keywords}}	once per day; 15, 400 and 9 characters; at most 2 keywords of 10
setDeployerLabel	{label}	2 to 4 lowercase characters, unique across perp dexes and labels, once
enableQuoteToken	{token}	irreversible, no gas
enableAlignedQuoteToken	{token}	aligned quote asset requirements apply
disableQuoteToken	{token}
disableAlignedQuoteToken	{token}	must be sent after disableQuoteToken

Where deployments go wrong

• maxSupply is a checksum. Compute it from the userGenesis calls that succeeded, read back from spotDeployState.
• The Hyperliquidity account cannot receive a userGenesis balance.
• Anchor-token genesis is a snapshot: only balances above 0.0001 per cent of the anchor’s max supply count.
• Signing. Trailing zeros change the hash ("10", not "10.0"); addresses go lowercase (signing).

For what the token is, see HIP-1; for the ladder the fifth step configures, HIP-2; for fee shares, deployer economics and risk.