HTX 자동매매 봇 제작

HTX(구 Huobi)는 2023년 리브랜딩한 글로벌 메이저 거래소로, 아시아 시장에서 강력한 입지를 가지고 있습니다. 현물·USDT 선물·Coin 마진 선물·옵션을 모두 지원하며 REST + WebSocket 구조로 알고랩 표준 봇 제작이 가능합니다.

HTX (구 Huobi) 자동매매 주요 유형

• USDT 무기한 선물 트렌드 추종 — BTC·ETH 추세 매매
• 현물 그리드 봇 — 횡보 코인 일정 간격 매매
• 코인 마진 선물 운영 — USDT 대신 코인으로 증거금
• 현물·선물 헤지 — 현물 보유 + 선물 숏
• 거래소 간 차익거래 — HTX ↔ 바이낸스·바이비트
• 트레이딩뷰 웹훅 연동 — Pine Script → HTX 실거래

기술 구조

핵심 기능 구성 요소

• WebSocket gzip 자동 해제: 메시지 자동 압축 처리
• Spot·Futures API 어댑터 분리: 통합 인터페이스로 묶기
• 다중 상품 라우팅: 심볼에 따라 자동 분기
• 타임스탬프 동기화: 서버 시간 자동 보정
• 리스크 관리: 포지션·일일 한도, 청산 거리 모니터링
• 알림: 텔레그램 진입·청산·청산위험 즉시 알림

HTX (Huobi) API는 실제로 어떻게 호출하나

표만 봐서는 감이 안 오실 수 있어, 실제로 첫 인증까지 무엇을 하는지 그대로 적습니다. HTX API에서 가장 먼저 확인해야 할 것은 내가 쓸 상품군의 도메인입니다.

현물 코드를 그대로 복사해 선물에 쓰면 동작하지 않습니다. 도메인이 다르고, 공식 문서(huobiapi.github.io)도 Spot과 Futures가 분리돼 있으며, 호출 한도(Rate Limit)도 상품군별로 따로 계산됩니다. 통합 봇을 만들 때 어댑터를 상품별로 나누는 이유가 이것입니다.

인증 — 요청마다 붙는 4개 파라미터

HTX는 요청할 때마다 아래 네 개를 쿼리에 넣고, 이 값들로 만든 서명을 Signature로 함께 보냅니다.

AccessKeyId      = 발급받은 Access Key
SignatureMethod  = HmacSHA256          (문자열 고정)
SignatureVersion = 2                   (문자열 고정)
Timestamp        = 2026-08-03T03:14:05  ← UTC, 초 단위 문자열

계좌 조회 성공 응답 — account-id가 있어야 주문이 나간다

서명이 통과하면 현물 계좌 목록이 이렇게 돌아옵니다. 여기서 받은 id가 주문 요청의 account-id가 되므로, 첫 주문 전에 반드시 한 번 호출해 두어야 합니다.

{
  "status": "ok",
  "data": [
    { "id": 1234567, "type": "spot",   "subtype": "",        "state": "working" },
    { "id": 1234568, "type": "margin", "subtype": "btcusdt", "state": "working" }
  ]
}

실패하면 이렇게 옵니다

{
  "status": "error",
  "err-code": "api-signature-not-valid",
  "err-msg": "Signature not valid: Verification failure [_]",
  "data": null
}

api-signature-not-valid는 서명 대상 문자열이 서버 계산값과 다르다는 뜻 하나입니다. 원인은 ① Timestamp를 밀리초로 넣음 ② 파라미터를 ASCII 정렬하지 않음 ③ URL 인코딩을 서명 전후로 다르게 적용 ④ 서버·로컬 시간 차이 ⑤ HMAC 결과를 Base64가 아닌 hex로 인코딩 다섯 가지에 거의 다 들어갑니다. 파이썬 서명 구현 전체와 오류별 해결은 HTX(후오비) API 서명 오류 5가지 — 첫 주문까지에 코드로 정리해 두었습니다.

WebSocket — gzip 해제와 ping/pong

HTX의 WebSocket은 메시지를 gzip으로 압축해 보냅니다. 바이너리 프레임을 받아 압축을 풀고 JSON으로 파싱해야 하며, 서버가 보내는 ping에 pong으로 답하지 않으면 연결이 끊깁니다.

import gzip, json

def on_message(ws, message):
    data = json.loads(gzip.decompress(message).decode("utf-8"))
    if "ping" in data:                       # 응답하지 않으면 연결이 끊긴다
        ws.send(json.dumps({"pong": data["ping"]}))
        return
    handle(data)

2026-09-02 업데이트 — USDT 마진 선물(linear-swap)에서 실제로 걸리는 것

위 표는 도메인이 갈린다는 것까지만 말해 줍니다. 실제로 선물 봇을 붙이면 그 뒤에 네 가지가 더 기다립니다. 아래는 2026-09-02 기준으로 api.hbdm.com의 계약 정보 엔드포인트를 직접 호출해 받은 실제 응답과 HTX 공식 USDT 마진 계약 문서(huobiapi.github.io/docs/usdt_swap/v1/en/)를 대조한 것입니다.

