Hyperliquid MCP 서버 - 완전한 구현

이 MCP(모델 컨텍스트 프로토콜) 서버는 Hyperliquid SDK를 포괄적으로 감싸는 래퍼(wrapper)를 제공하여 AI 비서에게 현물 및 선물 시장의 모든 거래 기능을 제공합니다. 이를 통해 AI 비서가 Hyperliquid 거래소와 상호 작용하여 시장 데이터 검색, 거래 실행, 포지션 관리 등의 작업을 수행할 수 있습니다.

특징

포괄적인 API 범위

현물 및 선물 거래를 위한 모든 Hyperliquid SDK API의 완전한 구현
시장 데이터 검색(가격, 주문장, 캔들)
주문 배치 및 관리(시장가, 지정가, 트리거, TWAP)
포지션 관리(레버리지, 마진, 마감)
계좌 정보 및 잔액
자금 조달 비율 정보
이체 및 출금
금고 관리
하위 계정 관리
추천 시스템 통합

기술적 특징

개인 키와 지갑 주소를 모두 사용한 적절한 인증
포괄적인 오류 처리 및 검증
실시간 시장 데이터 접근
주문 추적을 위한 클라이언트 주문 ID(cloid) 지원
테스트넷과 메인넷 모두 지원

식별된 API 및 구현

Hyperliquid SDK 저장소를 철저히 조사한 결과, 다음 API를 식별하고 구현했습니다.

시장 데이터 API

API	설명	구현
`getAllMids`	사용 가능한 모든 암호화폐의 중간 가격을 알아보세요	SDK의 `info.getAllMids()` 에 직접 매핑
`getL2Book`	심볼에 대한 주문장 데이터 가져오기	SDK의 `info.getL2Book()` 에 직접 매핑
`getCandleSnapshot`	과거 캔들 데이터 가져오기	SDK의 `info.getCandleSnapshot()` 에 직접 매핑
`getMetaAndAssetCtxs`	영구 선물에 대한 메타데이터 및 자산 컨텍스트 가져오기	SDK의 `info.perpetuals.getMetaAndAssetCtxs()` 에 직접 매핑
`getSpotMetaAndAssetCtxs`	현물 시장에 대한 메타데이터 및 자산 컨텍스트 가져오기	SDK의 `info.spot.getSpotMetaAndAssetCtxs()` 에 직접 매핑

계정 정보 API

API	설명	구현
`getClearinghouseState`	영구 선물 계좌 상태 가져오기	SDK의 `info.perpetuals.getClearinghouseState()` 에 직접 매핑
`getSpotClearinghouseState`	스팟 계정 상태 가져오기	SDK의 `info.spot.getSpotClearinghouseState()` 에 직접 매핑
`getUserOpenOrders`	미결 주문 받기	SDK의 `info.getUserOpenOrders()` 에 직접 매핑
`getUserFills`	거래 채우기를 받으세요	SDK의 `info.getUserFills()` 에 직접 매핑
`getUserFillsByTime`	시간 범위별로 거래 채우기 받기	SDK의 `info.getUserFillsByTime()` 에 직접 매핑
`getUserFunding`	자금 지급 받기	SDK의 `info.perpetuals.getUserFunding()` 에 직접 매핑
`getFundingHistory`	자금 조달 비율 내역 가져오기	SDK의 `info.perpetuals.getFundingHistory()` 에 직접 매핑
`getPredictedFundings`	예상 자금 조달 금리를 받으세요	SDK의 `info.perpetuals.getPredictedFundings()` 에 직접 매핑

주문 관리 API

API	설명	구현
`placeOrder`	주문하기(시장가, 지정가, 트리거)	SDK의 `exchange.placeOrder()` 에 직접 매핑
`placeTwapOrder`	TWAP 주문하기	SDK의 `exchange.placeTwapOrder()` 에 직접 매핑
`cancelOrder`	주문 취소	SDK의 `exchange.cancelOrder()` 에 직접 매핑
`cancelOrderByCloid`	클라이언트 주문 ID로 주문 취소	SDK의 `exchange.cancelOrderByCloid()` 에 직접 매핑
`cancelTwapOrder`	TWAP 주문 취소	SDK의 `exchange.cancelTwapOrder()` 에 직접 매핑
`modifyOrder`	기존 주문 수정	SDK의 `exchange.modifyOrder()` 에 직접 매핑

위치 관리 API

