Hyperliquid에서 100줄로 예측 시장 봇 구축하기

대부분의 예측 시장 튜토리얼은 "SDK 설치 후 주문 넣기"에서 멈춥니다. 그건 쉬운 부분입니다. 어려운 부분은 어떤 시장을 거래할지, 그리고 가격이 잘못됐을 때를 아는 것입니다. Hyperliquid의 HIP-4 결과 시장은 퍼프 및 스팟과 동일한 매칭 엔진 위에서 작동합니다. 즉, 코호트 포지셔닝 데이터를 이진 결과 거래 위에 얹어서 순수 예측 시장 트레이더들이 볼 수 없는 가격 오류를 잡아낼 수 있습니다.

이 가이드는 HIP-4 시장을 탐색하고, 오더북을 읽고, 기초 자산에서 Smart Money가 무엇을 하는지 확인하고, 신호가 일치할 때 거래를 실행하는 Python 봇을 구축하는 과정을 안내합니다. 전체 코드는 약 100줄로 작동합니다.

HIP-4 결과 시장의 실제 작동 방식

HIP-4는 2026년 5월 2일 Hyperliquid 메인넷에 출시되었습니다. 각 시장은 이진 질문을 제시합니다. BTC가 특정 만기일까지 목표 가격을 초과할까요? 트레이더는 USDC를 담보로 YES 또는 NO 포지션을 매수합니다. 만기 시, 승리한 쪽은 단위당 1 USDC로 정산되고 패배한 쪽은 0으로 정산됩니다.

어느 순간의 YES 토큰 가격은 해당 사건이 발생할 시장의 내재 확률을 나타냅니다. YES가 $0.65에 거래된다면, 시장은 해당 사건이 발생할 확률을 65%로 가격 책정하는 것입니다. 보완적인 NO 토큰은 $0.35 근처에서 거래되어야 합니다. 두 쪽이 통합된 오더북을 공유하며, 가격 p에서의 YES 매수는 1-p에서의 NO 매도를 반영하기 때문입니다.

HIP-4를 Polymarket과 다르게 만드는 세 가지가 있습니다. 첫째, 정산이 결정론적입니다. Hyperliquid의 밸리데이터 세트는 분쟁 기간이나 토큰 투표 없이 사전에 지정된 객관적 데이터 소스를 기준으로 각 계약을 해결합니다. 둘째, 레버리지가 없고 청산 위험이 없습니다. 포지션은 개시 시점에 완전히 담보됩니다. 셋째, 현재 포지션 개시 수수료는 없지만, 체결 시 빌더 코드는 여전히 적용됩니다.

반드시 제대로 이해해야 할 인코딩 시스템

HIP-4는 처음 접하는 모든 빌더를 당혹스럽게 만드는 세 가지 형식의 인코딩 시스템을 사용합니다. 각 결과에는 ID가 있으며, 각 측면(YES = 0, NO = 1)은 encoding = 10 * outcome_id + side 공식을 사용해 숫자 인코딩을 생성합니다.

하지만 사용하는 형식은 컨텍스트에 따라 달라집니다. 주문 실행과 오더북 쿼리에는 # 접두사를 붙이므로, 결과 2 YES는 #20이 됩니다. 잔액 조회에는 + 접두사를 사용하므로 동일한 포지션은 +20이 됩니다. 내부 SDK 자산 ID에는 인코딩에 100,000,000을 더합니다.

이 형식들은 서로 바꿔 쓸 수 없습니다. 잔액 조회에 #20을 사용하거나 주문에 +20을 사용하면 오류 메시지 없이 조용히 실패합니다. 다음은 헬퍼 함수들입니다:

def encode_coin(outcome_id: int, side: int) -> str:
    """Order placement and book queries."""
    return f"#{10 * outcome_id + side}"

def encode_balance_coin(outcome_id: int, side: int) -> str:
    """Balance lookups only."""
    return f"+{10 * outcome_id + side}"

def encode_asset_id(outcome_id: int, side: int) -> int:
    """SDK internal mapping."""
    return 100_000_000 + 10 * outcome_id + side

