cloudzombie/wallets

Wallets on Hyperliquid

What You Probably Got Wrong

"I can use my Ethereum wallet directly." For HyperEVM: yes, same wallet, add the chain. For HyperCore: the API uses EIP-712 typed data signatures — you need to understand the signing scheme, not just connect MetaMask.

"Private key = full access." For automated agents, use the API wallet pattern — approve a subaccount agent key with limited permissions. The agent key can trade but can't withdraw beyond the approved limit. Main wallet stays cold.

"Any nonce works." HyperCore nonces are NOT sequential. They use a rolling-set scheme — you can use any nonce that's greater than the lowest in your recent 20 nonces. This is fundamentally different from Ethereum. Getting this wrong means rejected orders.

---

HyperEVM: Adding to MetaMask

Add HyperEVM to any EVM-compatible wallet:

| Parameter | Mainnet | Testnet | |-----------|---------|---------| | Chain ID | 999 | 998 | | RPC URL | https://rpc.hyperliquid.xyz/evm | https://rpc.hyperliquid-testnet.xyz/evm | | Chain Name | HyperEVM | HyperEVM Testnet | | Currency Symbol | HYPE | HYPE | | Block Explorer | https://explorer.hyperliquid.xyz | https://explorer-testnet.hyperliquid.xyz |

// Programmatically add to MetaMask
await window.ethereum.request({
  method: 'wallet_addEthereumChain',
  params: [{
    chainId: '0x3E7',  // 999 in hex
    chainName: 'HyperEVM',
    nativeCurrency: { name: 'HYPE', symbol: 'HYPE', decimals: 18 },
    rpcUrls: ['https://rpc.hyperliquid.xyz/evm'],
    blockExplorerUrls: ['https://explorer.hyperliquid.xyz'],
  }],
});

Same address as Ethereum. Your Ethereum address works on HyperEVM. Same private key, same address, different chain.

---

HyperCore: How Signing Works

HyperCore uses EIP-712 typed data signatures for all exchange actions. This is NOT a standard EVM transaction — it's a signed message that the HyperCore API validates.

The Signing Flow

1. Build the action payload (order, cancel, transfer, etc.)
2. Hash it with EIP-712 (domain + struct hash)
3. Sign with your private key (standard eth_signTypedData_v4)
4. POST to /exchange with { action, nonce, signature, vaultAddress? }

Domain Separator for HyperCore

const domain = {
  name: 'Exchange',
  version: '1',
  chainId: 1337,           // HyperCore always uses chainId 1337 for signing
  verifyingContract: '0x0000000000000000000000000000000000000000',
};

Critical: The chainId for EIP-712 signing in HyperCore is ALWAYS 1337 — regardless of whether you're on mainnet or testnet. This is NOT the HyperEVM chain ID (999/998).

---

API Wallet Pattern (For Agents)

Never use your main wallet private key in an automated bot. Use the API wallet pattern:

Step 1: Create an Agent Wallet

Generate a new private key. This is your agent key — it will have limited permissions.

from eth_account import Account

# Generate a new random private key for the agent
agent_key = Account.create()
print(f"Agent address: {agent_key.address}")
print(f"Agent key: {agent_key.key.hex()}")

Step 2: Approve the Agent Wallet

The main wallet approves the agent key via the API:

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

# Using the main wallet
exchange = Exchange(main_wallet, constants.MAINNET_API_URL)

# Approve agent key to trade on behalf of main wallet
result = exchange.approve_agent(
    agent_address=agent_key.address,
    agent_name="MyTradingBot"
)

Step 3: Agent Uses Its Own Key

The agent wallet submits orders independently, signing with its own key:

# Agent trades using its own key, but against main wallet's account
agent_exchange = Exchange(
    agent_key,
    constants.MAINNET_API_URL,
    account_address=main_wallet.address  # Trading on behalf of main wallet
)

# Place order
order_result = agent_exchange.order(
    "ETH",
    is_buy=True,
    sz=0.1,
    limit_px=2000.0,
    order_type={"limit": {"tif": "Gtc"}}
)

Benefits:

• Agent key can be compromised without losing your main wallet funds
• Set withdrawal limits: agent can't drain beyond a threshold
• Revoke agent access anytime from main wallet
• Different agents for different strategies

---

Nonce Management on HyperCore

HyperCore nonces are NOT sequential like Ethereum. They use a rolling-set scheme.

How it works:

• Each signer has a set of "recent nonces" (the 20 highest nonces seen)
• Any new nonce must be greater than the LOWEST nonce in the set
• Once the set has 20 entries, the lowest is evicted as new ones are added
• This allows batching and out-of-order submission within a window

Practical implications:

# ✅ CORRECT: Use timestamp-based nonces (milliseconds since epoch)
import time
nonce = int(time.time() * 1000)  # milliseconds — always increasing

# ✅ CORRECT: The SDK handles nonces automatically
# hyperliquid-python-sdk manages nonce generation internally

# ❌ WRONG: Don't manually track sequential nonces
nonce = last_nonce + 1  # This breaks with concurrent requests

The recommended approach: Use the official SDK — it handles nonce generation (typically millisecond timestamps) correctly.

---

🚨 NEVER COMMIT SECRETS TO GIT

This applies to Hyperliquid exactly as it does to Ethereum. Bots scrape GitHub in real-time.

Things that must NEVER be committed:

• Main wallet private keys
• Agent wallet private keys
• API credentials

# .gitignore MUST include:
.env
.env.*
*.key
*.pem
secrets/

# ✅ Load from environment
import os
from eth_account import Account

private_key = os.environ['HYPERLIQUID_PRIVATE_KEY']
wallet = Account.from_key(private_key)

# ❌ NEVER hardcode
private_key = "0xdeadbeef..."  # DON'T DO THIS

If you leaked a key:

1. Assume it's compromised immediately
2. Move all funds to a new wallet NOW
3. Revoke agent approvals from the compromised wallet
4. Rotate to new keys
5. Clean git history (but the key is already burned)

---

CRITICAL Guardrails for AI Agents

1. NEVER use main wallet for automated trading. Use agent wallet pattern.
2. NEVER store private keys in chat logs, code, or version control.
3. NEVER move funds without human confirmation for amounts above threshold.
4. Always verify the action before signing. Check the order params, size, price.
5. Use a dedicated wallet with limited funds for agent operations.
6. Set withdrawal limits on agent wallets via the API.
7. Log all transactions (never log keys).
8. Test on testnet first. Use api.hyperliquid-testnet.xyz.
9. Implement position size limits. Require human approval above threshold.
10. Monitor for anomalies. Alert if agent places orders outside expected parameters.

---

Multisig for HyperEVM

For HyperEVM contracts holding significant value, use a multisig:

• Safe (Gnosis Safe) works on HyperEVM — it's EVM-compatible
• For contract ownership, use a multisig not a single EOA
• HyperCore doesn't have native multisig but you can control HyperCore accounts from a HyperEVM multisig via custom contract logic

---

Wallet Libraries

TypeScript/JavaScript:

import { createWalletClient, http, privateKeyToAccount } from 'viem';
import { hyperliquid } from './chains';

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const client = createWalletClient({
  account,
  chain: hyperliquid,
  transport: http('https://rpc.hyperliquid.xyz/evm'),
});

Python:

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

wallet = Account.from_key(os.environ['PRIVATE_KEY'])
exchange = Exchange(wallet, constants.MAINNET_API_URL)
info = exchange.info  # Read-only info client