API	설명	구현
`updateLeverage`	심볼의 레버리지 업데이트	SDK의 `exchange.updateLeverage()` 에 직접 매핑
`updateIsolatedMargin`	포지션에 대한 분리된 마진 업데이트	SDK의 `exchange.updateIsolatedMargin()` 에 직접 매핑
`marketClose`	시장가 주문으로 포지션을 마감하세요	SDK의 `custom.marketClose()` 를 통해 구현됨
`closeAllPositions`	모든 포지션을 닫으세요	SDK의 `custom.closeAllPositions()` 를 통해 구현됨

이체 및 출금 API

API	설명	구현
`usdTransfer`	USDC를 다른 지갑으로 이체하세요	SDK의 `exchange.usdTransfer()` 에 직접 매핑
`initiateWithdrawal`	Arbitrum으로 USDC 인출	SDK의 `exchange.initiateWithdrawal()` 에 직접 매핑
`spotTransfer`	스팟 자산을 다른 지갑으로 전송	SDK의 `exchange.spotTransfer()` 에 직접 매핑
`transferBetweenSpotAndPerp`	현물계좌와 정기계좌 간 이체	SDK의 `exchange.transferBetweenSpotAndPerp()` 에 직접 매핑

볼트 관리 API

API	설명	구현
`createVault`	새로운 볼트를 생성하세요	SDK의 `exchange.createVault()` 에 직접 매핑
`getVaultDetails`	보관소 세부 정보 받기	SDK의 `info.getVaultDetails()` 에 직접 매핑
`vaultTransfer`	볼트와 지갑 간 자금 이체	SDK의 `exchange.vaultTransfer()` 에 직접 매핑
`vaultDistribute`	금고에서 팔로워에게 자금을 분배합니다.	SDK의 `exchange.vaultDistribute()` 에 직접 매핑
`vaultModify`	볼트 구성 수정	SDK의 `exchange.vaultModify()` 에 직접 매핑

하위 계정 관리 API

API	설명	구현
`createSubAccount`	새로운 하위 계정을 만드세요	SDK의 `exchange.createSubAccount()` 에 직접 매핑
`getSubAccounts`	모든 하위 계정 가져오기	SDK의 `info.getSubAccounts()` 에 직접 매핑
`subAccountTransfer`	하위 계좌 간 자금 이체(영구)	SDK의 `exchange.subAccountTransfer()` 에 직접 매핑
`subAccountSpotTransfer`	하위 계정 간 스팟 자산 이전	SDK의 `exchange.subAccountSpotTransfer()` 에 직접 매핑

다양한 API

API	설명	구현
`setReferrer`	추천인 코드 설정	SDK의 `exchange.setReferrer()` 에 직접 매핑
`referral`	추천 정보를 얻으세요	SDK의 `info.referral()` 에 직접 매핑
`setDisplayName`	리더보드의 표시 이름 설정	SDK의 `exchange.setDisplayName()` 에 직접 매핑
`getUserRole`	사용자 역할 가져오기	SDK의 `info.getUserRole()` 에 직접 매핑
`approveAgent`	사용자를 대신하여 거래할 에이전트 승인	SDK의 `exchange.approveAgent()` 에 직접 매핑
`approveBuilderFee`	건설업체 수수료 승인	SDK의 `exchange.approveBuilderFee()` 에 직접 매핑

인증 구현

MCP 서버는 개인 키와 지갑 주소를 모두 사용하여 인증을 구현합니다.

개인 키 인증 : 서버는 환경 변수 또는 구성 파일을 통해 개인 키를 받습니다. 이 개인 키는 Hyperliquid API를 통해 트랜잭션에 서명하고 인증하는 데 사용됩니다.
지갑 주소 인증 : 서버는 읽기 전용 작업에 사용되는 지갑 주소도 허용합니다. 개인 키는 제공되지만 지갑 주소가 제공되지 않은 경우, 서버는 개인 키에서 지갑 주소를 도출합니다.
볼트 주소 지원 : 볼트 작업의 경우 서버는 볼트 주소 지정도 지원합니다.

사용자가 거래를 실행하거나 계좌 정보에 접근하기 전에 적절하게 인증되었는지 확인하기 위해 필요한 작업을 실행하기 전에 인증 검증이 수행됩니다.

오류 처리 및 유효성 검사

MCP 서버는 포괄적인 오류 처리 및 검증을 구현합니다.

