API 트레이딩

마켓메이커, 호가 시스템 또는 체결 서비스를 Hypercall에 연동하는 경우 이 가이드를 사용하시기 바랍니다.

프로덕션 API

REST 기본 URL: https://api.hypercall.xyz

WebSocket URL: wss://api.hypercall.xyz/ws

테스트넷 상태: Hypercall이 추가 테스트넷 HYPE를 확보할 때까지 테스트넷은 일시적으로 비활성화되어 있습니다. 신규 마켓메이커 연동은 Hypercall이 전용 환경을 제공하지 않는 한 프로덕션을 사용해야 합니다.

허용 목록 기반 스트림

지시성 호가 제공자(quote-provider) 스트리밍은 아직 일반적으로 제공되지 않습니다. Hypercall은 승인된 연동에 한해 이를 활성화할 수 있지만, 일반적인 마켓메이커 온보딩은 REST 시장 데이터와 인증된 주문, 체결, 포트폴리오 WebSocket 채널을 사용해야 합니다.

온보딩 체크리스트

트레이딩 지갑: EIP-712 타입 데이터에 서명할 수 있는 EVM 지갑.
자금: app.hypercall.xyz에서 프로덕션 USDC 자금 입금.
접근 권한: 마켓메이커 한도, 매도자(writer) 접근 권한 또는 지시성 호가 제공자 스트리밍이 필요한 경우 Hypercall에 문의하시기 바랍니다.
환경: 위의 프로덕션 REST 및 WebSocket URL을 사용합니다. 테스트넷이 사용 가능하다고 가정하지 마십시오.
정합성 확인: 자체 클라이언트 주문 ID, 논스, 주문, 체결 및 포지션 스냅샷을 직접 보관하십시오.

연동 경로

Rust 크레이트

Hypercall은 지원되는 연동 인터페이스를 위한 공개 Rust 크레이트를 배포합니다:

공개 Rust 저장소는 github.com/hypercall-public/hypercall-rust입니다.

크레이트	용도
`hypercall-client`	REST 클라이언트, WebSocket 클라이언트, EIP-712 서명 헬퍼, 로컬 서명 및 AWS KMS 서명
`hypercall-sdk-types`	클라이언트가 공유하는 공개 요청 및 응답 DTO
`hypercall-ws-protocol`	공개 WebSocket 메시지 타입
`hypercall-hyperliquid`	Hyperliquid에서 헤지도 수행하는 연동을 위한 선택적 Hyperliquid 헬퍼 크레이트
`hypercall-liquidator`	표준 증거금(Standard Margin) 청산 레퍼런스 클라이언트. 일반적인 마켓메이킹에는 필요하지 않습니다

가능하면 크레이트를 사용하시기 바랍니다. 크레이트에는 수동으로 구현하면 실수하기 쉬운 현재 서명 도메인, 요청 형식, 라우트 규칙 및 문자열 포맷 규칙이 내장되어 있습니다.

순수 REST 및 WebSocket

Rust를 사용하지 않는 경우, API 레퍼런스, 인증 및 서명, WebSocket API 페이지를 기준 문서로 사용하시기 바랍니다.

1. 마켓 조회

먼저 활성 마켓과 상품 스펙을 로드합니다:

curl https://api.hypercall.xyz/markets
curl "https://api.hypercall.xyz/instrument-specs?currency=BTC"
curl "https://api.hypercall.xyz/options-summary?currency=BTC"

용도:

GET /markets: 상장된 기초자산 및 만기 그룹 조회.
GET /instrument-specs?currency=BTC: 거래 가능한 옵션 스펙 조회.
GET /options-summary?currency=BTC: 체인 수준의 최우선 매수호가, 최우선 매도호가, 마크 가격 및 그릭스(Greeks) 유형 요약 필드 조회.

2. 서명 설정

쓰기 작업에는 EIP-712 서명이 사용됩니다.

프로덕션 체인 ID: 999
도메인 이름: Hypercall
도메인 버전: 1
검증 컨트랙트: 0x0000000000000000000000000000000000000000

마켓메이커는 일반적으로 에이전트 지갑을 사용해야 합니다:

소유자 지갑이 POST /approve-agent로 에이전트를 승인합니다.
에이전트 지갑이 소유자 지갑을 대신해 주문과 취소에 서명합니다.
소유자 지갑은 포트폴리오, 자금 및 리스크 주체로 유지됩니다.

정확한 구조체와 필드 이름은 인증 및 서명을 참조하시기 바랍니다.

3. 대량 주문으로 호가 제시

마켓메이커 호가에는 route: "book_only"와 함께 POST /bulk_order를 사용합니다.

curl -X POST https://api.hypercall.xyz/bulk_order \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "wallet": "0x...",
        "symbol": "BTC-20260131-100000-C",
        "price": "100.0",
        "size": "0.1",
        "side": "Buy",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-bid-1",
        "mmp_enabled": true,
        "nonce": 1001,
        "signature": "0x..."
      },
      {
        "wallet": "0x...",
        "symbol": "BTC-20260131-100000-C",
        "price": "101.0",
        "size": "0.1",
        "side": "Sell",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-ask-1",
        "mmp_enabled": true,
        "nonce": 1002,
        "signature": "0x..."
      }
    ]
  }'

중요한 규칙:

