LayerZero Labs reference EVM OmniChain Fungible Token (OFT) implementation for Hyperliquid
npm install @layerzerolabs/hyperliquid-composerThis SDK provides a complete toolkit for deploying and managing HyperLiquid HIP-1 tokens and connecting them to LayerZero OFTs. Commands are organized by workflow to guide you through the deployment process.
To view all commands, run:
``bash`
npx @layerzerolabs/hyperliquid-composer -h
`bash`
npx @layerzerolabs/hyperliquid-composer set-block \
--size {small | big} \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY \
[--log-level {info | verbose}]
`bashCreate deployment configuration with optional freeze/quote features
npx @layerzerolabs/hyperliquid-composer core-spot \
--action create \
--oapp-config
--token-index
--network {testnet | mainnet} \
[--log-level {info | verbose}]
HIP-1 Deployment Workflow
Complete the following steps in order to deploy your HIP-1 token:
$3
Must be done before genesis if you want freeze capability.
`bash
npx @layerzerolabs/hyperliquid-composer enable-freeze-privilege \
--token-index \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]
`$3
`bash
npx @layerzerolabs/hyperliquid-composer user-genesis \
--token-index \
[--action {* | userAndWei | existingTokenAndWei | blacklistUsers}] \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]
`$3
`bash
npx @layerzerolabs/hyperliquid-composer set-genesis \
--token-index \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]
`$3
`bash
npx @layerzerolabs/hyperliquid-composer register-spot \
--token-index \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]
`$3
`bash
npx @layerzerolabs/hyperliquid-composer create-spot-deployment \
--token-index \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]
`$3
Can be done at any time after deployment. Note: If you plan to enable quote token capability, read the Permissionless Spot Quote Assets documentation before setting this value.
`bash
npx @layerzerolabs/hyperliquid-composer trading-fee \
--token-index \
--share <[0%,100%]> \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]
`$3
Enables your token to be used as a quote asset for trading pairs.
> ⚠️ Important: Review the complete Quote Assets (Fee Tokens) section for:
> - Mainnet requirements (technical and liquidity)
> - Testnet requirements (50 HYPE stake + active order book)
> - Order book maintenance for
HYPE/YOUR_ASSET pair
> - Composer selection guidance (use FeeToken variant for quote assets)Dependency: Requires trading fee share configuration (see Step 6 above).
`bash
npx @layerzerolabs/hyperliquid-composer enable-quote-token \
--token-index \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]
`$3
Enables your token to be used as an aligned quote asset for trading pairs. Aligned quote tokens have special properties and requirements. See: Aligned Quote Assets
`bash
npx @layerzerolabs/hyperliquid-composer enable-aligned-quote-token \
--token-index \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]
`EVM-HyperCore Linking
After completing HIP-1 deployment, link your token to a LayerZero OFT:
$3
`bash
npx @layerzerolabs/hyperliquid-composer request-evm-contract \
--oapp-config \
--token-index \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]
`$3
`bash
npx @layerzerolabs/hyperliquid-composer finalize-evm-contract \
--oapp-config \
--token-index \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]
`Alternative: Using CoreWriter directly with Foundry
If you prefer to use Foundry's
cast command, you can generate the calldata and send the transaction directly:`bash
npx @layerzerolabs/hyperliquid-composer finalize-evm-contract-corewriter \
--token-index \
--nonce \
--network {testnet | mainnet}
`Post-Launch Management
$3
Only available if freeze privilege was enabled before genesis:
`bash
Freeze a user
npx @layerzerolabs/hyperliquid-composer freeze-user \
--token-index \
--user-address <0x...> \
--freeze true \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]Unfreeze a user
npx @layerzerolabs/hyperliquid-composer freeze-user \
--token-index \
--user-address <0x...> \
--freeze false \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]
`$3
Permanently removes freeze capability (irreversible):
`bash
npx @layerzerolabs/hyperliquid-composer revoke-freeze-privilege \
--token-index \
--network {testnet | mainnet} \
--private-key $PRIVATE_KEY_HYPERLIQUID \
[--log-level {info | verbose}]
`Info & Queries
$3
`bash
npx @layerzerolabs/hyperliquid-composer spot-deploy-state \
--token-index \
--network {testnet | mainnet} \
[--deployer-address <0x...>] \
[--log-level {info | verbose}]
`$3
`bash
npx @layerzerolabs/hyperliquid-composer hip-token \
--token-index \
--network {testnet | mainnet} \
[--log-level {info | verbose}]
`$3
`bash
npx @layerzerolabs/hyperliquid-composer is-account-activated \
--user <0x...> \
--network {testnet | mainnet} \
[--log-level {info | verbose}]
`$3
`bash
npx @layerzerolabs/hyperliquid-composer get-core-balances \
--user <0x...> \
[--show-zero {false | true}] \
--network {testnet | mainnet} \
[--log-level {info | verbose}]
`$3
`bash
npx @layerzerolabs/hyperliquid-composer list-spot-pairs \
--token-index \
--network {testnet | mainnet} \
[--log-level {info | verbose}]
`$3
`bash
npx @layerzerolabs/hyperliquid-composer spot-auction-status \
--network {testnet | mainnet} \
[--log-level {info | verbose}]
`$3
Check if a specific token is a quote asset, or list all quote assets when no token index is provided.
`bash
List all quote assets
npx @layerzerolabs/hyperliquid-composer list-quote-asset \
--network {testnet | mainnet} \
[--log-level {info | verbose}]Check if specific token is a quote asset
npx @layerzerolabs/hyperliquid-composer list-quote-asset \
--filter-token-index \
--network {testnet | mainnet} \
[--log-level {info | verbose}]
`The command returns
yes or no when checking a specific token, or lists all quote assets when no token index is provided.Utilities
$3
`bash
npx @layerzerolabs/hyperliquid-composer to-bridge \
--token-index \
[--log-level {info | verbose}]
`Advanced: Creating Custom Scripts
You can create your own custom scripts using the
HyperliquidClient directly. This is useful for actions not covered by the CLI or for building custom automation.$3
`typescript
import { HyperliquidClient } from '@layerzerolabs/hyperliquid-composer'
import { Wallet } from 'ethers'async function customAction() {
// Initialize wallet
const wallet = new Wallet(process.env.PRIVATE_KEY!)
// Create client (testnet or mainnet)
const isTestnet = true
const logLevel = 'info'
const hyperliquidClient = new HyperliquidClient(isTestnet, logLevel)
// Define your action
const action = {
type: 'spotDeploy',
enableAlignedQuoteToken: {
token: 1234, // your token index
},
}
// Submit the action
const response = await hyperliquidClient.submitHyperliquidAction(
'/exchange',
wallet,
action
)
console.log('Response:', response)
}
customAction()
`$3
Refer to the Hyperliquid API documentation for all available action types and their parameters. The SDK supports any valid HyperCore action through
submitHyperliquidAction`.