클라이언트 검증 : 어떠한 작업도 실행하기 전에 서버는 Hyperliquid 클라이언트가 초기화되었는지 검증합니다.
인증 검증 : 인증이 필요한 작업의 경우, 서버는 사용자가 적절하게 인증되었는지 검증합니다.
매개변수 검증 : 서버는 SDK에 전달하기 전에 모든 매개변수를 검증하여 올바른 유형과 형식인지 확인합니다.
오류 처리 : 서버는 SDK에서 발생하는 모든 오류를 포착하고 처리하여 사용자에게 명확한 오류 메시지를 제공합니다.
로깅 : 서버는 모든 작업과 오류를 기록하여 문제를 쉽게 디버깅할 수 있습니다.

구현 과제 및 특별 고려 사항

1. 시장 주문 구현

Hyperliquid의 API에는 직접적인 "시장가 주문" 엔드포인트가 없습니다. 대신, 시장가 주문은 즉시 주문 또는 취소(IOC) 시간 제한이 있는 공격적인 지정가 주문으로 구현됩니다. 체결을 보장하기 위해 현재 가격에 슬리피지 팩터를 적용합니다.

지엑스피1

2. 현물 시장 심볼 처리

Hyperliquid의 현물 시장 심볼에는 "-SPOT" 접미사가 붙습니다. MCP 서버는 필요에 따라 접미사를 추가하여 이를 투명하게 처리합니다.

// For spot market orders, we need to use the same API endpoint but with the spot symbol
const spotSymbol = `${symbol}-SPOT`;

3. 주문 응답 구문 분석

Hyperliquid API에서 주문을 위한 응답 형식은 복잡하며 주문 ID를 추출하기 위해 신중한 구문 분석이 필요합니다.

// Extract order ID from the response
let orderId = null;
if (result.response && result.response.data && result.response.data.statuses) {
  for (const status of result.response.data.statuses) {
    if (status.resting) {
      orderId = status.resting.oid;
      break;
    } else if (status.filled) {
      orderId = status.filled.oid;
      break;
    }
  }
}

4. 숫자 값 처리

Hyperliquid API는 숫자 값을 문자열로 반환하는 경우가 많습니다. MCP 서버는 이를 숫자로 변환하여 더 쉽게 사용할 수 있도록 합니다.

// Convert string values to numbers
const result = {};
for (const [symbol, price] of Object.entries(allMids)) {
  result[symbol] = parseFloat(price);
}

5. 웹소켓 지원

Hyperliquid SDK는 실시간 데이터를 위한 WebSocket 연결을 지원합니다. MCP 서버는 WebSocket 지원을 활성화하여 클라이언트를 초기화합니다.

client = new Hyperliquid({
  privateKey: config.privateKey,
  testnet: config.testnet,
  walletAddress: config.walletAddress,
  vaultAddress: config.vaultAddress,
  enableWs: true
});

필수 조건

Node.js(v14 이상)
Hyperliquid 계정
인증을 위한 Ethereum 개인 키(거래에 필요)
귀하의 지갑 주소(거래에 필요)

구성

서버는 환경 변수나 구성 파일을 사용하여 구성할 수 있습니다.

환경 변수

HYPERLIQUID_PRIVATE_KEY : 거래를 위해 인증에 필요한 Ethereum 개인 키입니다.
HYPERLIQUID_WALLET_ADDRESS : 귀하의 지갑 주소(거래에 필요)
HYPERLIQUID_VAULT_ADDRESS : 볼트 주소(볼트 작업의 경우 선택 사항)
HYPERLIQUID_TESTNET : 테스트넷을 사용하려면 'true'로 설정하고, 메인넷을 사용하려면 'false'로 설정합니다(기본값: false).
LOG_LEVEL : 로깅 레벨 - 'debug', 'info', 'warn' 또는 'error' (기본값: 'info')

구성 파일

서버와 같은 디렉토리에 다음과 같은 구조의 .hyperliquid-config.json 파일을 만들 수도 있습니다.

{
  "privateKey": "your-ethereum-private-key",
  "walletAddress": "your-wallet-address",
  "vaultAddress": "your-vault-address",
  "testnet": false,
  "logLevel": "info",
  "popularCoins": ["BTC", "ETH", "SOL", "AVAX", "ARB", "DOGE", "LINK", "MATIC"]
}

서버 실행

다음을 실행하여 서버를 시작합니다.

node hyperliquid-mcp-server-complete.js

사용 가능한 도구

