# 원화 입출금

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

## 입금 요청 {#post-_v2_krw_sendKrwDepositPush}

```
POST /v2/krw/sendKrwDepositPush
```

코빗 모바일 앱으로 원화 입금 요청 알림을 전송합니다.
알림 수신 후, 앱에서 인증을 완료해야 원화 입금이 진행됩니다.
알림 수신을 위해서는 앱 알림 설정에서 앱 푸시 알림 받기 설정이 되어 있어야 합니다.

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

### 스키마

```ts
// POST 본문 — `Content-Type: application/x-www-form-urlencoded`
type RequestBody = {
  /** 어카운트 시퀀스 번호. 입출금 API는 메인 어카운트에서만 동작하므로 `1`만 입력 가능합니다. 기본값은 1. Example: 1 */
  accountSeq?: number;
  /** 입금 요청할 금액. Example: "50000" */
  amount: string;
};
```

### 예시

#### 요청
```sh
curl -X POST -H X-KAPI-KEY=API키 'https://api.korbit.co.kr/v2/krw/sendKrwDepositPush' -H Content-Type: application/x-www-form-urlencoded --data-raw amount=50000&timestamp=시각&signature=서명
```
#### 응답
```json
{"success":true}
```

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

```
POST /v2/krw/sendKrwWithdrawalPush
```

코빗 모바일 앱으로 원화 출금 요청 알림을 전송합니다.
알림 수신 후, 앱에서 인증을 완료해야 원화 출금이 진행됩니다.
알림 수신을 위해서는 앱 알림 설정에서 앱 푸시 알림 받기 설정이 되어 있어야 합니다.

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

### 스키마

```ts
// POST 본문 — `Content-Type: application/x-www-form-urlencoded`
type RequestBody = {
  /** 어카운트 시퀀스 번호. 입출금 API는 메인 어카운트에서만 동작하므로 `1`만 입력 가능합니다. 기본값은 1. Example: 1 */
  accountSeq?: number;
  /** 출금 요청할 금액. Example: "50000" */
  amount: string;
};
```

### 예시

#### 요청
```sh
curl -X POST -H X-KAPI-KEY=API키 'https://api.korbit.co.kr/v2/krw/sendKrwWithdrawalPush' -H Content-Type: application/x-www-form-urlencoded --data-raw amount=50000&timestamp=시각&signature=서명
```
#### 응답
```json
{"success":true}
```

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

```
GET /v2/krw/recentDeposits
```

최근 KRW 입금 내역을 조회합니다.

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

### 스키마

```ts
// URL 쿼리 파라미터
type RequestQuery = {
  /** 어카운트 시퀀스 번호. 입출금 API는 메인 어카운트에서만 동작하므로 `1`만 입력 가능합니다. 기본값은 1. Example: 1 */
  accountSeq?: number;
  /** 최대 조회 건수 (범위: 1 - 100). Example: 100 */
  limit?: number;
  /** 전체 내역 조회 여부 */
  includeAll?:
    | "false"  // 일반 원화 입금만 (기본값)
    | "true"  // 원화 입금 외 예치금 이용료, 이벤트 보상 지급 등 포함
    ;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = Array<{
  /** KRW 입금 ID. Example: 1234 */
  id: number;
  /** 입금 구분 (includeAll=true인 경우) */
  type?:
    | "general"  // 일반 원화 입금
    | "depositInterest"  // 예치금 이용료
    | "makerIncentive"  // 메이커 인센티브
    | "reward"  // 이벤트 보상
    | "etc"  // 기타
    ;
  /** KRW 입금 진행 상황 */
  status:
    | "pending"  // 입금 접수중
    | "processing"  // 입금 처리중
    | "reviewing"  // 입금 심사중 (취소 가능)
    | "done"  // 입금 완료
    | "canceling"  // 입금 취소 접수됨
    | "canceled"  // 입금 취소 완료
    | "failed"  // 입금 실패
    ;
  /** 입금 금액. Example: "1.234" */
  quantity: string;
  /** 입금 수신 시각(timestamp). Example: 1700000000000 */
  createdAt: number;
}>;
```

### 예시

#### 요청
```sh
curl -H X-KAPI-KEY=API키 'https://api.korbit.co.kr/v2/krw/recentDeposits?limit=100&timestamp=시각&signature=서명'
```
#### 응답
```json
{
  "success": true,
  "data": [
    {
      "id": 1234,
      "status": "done",
      "quantity": "50000",
      "createdAt": 1700000000000
    }
  ]
}
```

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

```
GET /v2/krw/recentWithdrawals
```

최근 KRW 출금내역을 조회합니다.

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

### 스키마

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

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = Array<{
  /** KRW 출금 ID. Example: 1234 */
  id: number;
  /** 출금된 KRW 수량. (수수료 제외 수량). Example: "50000" */
  quantity: string;
  /** 출금 수수료. Example: "1000" */
  fee: string;
  /** KRW 출금 진행 상황 */
  status:
    | "pending"  // 출금 요청 접수됨
    | "reviewing"  // 출금 심사 중. 코빗 정책에 따라 심사 후 출금이 지연될 수 있습니다.
    | "processing"  // 출금 처리중
    | "done"  // 출금 완료
    | "failed"  // 출금 실패
    | "canceled"  // 출금 취소
    ;
  /** 출금 요청 시각(timestamp). Example: 1700000000000 */
  createdAt: number;
}>;
```

### 예시

#### 요청
```sh
curl -H X-KAPI-KEY=API키 'https://api.korbit.co.kr/v2/krw/recentWithdrawals?limit=100&timestamp=시각&signature=서명'
```
#### 응답
```json
{
  "success": true,
  "data": [
    {
      "id": 1234,
      "quantity": "50000",
      "fee": "1000",
      "status": "done",
      "createdAt": 1700000000000
    }
  ]
}
```