Withdraw USDC from HyperCore to EVM chains

This guide shows how to withdraw USDC from a HyperCore spot or perp balance to an external EVM blockchain (such as Arbitrum, Ethereum, or Base) using the HyperCore API. Withdrawals from HyperCore to EVM chains default to the Fast Transfer method, due to the fast finality of HyperEVM. The withdrawal process:

Debits your HyperCore balance (spot or perp)
Routes through HyperEVM where USDC is burned via CCTP
CCTP attests to the burn and mints on the destination chain
If automatic forwarding is enabled, the recipient receives funds directly

Note: Withdrawals include a HyperCore fee and may include a CCTP forwarding fee. Ensure your withdrawal amount exceeds these fees.

Important considerations

Keep these things in mind when withdrawing USDC from HyperCore to EVM chains:

Data field: If the data field is empty, the CoreDepositWallet automatically sets a default hook that enables automatic message forwarding on the destination blockchain, provided that the blockchain supports CCTP forwarding. If the data field is not empty, its contents are passed to the CCTP protocol as the value of the hookData field.
Destination caller: The CCTP destinationCaller is always set to the zero address. Passing your own hook data means that anyone can receive the message on the destination blockchain.
Withdrawal fees: In addition to the maxFee charged by the HyperCore blockchain, an additional fixed forwarding fee may be charged by CCTP if automatic forwarding is enabled. The forwarding fee amount depends on the destination blockchain and can be viewed by querying the CoreDepositWallet smart contract. Initially, the fee for forwarding to Arbitrum is 0.2 USDC. If the withdrawal includes custom hook data, the forwarding fee is not set and users have to receive the message on the destination blockchain themselves.
Minimum withdrawal amount: If the withdrawal amount is less than the required forwarding fee, the transaction on HyperEVM reverts. Make sure the withdrawal amount is larger than the fees.

Prerequisites

Before you start, you should have:

Installed Node.js and npm on your development machine
A wallet with USDC balance on HyperCore (spot or perp)
Your wallet’s private key available
Created a new Node project and have the following dependencies installed:
- ethers

Steps

Use the following steps to withdraw USDC from HyperCore to an EVM blockchain.

Step 1. Construct the `sendToEvmWithData` action

Create a sendToEvmWithData action object with the following parameters:

type: sendToEvmWithData
hyperliquidChain: Mainnet (or Testnet for testnet)
signatureChainId: The blockchain ID used for signing (for example, "0xa4b1" for Arbitrum)
token: USDC
amount: The amount of USDC in HyperCore minor units (8 decimal places)
sourceDex: spot to withdraw from spot balance, or leave blank for perp balance
destinationRecipient: The recipient address on the destination blockchain
addressEncoding: hex for EVM chains or base58 for Solana
destinationChainId: The CCTP destination domain ID (for example, 3 for Arbitrum, 0 for Ethereum, 6 for Base)
gasLimit: The HyperCore transaction gas limit
data: CCTP hook data (use "0x" for automatic forwarding)
nonce: Current timestamp in milliseconds

// Example action payload for sendToEvmWithData
const action = {
  type: "sendToEvmWithData",
  hyperliquidChain: "Mainnet",
  signatureChainId: "0xa4b1", // Arbitrum chain ID used for signing
  token: "USDC",
  amount: "1000000000", // 10 USDC in 8-decimal asset units
  sourceDex: "spot", // or "" for `perp`
  destinationRecipient: "0x1234567890123456789012345678901234567890",
  addressEncoding: "hex",
  destinationChainId: 3, // Arbitrum CCTP domain
  gasLimit: 200000,
  data: "0x", // "0x" enables automatic forwarding on the destination
  nonce: Date.now(),
};

Step 2. Sign the action using EIP-712

Sign the action using the EIP-712 typed data signing standard. The signature proves that you authorize this withdrawal. The signing domain should include:

name: "HyperliquidTransaction:SendToEvmWithData"
version: "1"
chainId: The chain ID from signatureChainId (as a number)
verifyingContract: "0x0000000000000000000000000000000000000000"