이 서버는 Hyperliquid 거래소와 상호 작용할 수 있는 포괄적인 도구 세트를 제공합니다. 다음은 몇 가지 예입니다.

시장 데이터 도구

getMarketPrice : 지정된 암호화폐의 현재 가격을 가져옵니다.
getOrderBook : 지정된 암호화폐에 대한 현재 주문장을 가져옵니다.
getCandleData : 지정된 암호화폐에 대한 과거 캔들 데이터를 가져옵니다.
getAllMids : 사용 가능한 모든 암호화폐의 모든 중간 가격을 가져옵니다.

계정 정보 도구

getAccountInfo : 사용자의 영구 선물 계좌에 대한 정보를 가져옵니다.
getSpotAccountInfo : 사용자의 스팟 거래 계좌에 대한 정보를 가져옵니다.
getUserOpenOrders : 사용자의 모든 미결 주문을 가져옵니다.
getUserFills : 사용자의 최근 채우기를 가져옵니다.

주문 관리 도구

placeMarketOrder : 지정된 암호화폐에 대한 시장 주문을 넣습니다.
placeLimitOrder : 지정된 암호화폐에 대한 제한 주문을 넣습니다.
placeTriggerOrder : 트리거 주문(손절매 또는 이익실현)을 실행합니다.
placeTwapOrder : TWAP(시간 가중 평균 가격) 주문을 합니다.
cancelOrder : 기존 주문 취소
cancelOrderByCloid : 클라이언트 주문 ID로 주문 취소
cancelAllOrders : 모든 미결 주문 취소
modifyOrder : 기존 주문을 수정합니다.

직위 관리 도구

updateLeverage : 지정된 암호화폐의 레버리지를 업데이트합니다.
updateIsolatedMargin : 위치의 격리된 마진을 업데이트합니다.
closePosition : 오픈 포지션을 닫습니다
closeAllPositions : 모든 오픈 포지션을 닫습니다.

이체 및 출금 도구

usdTransfer : USDC를 다른 지갑으로 전송
initiateWithdrawal : Arbitrum으로 USDC 출금
spotTransfer : 다른 지갑으로 스팟 자산을 전송합니다.
transferBetweenSpotAndPerp : 현물 계좌와 정기 계좌 간 자금 이체

볼트 관리 도구

createVault : 새로운 볼트를 생성합니다
getVaultDetails : 볼트에 대한 세부 정보를 가져옵니다.
vaultTransfer : Vault와 Permanent Futures Wallet 간 자금 이체
vaultDistribute : 금고에서 팔로워에게 자금을 분배합니다.
vaultModify : 볼트 구성 수정

하위 계정 관리 도구

createSubAccount : 새로운 하위 계정을 생성합니다
getSubAccounts : 사용자의 모든 하위 계정을 가져옵니다.
subAccountTransfer : 하위 계좌 간 자금 이체(영구)
subAccountSpotTransfer : 하위 계정 간 스팟 자산 전송

사용 가능한 리소스

서버는 다음과 같은 리소스를 제공합니다.

market-data : 영구 선물 시장에서 인기 있는 암호화폐에 대한 시장 데이터
account-info : 영구선물의 잔액 및 포지션을 포함한 계좌 정보
spot-market-data : 현물 시장에서 인기 있는 암호화폐에 대한 시장 데이터
spot-account-info : 현물 거래 잔액을 포함한 계좌 정보
open-orders : 사용자의 모든 미결 주문
positions : 사용자를 위한 모든 오픈 포지션
funding-rates : 모든 암호화폐의 현재 자금 조달 금리

보안 고려 사항

개인 키 보안 : 이더리움 개인 키는 자금에 대한 완전한 접근 권한을 제공합니다. 공개 저장소에 공유하거나 노출하지 마세요.
먼저 테스트넷을 사용하세요 : 메인넷에서 실제 자금을 사용하기 전에 항상 테스트넷에서 설정을 테스트하세요.
액세스 제한 : 신뢰할 수 있는 AI 도우미 및 애플리케이션으로 MCP 서버에 대한 액세스를 제한합니다.

부인 성명

암호화폐 거래에는 상당한 위험이 따릅니다. 본 도구는 교육 및 정보 제공 목적으로만 제공됩니다. 거래 전에 항상 관련 위험을 숙지하고, 손실을 감당할 수 없는 자금으로 거래하지 마십시오.

Hyperliquid MCP Server