이 페이지는 자동 번역되었습니다. 영어 원문이 정본입니다. 영어로 읽기 →
메인 콘텐츠로 건너뛰기

WebSocket API

Hypercall 옵션 거래를 위한 실시간 데이터 스트리밍입니다.

인터랙티브 레퍼런스

실시간 예제와 스키마 세부 정보를 더 편리하게 살펴보려면 인터랙티브 WebSocket API 레퍼런스를 확인하십시오.

기계 판독용 명세

프로그래밍 방식으로 사용하려면 AsyncAPI 명세를 다운로드하십시오.

추가 방식의 스키마 변경

WebSocket 메시지 객체에는 사전 공지 없이 새 필드가 추가될 수 있습니다. 클라이언트는 인식하지 못하는 필드를 무시해야 합니다. Hypercall은 기존 메시지 스키마에서 필드를 제거하지 않습니다.

연결​

wss://HOST/ws에 연결합니다.

엔드포인트:

  • 프로덕션: wss://api.hypercall.xyz/ws
  • 로컬: ws://localhost:3000/ws
테스트넷 상태

Hypercall이 테스트넷 HYPE를 추가로 확보할 때까지 테스트넷은 일시적으로 비활성화되어 있습니다.

압축​

/ws는 RFC 7692 permessage-deflate를 지원합니다. 클라이언트에서 이를 활성화하면 시장 데이터 대역폭을 줄일 수 있습니다. 실제 프로덕션 트래픽을 수집해 측정한 결과, 개별적으로 압축된 프레임은 약 45%, 인덱스 가격 배치는 약 70% 작아졌습니다.

  • 클라이언트는 업그레이드 요청에서 확장을 제안합니다. 예: Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits.
  • 서버가 이를 수락하면 101 응답에 Sec-WebSocket-Extensions: permessage-deflate; server_no_context_takeover가 포함됩니다. 이후 서버의 각 메시지는 공유 슬라이딩 윈도우 없이 개별적으로 압축되며, 수백 바이트 미만의 메시지는 여전히 압축되지 않은 상태로 전송됩니다. 압축 해제는 라이브러리가 투명하게 처리합니다.
  • 응답에 Sec-WebSocket-Extensions 헤더가 없으면 모든 프레임이 압축되지 않습니다. 압축은 환경별로 활성화되므로 클라이언트는 두 경우를 모두 처리해야 하며, JSON 메시지는 어느 쪽이든 동일합니다. 프로덕션은 아직 이 확장을 수락하지 않으므로 현재 프로덕션 프레임은 압축되지 않습니다.
  • 클라이언트는 전송하는 메시지를 압축할 수 있습니다. 서버는 각 클라이언트 메시지를 최대 256 KiB까지 압축 해제하며, 이를 초과하는 메시지가 있으면 연결을 종료합니다.

브라우저는 확장을 자동으로 협상합니다. 대부분의 라이브러리는 변경이 필요하지 않습니다.

Python (websockets는 기본적으로 압축을 활성화합니다):

import websockets

async with websockets.connect("wss://api.hypercall.xyz/ws", compression="deflate") as ws:
    ...

Node.js (ws):

import WebSocket from "ws";

const ws = new WebSocket("wss://api.hypercall.xyz/ws", { perMessageDeflate: true });

Rust: hypercall-client의 WsClient는 기본적으로 permessage-deflate를 협상합니다(예제: Rust 클라이언트 참조). 일반 tungstenite와 tokio-tungstenite는 아직 이를 구현하지 않으므로 압축 없이 연결됩니다. 직접 구현한 소켓에서 압축을 사용하려면 yawc처럼 이를 구현한 클라이언트를 사용하십시오.

let url = "wss://api.hypercall.xyz/ws".parse()?;
let mut ws = yawc::WebSocket::connect(url)
    .with_options(yawc::Options::default().with_low_latency_compression())
    .await?;

지갑 식별​

인증 채널(주문, 체결, 포트폴리오)의 데이터를 수신하려면 연결 후 Authenticate 메시지를 보내 지갑을 식별해야 합니다.

{"type": "Authenticate", "wallet": "0x1234..."}

서버는 확인 메시지로 응답합니다.

{"type": "Authenticated", "wallet": "0x1234..."}

Authenticated를 수신한 후 인증 채널을 구독할 수 있습니다. 지갑 주소가 유효하지 않으면 서버는 Error 메시지로 응답하며 연결은 유지됩니다.

지원 중단: 쿼리 파라미터 인증

