Hyperliquid를 지갑에 통합하는 개발자 가이드

2026년 5월 6일

탈중앙화 파생상품 시장이 성숙해지면서, 지갑 개발팀 사이에서도 Hyperliquid의 무기한 선물 거래 기능을 지갑 인터페이스 안에 직접 넣고자 하는 수요가 늘고 있어요. 사용자가 별도 웹앱을 오가지 않고 지갑 안에서 포지션 확인, 주문, 서명까지 처리할 수 있다면 더 일관된 DeFi 경험을 제공할 수 있습니다.

이 글은 지갑 개발자를 대상으로 Hyperliquid 통합에 필요한 기술 흐름을 정리합니다. 계정 모델, 서명 방식, 프런트엔드 SDK 호출, 보안 설계까지 살펴보며, 실제 제품 관점에서는 OneKey Perps와 같은 하드웨어 보안 기반 워크플로를 참고할 수 있습니다.

Hyperliquid의 계정 모델

Hyperliquid는 EVM 호환 주소 체계, 즉 이더리움 형식의 주소를 사용합니다. 사용자는 표준 ECDSA 개인키로 서명합니다. 공식 문서 기준으로 계정은 크게 두 가지로 나뉩니다.

Vault Address: 프로토콜 레벨의 메인 주소로, 자산 소유권을 가집니다.
Agent Address: 권한을 위임받은 하위 서명 주소로, 반복적인 거래 작업의 마찰을 줄이는 데 사용됩니다.

지갑 통합에서 가장 일반적인 방식은 사용자의 메인 지갑 주소를 Vault Address로 사용하고, 필요에 따라 고빈도 거래용 핫월렛 Agent를 선택적으로 승인하도록 하는 것입니다.

연결 방식: WalletConnect vs 직접 RPC

방법 1: WalletConnect 2.0

WalletConnect는 현재 가장 널리 쓰이는 지갑 연결 프로토콜입니다. Hyperliquid 웹 애플리케이션도 WalletConnect 2.0을 기본 지원합니다. 일반적인 통합 절차는 다음과 같습니다.

지갑 앱에서 WalletConnect 2.0 Session Proposal 처리를 구현합니다.
사용자가 QR 코드를 스캔하거나 딥링크를 클릭해 연결을 승인합니다.
지갑은 eth_sendTransaction, personal_sign 요청을 수신하고 서명을 반환합니다.

이 방식의 장점은 침투성이 낮다는 점입니다. 지갑이 Hyperliquid 내부 프로토콜을 깊게 이해하지 않아도, 표준 이더리움 서명 인터페이스만 지원하면 기본 연결이 가능합니다.

방법 2: Hyperliquid Python/JS SDK 직접 통합

지갑 안에서 포지션 조회, 직접 주문, 주문 취소 등 더 깊은 기능을 제공하려면 공식 또는 커뮤니티 SDK를 사용할 수 있습니다.

pip install hyperliquid-python-sdk

# 또는
npm install @nktkas/hyperliquid

Hyperliquid Python SDK는 서명과 요청 로직을 비교적 완전하게 캡슐화하고 있어, 백엔드나 내부 도구에서 빠르게 연동 흐름을 검증하는 데 유용합니다.

서명 방식: EIP-712 구조화 서명

Hyperliquid의 모든 쓰기 작업, 예를 들어 주문, 주문 취소, 입출금 관련 작업은 단순한 eth_sign이 아니라 EIP-712 구조화 서명을 사용합니다. 이는 사용자 경험과 보안에 큰 영향을 줍니다.

EIP-712를 지원하는 지갑은 사용자에게 사람이 읽을 수 있는 서명 내용을 보여줄 수 있습니다. 예: “BTC 무기한 선물 0.01 계약 롱, 지정가 65000 USDC”
EIP-712를 제대로 지원하지 않는 지갑은 16진수 바이트만 표시하게 되며, 이는 사용자 경험이 좋지 않을 뿐 아니라 피싱 및 오서명 위험도 키웁니다.

따라서 지갑 통합에서는 EIP-712 파싱과 표시 로직을 우선적으로 구현하는 것이 좋습니다. 구현 시 EIP-712 표준의 signTypedData_v4 방식을 참고할 수 있습니다.

핵심 API 통합: 주문 흐름

다음은 JavaScript에서 직접 API 호출로 지정가 매수 주문을 보내는 예시입니다.

import { ethers } from "ethers";

const EXCHANGE_ENDPOINT = "https://api.hyperliquid.xyz/exchange";

async function placeOrder(wallet, coin, isBuy, price, size) {
  const nonce = Date.now();

  const orderPayload = {
    type: "order",
    orders: [{
      a: 0,          // asset index (0 = BTC)
      b: isBuy,
      p: price.toString(),
      s: size.toString(),
      r: false,      // reduce-only
      t: { limit: { tif: "Gtc" } }
    }],
    grouping: "na"
  };

  // EIP-712 Domain 및 Types 정의는 공식 문서를 참고하세요.
  const signature = await wallet._signTypedData(domain, types, orderPayload);

  const body = {
    action: orderPayload,
    nonce,
    signature,
  };

  const resp = await fetch(EXCHANGE_ENDPOINT, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  return resp.json();
}

전체 Domain 및 Types 정의는 Hyperliquid 공식 문서의 Exchange Endpoint 설명을 기준으로 구현해야 합니다.

계정 잔고와 포지션 조회

잔고와 포지션 조회는 읽기 작업이므로 서명이 필요하지 않습니다.

async function getAccountInfo(address) {
  const resp = await fetch("https://api.hyperliquid.xyz/info", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      type: "clearinghouseState",
      user: address,
    }),
  });

  return resp.json();
}