price와 size는 문자열입니다 — 서명 페이로드와 JSON 본문 모두에서 마찬가지입니다.
문자열 포맷은 서명과 JSON 본문 간에 정확히 일치해야 합니다.
대량 주문 크기는 요청당 50개 주문으로 제한됩니다.
대량 라우트는 book-only 전용입니다. route: "best_execution"과 route: "rfq_only"는 단일 주문 경로이며, 대량 호가 경로가 아닙니다.
대부분의 거래 거절은 HTTP 200과 함께 status: "REJECTED"를 반환합니다. 항상 각 결과를 확인하시기 바랍니다.

4. 호가 갱신

기존 호가 주문을 취소하고 대체 주문을 하나의 요청으로 제출하려면 PUT /bulk_order를 사용합니다.

curl -X PUT https://api.hypercall.xyz/bulk_order \
  -H "Content-Type: application/json" \
  -d '{
    "replacements": [
      {
        "wallet": "0x...",
        "order_id": 12345,
        "symbol": "BTC-20260131-100000-C",
        "price": "99.5",
        "size": "0.1",
        "side": "Buy",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-bid-1",
        "nonce": 1003,
        "signature": "0x..."
      }
    ]
  }'

PUT /bulk_order는 새 배치를 생성하기 전에 기존 배치를 취소합니다. 결과는 요청 순서대로 각 대체 주문별로 반환됩니다. 취소가 실패하면 해당 대체 주문은 생성되지 않습니다.

지연시간에 민감한 단건 대체에는 PUT /order를 사용하시기 바랍니다.

5. 업데이트 구독

프로덕션 WebSocket에 연결합니다:

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

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

용도:

order_updates: 주문 상태 변경. 부분 체결 업데이트는 이 채널에서 의도적으로 제외됩니다.
fills: 부분 체결 및 체결된 거래의 기준 소스.
portfolio: 계정 상태 업데이트.
orderbook, trades, options_chain, index_prices: 공개 시장 데이터.

채널 형식과 라이브니스 동작은 WebSocket API를 참조하시기 바랍니다.

6. 상태 정합성 확인

WebSocket 연결이 정상이더라도 정합성 확인 루프를 실행하시기 바랍니다.

상태	REST 폴백	WebSocket 채널
주문	`GET /orders?wallet=...`	`order_updates`
체결	`GET /fills?wallet=...`	`fills`
포트폴리오	`GET /portfolio?wallet=...`	`portfolio`
마켓	`GET /markets`, `GET /instrument-specs`	`market_updates`, `options_chain`

권장 루프:

시작 시 마켓 로드.
호가 제시 전에 미체결 주문과 최근 체결 로드.
WebSocket 업데이트 구독.
결정적인(deterministic) 클라이언트 ID로 호가 제시.
주기적인 REST 폴링으로 연결 끊김이나 누락된 메시지를 복구.
알 수 없는 상태에서는 호가 중단 — REST와 WebSocket 상태가 다시 일치할 때까지.

7. 런칭 범위 이해

메인넷 알파는 의도적으로 제한되어 있습니다.

증거금: 표준 증거금(Standard Margin)이 운영 중입니다. 포트폴리오 증거금(Portfolio Margin)은 일반적으로 활성화되어 있지 않습니다.
매도자 접근 권한: 옵션 숏 익스포저에는 승인된 접근 권한이 필요합니다.
지시성 스트리밍: 호가 제공자 스트림은 허용 목록 기반이며 아직 일반 공개 연동 경로가 아닙니다.
청산 도구: 공개 리퀴데이터(liquidator) 크레이트는 표준 증거금 청산 워크플로우용이며, 일반적인 마켓메이킹용이 아닙니다.
테스트넷: Hypercall이 추가 테스트넷 HYPE를 확보할 때까지 사용할 수 없습니다.

자주 발생하는 문제

서명 검증 실패

price와 size가 JSON 문자열인지 확인하십시오.
서명된 문자열이 제출된 문자열과 정확히 일치하는지 확인하십시오.
프로덕션에서는 체인 ID 999를 사용하십시오.
서명된 각 쓰기 작업마다 새 논스를 사용하십시오.
서명자가 해당 지갑 또는 승인된 에이전트인지 확인하십시오.

증거금 부족

GET /portfolio?wallet=...를 확인하십시오.
담보를 추가하거나 호가 수량을 줄이십시오.
호가를 제시하는 전략에 필요한 접근 수준을 지갑이 보유하고 있는지 확인하십시오.

접근 권한 또는 커버리지로 인한 매도 거절

매도가 체결된 롱 재고로 커버되는지 확인하거나, 매도자(writer) 접근 권한에 대해 Hypercall에 문의하십시오.
신규 지갑에 매도자 접근 권한이 활성화되어 있다고 가정하지 마십시오.

WebSocket에서 체결이 수신되지 않음

인증된 채널을 구독하기 전에 Authenticate 메시지를 전송하십시오.
order_updates만이 아니라 fills도 구독하십시오.
재연결 후에는 GET /fills?wallet=...로 폴백하십시오.

다음 단계

인증: 인증 및 서명
WebSocket 프로토콜: WebSocket API
레이트 리밋: 레이트 리밋
에러: 에러 및 거절 사유
레퍼런스: API 레퍼런스

온보딩 체크리스트​

연동 경로​

Rust 크레이트​

순수 REST 및 WebSocket​

1. 마켓 조회​

2. 서명 설정​

3. 대량 주문으로 호가 제시​

4. 호가 갱신​

5. 업데이트 구독​

6. 상태 정합성 확인​

7. 런칭 범위 이해​

자주 발생하는 문제​

서명 검증 실패​

증거금 부족​

접근 권한 또는 커버리지로 인한 매도 거절​

WebSocket에서 체결이 수신되지 않음​

다음 단계​