Deposit, withdraw, and convert USDC on HIP-4 wallets

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 USDC 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 USDC 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>;
}

This interface is compatible with viem’s 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	=
`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"`)

All amounts are strings representing USDC quantities with up to 6 decimal places (e.g. "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
}

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 USDC on the spot market (L1 agent signing)
const buy = await hip4.wallet.buyUsdc("100");
if (!buy.success) {
  throw new Error(`Buy failed: ${buy.error}`);
}

console.log(`Bought ${buy.filledSz} USDC at avg price ${buy.avgPx}`);

Withdraw flow

To exit a prediction position and withdraw funds, sell USDC back to USDC, move it to your perp account, then withdraw.

// Step 1: Sell USDC on the spot market (L1 agent signing)
const sell = await hip4.wallet.sellUsdc("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 USDC). Use this to convert HYPE - for example, balance received on Hypercore - back into USDC. Like buyUsdc/sellUsdc, 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}`);

The correct HYPE/USDC spot index is selected automatically from the adapter’s 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)

buyUsdc, sellUsdc, 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.

Get Started

Concepts

Adapters

Utilities

Rewards

Changelog

Deposit, withdraw, and convert USDC on HIP-4 wallets

Two signers

`setSigner` interface

Methods

`WalletActionResult`

Deposit flow

Withdraw flow

`sellHype(amount)`

`agentSetAbstraction(mode)`

​Two signers

​setSigner interface

​Methods

​WalletActionResult

​Deposit flow

​Withdraw flow

​sellHype(amount)

​agentSetAbstraction(mode)

Two signers

`setSigner` interface

Methods

`WalletActionResult`

Deposit flow

Withdraw flow

`sellHype(amount)`

`agentSetAbstraction(mode)`