@layerzerolabs/hyperliquid-composer

Using the LayerZero Hyperliquid SDK

This 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`

`Setup & Environment`

`$3`

`bash npx @layerzerolabs/hyperliquid-composer set-block \ --size {small | big} \ --network {testnet | mainnet} \ --private-key $PRIVATE_KEY \ [--log-level {info | verbose}]`

`Core Spot Management`

`$3`

`bash

`Create 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}]
Get existing metadata

npx @layerzerolabs/hyperliquid-composer core-spot \
    --action get \
    --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 forHYPE/YOUR_ASSETpair > - Composer selection guidance (useFeeToken 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`.

@layerzerolabs/hyperliquid-composer

Using the LayerZero Hyperliquid SDK

To view all commands, run:

``bash npx @layerzerolabs/hyperliquid-composer -h`

`Setup & Environment`

`$3`

`bash npx @layerzerolabs/hyperliquid-composer set-block \ --size {small | big} \ --network {testnet | mainnet} \ --private-key $PRIVATE_KEY \ [--log-level {info | verbose}]`

`Core Spot Management`

`$3`

`bash

`Create 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}]
Get existing metadata

npx @layerzerolabs/hyperliquid-composer core-spot \
    --action get \
    --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 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.

`$3`

Enables your token to be used as a quote asset for trading pairs.

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`

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'

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`.