Hyperliquid signing overview

​

Quick reference

​

Architecture overview

L1 Actions → Phantom Agent → ChainId 1337
                ↑
           Agent Wallet (approved via user-signed)
                ↑
User-Signed → Direct EIP-712 → ChainId 0x66eee

​

L1 Actions

​

Characteristics

• Chain ID: 1337 (NOT Arbitrum’s 42161)
• Domain name: “Exchange”
• Serialization: Msgpack binary format before hashing
• Agent construction: Phantom agent from action hash

​

Supported actions

• order, cancel, cancelByCloid
• modify, batchModify
• scheduleCancel
• updateLeverage, updateIsolatedMargin
• vaultTransfer, subAccountTransfer

​

Example

from hyperliquid.utils.signing import sign_l1_action, get_timestamp_ms

timestamp = get_timestamp_ms()
action = {"type": "order", "orders": [...]}

signature = sign_l1_action(
    wallet,
    action,
    None,  # vault_address
    timestamp,
    None,  # expires_after
    True   # is_mainnet
)

​

User-Signed actions

​

Characteristics

• Chain ID: 0x66eee (421614 in decimal)
• Domain name: “HyperliquidSignTransaction”
• Serialization: Direct JSON structure
• No phantom agent: Direct signing of typed data

​

Supported actions

• approveAgent → sign_agent()
• usdSend → sign_usd_transfer_action()
• spotSend → sign_spot_transfer_action()
• withdraw → sign_withdraw_from_bridge_action()
• approveBuilderFee → sign_approve_builder_fee()
• usdClassTransfer → sign_usd_class_transfer_action()
• tokenDelegate → sign_token_delegate_action()

​

Example

from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants

exchange = Exchange(
    wallet=master_wallet,
    base_url=constants.MAINNET_API_URL
)

# Approve an agent wallet
result, agent_key = exchange.approve_agent("bot_v1")

​

Key concepts

​

Phantom Agent

1. Action serialized with msgpack
2. Nonce and vault address appended
3. Data hashed with keccak256
4. Temporary “agent” object created with hash as connectionId
5. This phantom agent is signed via EIP-712

​

Agent Wallet

• Stateless: No funds or positions
• Nonce isolation: Independent nonce tracking
• Limited scope: Can only sign L1 actions, not transfers
• Created via: User-signed approveAgent action

​

SDK support

​

Installation

pip install hyperliquid-python-sdk

​

Configuration

{
    "private_key": "0x...",
    "account_address": "0x..."
}

​

Common pitfalls

​

Decision flowchart

​

Related guides

• L1 Action signing guide — Detailed guide for trading operations
• User-signed actions guide — Complete guide for administrative operations
• Authentication guide — Overview of authentication mechanisms