# 가상자산 출금

[← REST API 가이드](../rest_api.md)

## 출금 가능 주소 목록 조회 {#get-_v2_coin_withdrawableAddresses}

```
GET /v2/coin/withdrawableAddresses
```

API 출금 가능 주소로 등록된 주소를 조회합니다.

**필요 권한:** `readWithdrawals`

### 스키마

```ts
// URL 쿼리 파라미터
type RequestQuery = {
  /** 어카운트 시퀀스 번호. 입출금 API는 메인 어카운트에서만 동작하므로 `1`만 입력 가능합니다. 기본값은 1. Example: 1 */
  accountSeq?: number;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = Array<{
  /** 블록체인 네트워크 심볼. Example: "ETH" */
  network: string;
  /** 가상자산의 심볼. 네트워크를 대상으로 등록된 지갑 주소의 경우 생략되며, 이 경우 모든 자산을 출금할 수 있습니다. Example: "btc" */
  currency?: string;
  /** 등록된 출금 가능 주소. Example: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" */
  address: string;
  /** 2차 주소 (Destination Tag, Memo 등. 없으면 null) */
  secondaryAddress?: string | null;
}>;
```

### 예시

#### 요청
```sh
curl -H X-KAPI-KEY=API키 'https://api.korbit.co.kr/v2/coin/withdrawableAddresses?timestamp=시각&signature=서명'
```
#### 응답
```json
{
  "success": true,
  "data": [
    {
      "network": "BTC",
      "currency": "btc",
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
    },
    {
      "network": "ETH",
      "address": "0x05a56e2d52c817161883f50c441c3228cfe54d9f"
    }
  ]
}
```

## 출금 가능 수량 조회 {#get-_v2_coin_withdrawableAmount}

```
GET /v2/coin/withdrawableAmount
```

출금 가능 수량을 조회합니다.

**필요 권한:** `readWithdrawals`

### 스키마

```ts
// URL 쿼리 파라미터
type RequestQuery = {
  /** 어카운트 시퀀스 번호. 입출금 API는 메인 어카운트에서만 동작하므로 `1`만 입력 가능합니다. 기본값은 1. Example: 1 */
  accountSeq?: number;
  /** 가상자산의 심볼. 입력하지 않으면 모든 가상자산을 조회합니다. Example: "btc" */
  currency?: string;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = Array<{
  /** 가상자산의 심볼. Example: "btc" */
  currency: string;
  /** 출금 가능 수량. Example: "1.52" */
  withdrawableAmount: string;
  /** 출금 진행 중 수량. Example: "0.005" */
  withdrawalInUseAmount: string;
}>;
```

### 예시

#### 요청
```sh
curl -H X-KAPI-KEY=API키 'https://api.korbit.co.kr/v2/coin/withdrawableAmount?currency=btc&timestamp=시각&signature=서명'
```
#### 응답
```json
{
  "success": true,
  "data": [
    {
      "currency": "btc",
      "withdrawableAmount": "1.52",
      "withdrawalInUseAmount": "0.005"
    },
    {
      "currency": "eth",
      "withdrawableAmount": "10.52",
      "withdrawalInUseAmount": "2.5"
    }
  ]
}
```

## 출금 요청 {#post-_v2_coin_withdrawal}

```
POST /v2/coin/withdrawal
```

가상자산 출금을 요청합니다. 출금 API를 사용하기 위해서는, 코빗 개발자센터에서 API 출금 허용주소 등록이 필요합니다.

**필요 권한:** `writeWithdrawals`

### 스키마

```ts
// POST 본문 — `Content-Type: application/x-www-form-urlencoded`
type RequestBody = {
  /** 어카운트 시퀀스 번호. 입출금 API는 메인 어카운트에서만 동작하므로 `1`만 입력 가능합니다. 기본값은 1. Example: 1 */
  accountSeq?: number;
  /** 출금할 가상자산의 심볼. Example: "btc" */
  currency: string;
  /**
   * 블록체인 네트워크 심볼.  네트워크 정보는 `/v2/currencies` API로 확인 가능합니다.
   * 미입력시 해당 가상자산의 기본 네트워크를 사용합니다. 기본 네트워크는 변경될 수 있으므로, 오류를 방지하기 위하여 네트워크를 항상 명시해주시기 바랍니다.
   * Example: "BTC"
   */
  network?: string;
  /** 출금할 가상자산의 수량 (수수료 별도). Example: "0.02521236" */
  amount: string;
  /** 가상자산을 받을 주소. API 출금이 허용된 주소로만 출금할 수 있습니다. Example: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" */
  address: string;
  /** 2차 주소 (Destination Tag, Memo 등. 없으면 "" (빈 문자열) 세팅 또는 생략) */
  secondaryAddress?: string;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = {
  /** 출금 진행상황 */
  status:
    | "pending"  // 출금 요청 접수됨
    | "actionRequired"  // (출금 취소 가능) 이메일 확인 대기 중. 계속 진행하기 위해서는 코빗 회원정보의 주소로 전송된 출금 확인 이메일을 확인해야 합니다.
    | "reviewing"  // (출금 취소 가능) 출금 심사 중. 코빗 정책에 따라 심사 후 출금이 지연될 수 있습니다.
    | "processing"  // 출금 처리 중
    | "done"  // 출금 완료
    | "canceled"  // 출금 취소
    | "failed"  // 출금 실패 (잔고 부족 또는 기타 오류)
    ;
  /** 출금 요청 건의 고유 ID. Example: 1234 */
  coinWithdrawalId: number;
};
```