?wallet= 쿼리 파라미터는 하위 호환성을 위해 아직 지원되지만 지원 중단되었으며 향후 릴리스에서 제거될 예정입니다. 위의 메시지 기반 방식을 사용하십시오.

연결 활성 상태 확인​

서버는 WebSocket 하트비트를 강제합니다.

  • 20초마다 Ping 제어 프레임을 전송합니다
  • 60초 이내에 대응하는 Pong을 기대합니다
  • 클라이언트가 응답을 멈추면 종료 코드 1008, 사유 pong timeout으로 연결을 종료합니다

브라우저의 WebSocket 구현은 ping/pong을 자동으로 처리합니다. tungstenite와 tokio-tungstenite를 비롯한 많은 Rust WebSocket 라이브러리도 제어 프레임 ping/pong을 대신 처리합니다. 수동 Pong 처리를 추가하기 전에 클라이언트 라이브러리 문서를 확인하십시오. 커스텀 또는 원시 소켓 구현은 Ping 프레임에 Pong으로 응답해야 합니다.

느린 소비자 복구​

서버는 설정된 메시지 수, 인코딩된 바이트 수, 큐 대기 시간 또는 소켓 쓰기 안전 한도 내에서 아웃바운드 데이터를 비우지 못하는 /ws 연결을 종료합니다. 연결이 아직 종료 프레임을 받을 수 있는 경우, 서버는 코드 1008과 간결한 JSON 사유를 사용합니다.

{"error":"slow_consumer","class":"ordered_public","cause":"message_age","recovery":"snapshot_resubscribe"}

사유 필드는 다음과 같습니다.

필드의미
class안전 한도를 넘은 프레임의 전달 클래스입니다.
causemessage_limit, byte_limit, message_age 또는 write_timeout입니다.
recovery필요한 다음 조치입니다. 예: resubscribe, snapshot_resubscribe, portfolio_refetch, rest_reconcile.

연결이 끊긴 후에는 재연결하고, 필요한 경우 지갑을 다시 식별하고, 재구독한 뒤 새 이벤트를 처리하기 전에 현재 상태를 대사(reconcile)하십시오. 순서가 보장되는 공개 채널은 새 스냅샷이 필요합니다. 비공개 이벤트 채널은 아직 커서 재생을 지원하지 않으므로 권위 있는 REST 엔드포인트를 통한 대사가 필요합니다. 완전히 멈춘 연결은 종료 사유를 읽기 전에 끊어질 수 있으므로, 비정상 종료 시에도 클라이언트는 이 복구 절차를 따라야 합니다.

고빈도 공개 시장 데이터와 인증된 명령 또는 비공개 스트림에는 별도의 연결을 사용하십시오. 전달 클래스는 메트릭과 복구 동작을 결정하지만, 하나의 연결에 속한 프레임은 여전히 하나의 순차적 소켓 쓰기 경로를 공유합니다. 따라서 공개 데이터 쓰기가 멈추면 같은 연결의 이후 비공개 프레임도 쓰기 기한이 지나 연결이 종료될 때까지 지연될 수 있습니다.

채널 구독​

구독하려면 JSON 메시지를 전송합니다.

{"type": "Subscribe", "channel": "orderbook"}

구독을 해지하려면 다음과 같이 합니다.

{"type": "Unsubscribe", "channel": "orderbook"}

확인 메시지를 받게 됩니다.

{"type": "Subscribed", "channel": "orderbook"}

심볼 필터링​

order_updates 및 fills 채널은 선택적 symbols 필터를 지원합니다. 필터를 지정하면 서버는 기초자산이 지정된 심볼 중 하나와 일치하는 메시지만 전송합니다.

{"type": "Subscribe", "channel": "order_updates", "symbols": ["BTC"]}

기초자산 이름("BTC")과 전체 상품명("BTC-20260131-100000-C") 모두 사용할 수 있습니다. 심볼을 추가하려면 Subscribe를 다시 보내십시오. 특정 심볼을 제거하려면 다음과 같이 합니다.

{"type": "Unsubscribe", "channel": "order_updates", "symbols": ["BTC"]}

symbols를 지정하지 않으면 해당 지갑의 모든 업데이트가 전달됩니다.

공개 채널인 orderbook, trades, indicative_market_data, indicative_market_data_v2도 symbols를 지원하며, 기초자산이 아니라 정확한 상품 심볼(대소문자 구분 없음)과 일치시킵니다.

