# 가상자산 입금

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

## 입금 주소 전체 조회 {#get-_v2_coin_depositAddresses}

```
GET /v2/coin/depositAddresses
```

가상자산 입금 주소 목록을 조회합니다.

**필요 권한:** `readDeposits`

### 스키마

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

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = Array<{
  /** 가상자산 심볼. Example: "btc" */
  currency: string;
  /** 블록체인 네트워크 심볼. Example: "ETH" */
  network: 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/depositAddresses?timestamp=시각&signature=서명'
```
#### 응답
```json
{
  "success": true,
  "data": [
    {
      "currency": "btc",
      "network": "BTC",
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
    },
    {
      "currency": "xrp",
      "network": "XRP",
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "secondaryAddress": "1234"
    }
  ]
}
```

## 입금 주소 조회 {#get-_v2_coin_depositAddress}

```
GET /v2/coin/depositAddress
```

개별 가상자산의 입금 주소를 조회합니다.

**필요 권한:** `readDeposits`

### 스키마

```ts
// URL 쿼리 파라미터
type RequestQuery = {
  /** 어카운트 시퀀스 번호. 입출금 API는 메인 어카운트에서만 동작하므로 `1`만 입력 가능합니다. 기본값은 1. Example: 1 */
  accountSeq?: number;
  /** 가상자산 심볼. Example: "btc" */
  currency: string;
  /**
   * 블록체인 네트워크 심볼.  네트워크 정보는 `/v2/currencies` API로 확인 가능합니다.
   * 미입력시 해당 가상자산의 기본 네트워크를 사용합니다. 기본 네트워크는 변경될 수 있으므로, 오류를 방지하기 위하여 네트워크를 항상 명시해주시기 바랍니다.
   * Example: "BTC"
   */
  network?: string;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = {
  /** 가상자산 심볼. Example: "btc" */
  currency: string;
  /** 블록체인 네트워크 심볼. Example: "ETH" */
  network: 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/depositAddress?currency=btc&timestamp=시각&signature=서명'
```
#### 응답
```json
{
  "success": true,
  "data": {
    "currency": "btc",
    "network": "BTC",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  }
}
```

## 입금 주소 생성 {#post-_v2_coin_depositAddress}

```
POST /v2/coin/depositAddress
```

가상자산을 입금할 주소를 발급합니다. 입금 주소가 이미 존재한다면 신규 발급 없이 기존 입금 주소를 응답합니다.

**필요 권한:** `writeDeposits`

### 스키마

```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;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = {
  /** 가상자산 심볼. Example: "btc" */
  currency: string;
  /** 블록체인 네트워크 심볼. Example: "ETH" */
  network: string;
  /** 입금 주소. Example: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" */
  address: string;
  /** 입금 2차 주소 (Destination Tag, Memo 등. 없으면 null) */
  secondaryAddress?: string | null;
};
```

### 예시

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

## 최근 입금내역 조회 {#get-_v2_coin_recentDeposits}

```
GET /v2/coin/recentDeposits
```

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

**필요 권한:** `readDeposits`

### 스키마

```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: "ETH" */
  network: string;
  /** 입금 주소. Example: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" */
  address: string;
  /** 입금 2차 주소 (Destination Tag, Memo 등. 없으면 null) */
  secondaryAddress?: string | null;
  /** 입금 진행 상황 */
  status:
    | "pending"  // 블록체인 네트워크에서 입금 트랜잭션을 발견한 상태
    | "actionRequired"  // 입금계류 서류제출 대기 중 (입금을 위해서는 코빗 웹사이트에서 필요한 서류를 제출해야 합니다.)
    | "reviewing"  // 입금계류 제출서류 심사 중
    | "done"  // 입금 완료
    | "refunded"  // 심사 거절 후 입금 금액이 반환된 상태
    | "failed"  // 입금 실패 (입금 트랜잭션에 문제가 있는 경우 등)
    ;
  /** 블록체인 트랜잭션 해시. Example: "0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f" */
  transactionHash: string;
  /** 입금 중인 가상자산의 심볼. Example: "btc" */
  currency: string;
  /** 입금 중인 가상자산의 수량 (트랜잭션에 기록되는 수량과 같음). Example: "1.234" */
  quantity: string;
  /** 입금 수신 시각(timestamp). Example: 1700000000000 */
  createdAt: number;
}>;
```

### 예시

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

## 입금 진행상황 조회 {#get-_v2_coin_deposit}

```
GET /v2/coin/deposit
```

가상자산 입금 진행 상태를 조회합니다.

**필요 권한:** `readDeposits`

### 스키마

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

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = {
  /** 코인 입금 ID. Example: 1234 */
  id: number;
  /** 블록체인 네트워크 심볼. Example: "ETH" */
  network: string;
  /** 입금 주소. Example: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" */
  address: string;
  /** 입금 2차 주소 (Destination Tag, Memo 등. 없으면 null) */
  secondaryAddress?: string | null;
  /** 입금 진행 상황 */
  status:
    | "pending"  // 블록체인 네트워크에서 입금 트랜잭션을 발견한 상태
    | "actionRequired"  // 입금계류 서류제출 대기 중 (입금을 위해서는 코빗 웹사이트에서 필요한 서류를 제출해야 합니다.)
    | "reviewing"  // 입금계류 제출서류 심사 중
    | "done"  // 입금 완료
    | "refunded"  // 심사 거절 후 입금 금액이 반환된 상태
    | "failed"  // 입금 실패 (입금 트랜잭션에 문제가 있는 경우 등)
    ;
  /** 블록체인 트랜잭션 해시. Example: "0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f" */
  transactionHash: string;
  /** 입금 중인 가상자산의 심볼. Example: "btc" */
  currency: string;
  /** 입금 중인 가상자산의 수량 (트랜잭션에 기록되는 수량과 같음). Example: "1.234" */
  quantity: string;
  /** 입금 수신 시각(timestamp). Example: 1700000000000 */
  createdAt: number;
};
```

### 예시

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