async function signSendToEvmWithDataAction(action, privateKey) {
  const wallet = new ethers.Wallet(privateKey);

  // Convert chainId from hex to number
  const chainId = parseInt(action.signatureChainId, 16);

  // EIP-712 domain
  const domain = {
    name: "HyperliquidSignTransaction",
    version: "1",
    chainId: chainId,
    verifyingContract: "0x0000000000000000000000000000000000000000",
  };

  // EIP-712 types
  const primaryType = "HyperliquidTransaction:SendToEvmWithData";
  const types = {
    [primaryType]: [
      { name: "hyperliquidChain", type: "string" },
      { name: "token", type: "string" },
      { name: "amount", type: "string" },
      { name: "sourceDex", type: "string" },
      { name: "destinationRecipient", type: "string" },
      { name: "addressEncoding", type: "string" },
      { name: "destinationChainId", type: "uint32" },
      { name: "gasLimit", type: "uint64" },
      { name: "data", type: "bytes" },
      { name: "nonce", type: "uint64" },
    ],
  };

  // Message to sign
  const message = {
    hyperliquidChain: action.hyperliquidChain,
    token: action.token,
    amount: action.amount,
    sourceDex: action.sourceDex,
    destinationRecipient: action.destinationRecipient,
    addressEncoding: action.addressEncoding,
    destinationChainId: action.destinationChainId,
    gasLimit: BigInt(action.gasLimit),
    data: action.data,
    nonce: BigInt(action.nonce),
  };

  // Sign the typed data
  const signature = await wallet.signTypedData(domain, types, message);

  // Split signature into r, s, v components
  const sig = ethers.Signature.from(signature);

  return {
    r: sig.r,
    s: sig.s,
    v: sig.v,
  };
}

Step 3. Submit the signed action to the exchange API

Call the exchange endpoint with the action, nonce, and signature.

async function submitSendToEvmWithData(action, signature) {
  const response = await fetch("https://api.hyperliquid.xyz/exchange", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      action: action,
      nonce: action.nonce,
      signature: signature,
    }),
  });

  const data = await response.json();

  if (data.status === "ok") {
    console.log("Withdrawal successful:", data);
    return data;
  } else {
    throw new Error(`Withdrawal failed: ${JSON.stringify(data)}`);
  }
}

Full example code

The following is a complete example of how to withdraw USDC from HyperCore to an external EVM blockchain.

#!/usr/bin/env node

/**
 * Cross-chain withdrawal with data (sendToEvmWithData)
 * - Sends USDC from HyperCore to an external EVM chain with optional calldata and gas limit
 * - Signs an EIP-712 transaction and POSTs it to the Hyperliquid /exchange API
 *
 * Required env:
 *   PRIVATE_KEY            - 0x-prefixed private key for the HyperCore account
 *   AMOUNT                 - amount of USDC to withdraw (string, in asset units)
 *   SOURCE_DEX             - "" for perp (default), "spot" for spot
 *   DESTINATION_RECIPIENT  - destination chain recipient address (0x...)
 *   DESTINATION_CHAIN_ID   - CCTP domain ID (e.g., 3 = Arbitrum)
 * Optional env:
 *   ADDRESS_ENCODING       - "hex" | "base58" (default: "hex")
 *   GAS_LIMIT              - destination gas limit (default: "200000")
 *   DATA                   - calldata for the destination chain (hex, default: "0x")
 *   HL_IS_MAINNET          - "true" | "false" (default: "true"; selects mainnet vs testnet API URL)
 *
 * Notes:
 * - Token is fixed to USDC in this script.
 * - Signature chain ID is set to Arbitrum (0xa4b1) for the EIP-712 domain.
 *
 * Example (testnet, perp → Arbitrum):
 *   PRIVATE_KEY=0x... AMOUNT=10 SOURCE_DEX="" DESTINATION_RECIPIENT=0xDest DESTINATION_CHAIN_ID=3 HL_IS_MAINNET=false \
 *   node scripts/js/sendToEvmWithData.js
 */

import { Wallet, Signature } from "ethers";

// Get current timestamp in milliseconds (used as EIP-712 nonce and API nonce)
function nowMs() {
  return Number(Date.now());
}

// Parse hex-encoded chain ID (e.g. "0xa4b1") into a decimal number
function parseHexChainId(hexStr) {
  if (!hexStr) return 1;
  return Number(BigInt(hexStr));
}