{"type": "Subscribe", "channel": "orderbook", "symbols": ["BTC-20260131-100000-C"]}

symbols가 없으면 이 채널들은 모든 상품을 전달합니다.

옵션 체인 필터링​

options_chain 채널은 상품 심볼, 만기일, 옵션 유형으로 필터링할 수 있습니다.

{
  "type": "Subscribe",
  "channel": "options_chain",
  "symbols": ["BTC-20260131-100000-C"],
  "expiry": "2026-01-31",
  "option_type": "call"
}
필터값기본값
symbols전체 상품 심볼 배열 (예: ["BTC-20260131-100000-C"])모든 상품
expiry날짜 문자열 "YYYY-MM-DD", 각 상품 만기의 UTC 달력 날짜와 비교모든 만기
option_type"call", "put", "both", 또는 생략 시 둘 다둘 다

배치 전달​

indicative_market_data_v2는 indicative_market_data와 같은 행을 프레임당 여러 개씩 담아 전달합니다.

{"type": "Subscribe", "channel": "indicative_market_data_v2", "symbols": ["BTC-20260131-100000-C"]}

서버는 배치 표시와 함께 확인 메시지를 보냅니다.

{"type": "Subscribed", "channel": "indicative_market_data_v2", "batch": true}

이후 서버는 각 행을 최대 하나의 배치 윈도우(기본 25 ms) 동안 보관하고, 해당 윈도우에 게시된 행을 하나의 IndicativeMarketDataBatch 프레임으로 전송합니다. 배치가 256개 행에 도달하면 윈도우가 끝나기 전에 전송됩니다.

  • 지원 여부 확인: "batch": true가 포함된 확인 메시지만이 서버가 배치를 지원한다는 의미입니다. 이 채널이 도입되기 전에 릴리스된 서버는 모든 채널 이름을 표시 없이 확인한 뒤 아무것도 보내지 않으며, 현재 서버는 알 수 없는 채널에 unknown_channel 오류로 응답합니다. 두 경우 모두 indicative_market_data_v2 구독을 해지하고 같은 연결에서 indicative_market_data를 구독하십시오.
  • 지연 시간: 행은 indicative_market_data보다 최대 한 윈도우만큼 늦게 도착합니다. 기본 윈도우로 프로덕션 트래픽을 측정한 결과, 행의 대기 시간은 평균 12 ms였고 25 ms를 넘은 적이 없었습니다. 개별 호가 업데이트에 밀리초 단위로 대응해야 한다면 v1 채널을 사용하십시오.
  • 대역폭: 배치만으로는 약 7%의 바이트가 절약됩니다. 큰 절감 효과는 permessage-deflate와 함께 사용할 때 나타납니다. 압축된 배치는 필터 없는 구독에서 압축되지 않은 단일 행 프레임보다 약 9.8배, 단일 옵션 체인에서는 약 8.3배 작으며, 행을 하나씩 압축할 때는 약 1.8배에 그칩니다.
  • 순서: updates의 행은 게시 순서대로 정렬되며, 배치도 순서대로 도착합니다. 행은 병합되지 않으므로 한 상품이 하나의 배치에 여러 번 나타날 수 있습니다. 행을 순서대로 적용하면 v1 채널과 동일한 상태에 도달합니다.
  • 스냅샷: 구독 시점의 스냅샷도 배치 프레임으로 도착합니다.
  • 필터: symbols는 indicative_market_data와 동일하게 동작합니다. 필터를 좁히거나 구독을 해지하면 먼저 이전 필터 기준으로 대기 중이던 행을 전송한 후 Unsubscribed 확인을 보내므로, 행이 유실되거나 중복되지 않습니다.
  • 독립 채널: 하나의 연결에서 두 채널을 서로 다른 필터로 구독할 수 있습니다. indicative_market_data는 변경되지 않습니다.

사용 가능한 채널​

채널인증 필요설명
orderbook아니요모든 심볼의 L2 호가창 업데이트
trades아니요공개 체결 피드
market_updates아니요마켓 상장 변경 (생성/삭제/만기)
options_chain아니요증분 옵션 체인 업데이트 (symbols, expiry, option_type으로 필터링 가능)
index_prices아니요모든 기초자산의 실시간 현물/인덱스 가격
indicative_market_data아니요허용 목록에 등록된 호가 제공자 스트림. 아직 일반 공개되지 않음
indicative_market_data_v2아니요동일한 스트림의 배치 프레임 버전. 배치 전달 참조
order_updates예내 주문 상태 변경 (심볼로 필터링 가능)
fills예내 체결 내역 (심볼로 필터링 가능)
portfolio예내 포지션 및 잔고 업데이트
liquidation예내 청산 상태 변경
rfq예RFQ 호가, 상태 업데이트, 체결 알림
experimental_order_updates, experimental_combo_fills예실험적 콤보 채널. 실험적 콤보 API 참조
experimental_combo_trades아니요실험적 공개 콤보 체결