SDK 패치 필요: 공식 hyperliquid-python-sdk는 HIP-4를 기본으로 지원하지 않습니다. 이 SDK의 coin_to_asset 맵은 spot_meta만으로 구성되어 있어, 100,000,000부터 시작하는 결과 인코딩은 리졸버에게 알려지지 않습니다. outcomeMeta를 가져와서 매핑을 수동으로 주입해야 합니다. 아래 코드가 이를 처리합니다.

활성 시장 탐색

봇이 가장 먼저 해야 할 일은 어떤 시장이 존재하는지 찾는 것입니다. outcomeMeta 엔드포인트는 활성 및 정산된 모든 결과를 반환합니다. 여기에는 결과 ID, 파이프로 구분된 설명(클래스, 기초 자산, 만기일, 목표 가격), 그리고 측면 사양이 포함됩니다.

import httpx

BASE_URL = "https://api.hyperliquid.xyz"

def fetch_outcome_meta():
    r = httpx.post(
        f"{BASE_URL}/info",
        json={"type": "outcomeMeta"},
        timeout=10.0,
    )
    return r.json()

def parse_active_markets(meta):
    markets = []
    for o in meta.get("outcomes", []):
        desc = o.get("description", "")
        parts = desc.split("|")
        if len(parts) >= 4:
            markets.append({
                "outcome_id": o["outcome"],
                "underlying": parts[1].strip(),
                "expiry": parts[2].strip(),
                "target": parts[3].strip(),
            })
    return markets

이를 통해 플랫폼의 모든 결과 시장 목록을 얻을 수 있습니다. 만기일로 필터링해서 아직 정산되지 않은 시장에 집중하세요. 예를 들어, 매일 반복되는 BTC 시장은 매일 06:00 UTC에 BTC 마크 가격 기준으로 정산됩니다.

오더북과 내재 확률 읽기

각 결과 측면에는 고유한 오더북이 있습니다. #N 코인 형식을 사용해 스팟 오더북을 쿼리하는 것과 동일한 방식으로 쿼리합니다:

def fetch_book(coin: str):
    r = httpx.post(
        f"{BASE_URL}/info",
        json={"type": "l2Book", "coin": coin},
        timeout=10.0,
    )
    levels = r.json().get("levels", [[], []])
    bids = [(float(p), float(s)) for p, s in levels[0]]
    asks = [(float(p), float(s)) for p, s in levels[1]]
    return bids, asks

def get_mid_price(coin: str) -> float:
    bids, asks = fetch_book(coin)
    if bids and asks:
        return (bids[0][0] + asks[0][0]) / 2
    return 0.0

# Example: outcome 2
yes_mid = get_mid_price("#20")
no_mid = get_mid_price("#21")
print(f"YES: {yes_mid:.4f}, NO: {no_mid:.4f}, sum: {yes_mid + no_mid:.4f}")

공정한 시장에서 YES 중간값 + NO 중간값은 약 1.0이 되어야 합니다. 지속적인 편차는 수수료 효과이거나 조사할 가치가 있는 가격 오류입니다. 두 측면 사이의 스프레드가 첫 번째 신호입니다.

결과 가격 위에 코호트 신호 얹기

바로 여기서 예측 시장 봇이 흥미로워집니다. 순수한 예측 시장 트레이더는 오더북과 외부 뉴스 정도를 봅니다. 코호트 데이터에 접근할 수 있는 빌더는 다른 것을 볼 수 있습니다. Hyperliquid에서 가장 수익성 높은 지갑들이 기초 자산에서 실제로 무엇을 하고 있는지를요.

BTC 결과 시장이 만기일까지 BTC가 목표 가격을 초과할 확률을 55%로 가격 책정한다고 상상해보세요. 그게 시장의 최선의 추측입니다. 하지만 우리의 코호트 데이터는 Money Printer 지갑들(올타임 수익 $100만 이상)이 BTC 퍼프에서 크게 순매수인 반면, Giga-Rekt 지갑들(올타임 손실 $100만 이상)은 순매도임을 보여줍니다. 최고의 실적을 가진 트레이더들이 예측 시장의 내재 확률과 다른 방향을 보고 있을 때, 그 괴리는 행동할 가치가 있는 신호입니다.

