실험적 콤보 API
콤보는 고정된 비율의 옵션 레그를 하나의 주문으로 거래합니다. 체결 시 필요한 모든 레그가 함께 실행됩니다. 보유 포지션은 개별 옵션으로 유지됩니다.
모든 /experimental 엔드포인트와 명시적으로 실험적이라고 표시된 WebSocket 메시지는 불안정합니다. 호환성을 깨는 변경은 하루(24시간) 전 사전 공지만으로 적용될 수 있습니다. 여기에는 필드나 엔드포인트의 제거 또는 이름 변경, 필드 타입 변경, 요청 또는 응답 동작의 변경이 포함됩니다. 변경 사항은 API 변경 로그에 공지됩니다. 클라이언트는 이러한 공지를 모니터링하고 명시된 적용 시각 이전에 업데이트해야 합니다. 기존의 비실험적 API 계약은 이 정책의 적용 대상이 아닙니다.
사용 가능 여부는 환경에 따라 다릅니다. 이 페이지는 실험적 인터페이스를 설명할 뿐이며, 프로덕션 출시나 트레이딩 앱의 새 인터페이스를 공지하는 것이 아닙니다.
공통 연결 및 서명 규칙은 REST 레퍼런스, 인증 가이드, WebSocket 가이드를 참고하십시오.
콤보 조회
| 요청 | 결과 |
|---|---|
GET /experimental/combos | 만기되지 않은 정의의 제한된 페이지이며, 선택적으로 underlying으로 필터링할 수 있습니다 |
GET /experimental/combos/{symbol} | 만기되지 않은 단일 정의와 해석된 옵션 레그 |
첫 주문으로 생성: 콤보가 아직 조회되지 않는 경우 POST /order와 함께 정규화된 combo_definition을 제출합니다. 처음 수락된 주문이 해당 정의를 게시하며, 즉시 체결되는 주문도 마찬가지입니다. 거부된 주문은 아무것도 게시하지 않습니다. 별도의 생성 엔드포인트는 없습니다.
조회 유지 기간: 정의는 대기 주문이 없더라도 첫 번째 레그가 만기될 때까지 조회 가능한 상태로 유지됩니다.
페이지네이션: 응답에는 combos와 next_cursor가 포함됩니다. limit은 1–1,000(기본값 100)으로 설정합니다. 다음 요청에서 반환된 커서를 cursor로 전달하되, 동일한 underlying 필터를 유지하십시오. 커서가 null이면 더 이상 조회된 행이 없다는 뜻입니다. 잘못된 limit이나 커서는 HTTP 400을 반환합니다.
GET /experimental/combos?underlying=BTC&limit=100
GET /experimental/combos?underlying=BTC&limit=100&cursor=<next_cursor>
페이지 정렬: 가장 이른 레그 만기 순, 그다음 콤보 ID 순입니다. 커서는 불투명한 값으로 취급하십시오. 각 페이지는 현재 조회 상태를 반영하며, 요청 사이에 정의가 만기되거나 추가될 수 있습니다. 저장된 커서보다 앞에 정렬되는 신규 정의를 포착하려면 생성 업데이트를 사용하거나 조회를 처음부터 다시 시작하십시오.
식별자: 심볼은 COMBO- 뒤에 64자리 소문자 16진수가 붙은 형식입니다. 내용에 결합된 ID가 레그 상품과 부호 있는 정수 비율을 고정합니다. 기존 심볼의 의미는 변경될 수 없습니다.
초기 범위: 동일한 기초자산을 갖는 서로 다른 옵션 레그 2개에서 8개까지입니다. 모든 레그는 상장되어 있고, 만기되지 않았으며, 요청한 체결 경로에 적합해야 합니다.
방향, 가격, 수량 이해하기
비율이 +1 A, -1 B인 정규화된 정의의 경우:
- 패키지 1개 매수: A를 1개 매수하고 B를 1개 매도합니다.
- 패키지 1개 매도: A를 1개 매도하고 B를 1개 매수합니다.
- 순가격:
price(A) - price(B)이며, 패키지당 호가됩니다. - 지정가: 매수는 지정가 이하의 순가격을 수락하고, 매도는 지정가 이상의 순가격을 수락합니다.
음수 및 0 가격도 유효합니다. A가 10에 거래되면 정규화된 순가격은 -2입니다. 이 패키지를 매수하면 수수료 차감 전 2를 지불합니다. 각 실제 옵션 레그의 체결 가격은 여전히 양수입니다.
주문 단위: 패키지 수량은 사람이 읽는 계약 단위를 사용하며 증분은 0.000001입니다. 순 지정가의 증분도 0.000001입니다. 체결되는 모든 레그는 각자의 수량 및 가격 증분도 충족해야 합니다. 부분 체결 시 모든 비율이 유지되며, 허용 가능한 완전한 패키지 수량만큼 체결됩니다.
수수료: 기존 레그별 요율과 적용 조건이 그대로 적용되며, 패키지 할인은 없습니다. 신규 주문은 자신의 레그에 대해 테이커가 되며, 제출한 빌더 귀속이 적용됩니다. 아웃라이트-콤보 경유 경로에서는 콤보 부모 주문이 보조 아웃라이트 메이커를 상대로 한 추가 보조 레그에 대해 일반 테이커 수수료 귀속을 받으며, 이 레그에는 빌더 귀속이 없습니다. 대기 중인 콤보의 예약 금액은 총 레그 금액에 대한 예상 테이커 수수료를 보수적으로 포함합니다. 현재 Standard Margin 체결은 호가창 및 RFQ 체결 모두에서 거래 수수료가 0이어야 하며, SM 참여자가 포함된 경로는 0이 아닌 거래 수수료로 체결될 수 없습니다.
증거금: 거래소는 각 계정별로 결과 옵션 포지션과 남은 주문 익스포저를 확인합니다. 콤보는 여러 지갑의 담보를 합산하거나 특정 증거금 감소를 보장하지 않습니다. 계정 등급이 커버드 옵션 매도만 허용하는 경우, 대기 중인 아웃라이트 주문과 모든 콤보 부모 주문의 매도 레그는 동일한 체결 완료 롱 재고를 공유합니다. 별개의 부모 주문이나 분할 체결이 각각 그 재고를 재사용할 수 없으며, 미체결 매수 레그는 커버리지를 추가하지 않습니다.
주문하기
콤보 심볼과 함께 기존의 서명된 POST /order 요청을 사용합니다. 주문 서명 필드는 변경되지 않습니다. 전송하는 symbol, size, price 문자열을 음수 가격의 마이너스 기호까지 포함하여 정확히 서명하십시오. 신규 콤보의 경우 아래 설명대로 정규화된 combo_definition을 추가합니다. 서명된 내용 결합 심볼이 해당 정의를 확정하므로, 일치하지 않는 정의는 거부됩니다. 이미 알려진 콤보는 이를 생략할 수 있습니다.
{
"wallet": "<your wallet>",
"symbol": "<discovered COMBO symbol>",
"side": "Buy",
"size": "1",
"price": "-2",
"tif": "gtc",
"route": "best_execution",
"client_id": "spread-001",
"reduce_only": false,
"mmp_enabled": false,
"nonce": 1,
"signature": "<signed order>"
}
플레이스홀더와 nonce를 실제 값으로 바꾸십시오. 가격은 예시일 뿐이며 현재 시장 호가가 아닙니다.
| 설정 | 동작 |
|---|---|
route: "book_only" | 사용 가능한 직접 유동성 및 지원되는 내재(implied) 유동성과 매칭한 후 유효 기간 조건을 적용합니다 |
route: "best_execution" | 패키지 전체 가격 개선 경매를 고려하고, 적절한 경우 호가창 체결로 전환합니다 |
route: "rfq_only" | /order에서는 거부됩니다 |
tif: "gtc" | 미체결 패키지 잔량을 대기시킵니다 |
tif: "ioc" | 미체결 잔량을 취소합니다 |
tif: "fok" | 요청한 패키지 수량 전체를 체결하거나 아무것도 체결하지 않습니다 |
가격 개선은 패키지 전체의 부호 있는 순가격을 체결 가능한 전체 수량 기준 호가창 참조가격과 비교합니다. 호가 제공자는 요청된 정확한 비율과 수량으로 모든 레그를 제시해야 합니다. 첫 번째 레그만으로 호가 순위를 매기는 것은 충분하지 않습니다. 직접 콤보 유동성과 지원되는 내재 경로 모두 참조가격에 기여할 수 있습니다. 참조가격을 사용할 수 없거나 불완전하면 주문은 호가창 체결로 전달됩니다.
호가 적격성: 기존 RFQ 수수료 규칙도 적용됩니다. 참여자 중 어느 한쪽이라도 Standard Margin을 사용하면 RFQ 체결 시 거래 수수료가 0이어야 합니다. 수수료, 담보 또는 정확한 배분 검사를 통과하지 못한 호가는 현재 호가창 경로로 체결을 넘기며, 해당 레그를 부분 체결하지 않습니다.
내재 매칭은 하나의 콤보를 그 보조 아웃라이트 옵션 유동성과 결합할 수 있습니다. 예를 들어 아웃라이트 A 주문은 A-마이너스-B 콤보 및 B 유동성과 원자적으로 거래될 수 있습니다. A만 거래하는 고객은 B 포지션을 받지 않습니다.
내재 탐색에는 리소스 한도가 있습니다. 아웃라이트 주문이 그 한도에 도달하거나, 보조 유동성을 사용할 수 없게 되거나, 선택적 경로가 아웃라이트 주문 증분을 표현할 수 없는 경우에도 일반 주문 규칙에 따라 직접 옵션 호가창과는 여전히 거래할 수 있습니다. 콤보 지원은 허용되는 아웃라이트 수량이나 가격 증분을 변경하지 않습니다. 대상 옵션은 호가창 거래에 계속 적격이어야 합니다. 탐색 한도를 초과하는 콤보 주문은 부분 배분 없이 거부됩니다.
현재 제한 사항: 네이티브 콤보 주문은 mmp_enabled: false가 필요합니다. 보호받는 아웃라이트 참여자는 MMP를 유지합니다. 임계값을 발동시키는 패키지는 해당 레그를 완료한 후 추가 매칭을 중단하며, 불완전한 FOK 또는 원자적 교체는 후보 전체를 롤백합니다. Reduce-only 주문은 가격 개선 경매를 건너뛰고 호가창 접수를 사용하며, 결과로 생기는 각 레그가 reduce-only 검사를 충족해야 합니다. 대기 중인 콤보는 기존 취소 엔드포인트를 사용해 부모 주문 ID 또는 클라이언트 주문 ID로 취소하십시오.
교체: PUT /order는 동일한 콤보 정의 내에서 부모 주문을 원자적으로 교체할 수 있습니다. 거부된 교체는 기존 주문을 그대로 유지합니다. 일괄 교체에 포함된 네이티브 항목도 부모 주문마다 하나의 원자적 명령을 사용하며, 배치 전체가 하나의 전부-아니면-전무 트랜잭션은 아닙니다. 콤보와 아웃라이트 간 교체, 또는 서로 다른 콤보 정의 간 교체는 거부됩니다.
자기거래 방지: 경로가 계정을 자기 자신과 거래시키기 전에 매칭이 중단되며, 대기 중인 메이커 주문이 취소됩니다. 이전에 완료된 체결은 유지되고, 신규 주문의 잔량은 취소됩니다. 이전 체결이 없으면 신규 주문이 거부됩니다. FOK 주문과 실패한 원자적 교체는 잠정적인 메이커 취소의 롤백을 포함하여 전부-아니면-전무 동작을 유지합니다.
첫 주문에서 콤보 정의하기
서명 전 정규화: 중복된 상품 ID를 합치고, 0인 비율을 제거하고, ID를 숫자 순으로 정렬하고, 비율을 최대공약수로 나눈 후, 첫 번째 비율을 양수로 만듭니다. 정규화로 비율의 부호가 뒤집히면 의도한 주문 방향을 반대로 하고 순가격의 부호를 바꾸십시오. 비율을 어떤 배수로 나눴다면 패키지 수량에 그 배수를 곱하고 순가격을 그 배수로 나누십시오.
버전 1 ID는 다음 연결값의 Keccak-256입니다.
UTF-8("hypercall:combo-definition\0")
|| version as unsigned 16-bit big-endian (1)
|| leg count as unsigned 16-bit big-endian
|| each sorted leg:
instrument ID as 32 big-endian bytes
ratio as signed 64-bit two's-complement big-endian
상품 ID는 UTF-8 "instrument" 뒤에 정확한 정규 옵션 심볼을 붙인 값의 Keccak-256입니다. 게시되는 콤보 ID는 전체 다이제스트이며, 0x와 64자리 소문자 16진수로 인코딩됩니다. 콤보 심볼은 COMBO- 뒤에 동일한 16진수 자릿수를 사용합니다.
일반 서명 POST /order 본문에 combo_definition을 포함하십시오. 정의에는 version, id, legs가 포함되며, 각 레그에는 instrument_id와 ratio가 포함됩니다. ID는 0x와 64자리 소문자 16진수로, 비율은 "1" 또는 "-1"과 같은 정규 부호 있는 10진수 문자열로 인코딩하십시오. 비율에 JSON 숫자, 앞에 붙은 플러스 기호, 앞자리 0을 사용하면 거부됩니다.
{
"combo_definition": {
"version": 1,
"id": "<canonical content hash as 0x plus 64 hex digits>",
"legs": [
{"instrument_id": "<first canonical instrument ID>", "ratio": "1"},
{"instrument_id": "<second canonical instrument ID>", "ratio": "-1"}
]
}
}
이 조각은 위의 전체 주문 예시에 추가됩니다. 플레이스홀더를 실제 ID로 바꾸고 해당하는 COMBO- 심볼을 사용하십시오. 별도의 정의 서명이나 게시용 nonce는 없습니다. 서비스는 정규 내용과 그 식별자를 서명된 심볼과 대조하여 검증하며, 아웃라이트 주문은 combo_definition을 생략해야 합니다.
수락 및 조회: 수락된 모든 콤보 주문은 영속 주문 레코드에 정의를 보관하고, 카탈로그 항목이 존재하도록 멱등적으로 보장합니다. 이후 주문은 최초 생성 레코드를 덮어쓰지 않습니다. 즉시 체결된 주문도 조회 데이터를 생성하지만, 거부된 주문은 생성하지 않습니다. 조회 데이터는 커밋된 데이터에서 투영되므로 주문 확인보다 늦게 반영될 수 있습니다. 이후 주문에서 동일한 정의를 다시 제출하는 것은 지원되며, 최초 카탈로그 항목이 아직 반영 중일 때도 마찬가지입니다.
주문 및 체결 조회
| 요청 | 용도 |
|---|---|
GET /experimental/orders | 콤보 부모 주문을 포함하여 명시적인 상품 분류와 함께 주문을 조회합니다 |
GET /experimental/trades | 기본적으로 실제 레그 거래를 조회하거나, view=packages&symbol=<COMBO symbol>로 단일 콤보의 패키지 요약을 조회합니다 |
GET /experimental/fills | 기본적으로 지갑 체결을 조회하거나, view=packages로 지갑 패키지 요약을 조회합니다 |
지원되는 필터와 커서는 REST 레퍼런스를 참고하십시오. 패키지 뷰는 offset이 아니라 limit(1~1,000, 기본값 100)과 before_execution_id로 페이지를 나눕니다. 다음 페이지를 가져오려면 반환된 next_before_execution_id를 전달하십시오. 패키지 거래 조회에는 정규 COMBO- symbol이 필요하며, 패키지 체결 조회는 wallet과 선택적 symbol을 받습니다. 패키지 요약은 그룹화 레코드입니다. 체결 ID와 레그 거래 ID를 통해 실제 옵션 체결과 연결할 수 있습니다. 계정 합계를 계산할 때 패키지 수량, 프리미엄, 수수료를 구성 체결에 더하지 마십시오.
식별자 정밀도: 실험적 주문 ID, 패키지 체결 ID, 구성 거래/주문 ID, 부모 주문 ID, 패키지 페이지네이션 커서는 10진수 문자열입니다. 클라이언트에서 문자열로 유지하십시오. JavaScript 숫자로 변환하면 정밀도가 손실될 수 있습니다. 레거시 view=legs 응답은 기존 표현을 유지합니다.
호환성: 레거시 상품 조회 및 주문 뷰는 기존 아웃라이트 계약을 유지합니다. 실제 옵션 레그 체결은 레거시 거래/체결 피드에 계속 표시되며, 포지션은 옵션 포지션으로 유지됩니다. 콤보의 부모 주문은 독립적으로 대기하는 레그 주문들의 모음이 아닙니다.
명시적으로 구독하기
실험적 비공개 채널은 기존 WebSocket 인증 단계와 명시적 구독이 필요합니다. 인증된 지갑의 부모 레코드만 게시합니다.
| 채널 | 메시지 | 대상 |
|---|---|---|
experimental_order_updates | 부모 ID, 심볼, 상품 유형(option, perp, combo), 상태, 수량, 체결 수량, 순가격을 포함한 ExperimentalOrderUpdate | 인증된 지갑 |
experimental_combo_trades | 체결 ID, 심볼, 패키지 수량, 순가격, 레그 거래 ID를 포함한 ComboTrade | 공개 |
experimental_combo_fills | 지갑의 부모 주문 ID, 방향, 패키지 체결을 포함한 ComboFill | 인증된 지갑 |
{"type":"Subscribe","channel":"experimental_order_updates"}
ExperimentalOrderUpdate.status는 OrderUpdate의 대문자 값이 아니라 Acked, Open, PartiallyFilled, Filled, Canceled, Rejected를 사용합니다. ID와 수량은 문자열입니다.
조회한 콤보 심볼로 기존 호가창 채널을 구독하십시오.
{"type":"Subscribe","channel":"orderbook","symbols":["<discovered COMBO symbol>"]}
시장 조회 업데이트는 동일한 불변 정의를 반복해서 보낼 수 있으므로 콤보 ID로 중복을 제거하십시오. 이 업데이트는 market_updates에서 MarketUpdate를 사용하며, action: "ComboCreated", 콤보 심볼, ID, 정규 레그, 타임스탬프를 포함합니다. 클라이언트에서 대사(reconciliation)할 때는 조회 정보, 부모 주문 상태, 패키지 체결 요약, 실제 레그 체결을 서로 다른 레코드로 취급하십시오.