대회 및 리더보드 데이터는 WebSocket과 REST 모두 api.hypercall.xyz에서 제공되지 않습니다. 폐지된 competition 또는 competition_engagement 채널을 구독하면 Error가 반환됩니다. 트레이딩 앱은 https://api-ui.hypercall.xyz의 분석 서비스에서 HTTP로 대회 정보를 읽습니다. 예: GET /v2/competitions, GET /v2/competitions/{id}, GET /v2/competitions/leaderboard, GET /v2/competitions/all-time/leaderboard.

메시지 유형​

주문 접수 (인증 필요)​

WebSocket 명령 경로를 통해 주문을 접수합니다.

{
  "type": "PlaceOrder",
  "wallet": "0x1234...",
  "symbol": "BTC-20260131-100000-C",
  "side": "Buy",
  "size": "1",
  "price": "100",
  "tif": "gtc",
  "route": "book_only",
  "client_id": "my-order-1",
  "nonce": 1780000000000,
  "signature": "0x..."
}

위의 nonce는 예시입니다. 주문마다 현재 Unix 시간(밀리초)으로 새 값을 생성하십시오. 예를 들어 JavaScript에서는 Date.now()를 사용합니다. 고정된 값을 복사해 사용하면 허용 범위를 벗어나 거부됩니다.

필드타입설명
walletstring주문을 소유한 지갑 주소
symbolstring옵션 심볼
sidestring"Buy" 또는 "Sell"
sizestring계약 수량. 서명된 값과 정확히 일치해야 함
pricestring지정가. 서명된 값과 정확히 일치해야 함
tifstring선택 사항인 주문 유효 기간(time-in-force). 기본값은 "gtc"
routestring"book_only"를 사용하십시오. route를 생략해도 아직 허용되지만 지원 중단되었으며 종료 예정일이 이미 지났습니다.
client_idstring선택 사항인 클라이언트 주문 ID
reduce_onlyboolean선택 사항, 기본값 false. reduce-only 주문은 PlaceOrderReduceOnly로 서명하며 명시적인 route가 필요함
mmp_enabledboolean선택 사항, 기본값 false
builder_code_addressstring선택 사항인 빌더 코드 지갑
nonceinteger필수 서명 nonce. 현재 Unix 시간(밀리초)입니다. 현재 시각 기준 2일 전부터 1일 후 사이여야 합니다. 각 nonce는 서명자당 한 번만 허용되며, REST와 WebSocket 주문은 같은 nonce 공간을 공유합니다. 재전송된 프레임은 거부됩니다.
signaturestringEIP-712 PlaceOrder 서명

연결에서 먼저 Authenticate를 보내야 합니다. 그렇지 않으면 서버는 {"type": "Error", "message": "Not authenticated"}로 응답합니다. 서명자는 wallet 본인이거나 해당 지갑의 승인된 에이전트여야 합니다.

WebSocket PlaceOrder는 현재 주문을 호가창으로 직접 전달합니다. 이 경로는 아직 RPI/RFQ 라우팅을 수행하지 않으므로 WebSocket에서는 route="best_execution"과 route="rfq_only"가 거부됩니다. best_execution에는 POST /order를 사용하십시오.

접수된 주문에 대해서는 같은 연결로 OrderResult 응답이 전송됩니다.

{
  "type": "OrderResult",
  "order_id": 12345,
  "status": "ACKED",
  "symbol": "BTC-20260131-100000-C",
  "side": "Buy",
  "price": "100",
  "size": "1"
}

주문이 수락되지 않으면 reason이 추가됩니다. 유효성 검사, 서명, 요청 한도 관련 실패는 message가 Order placement failed:로 시작하는 Error로 전송됩니다. 이후의 상태 변경은 order_updates로 도착합니다.

호가창 업데이트​

심볼별 L2 호가창 스냅샷/업데이트입니다.