### 오류 코드

- `INVALID_CURRENCY` — 잘못된 가상자산 심볼입니다.
- `WITHDRAWAL_SUSPENDED` — 출금이 중단된 상태입니다.
- `UNREGISTERED_WITHDRAWAL_ADDRESS` — Open API 출금 허용 주소로 등록되어 있지 않은 주소입니다.
- `FORBIDDEN_WITHDRAWAL_ADDRESS` — 코빗 정책에 따라 출금이 불가능한 주소입니다.
- `WITHDRAWAL_ALREADY_IN_PROGRESS` — 이미 출금 진행 중입니다. 다른 출금 건이 완료된 후 다시 시도해 주세요.
- `INVALID_USER_STATUS` — 거래가 제한된 계정입니다. 코빗 웹사이트 또는 고객센터를 통해 상태를 확인하세요.
- `NO_BALANCE` — 잔고가 부족합니다. 참고: 잔고가 부족한 경우, `NO_BALANCE` 오류가 발생할 수도 있고 출금 요청은 성공했으나 출금 내역 조회 시 `failed` 상태로 표시될 수도 있습니다.
- `DAILY_LIMIT_EXCEEDED` — 일일 출금 한도를 초과했습니다.

### 예시

#### 요청
```sh
curl -X POST -H X-KAPI-KEY=API키 'https://api.korbit.co.kr/v2/coin/withdrawal' -H Content-Type: application/x-www-form-urlencoded --data-raw address=1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa&amount=0.02521236&currency=btc&timestamp=시각&signature=서명
```
#### 응답
```json
{
  "success": true,
  "data": {
    "status": "pending",
    "coinWithdrawalId": 1234
  }
}
```

## 출금 취소 {#delete-_v2_coin_withdrawal}

```
DELETE /v2/coin/withdrawal
```

가상자산 출금을 취소합니다.
해당 출금 건의 상태가 아래 중 하나인 경우에만 취소 가능합니다.
- `actionRequired`
- `reviewing`

**필요 권한:** `writeWithdrawals`

### 스키마

```ts
// URL 쿼리 파라미터
type RequestQuery = {
  /** 어카운트 시퀀스 번호. 입출금 API는 메인 어카운트에서만 동작하므로 `1`만 입력 가능합니다. 기본값은 1. Example: 1 */
  accountSeq?: number;
  /** 출금 ID (출금 요청 API 응답에서 받은 값). Example: 1234 */
  coinWithdrawalId: number;
};
```

### 오류 코드

- `WITHDRAWAL_ALREADY_FINISHED` — 출금이 이미 완료되었습니다.
- `CANNOT_CANCEL_WITHDRAWAL` — 출금 취소가 불가능합니다. (출금 처리가 이미 시작된 경우 등)
- `NOT_FOUND` — 출금 정보가 존재하지 않습니다.

### 예시

#### 요청
```sh
curl -X DELETE -H X-KAPI-KEY=API키 'https://api.korbit.co.kr/v2/coin/withdrawal?coinWithdrawalId=1234&timestamp=시각&signature=서명'
```
#### 응답
```json
{
  "success": true
}
```

## 최근 출금내역 조회 {#get-_v2_coin_recentWithdrawals}

```
GET /v2/coin/recentWithdrawals
```

최근 가상자산 출금내역을 조회합니다.

**필요 권한:** `readWithdrawals`

### 스키마