import requests

HT_BASE = "https://ht-api.coinmarketman.com/api/external"
HT_TOKEN = "your_hypertracker_jwt"

def get_cohort_bias(coin: str = "BTC"):
    """Fetch Money Printer and Giga-Rekt positioning."""
    headers = {"Authorization": f"Bearer {HT_TOKEN}"}
    r = requests.get(
        f"{HT_BASE}/cohort/metrics",
        params={"coin": coin},
        headers=headers,
    )
    data = r.json()
    # Extract cohort-level long/short ratio
    money_printer = next(
        (c for c in data if c.get("cohortId") == 8), None
    )
    giga_rekt = next(
        (c for c in data if c.get("cohortId") == 15), None
    )
    return money_printer, giga_rekt

코호트 ID는 HyperTracker의 16개 세그먼트 분류 시스템에서 가져옵니다. 퍼프 자산 규모별 8개 세그먼트(Shrimp부터 Leviathan까지)와 올타임 PnL별 8개 세그먼트(Money Printer부터 Giga-Rekt까지)로 구성됩니다. Money Printer는 코호트 8이고 Giga-Rekt는 코호트 15입니다. Money Printer들이 한 방향으로 포지션을 쌓는 동안 결과 시장이 반대로 가격 책정되어 있을 때, 그것이 봇이 노리는 틈새입니다.

HIP-4 시장에서 주문 실행

주문 실행은 스팟 거래와 동일한 패턴을 따르되, HIP-4 특유의 제약이 몇 가지 있습니다. 수량은 정수여야 합니다(소수 단위 불가). 최소 명목 금액은 $10 USDC, 즉 size * price >= 10입니다. 가격 범위는 0.001에서 0.999입니다.

from hyperliquid.exchange import Exchange
from eth_account import Account

def place_outcome_order(exchange, outcome_id, side, is_buy, price, size):
    coin = encode_coin(outcome_id, side)
    result = exchange.order(
        coin,
        is_buy=is_buy,
        sz=size,
        limit_px=price,
        order_type={"limit": {"tif": "Gtc"}},
    )
    return result

# Example: buy 25 YES on outcome 2 at $0.45
# Cost: 25 * 0.45 = $11.25 (above $10 min)
# If YES wins: receive 25 * $1 = $25, profit = $13.75
result = place_outcome_order(exchange, 2, 0, True, 0.45, 25)

기억하세요: HIP-4 포지션은 완전히 담보됩니다. 레버리지도 없고 청산도 없습니다. 어떤 거래에서든 최대 손실은 정확히 개시 시점에 지불한 금액입니다. 이 때문에 예측 시장 봇은 퍼프 봇보다 논리적으로 훨씬 단순합니다. 마진 유지나 강제 청산을 걱정할 필요가 전혀 없으니까요.

모두 합치기: 완전한 봇

다음은 완전한 루프입니다. 봇은 활성 시장을 탐색하고, 오더북을 읽고, 기초 자산의 코호트 포지셔닝을 확인하고, 예측 시장의 내재 확률이 가장 수익성 높은 트레이더들의 실제 행동과 괴리될 때 거래를 실행합니다.

import time

def run_bot(exchange, info):
    """Main loop: discover, price, signal, execute."""
    meta = fetch_outcome_meta()
    markets = parse_active_markets(meta)

    for market in markets:
        oid = market["outcome_id"]
        underlying = market["underlying"]

        # Step 1: Get implied probability
        yes_mid = get_mid_price(encode_coin(oid, 0))
        no_mid = get_mid_price(encode_coin(oid, 1))
        if yes_mid == 0 or no_mid == 0:
            continue

        # Step 2: Get cohort positioning
        mp, gr = get_cohort_bias(underlying)
        if not mp or not gr:
            continue

        # Step 3: Simple divergence check
        # Thresholds below are illustrative -- calibrate via backtesting
        mp_long_pct = mp.get("longPct", 50)
        if mp_long_pct > 70 and yes_mid < 0.50:  # example values
            # Example sizing to meet $10 minimum notional
            size = max(10, int(10 / yes_mid) + 1)
            print(f"Signal: {underlying} MP {mp_long_pct}% long, "
                  f"YES at {yes_mid:.2f}. Buying YES.")
            place_outcome_order(exchange, oid, 0, True, yes_mid, size)

    time.sleep(300)  # 5-minute cycle