GET https://api.hbdm.com/linear-swap-api/v1/swap_contract_info?contract_code=BTC-USDT

{
  "status": "ok",
  "data": [{
    "symbol": "BTC",
    "contract_code": "BTC-USDT",
    "contract_size": 0.001,        ← 1장 = 0.001 BTC
    "price_tick": 0.1,             ← 호가 단위
    "contract_status": 1,
    "support_margin_mode": "all",
    "business_type": "swap",
    "contract_type": "swap",
    "pair": "BTC-USDT",
    "trade_partition": "USDT"
  }]
}

② contract_code 표기 체계가 상품마다 다릅니다. 공식 문서 기준으로 무기한 스왑은 BTC-USDT이고, 만기가 있는 인도 계약은 접미사가 붙습니다.

스왑용으로 짠 심볼 조립 로직에 인도 계약 코드를 넣으면 조회는 성공했는데 엉뚱한 만기의 계약에 주문이 나갑니다. 응답의 business_type·contract_type·pair를 함께 저장해 두고 주문 직전에 검증하는 편이 안전합니다.

④ v1과 v3가 공존하고, 계정 유형이 먼저입니다. USDT 마진 계약 API의 경로는 한 갈래가 아닙니다. 주문·계좌는 /linear-swap-api/v1, 계정 유형처럼 나중에 생긴 기능은 /linear-swap-api/v3, 시세는 /linear-swap-ex, 배치 시세는 /v2/linear-swap-ex, 지수·베이시스는 /index/market으로 갈립니다.

그래서 실무 순서는 “계정 유형 조회 → 계약 정보 조회 → 그다음 주문”입니다. 계정 유형을 확인하지 않고 v1 계좌 조회부터 때리면, 통합 계정으로 전환된 사용자에게서 기대와 다른 값이 나와도 원인을 못 찾습니다.

거래소를 아직 확정하지 못했다면 코인 자동매매 프로그램 제작 — 업비트 vs 바이낸스 7기준에서 원화 경로·키 발급·요청 제한 기준으로 먼저 갈라 보시는 편이 빠릅니다.

제작 비용·기간 가이드

자주 묻는 질문

HTX(후오비) API의 도메인은 무엇인가요?

상품군에 따라 다릅니다. 현물은 api.huobi.pro, 선물·스왑은 api.hbdm.com이며 USDT 마진 계약은 /linear-swap-api 경로를 씁니다. 코인 마진 스왑은 또 별도 문서·경로입니다. 도메인·경로는 변경될 수 있으니 공식 문서 확인이 필요합니다.

HTX API 인증은 어떻게 하나요?

API Key·Secret으로 HMAC-SHA256 서명을 만들어 붙입니다. 요청마다 AccessKeyId·SignatureMethod·SignatureVersion·Timestamp 네 개가 필요하고, Timestamp는 밀리초가 아니라 UTC 날짜·시간 문자열입니다. 서명 결과는 Base64로 인코딩합니다.

api-signature-not-valid 오류는 왜 나나요?

서명 대상 문자열이 서버 계산값과 다르기 때문입니다. Timestamp 형식, 파라미터 ASCII 정렬, URL 인코딩 시점, 서버 시간 차이, Base64 대신 hex 인코딩 — 이 다섯 가지가 원인의 대부분입니다.

HTX와 Huobi가 같은 거래소인가요?

네, 2023년 10월 Huobi가 HTX로 리브랜딩했습니다. 도메인·API 엔드포인트 일부가 변경되었지만 기존 Huobi API 코드는 대부분 호환됩니다.

바이낸스·바이비트 대비 HTX의 강점은?

아시아 시장 유동성이 풍부하고 일부 알트코인 가격이 다른 거래소와 미세하게 차이 나서 차익거래 기회가 있습니다. 코인 마진 선물 상품 다양성도 강점.

WebSocket gzip 처리가 까다로운가요?

Python 표준 라이브러리로 처리 가능합니다. 알고랩 봇은 자동 해제 + 누락 메시지 재전송 요청까지 표준 포함.

HTX 선물 주문 수량은 코인 개수인가요?

아닙니다. USDT 마진 계약의 volume은 장(계약) 수입니다. swap_contract_info 응답의 contract_size가 1장에 해당하는 코인 수량이며, 2026-09-02 조회 기준 BTC-USDT는 0.001입니다. 즉 0.5 BTC 상당이면 volume은 500입니다. 값은 종목마다 다르고 변경될 수 있으니 하드코딩하지 말고 봇 시작 시 조회해 캐싱하십시오.

한국 사용자도 이용 가능한가요?

현재까지 가능. 가입·KYC는 의뢰자가 직접 진행하며 알고랩은 API 연동만 담당.

제작 사례

HTX (구 Huobi) 자동매매 제작 사례는 포트폴리오에서 확인하실 수 있습니다.