```ts
// URL 쿼리 파라미터
type RequestQuery = {
  /** 어카운트 시퀀스 번호. 입출금 API는 메인 어카운트에서만 동작하므로 `1`만 입력 가능합니다. 기본값은 1. Example: 1 */
  accountSeq?: number;
  /** 조회할 가상자산의 심볼. Example: "btc" */
  currency: string;
  /** 최대 조회 건수 (범위: 1 - 100). Example: 100 */
  limit?: number;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = Array<{
  /** 가상자산 출금 ID. Example: 1234 */
  id: number;
  /** 출금된 가상자산 수량. (수수료를 제외한 값으로 블록체인 트랜잭션에 기록되는 수량과 동일함). Example: "1.234" */
  quantity: string;
  /** 출금 수수료. Example: "0.0001" */
  fee: string;
  /** 출금 요청한 가상자산의 심볼. Example: "btc" */
  currency: string;
  /** 출금 진행상황 */
  status:
    | "pending"  // 출금 요청 접수됨
    | "actionRequired"  // (출금 취소 가능) 이메일 확인 대기 중. 계속 진행하기 위해서는 코빗 회원정보의 주소로 전송된 출금 확인 이메일을 확인해야 합니다.
    | "reviewing"  // (출금 취소 가능) 출금 심사 중. 코빗 정책에 따라 심사 후 출금이 지연될 수 있습니다.
    | "processing"  // 출금 처리 중
    | "done"  // 출금 완료
    | "canceled"  // 출금 취소
    | "failed"  // 출금 실패 (잔고 부족 또는 기타 오류)
    ;
  /** 블록체인 네트워크 심볼. Example: "ETH" */
  network: string;
  /** 출금 주소. Example: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" */
  address: string;
  /** 출금 2차 주소 (Destination Tag, Memo 등. 없으면 null) */
  secondaryAddress?: string | null;
  /** 블록체인 트랜잭션 해시. (아직 네트워크로 전송되지 않았다면 null). Example: "0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f" */
  transactionHash?: string | null;
  /** 출금 요청 시각(timestamp). Example: 1700000000000 */
  createdAt: number;
}>;
```

### 예시

#### 요청
```sh
curl -H X-KAPI-KEY=API키 'https://api.korbit.co.kr/v2/coin/recentWithdrawals?currency=btc&limit=100&timestamp=시각&signature=서명'
```
#### 응답
```json
{
  "success": true,
  "data": [
    {
      "id": 1234,
      "quantity": "1.234",
      "fee": "0.0001",
      "currency": "btc",
      "status": "done",
      "network": "BTC",
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "secondaryAddress": null,
      "transactionHash": "0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f",
      "createdAt": 1700000000000
    }
  ]
}
```

## 출금 진행상황 조회 {#get-_v2_coin_withdrawal}

```
GET /v2/coin/withdrawal
```

요청한 출금의 진행 상황을 조회합니다.

**필요 권한:** `readWithdrawals`

### 스키마

```ts
// URL 쿼리 파라미터
type RequestQuery = {
  /** 어카운트 시퀀스 번호. 입출금 API는 메인 어카운트에서만 동작하므로 `1`만 입력 가능합니다. 기본값은 1. Example: 1 */
  accountSeq?: number;
  /** 조회할 가상자산의 심볼. Example: "btc" */
  currency: string;
  /** 가상자산 출금 ID. Example: 1234 */
  coinWithdrawalId: number;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = {
  /** 가상자산 출금 ID. Example: 1234 */
  id: number;
  /** 출금된 가상자산 수량. (수수료를 제외한 값으로 블록체인 트랜잭션에 기록되는 수량과 동일함). Example: "1.234" */
  quantity: string;
  /** 출금 수수료. Example: "0.0001" */
  fee: string;
  /** 출금 요청한 가상자산의 심볼. Example: "btc" */
  currency: string;
  /** 출금 진행상황 */
  status:
    | "pending"  // 출금 요청 접수됨
    | "actionRequired"  // (출금 취소 가능) 이메일 확인 대기 중. 계속 진행하기 위해서는 코빗 회원정보의 주소로 전송된 출금 확인 이메일을 확인해야 합니다.
    | "reviewing"  // (출금 취소 가능) 출금 심사 중. 코빗 정책에 따라 심사 후 출금이 지연될 수 있습니다.
    | "processing"  // 출금 처리 중
    | "done"  // 출금 완료
    | "canceled"  // 출금 취소
    | "failed"  // 출금 실패 (잔고 부족 또는 기타 오류)
    ;
  /** 블록체인 네트워크 심볼. Example: "ETH" */
  network: string;
  /** 출금 주소. Example: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" */
  address: string;
  /** 출금 2차 주소 (Destination Tag, Memo 등. 없으면 null) */
  secondaryAddress?: string | null;
  /** 블록체인 트랜잭션 해시. (아직 네트워크로 전송되지 않았다면 null). Example: "0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f" */
  transactionHash?: string | null;
  /** 출금 요청 시각(timestamp). Example: 1700000000000 */
  createdAt: number;
};
```

### 예시

#### 요청
```sh
curl -H X-KAPI-KEY=API키 'https://api.korbit.co.kr/v2/coin/withdrawal?coinWithdrawalId=1234&currency=btc&timestamp=시각&signature=서명'
```
#### 응답
```json
{
  "success": true,
  "data": {
    "id": 1234,
    "quantity": "1.234",
    "fee": "0.0001",
    "currency": "btc",
    "status": "done",
    "network": "BTC",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "secondaryAddress": null,
    "transactionHash": "0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f",
    "createdAt": 1700000000000
  }
}
```