{
  "type": "OrderbookUpdate",
  "symbol": "BTC-20260131-100000-C",
  "option_token_address": "0x...",
  "bids": [["95000.5", "10.5"], ["94999.0", "25.0"]],
  "asks": [["95001.0", "8.0"], ["95002.5", "15.0"]],
  "timestamp": 1737331200000
}
필드타입설명
symbolstring옵션 심볼
option_token_addressstring?알려진 경우 온체인 옵션 토큰 주소
bidsarray[price, size] 튜플 형식의 매수호가 단계. 수량은 사람이 읽을 수 있는 계약 단위
asksarray[price, size] 튜플 형식의 매도호가 단계. 수량은 사람이 읽을 수 있는 계약 단위
timestampintegerUnix 타임스탬프 (밀리초)

체결​

공개 체결 이벤트입니다.

{
  "type": "Trade",
  "symbol": "BTC-20260131-100000-C",
  "price": "0.0523",
  "size": "5.0",
  "side": "Buy",
  "timestamp": 1737331200000
}
필드타입설명
symbolstring옵션 심볼
pricestringUSD 기준 체결 가격
sizestring계약 단위 체결 수량
sidestring공격자(aggressor) 방향 (Buy 또는 Sell)
timestampintegerUnix 타임스탬프 (밀리초)

내 체결 (인증 필요)​

내 체결 알림입니다.

{
  "type": "Fill",
  "order_id": 12345,
  "fill_id": 67890,
  "symbol": "BTC-20260131-100000-C",
  "side": "Buy",
  "price": "0.0523",
  "size": "5.0",
  "timestamp": 1737331200000,
  "wallet_address": "0x1234...abcd",
  "fee": "0",
  "trade_id": 99999,
  "is_taker": true,
  "builder_code_address": null,
  "builder_code_fee": null,
  "instrument_type": "option"
}
필드타입설명
order_idinteger내 주문 ID
fill_idinteger체결 ID
symbolstring옵션 심볼
sidestring거래에서 내 방향 (Buy 또는 Sell)
pricestringUSD 기준 체결 가격
sizestring계약 단위 체결 수량
timestampintegerUnix 타임스탬프 (밀리초)
wallet_addressstring내 지갑 주소
feestring부과된 거래 수수료. 출시 기간 거래소 수수료가 비활성화된 동안에는 0을 반환
trade_idinteger고유 거래 ID
is_takerboolean테이커였는지 여부
builder_code_addressstring?빌더 코드 지갑 (있는 경우)
builder_code_feestring?빌더 코드 수수료. 출시 기간 거래소 수수료가 비활성화된 동안에는 null을 반환
instrument_typestring"option"

포트폴리오 업데이트 (인증 필요)​

portfolio 채널로 포지션, 잔고, 증거금, 그릭스 정보가 전송됩니다. 구독 시 서버는 Initial 스냅샷을 보낸 후 증분 업데이트를 전송합니다.

각 프레임의 type은 업데이트 종류입니다.

업데이트 종류timestamp 외 필드
Initialpositions
PositionUpdateposition
BalanceUpdatetotal_margin_used
MarginUpdatespan_margin, margin_summary, margin_mode, total_margin_used, available_balance
GreeksUpdateper_leg, aggregate

portfolio 프레임의 timestamp는 다른 채널의 밀리초 타임스탬프와 달리 Unix 초 단위입니다.

그릭스 업데이트 예시:

{
  "type": "GreeksUpdate",
  "timestamp": 1737331200,
  "per_leg": [
    {
      "symbol": "BTC-20260131-100000-C",
      "quantity": "2.0",
      "delta": 0.91,
      "gamma": 0.003,
      "theta": -0.12,
      "vega": 0.44,
      "iv": 0.63
    }
  ],
  "aggregate": {
    "delta": 0.91,
    "gamma": 0.003,
    "theta": -0.12,
    "vega": 0.44,
    "iv": 0.63
  }
}

포트폴리오가 비어 있으면 그릭스 업데이트는 다음 값을 사용합니다.

  • per_leg: []
  • aggregate: null

주문 업데이트 (인증 필요)​

주문 상태 변경 알림입니다. PARTIALLY_FILLED 업데이트도 포함됩니다. filled_size는 최근 체결 한 건의 수량이 아니라 해당 주문의 모든 체결에 걸친 누적 체결 수량입니다.

{
  "type": "OrderUpdate",
  "order_id": 12345,
  "client_id": "my-order-1",
  "request": {
    "price": "0.0523",
    "size": "10.0",
    "symbol": "BTC-20260131-100000-C",
    "side": "Buy",
    "tif": "gtc"
  },
  "status": "PARTIALLY_FILLED",
  "filled_size": "0.75",
  "timestamp": 1767225600000,
  "reason": null,
  "wallet_address": "0x0000000000000000000000000000000000000001",
  "instrument_type": "option"
}