반환 데이터에는 다음과 같은 정보가 포함됩니다.

marginSummary: 사용 가능 증거금, 총 계정 가치 등
assetPositions: 각 자산별 포지션 상세 정보
crossMaintenanceMarginUsed: 교차 증거금 유지증거금 사용량 등

보안 설계 핵심 포인트

파생상품 프로토콜을 지갑에 통합할 때는 보안이 가장 중요합니다. 특히 무기한 선물은 레버리지와 청산 위험이 있으므로, 서명 UX와 권한 관리가 제품의 핵심이 됩니다.

1. 개인키 격리

거래 서명은 Secure Enclave 또는 하드웨어 기기 안에서 수행되어야 하며, 개인키가 애플리케이션 레이어 코드에 노출되어서는 안 됩니다. 하드웨어 지갑 기반 구조는 OneKey의 오픈소스 아키텍처를 참고할 수 있습니다.

2. 주문 금액 2차 확인

주문 전에는 사용자에게 명확하고 사람이 읽을 수 있는 확인 화면을 제공해야 합니다. 최소한 다음 정보는 표시하는 것이 좋습니다.

거래 종목
방향: 롱/숏 또는 매수/매도
수량
레버리지
주문 가격
예상 청산가 또는 관련 위험 정보

3. Agent 권한 제한

Agent 모드를 사용하는 경우, 사용자가 언제든 Agent 권한을 철회할 수 있어야 합니다. 또한 UI에서 현재 승인된 Agent 주소와 권한 범위를 명확히 보여줘야 합니다.

Agent는 일반적으로 주문과 같은 특정 작업에만 사용되며, 출금 권한까지 부여하지 않는 구조가 손실 범위를 줄이는 데 도움이 됩니다.

4. 재전송 공격 방지

Hyperliquid의 nonce 메커니즘을 활용해 각 주문의 nonce가 단조 증가하도록 관리해야 합니다. 이를 통해 동일 서명이 다시 제출되는 재전송 공격을 방지할 수 있습니다.

권장 아키텍처: OneKey 기반 통합

OneKey 하드웨어 지갑은 이더리움 EIP-712 서명을 지원하며, 오픈소스 SDK를 통해 구조화 서명 API를 제공합니다. Hyperliquid와 같은 EVM 계열 파생상품 프로토콜을 깊게 통합하려는 개발팀에게 적합한 참고 구조가 될 수 있습니다.

사용자에게 무기한 선물 기능을 제공하려는 지갑 팀이라면 OneKey Perps의 설계 방향을 참고할 만합니다. 핵심은 속도를 위해 보안을 희생하는 것이 아니라, 하드웨어 보안 기반 위에서 가능한 한 매끄러운 파생상품 거래 경험을 제공하는 것입니다.

실제 사용자는 OneKey를 다운로드해 지갑을 설정한 뒤, 지원되는 환경에서 OneKey Perps를 통해 Hyperliquid 기반 무기한 선물 거래 흐름을 직접 확인할 수 있습니다. 개발팀은 OneKey의 오픈소스 SDK와 구조화 서명 UX를 참고해 자체 지갑 통합 설계를 검토해볼 수 있습니다.

자주 묻는 질문

Q1. Hyperliquid는 어떤 지갑 연결 방식을 지원하나요?

Hyperliquid는 MetaMask, WalletConnect 2.0 호환 지갑, 그리고 개인키를 통한 프로그래밍 방식의 직접 서명을 지원합니다. 이론적으로 ECDSA 서명이 가능한 이더리움 지갑이라면 통합할 수 있습니다.

Q2. Agent Address와 메인 주소는 무엇이 다른가요?

Agent Address는 메인 주소가 권한을 위임한 하위 서명 주소입니다. 보통 자동화 트레이딩 봇이나 고빈도 주문에 사용됩니다. Agent는 특정 작업, 예를 들어 주문 실행만 수행하도록 제한할 수 있으며, 출금 권한을 갖지 않도록 설계하면 개인키 노출 시 손실 범위를 줄일 수 있습니다. 자세한 내용은 Hyperliquid 문서를 참고해야 합니다.

Q3. 통합하려면 Hyperliquid 팀에 API 사용 허가를 받아야 하나요?

Hyperliquid는 퍼미션리스 프로토콜입니다. Info Endpoint는 공개되어 있으며, Exchange Endpoint의 쓰기 작업은 유효한 EIP-712 서명만 있으면 됩니다. 별도의 허가나 화이트리스트 신청은 필요하지 않습니다.

Q4. 지갑 UI에서 미실현 손익(PnL)은 어떻게 표시하나요?

clearinghouseState 인터페이스가 반환하는 assetPositions 안에 각 포지션의 unrealizedPnl 필드가 포함됩니다. 해당 값을 UI에 표시하면 됩니다. 단, 이 값은 USDC 기준이라는 점을 함께 고려해야 합니다.

Q5. 테스트넷 주소는 무엇인가요?

Hyperliquid 테스트넷 인터페이스는 다음 주소를 사용합니다.

https://api.hyperliquid-testnet.xyz/

개발 단계에서 실제 자금을 사용하지 않고 기능 테스트를 진행하는 데 활용할 수 있습니다.

리스크 안내

이 글은 기술 통합 참고 자료이며 투자 조언, 법률 조언 또는 재무 조언이 아닙니다. 무기한 선물 거래는 높은 레버리지와 청산 위험을 수반합니다. 개발자는 프로토콜 규칙과 서명 구조, 권한 관리 방식을 충분히 이해한 뒤 프로덕션 통합을 진행해야 합니다.