async function main() {
  // Parse environment variables
  const PRIVATE_KEY = process.env.PRIVATE_KEY || "PRIVATE_KEY_HERE";
  const AMOUNT = process.env.AMOUNT || "1";
  const SOURCE_DEX = process.env.SOURCE_DEX || ""; // "" for perp, "spot" for spot
  const DESTINATION_RECIPIENT =
    process.env.DESTINATION_RECIPIENT || "0xDESTINATION_RECIPIENT_HERE";
  const DESTINATION_CHAIN_ID = process.env.DESTINATION_CHAIN_ID || 3; // 3 = Arbitrum
  const ADDRESS_ENCODING = process.env.ADDRESS_ENCODING || "hex";
  const GAS_LIMIT = process.env.GAS_LIMIT || "200000";
  const DATA = process.env.DATA || "0x";
  const HL_IS_MAINNET =
    String(process.env.HL_IS_MAINNET || "true").toLowerCase() === "true";
  const API_URL =
    process.env.HL_API_URL ||
    (HL_IS_MAINNET
      ? "https://api.hyperliquid.xyz"
      : "https://api.hyperliquid-testnet.xyz");
  const SIGNATURE_CHAIN_ID = "0xa4b1"; // Arbitrum chain ID for signing

  const TOKEN = "USDC";

  // Validate required parameters
  if (
    !PRIVATE_KEY ||
    !TOKEN ||
    !AMOUNT ||
    SOURCE_DEX === undefined ||
    !DESTINATION_RECIPIENT ||
    !DESTINATION_CHAIN_ID
  ) {
    console.error("Missing required env vars");
    console.error(
      "Required: PRIVATE_KEY, TOKEN, AMOUNT, SOURCE_DEX, DESTINATION_RECIPIENT, DESTINATION_CHAIN_ID",
    );
    console.error("\nExample:");
    console.error('  PRIVATE_KEY=0x... TOKEN=USDC AMOUNT=1 SOURCE_DEX="" \\');
    console.error("  DESTINATION_RECIPIENT=0x... DESTINATION_CHAIN_ID=3 \\");
    console.error("  node sendToEvmWithData.js");
    process.exit(1);
  }

  // Derive chain parameters
  const chainId = parseHexChainId(SIGNATURE_CHAIN_ID);
  const hyperliquidChain = HL_IS_MAINNET ? "Mainnet" : "Testnet";
  const timestamp = nowMs();

  // EIP-712 Domain
  const domain = {
    name: "HyperliquidSignTransaction",
    version: "1",
    chainId,
    verifyingContract: "0x0000000000000000000000000000000000000000",
  };

  // EIP-712 Types for CrossChainWithdrawPayload
  const primaryType = "HyperliquidTransaction:SendToEvmWithData";
  const types = {
    [primaryType]: [
      { name: "hyperliquidChain", type: "string" },
      { name: "token", type: "string" },
      { name: "amount", type: "string" },
      { name: "sourceDex", type: "string" },
      { name: "destinationRecipient", type: "string" },
      { name: "addressEncoding", type: "string" },
      { name: "destinationChainId", type: "uint32" },
      { name: "gasLimit", type: "uint64" },
      { name: "data", type: "bytes" },
      { name: "nonce", type: "uint64" },
    ],
  };

  // Message to sign
  const message = {
    hyperliquidChain,
    token: TOKEN,
    amount: String(AMOUNT),
    sourceDex: SOURCE_DEX,
    destinationRecipient: DESTINATION_RECIPIENT,
    addressEncoding: ADDRESS_ENCODING,
    destinationChainId: Number(DESTINATION_CHAIN_ID),
    gasLimit: BigInt(GAS_LIMIT),
    data: DATA,
    nonce: BigInt(timestamp),
  };

  // Sign the message using EIP-712
  const wallet = new Wallet(PRIVATE_KEY);
  const sigHex = await wallet.signTypedData(domain, types, message);
  const sig = Signature.from(sigHex);
  const signature = { r: sig.r, s: sig.s, v: sig.v };

  // Build action (includes signatureChainId and hyperliquidChain)
  const action = {
    type: "sendToEvmWithData",
    hyperliquidChain,
    signatureChainId: SIGNATURE_CHAIN_ID,
    token: TOKEN,
    amount: String(AMOUNT),
    sourceDex: SOURCE_DEX,
    destinationRecipient: DESTINATION_RECIPIENT,
    addressEncoding: ADDRESS_ENCODING,
    destinationChainId: Number(DESTINATION_CHAIN_ID),
    gasLimit: Number(GAS_LIMIT),
    data: DATA,
    nonce: timestamp,
  };

  // Build request payload
  const payload = {
    action,
    nonce: timestamp,
    signature,
  };

  // Send request to Hyperliquid exchange endpoint
  const res = await fetch(`${API_URL}/exchange`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(payload),
  });

  // Parse and display response
  const json = await res
    .json()
    .catch(() => ({ error: "Failed to parse JSON response" }));

  console.log("\nStatus:", res.status);
  console.log("Response:", JSON.stringify(json, null, 2));

  if (res.status === 200 && json.status === "ok") {
    console.log("\n✓ Cross-chain withdrawal initiated successfully");
  } else {
    console.error("\n✗ Cross-chain withdrawal failed");
    process.exit(1);
  }
}

main().catch((e) => {
  console.error("Error:", e.message);
  process.exit(1);
});

Bridge Kit

CCTP

Gateway

Withdraw USDC from HyperCore to EVM chains

Important considerations

Prerequisites

Steps

Step 1. Construct the `sendToEvmWithData` action

Step 2. Sign the action using EIP-712

Step 3. Submit the signed action to the exchange API

Full example code

Bridge Kit

CCTP

Gateway

​Important considerations

​Prerequisites

​Steps

​Step 1. Construct the sendToEvmWithData action

​Step 2. Sign the action using EIP-712

​Step 3. Submit the signed action to the exchange API

​Full example code

Important considerations

Prerequisites

Steps

Step 1. Construct the `sendToEvmWithData` action

Step 2. Sign the action using EIP-712

Step 3. Submit the signed action to the exchange API

Full example code