status는 ACKED, OPEN, PARTIALLY_FILLED, FILLED, CANCELED, REJECTED 중 하나입니다. 주문에 client_id가 없으면 해당 필드는 생략됩니다. instrument_type은 "option" 또는 "perp"입니다.

마켓 업데이트​

마켓 상장 변경입니다.

마켓 생성:

{
  "type": "MarketUpdate",
  "action": "Created",
  "symbol": "BTC-20260131-100000-C",
  "strike": "100000",
  "is_call": true,
  "underlying": "BTC",
  "expiry": 1738281600,
  "timestamp": 1737331200000
}

마켓 만기:

{
  "type": "MarketUpdate",
  "action": "Expired",
  "symbol": "BTC-20260131-100000-C",
  "strike": "100000",
  "is_call": true,
  "underlying": "BTC",
  "expiry": 1738281600,
  "timestamp": 1738281600000
}

action은 Created, Expired, Deleted(symbol과 timestamp만 포함), 또는 ComboCreated(실험적 콤보 API 참조)입니다.

옵션 체인 업데이트​

상장 정보나 최우선 호가가 변경되면 options_chain으로 전송됩니다. action은 Upsert 또는 Remove입니다.

{
  "type": "OptionsChainUpdate",
  "action": "Upsert",
  "currency": "BTC",
  "expiry": 1769846400,
  "row": {
    "strike": 100000.0,
    "call": {
      "symbol": "BTC-20260131-100000-C",
      "bid_price_usd": 1520.0,
      "ask_price_usd": 1580.0
    }
  },
  "timestamp": 1737331200000
}

Upsert 행은 옵션 체인 스냅샷의 레그 필드를 가진 하나의 레그(call 또는 put)를 포함합니다. 레그 필드는 symbol, option_token_address, 매수호가 및 매도호가 가격, IV, 계약 단위 수량과 USD 명목금액, greeks_abs, greeks_cash입니다(위 예시는 축약된 형태입니다). 사용할 수 없는 값은 null이며, 업데이트에 포함되지 않은 레그는 생략됩니다. 상품이 삭제되거나, 만기되거나, 결제 대기 상태에 들어가면 currency, expiry, strike, option_type, symbol, timestamp를 포함한 Remove가 전송됩니다. expiry는 Unix 초 단위입니다.

포지션 만기 (인증 필요)​

포지션이 만기 시 결제되면 portfolio 채널로 전송됩니다.

{
  "type": "PositionExpired",
  "wallet_address": "0x1234...abcd",
  "symbol": "BTC-20260131-100000-C",
  "position_size": "10.0",
  "settlement_price": "105000",
  "settlement_value": "500.0",
  "settlement_entry_price": "100.0",
  "cost_basis": "1000.0",
  "net_pnl": "-500.0",
  "timestamp": 1738281600000
}

settlement_entry_price, cost_basis, net_pnl은 사용할 수 없는 경우 null입니다.

청산 상태 변경 (인증 필요)​

계정의 청산 상태가 변경되면 liquidation 채널로 전송됩니다.

{
  "type": "LiquidationStateChange",
  "wallet_address": "0x1234...abcd",
  "previous_state": "healthy",
  "new_state": "pre_liquidation",
  "liquidation_mode": "partial",
  "margin_mode": "standard",
  "equity": "10000.0",
  "mm_required": "10500.0",
  "maintenance_margin": "-500.0",
  "shortfall": "500.0",
  "partial_liquidation": { "...": "..." },
  "full_liquidation": null,
  "timestamp": 1737331200000
}
필드설명
previous_state, new_statehealthy, pre_liquidation, in_liquidation, 또는 liquidated
liquidation_modepartial, full, 또는 진행 중인 청산 절차가 없으면 null
margin_modestandard 또는 portfolio
equity계정 자산
mm_required유지증거금 요건
maintenance_margin계정 자산에서 유지증거금 요건을 뺀 값
shortfall계정이 유지증거금에 미달하는 금액
partial_liquidation부분 청산 진행 상황(진입 시각, 목표 자산, 단계 상향 기한, 활성 청산 주문, 보너스), 또는 null
full_liquidation전체 청산 경매 세부 정보(경매 ID, 시작 시각, 필요 증거금, 완료 시 낙찰자, 보너스, 처리 트랜잭션), 또는 null

