API 트레이딩

마켓메이커, 호가 제시 시스템 또는 주문 집행 서비스를 Hypercall과 연동하는 경우 이 가이드를 참고하십시오.

프로덕션 API

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

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

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

허용 목록 기반 스트림

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

온보딩 체크리스트

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

연동 방식

TypeScript SDK

타입이 지정된 REST 클라이언트, 런타임 요청 검증, EIP-712 서명 헬퍼를 사용하려면 공식 TypeScript 패키지를 설치하십시오.

npm install @hypercallxyz/sdk

시장 데이터 조회, 계정 조회, 서명된 쓰기 요청, 오류 처리, 패키지 진입점에 대해서는 TypeScript SDK 가이드를 참고하십시오. TypeScript SDK는 현재 REST와 서명만 지원합니다. 스트리밍 업데이트는 WebSocket API에 직접 연결하여 수신하십시오.

Rust 크레이트

Hypercall은 지원되는 연동 범위에 대한 공개 Rust 크레이트를 github.com/hypercall-public/hypercall-rust에서 배포합니다. 이 크레이트는 crates.io에 등록되어 있지 않습니다. git 의존성으로 추가하고 태그 또는 커밋을 고정하십시오.

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

가능하면 크레이트를 사용하십시오. 크레이트에는 현재 서명 도메인, 요청 형식, 라우팅 규칙, 그리고 수작업으로 구현하면 실수하기 쉬운 문자열 포맷 규칙이 반영되어 있습니다.

Raw 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: 옵션 체인 단위의 최우선 매수호가, 최우선 매도호가, 마크 가격 및 그릭스 형태의 요약 필드 조회.

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": 1791273600000,
        "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": 1791273600001,
        "signature": "0x..."
      }
    ]
  }'

중요한 규칙:

price와 size는 문자열입니다. 서명 페이로드와 JSON 본문 모두에서 문자열이어야 합니다.
문자열 포맷은 서명과 JSON 본문 간에 정확히 일치해야 합니다.
대량 주문은 요청당 최대 50건으로 제한됩니다.
대량 주문 라우팅은 오더북 전용입니다. route는 book_only이거나 생략할 수 있습니다. 대량 주문에서 route: "best_execution"은 거부되므로 이 경우 POST /order를 사용하십시오. route: "rfq_only"는 현재 모든 주문 엔드포인트에서 거부됩니다.
논스는 밀리초 단위 타임스탬프입니다. 서버 시간 기준 2일 전부터 1일 후 범위를 벗어난 논스는 거부됩니다. 논스 관리를 참고하십시오.
대부분의 거래 거부는 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",
        "client_id": "mm-bid-1",
        "mmp_enabled": true,
        "nonce": 1791273600002,
        "signature": "0x..."
      }
    ]
  }'

대체 주문에는 route 필드가 없으며, 주문 필드에 기존 orderId를 추가한 ReplaceOrder로 서명됩니다. 인증 및 서명을 참고하십시오.

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: PARTIALLY_FILLED를 포함한 주문 상태 변경. 이 채널의 filled_size는 해당 주문의 누적 체결 수량입니다.
fills: 개별 체결 내역과 체결별 수량.
portfolio: 계정 상태 업데이트.
orderbook, trades, options_chain, index_prices: 공개 시장 데이터.

채널 형식과 연결 유지(liveness) 동작은 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. 출시 범위 이해

Mainnet Alpha는 의도적으로 기능이 제한되어 있습니다.

증거금: Standard Margin과 Portfolio Margin이 모두 운영 중입니다. HyperCore 계정이 unified 모드인 모든 계정은 Portfolio Margin으로 전환할 수 있습니다.
옵션 숏: Standard Margin 옵션 숏이 활성화되어 있으며, 증거금 및 해당 등급의 한도가 적용됩니다. GET /risk/limits?wallet=...에서 standard_margin_shorts_enabled를 확인하십시오.
퍼프: 퍼프 주문은 별도의 서명 도메인과 엔드포인트를 사용합니다. 인증 및 서명을 참고하십시오.
참고용 호가 스트리밍: 호가 제공자 스트림은 허용 목록 기반이며, 아직 일반 공개 연동 경로가 아닙니다.
청산 도구: 공개 liquidator 크레이트는 일반적인 마켓메이킹용이 아니라 Standard Margin 청산 워크플로용입니다.
테스트넷: Hypercall이 테스트넷 HYPE를 추가로 확보할 때까지 사용할 수 없습니다.

자주 발생하는 문제

서명 검증 실패

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

증거금 부족

GET /portfolio?wallet=...를 확인하십시오.
담보를 추가하거나 호가 수량을 줄이십시오.
제시하려는 전략에 필요한 접근 등급이 지갑에 부여되어 있는지 확인하십시오.

접근 권한 또는 커버리지 문제로 매도 거부

GET /risk/limits?wallet=...를 확인하십시오. 일부 등급은 체결된 롱 보유분으로 커버되는 매도만 허용합니다.
지갑에 다른 등급이 필요한 경우 Hypercall에 문의하십시오.

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

인증이 필요한 채널을 구독하기 전에 Authenticate 메시지를 보내십시오.
order_updates뿐만 아니라 fills도 구독하십시오.
재연결 후에는 GET /fills?wallet=...로 보완 조회하십시오.

다음 단계

인증: 인증 및 서명
WebSocket 프로토콜: WebSocket API
요청 한도: 요청 한도
오류: 오류 및 거부 사유
레퍼런스: API 레퍼런스

온보딩 체크리스트​

연동 방식​

TypeScript SDK​

Rust 크레이트​

Raw REST 및 WebSocket​

1. 마켓 조회​

2. 서명 설정​

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

4. 호가 갱신​

5. 업데이트 구독​

6. 상태 대사​

7. 출시 범위 이해​

자주 발생하는 문제​

서명 검증 실패​

증거금 부족​

접근 권한 또는 커버리지 문제로 매도 거부​

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

다음 단계​