---
updatedAt: 2026-09-07T01:59:43.000Z
agentTools:
  projectIndex: https://apidocs.bithumb.com/llms.txt
---

# Private v2 마이그레이션 가이드

Private WebSocket `myOrder` 스트림 v1 → v2 마이그레이션 가이드

Private WebSocket 스트림이 v2 응답 스펙으로 변경됩니다. 이 가이드는 `myOrder` 마이그레이션을 다룹니다.

<Callout icon="fa-circle-info" theme="info">
  **이 가이드에 포함되지 않는 항목**

  * **MyAsset**: v1과 v2의 응답 구조가 동일하여 응답 처리 로직 변경은 불필요합니다. 단, 연결 엔드포인트는 v2 (`wss://ws-api.bithumb.com/websocket/v2/private`)로 변경해야 하며, v1 엔드포인트는 **2026년 10월 30일에 종료됩니다.**
  * **Public 스트림**(`ticker`, `trade`, `orderbook`): v1을 유지하므로 적용 대상 아님
</Callout>

## 변경된 필드

다음 필드의 이름 또는 값이 v2에서 변경됩니다.

| v1 필드              | v1 축약  | v2 필드                              | v2 축약      | 변경 내용                              |
| ------------------ | ------ | ---------------------------------- | ---------- | ---------------------------------- |
| `uuid`             | `uid`  | `order_id`                         | `oid`      |                                    |
| `trade_uuid`       | `tuid` | `trade_id`                         | `tid`      |                                    |
| `canceling_uuid`   | `cuid` | `canceling_order_id`               | `cnoid`    |                                    |
| `ask_bid`          | `ab`   | `side`                             | `sd`       | 값도 변경 (`BID`/`ASK` → `buy`/`sell`) |
| `price`            | `p`    | `order_price`, `trade_price`       | `op`, `tp` | **필드 분리**                          |
| `volume`           | `v`    | `order_quantity`, `trade_quantity` | `oq`, `tq` | **필드 분리** + `volume` → `quantity`  |
| `remaining_volume` | `rv`   | `remaining_quantity`               | `rq`       |                                    |
| `executed_volume`  | `ev`   | `executed_quantity`                | `eq`       |                                    |
| `executed_funds`   | `ef`   | `executed_amount`                  | `ea`       |                                    |

## 변경 없는 필드

<Accordion title="변경 없이 그대로 유지되는 필드(참고)">
  | 필드                | 축약     |
  | ----------------- | ------ |
  | `type`            | `ty`   |
  | `stream_type`     | `st`   |
  | `code`            | `cd`   |
  | `client_order_id` | `coid` |
  | `state`           | `s`    |
  | `reserved_fee`    | `rsf`  |
  | `remaining_fee`   | `rmf`  |
  | `paid_fee`        | `pf`   |
  | `cancel_type`     | `ct`   |
  | `trade_timestamp` | `ttms` |
  | `order_timestamp` | `otms` |
  | `timestamp`       | `tms`  |
</Accordion>

## 제거된 필드

다음 필드는 v2에서 제거됩니다.

| v1 필드          | v1 축약 |
| -------------- | ----- |
| `trades_count` | `tc`  |

## 새로 추가된 필드

| 필드              | 축약    | 타입     | 설명                                                           |
| --------------- | ----- | ------ | ------------------------------------------------------------ |
| `order_amount`  | `oa`  | Double | 주문 금액(모든 메시지에 포함; 시장가 매도/최유리 매도는 `0`)                        |
| `trade_amount`  | `ta`  | Double | 이번 체결 금액(체결 이벤트에서 채워짐)                                       |
| `time_in_force` | `tif` | String | 주문 처리 조건(`ioc`, `fok`, `post_only`). `limit`/`best` 주문에서만 사용 |

## `price`/`volume` 분리 가이드

v1에서는 `price`/`volume` 한 필드가 `state`에 따라 두 의미를 모두 담당했지만, v2에서는 주문 정보와 체결 정보를 별도 필드로 분리하여 제공합니다.

* 주문 가격, 수량: `order_price`, `order_quantity`(모든 메시지에서 채워짐)
* 체결 가격, 수량: `trade_price`, `trade_quantity`(체결 이벤트에서 채워짐)

```
v1: 한 필드가 state에 따라 두 의미를 모두 담당
  state = 'wait' 또는 'cancel':
    message.price    = 주문 가격
    message.volume   = 주문 수량
  state = 'trade':
    message.price    = 체결 가격
    message.volume   = 체결 수량

v2: 필드명이 의미를 직접 표현
  message.order_price       = 주문 가격     (모든 메시지)
  message.order_quantity    = 주문 수량     (모든 메시지)
  message.trade_price       = 체결 가격     (체결 이벤트에서만)
  message.trade_quantity    = 체결 수량     (체결 이벤트에서만)
```

이벤트별로 응답에 포함되는 필드는 [내 주문 및 체결 (MyOrder)](/reference/내-주문-및-체결-myorder) 페이지에서 확인하세요.

## 체크리스트

* [ ] **필드명 변경 반영** — 위 \[변경된 필드] 표의 v1 → v2 매핑대로 코드 교체
* [ ] `side`**&#x20;값 변경 반영** — `BID`/`ASK`에서 `buy`/`sell`로 변경
* [ ] **분리된 가격/수량 필드 사용** — `order_price`, `trade_price`, `order_quantity`, `trade_quantity` 명시적 필드를 직접 사용(v1처럼 `state` 값으로 분기할 필요 없음)
* [ ] **신규 필드 점검** — `order_amount`(주문 금액), `trade_amount`(이번 체결 금액), `time_in_force`(주문 처리 조건)이 필요한 로직이 있는지 점검