Hyperliquid Trade Connector

Features

crypto-hyperliquidConnector Key

Instruments

FXFUTURE

Request Types

SUBMITCANCEL

Order Types

LIMITMARKET

Time In Force

GTCIOC

Order ID Mapper

SEQUENCE

✗

Order Status Request

✗

Cancel On Disconnect

✓

Commission

✓

Post Only

✓

Fast Cancel

✗

Fast Replace

Notes

API Keys

The actual address of the account (master or sub account) should be always configured as first item in API Key list. No need to define a private key for the master account if you are planning to use [API Wallets[(#api-wallets). But if there is only one API Key in the list - apiSecret should contain master private key.

API Wallets

It is possible to use API wallets (also known as agent wallets) for trading. The API wallet should always be configured as the second API key in the list.

You can configure multiple API wallets. In this case the second API Key is treated as the default wallet for trading. The concrete wallet for signing can be passed in trade request in 6280 attribute/tag. Of course, this wallet must be configured in the list of API keys.

apiKeys: [
  {
    apiKey = "0xbb24cbb4f4b723f216567391a670f874bf67c753" # master account address
    apiSecret = "DUMMY" # pass any value here
  },
  {
    apiKey = "0xbABCDEF1234567890F05C1e06D2ED495A980F8f5"  # API wallet address
    apiSecret = "0xabcdefe03fc01ef6858f415ab3050ab6bf0e5d1ae32c97b909c0b0b972a345d9" # API wallet private key
  }
]

warning

Note that master account address is used for WebSocket subscription. A common mistake is setting the agent wallet as the first API key, which results in missing WebSocket events.

Subaccounts and Vaults

Subaccounts and vaults do not have private keys. To perform actions on behalf of a subaccount or vault signing should be done by the master account.

USAGE

apiKeys[0].apiKey and vaultAddress should be set to the address of the subaccount or vault.

Self-Trade Prevention

Trades between the same address cancel the resting order instead of causing a fill. No fees are deducted, nor does the the cancel show up in the trade feed.

Order Replacement

Although the HL API allows order "modification", the connector does not support this feature. In practice, the exchange does not support "atomic" replacement - it cancels the original order and places a new one.

From Discord

Modify is generally treated like a cancel followed by a place, so the new order will have whatever size was set in the modify regardless of the filled amount.

Symbology

Hyperliquid instruments are distinguished by Asset IDs.

The instrument's Asset ID should be specified in separate column: hyperliqdAssetId.
The value of name property (from universe array item) should be used as broker symbol (hyperliqdSymbol).

# spot instruments
curl -H "Content-Type: application/json" -X POST -d "{\"type\":\"spotMeta\"}" https://api.hyperliquid.xyz/info

# perpetuals instruments
curl -H "Content-Type: application/json" -X POST -d "{\"type\":\"meta\"}" https://api.hyperliquid.xyz/info

Configuration

Connector settings

Parameter	Default Value	Description
apiKeys[0].apiKey		The address of the master account, subaccount or vault.
apiKeys[0].apiSecret		The private key of master account. Optional. Set any dummy value if API wallets are used.
vaultAddress		The address of the subaccount or vault. Optional.
builderCode		The wallet address that should receive the additional fee.
builderFee		The size of the fee in tenths of a basis point e.g. if it is 10, 1bp of the order notional will be charged to the user and sent to the builder.

Supported order attributes

Key	Description
18	Post Only. Allowed values: 6 - post only orders submission.
6280	Wallet id to be used for order submission or cancellation. See API wallets.
6290	Builder code. The wallet address that should receive the additional fee.
6295	Builder fee. The size of the fee in tenths of a basis point e.g. if it is 10, 1bp of the order notional will be charged to the user and sent to the builder.

Config sample

connectors {
  HYPERLIQD: ${template.connector.crypto.hyperliquid} {
    settings {
      restUrl = "https://api.hyperliquid.xyz"
      websocketUrl = "wss://api.hyperliquid.xyz/ws"

      apiKeys: [
        {
          apiKey = "<MASTER_ACCOUNT_ADDRESS>"        # or <SUBACCOUNT_OR_VAULT_ADDRESS>
          apiSecret = "<MASTER_ACCOUNT_PRIVATE_KEY>" # optional if API wallets are configured
        },
        {
          apiKey = "<API_WALLET_ADDRESS>"
          apiSecret = "<API_WALLET_PRIVATE_KEY>"
        }
      ]

      vaultAddress = "<SUBACCOUNT_OR_VAULT_ADDRESS>"
    }
  }
}