각 상태의 의미는 청산을 참조하십시오.

인덱스 가격 업데이트​

모든 기초자산의 현물/인덱스 가격을 배치로 전달합니다.

{
  "type": "IndexPriceUpdate",
  "prices": [
    {"underlying": "BTC", "price": "97250.50", "timestamp": 1737331200000},
    {"underlying": "ETH", "price": "3200.00", "timestamp": 1737331199980},
    {"underlying": "NVDA", "price": "182.40", "timestamp": 1737331199950}
  ],
  "timestamp": 1737331199950
}
필드타입설명
pricesarray추적 중인 각 기초자산에 대한 {underlying, price, timestamp} 항목 배열
prices[].underlyingstring기초자산 심볼 (예: "BTC", "ETH")
prices[].pricestringUSD 기준 현재 현물/인덱스 가격
prices[].timestampinteger해당 기초자산의 원천 관측 시각, Unix 밀리초
timestampintegerprices에 포함된 원천 관측 시각 중 가장 오래된 값, Unix 밀리초

지표성 시장 데이터​

등록된 호가 제공자들의 최우선 매수호가/매도호가를 집계한, 허용 목록 기반 호가 제공자 스트림입니다. 이 채널은 아직 일반 공개되지 않았습니다. Hypercall이 귀하의 연동에 호가 제공자 스트리밍을 활성화하지 않았다면 REST 시장 데이터와 인증된 주문/체결/포트폴리오 채널을 사용하십시오.

{
  "type": "IndicativeMarketData",
  "instrument": "BTC-20260131-100000-C",
  "best_bid": "0.0520",
  "best_ask": "0.0530",
  "indicative_bid_size": "50.0",
  "indicative_ask_size": "25.0",
  "num_providers": 3,
  "published_at": 1737331200004,
  "timestamp": 1737331200000
}
필드타입설명
instrumentstring옵션 심볼
best_bidstring선택 사항. 집계된 최우선 매수호가
best_askstring선택 사항. 집계된 최우선 매도호가
bid_ivnumber선택 사항. 최우선 매수호가의 내재변동성
ask_ivnumber선택 사항. 최우선 매도호가의 내재변동성
indicative_bid_sizestring선택 사항. 제공자 전체의 총 매수호가 수량
indicative_ask_sizestring선택 사항. 제공자 전체의 총 매도호가 수량
num_providersinteger활성 호가 제공자 수
rfq_provider_quotesarray선택 사항. 제공자별 호가: wallet, bid_price, ask_price, max_bid_size, max_ask_size, updated_at
published_atinteger이 행이 게시된 API 시계 기준 시각, Unix 밀리초. rfq_provider_quotes의 경과 시간은 로컬 시계가 아닌 이 값을 기준으로 측정하십시오
timestampinteger최신 제공자 호가의 시각, Unix 밀리초

지표성 시장 데이터 배치​

indicative_market_data_v2 채널로 전송됩니다(배치 전달 참조). updates의 각 요소는 type을 제외하고 IndicativeMarketData 메시지와 동일한 필드를 가집니다.

{
  "type": "IndicativeMarketDataBatch",
  "flushed_at": 1737331200025,
  "updates": [
    {
      "instrument": "BTC-20260131-100000-C",
      "best_bid": "0.0520",
      "best_ask": "0.0530",
      "num_providers": 3,
      "published_at": 1737331200004,
      "timestamp": 1737331200000
    },
    {
      "instrument": "BTC-20260131-105000-C",
      "best_bid": "0.0310",
      "best_ask": "0.0322",
      "num_providers": 2,
      "published_at": 1737331200004,
      "timestamp": 1737331200001
    }
  ]
}
필드타입설명
flushed_atinteger배치가 전송된 API 시계 기준 시각, Unix 밀리초. flushed_at - published_at은 행의 배치 지연 시간입니다
updatesarray윈도우 동안 게시된 행, 오래된 순

RFQ 호가 (인증 필요)​

제출한 RFQ에 대한 응답으로 수신된 호가입니다.

{
  "type": "RfqQuotes",
  "rfq_id": "550e8400-e29b-41d4-a716-446655440000",
  "quotes": [
    {
      "quote_id": "660e8400-e29b-41d4-a716-446655440001",
      "net_premium": "52.30",
      "expires_at": 1737331225000
    }
  ],
  "status": "quoted",
  "taker_wallet": "0x1234...abcd"
}

RFQ 상태 업데이트 (인증 필요)​