# Patch SDK and run
info, exchange = make_clients(PRIVATE_KEY, ADDRESS, BASE_URL)
while True:
    run_bot(exchange, info)

여기서의 괴리 임계값과 수량 결정 로직은 예시입니다. 실제 운영에서는 백테스팅과 본인의 리스크 허용 범위를 기반으로 이를 조정해야 합니다. 핵심은 아키텍처입니다. 예측 시장 가격 + 코호트 포지셔닝 = 독립적인 예측 시장 트레이더들이 접근할 수 없는 신호 레이어.

엣지 케이스와 주의사항

SDK 패치는 필수

공식 hyperliquid-python-sdk는 HIP-4 자산을 인식하지 못합니다. 시작 시점에 outcomeMeta를 가져와서 모든 결과의 인코딩을 SDK의 coin_to_asset 및 name_to_coin 맵에 주입해야 합니다. 이 패치 없이는 SDK가 알 수 없는 코인에 대한 불명확한 오류와 함께 주문을 거부합니다.

def make_clients(private_key, address, base_url):
    account = Account.from_key(private_key)
    info = Info(base_url, skip_ws=True)
    exchange = Exchange(account, base_url, account_address=address)

    meta = fetch_outcome_meta()
    for o in meta.get("outcomes", []):
        for side in (0, 1):
            coin = encode_coin(o["outcome"], side)
            asset_id = encode_asset_id(o["outcome"], side)
            info.coin_to_asset[coin] = asset_id
            info.name_to_coin[coin] = coin
            exchange.info.coin_to_asset[coin] = asset_id
            exchange.info.name_to_coin[coin] = coin

    return info, exchange

정수 수량만 허용

소수 단위 거래가 가능한 퍼프 포지션과 달리, HIP-4는 정수 단위를 요구합니다. 계산된 수량이 22.7이 나오면 23으로 올림하세요. 최소 명목 금액을 항상 확인하세요: size * price >= 10 USDC.

정산은 자동

상환 함수를 별도로 호출할 필요가 없습니다. 만기 시, 어느 쪽이 이겼는지에 따라 USDC가 자동으로 계정에 입금됩니다. 가스비도 없고 청구 트랜잭션도 없습니다.

빌더 코드도 여기서 작동

HIP-4 위에 프론트엔드를 구축하는 경우, 빌더 코드는 스팟 거래와 동일한 방식으로 매도 주문에서 수수료를 획득합니다. 즉, Hyperliquid 위에 구축된 모든 예측 시장 플랫폼은 사용자에게 직접 요금을 부과하지 않고도 빌더 코드를 통해 수익을 창출할 수 있습니다.

예측 시장 봇에 코호트 인텔리전스 추가하기

HyperTracker의 API는 일반적인 예측 시장 봇을 Smart Money 인식 시스템으로 바꿔주는 코호트 포지셔닝 데이터를 제공합니다. 16개의 행동 세그먼트, 5분마다 갱신, API 한 번 호출로 접근 가능합니다.

HyperTracker로 구축 시작하기

예측 시장 생태계는 아직 초기 단계입니다. HIP-4는 Hyperliquid의 퍼프 및 스팟 시장과 동일한 매칭 엔진, 계정 모델, API 인터페이스를 공유합니다. 즉, Hyperliquid 위에서 구축하는 것에 대해 이미 알고 있는 모든 것이 그대로 적용됩니다. 새로운 개념은 인코딩 방식, 정수 수량, 그리고 포지션이 청산될 수 없다는 사실뿐입니다. 이미 코호트 데이터를 활용하는 빌더에게 예측 시장은 신호를 얹을 수 있는 또 하나의 수단일 뿐입니다. 엣지는 예측 시장 자체에 있지 않습니다. Smart Money가 기초 자산에서 무엇을 하는지를 결과 시장이 가격에 반영하기 전에 아는 것에 있습니다.