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 Wallets

API Wallets are also known as agent wallets in the docs.

note

Note that API wallets are only used to sign. To query the account data associated with a master or sub-account, you must pass in the actual address of that account. A common pitfall is to use the agent wallet which leads to an empty result.

Wallets Configuration

The actual address of the account (master 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 do not plan to use it for trading.

The second API Key is treated as the default wallet for trading. If there is only one item in the list, the master account is used to sign trade requests.

The concrete wallet id for signing can be passed in trade request in 6280 attribute/tag. Of course, this wallet should be configured in API Key list.

apiKeys: [
  {
    apiKey = "0xbb24cbb4f4b723f216567391a670f874bf67c753"
    apiSecret = "DUMMY" # pass any value here if you do not plan to use master account for trading
  },
  {
    apiKey = "0xbABCDEF1234567890F05C1e06D2ED495A980F8f5"
    apiSecret = "0xabcdefe03fc01ef6858f415ab3050ab6bf0e5d1ae32c97b909c0b0b972a345d9" # required
  }
]

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.

Client Order ID

Client Order ID (cloid) is an optional 128 bit hex string, e.g. 0x1234567890abcdef1234567890abcdef.
Therefore request sequence id is used as Client Order ID.

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 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 to used for order submission or cancellation.
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>"
    }
  }
}