제출한 RFQ의 상태 변경입니다.

{
  "type": "RfqStatusUpdate",
  "rfq_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "executed",
  "taker_wallet": "0x1234...abcd"
}

시계 동기화​

임의의 nonce 문자열과 함께 ClockSync를 보내면 같은 연결에서 API 시계 샘플을 받을 수 있습니다. 예를 들어 전송 지연의 범위를 추정할 때 사용합니다.

{"type": "ClockSync", "nonce": "abc"}
{"type": "ClockSynced", "nonce": "abc", "server_at": 1737331200000}

server_at은 Unix 밀리초입니다. 인증은 필요하지 않습니다.

오류​

서버 오류 메시지입니다. code가 있으면 message가 아닌 code를 기준으로 판별하십시오.

{
  "type": "Error",
  "message": "Unknown channel 'foobar'",
  "code": "unknown_channel",
  "channel": "foobar"
}
필드타입설명
messagestring사람이 읽을 수 있는 설명
codestring선택 사항. 안정적인 사유 코드. unknown_channel: Subscribe가 존재하지 않는 채널을 지정함
channelstring선택 사항. 거부된 Subscribe가 지정한 채널

사용 가능한 채널에 없는 채널로 Subscribe를 보내면 unknown_channel 오류로 응답하며 구독은 생성되지 않습니다. 이전 서버는 모든 이름을 확인한 뒤 아무것도 보내지 않았습니다.

그 밖의 오류에는 message만 포함됩니다. 예: Authenticate 전에 인증 채널을 구독하면 Authentication required for this channel, Authenticate 전에 PlaceOrder를 보내면 Not authenticated, 그리고 Invalid wallet address: ....

인증​

인증 채널을 사용하려면 연결 후 지갑 식별 메시지를 보내야 합니다.

{"type": "Authenticate", "wallet": "0x1234567890abcdef..."}

인증 채널의 메시지는 해당 지갑의 데이터만 표시되도록 필터링됩니다. WebSocket 연결에는 서명이 필요하지 않습니다.

예제: Python 클라이언트​

import asyncio
import websockets
import json

async def main():
    uri = "wss://api.hypercall.xyz/ws"

    async with websockets.connect(uri) as ws:
        # Identify the wallet before subscribing to authenticated channels.
        await ws.send(json.dumps({
            "type": "Authenticate",
            "wallet": "0xYourWallet"
        }))

        # Subscribe to orderbook
        await ws.send(json.dumps({
            "type": "Subscribe",
            "channel": "orderbook"
        }))

        # Subscribe to fills for BTC only
        await ws.send(json.dumps({
            "type": "Subscribe",
            "channel": "fills",
            "symbols": ["BTC"]
        }))

        # Listen for messages
        async for message in ws:
            data = json.loads(message)
            print(f"Received: {data['type']}")

asyncio.run(main())

예제: TypeScript 클라이언트​

const ws = new WebSocket("wss://api.hypercall.xyz/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "Authenticate", wallet: "0xYourWallet" }));

  // Subscribe to channels
  ws.send(JSON.stringify({ type: "Subscribe", channel: "orderbook" }));

  // Subscribe to order updates filtered to BTC
  ws.send(JSON.stringify({
    type: "Subscribe",
    channel: "order_updates",
    symbols: ["BTC"],
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(`Received: ${msg.type}`);

  if (msg.type === "OrderbookUpdate") {
    console.log(`${msg.symbol}: ${msg.bids.length} bids, ${msg.asks.length} asks`);
  }
};

예제: Rust 클라이언트​

hypercall-client 크레이트의 WsClient는 지갑을 식별하고, 재연결 후 구독을 복원하며, 서버 ping에 자동으로 응답합니다. 기본적으로 permessage-deflate 압축을 제안하며, 서버가 이를 수락하지 않으면 압축되지 않은 프레임으로 대체합니다. JSON 메시지는 어느 쪽이든 동일합니다. 압축 제안을 중단하려면 with_permessage_deflate(false)를 호출하십시오.

use hypercall_client::WsClient;

#[tokio::main]
async fn main() -> hypercall_client::Result<()> {
    let ws = WsClient::new();
    ws.connect("https://api.hypercall.xyz", None).await?;
    ws.subscribe(vec!["orderbook", "index_prices"]).await?;

    if let Some(msg) = ws.wait_for_message(|_| true, 5_000).await {
        println!("Received: {msg:?}");
    }
    Ok(())
}
최종 업데이트: