The wallet adapter (hip4.wallet) handles all fund management for HIP-4 prediction trading: moving USDC between your perp and spot accounts, buying and selling USDH on the spot market, and withdrawing funds to external addresses. It relies on two distinct signers - one for user-authorized EIP-712 operations, and one for L1 agent-signed spot orders - so you need to configure both before using the full method surface.
Two signers
The wallet adapter uses two separate signing keys depending on the operation:
User’s wallet - set via setSigner. Required for EIP-712 operations: transfers between spot and perps, withdrawals, and USD sends. The signer must produce a valid EIP-712 signature on the HyperliquidSignTransaction domain.
Agent key - initialized via hip4.auth.initAuth. Required for USDH spot buy/sell, which use L1 agent signing (MessagePack serialization + keccak-256 + EIP-712 on the Exchange domain, chain ID 1337). The agent key signs on behalf of the user’s wallet but is a separate keypair.
setSigner interface
interface WalletSigner {
address: string;
signTypedData: (domain: unknown, types: unknown, value: unknown) => Promise<string>;
}
walletClient.signTypedData and any other EIP-712-capable signer.
hip4.wallet.setSigner({
address: userAddress,
signTypedData: walletClient.signTypedData.bind(walletClient),
});
Methods
| Method | Signing | Description |
|---|
setSigner(signer) | - | Set the user’s wallet for EIP-712 operations |
buyUsdh(amount) | L1 agent | Buy USDH on spot; priced at oracle × 1.1, IOC |
sellUsdh(amount) | L1 agent | Sell USDH on spot; priced at oracle × 0.9, IOC |
sellHype(amount) | L1 agent | Sell HYPE on the HYPE/USDC spot market; size floored to 2 decimals |
transferToSpot(amount) | EIP-712 | Transfer USDC from perp → spot |
transferToPerps(amount) | EIP-712 | Transfer USDC from spot → perp |
withdraw({ destination, amount }) | EIP-712 | Withdraw USDC to an external address |
usdSend({ destination, amount }) | EIP-712 | Send USDC to another Hyperliquid address |
agentSetAbstraction(mode) | L1 agent | Switch the master account’s abstraction mode ("u" / "p" / "i") |
"100", "25.50").
WalletActionResult
Every method returns a Promise<WalletActionResult>:
interface WalletActionResult {
success: boolean;
error?: string;
filledSz?: string; // spot orders only: filled size
avgPx?: string; // spot orders only: average fill price
}
success before reading filledSz and avgPx. These fields are only populated for the spot-order methods (buyUsdh, sellUsdh, and sellHype).
Deposit flow
To fund a prediction account, transfer USDC from your perp balance to spot, then buy USDH on the spot market.
// Step 1: Transfer USDC from perp to spot (EIP-712, user's wallet)
const transfer = await hip4.wallet.transferToSpot("100");
if (!transfer.success) {
throw new Error(`Transfer failed: ${transfer.error}`);
}
// Step 2: Buy USDH on the spot market (L1 agent signing)
const buy = await hip4.wallet.buyUsdh("100");
if (!buy.success) {
throw new Error(`Buy failed: ${buy.error}`);
}
console.log(`Bought ${buy.filledSz} USDH at avg price ${buy.avgPx}`);
Withdraw flow
To exit a prediction position and withdraw funds, sell USDH back to USDC, move it to your perp account, then withdraw.
// Step 1: Sell USDH on the spot market (L1 agent signing)
const sell = await hip4.wallet.sellUsdh("50");
if (!sell.success) {
throw new Error(`Sell failed: ${sell.error}`);
}
// Step 2: Transfer USDC from spot to perp (EIP-712, user's wallet)
const transfer = await hip4.wallet.transferToPerps("50");
if (!transfer.success) {
throw new Error(`Transfer failed: ${transfer.error}`);
}
// Step 3: Withdraw USDC to an external address (EIP-712, user's wallet)
const withdrawal = await hip4.wallet.withdraw({
destination: "0xYourExternalWalletAddress",
amount: "50",
});
if (!withdrawal.success) {
throw new Error(`Withdrawal failed: ${withdrawal.error}`);
}
sellHype(amount)
Sells HYPE on the HYPE/USDC spot market (not USDH). Use this to convert HYPE - for example, balance received on Hypercore - back into USDC. Like buyUsdh/sellUsdh, it is an IOC spot order signed with the L1 agent key.
The amount is a HYPE quantity string. HYPE has 2 size decimals on the spot market, so the size is floored (ROUND_DOWN) to 2 decimal places before submission - never rounded up - so a sell can never exceed your HYPE balance.
// Sell 1.006 HYPE → floored to 1.00 before submission
const sell = await hip4.wallet.sellHype("1.006");
if (!sell.success) {
throw new Error(`Sell failed: ${sell.error}`);
}
console.log(`Sold ${sell.filledSz} HYPE at avg price ${sell.avgPx}`);
testnet flag (107 on mainnet, 1035 on testnet).
agentSetAbstraction(mode)
Switches the master account’s abstraction mode using the approved agent key. This is an L1 agent-signed action, so the agent must be initialized first.
const res = await hip4.wallet.agentSetAbstraction("u");
if (!res.success) {
throw new Error(`Set abstraction failed: ${res.error}`);
}
| Mode | Meaning |
|---|
"u" | Unified account - merges spot and perps into a single balance |
"p" | Portfolio margin |
"i" | Disabled (abstraction off) |
buyUsdh, sellUsdh, sellHype, and agentSetAbstraction require the agent to be initialized first. Call hip4.auth.initAuth(walletAddress, agentSigner) before invoking any of them, or they will fail with a "Not authenticated" error.
transferToSpot, transferToPerps, withdraw, and usdSend require setSigner to be called first with the user’s actual wallet. These operations use EIP-712 user signing and cannot use the agent key.
