@debate300/bithumb-pro/README.md

A real-time cryptocurrency price tracker for Bithumb (Pro).

# 빗썸 실시간 암호화폐 시세 표시기 (Pro)

[![NPM Version](https://img.shields.io/npm/v/@debate300/bithumb-pro.svg)](https://www.npmjs.com/package/@debate300/bithumb-pro)
[![NPM Downloads](https://img.shields.io/npm/dm/@debate300/bithumb-pro.svg)](https://www.npmjs.com/package/@debate300/bithumb-pro)

## Install

```bash
npm i -g @debate300/bithumb-pro
```

빗썸 거래소의 암호화폐 시세를 터미널에 실시간으로 표시하는 커맨드 라인 인터페이스(CLI) 애플리케이션입니다. `pro` 버전은 빗썸 API 키와 연동하여 사용자의 실제 자산 현황을 포함한 상세 정보를 제공하는 전문가용 버전입니다.

## `pro` 버전 주요 기능

- **기능**: 실시간 시세 추적, 한글 코인 이름, 수익률 계산, 시장 분위기 분석 등 기본 기능을 모두 포함합니다.
- **자동 포트폴리오 연동**: 빗썸 계좌에 보유한 모든 암호화폐 자산을 자동으로 가져와 시세와 함께 표시합니다.
- **상세 자산 정보**: 개별 코인의 평가손익, 보유수량, 매수금액, 평가금액을 상세히 보여줍니다.
- **종합 포트폴리오 요약**: 총 매수금액, 총 평가금액, 총 평가손익, 보유 원화(KRW) 등 전체 자산 현황을 한눈에 파악할 수 있습니다.
- **보유금액 순 정렬**: `--sort-by my` 옵션을 통해 보유한 코인을 평가금액 순으로 정렬할 수 있습니다.
- **실시간 가격 변동 알림**: 설정된 코인의 가격이 5%의 배수로 상승 또는 하락할 때마다 시스템 알림을 통해 즉시 알려줍니다.
- **인터랙티브 화면 전환**: `/1` (실시간 시세), `/2` (미체결 주문) 명령어를 통해 두 가지 화면을 실시간으로 전환하며 자산 현황과 주문 내역을 동시에 확인할 수 있습니다.

---

## 설치 및 실행

### 1. 사전 요구사항: Node.js 설치

이 애플리케이션을 실행하려면 [Node.js](https://nodejs.org/) (버전 18.x 이상 권장)가 시스템에 설치되어 있어야 합니다. Node.js를 설치하면 `npm`과 `npx`가 함께 설치됩니다.

[Node.js 공식 웹사이트](https://nodejs.org/ko/download)에서 사용 중인 운영체제에 맞는 LTS 버전을 다운로드하여 설치하세요.

### 2. 전역 설치/실행

모든 설정이 완료되면 터미널에 다음 명령어를 입력하여 바로 실행할 수 있습니다.

- **전역 설치 후 실행:**
  ```bash
  npm install -g @debate300/bithumb-pro
  debate300-pro
  ```

### 3. API 키 설정: `api_keys.json` (가장 중요)

`pro` 버전의 핵심 기능인 자동 자산 연동을 위해 API 키가 반드시 필요합니다.

**프로그램을 처음 실행하면, `~/.debate300/` 폴더에 `api_keys.json` 파일이 자동으로 생성됩니다.**

프로그램을 사용하기 전에, 이 파일을 열어 빗썸에서 발급받은 실제 API 키를 입력해야 합니다.

- **파일 위치**: `~/.debate300/api_keys.json` (macOS/Linux) 또는 `C:\Users\YOUR_USERNAME\.debate300\api_keys.json` (Windows)
- **파일 내용 (수정 필요)**:
  `json
  {
    "bithumb_api_key": "YOUR_API_KEY",
    "bithumb_secret_key": "YOUR_SECRET_KEY"
  }
  `
  **참고:** API 키가 설정되지 않은 상태로 프로그램을 실행하면, 키를 입력하라는 에러 메시지가 표시되고 프로그램이 종료됩니다.

#### API 키 발급 방법

- **중요:** 반드시 **API 버전 v2.0** 이상 을 선택하여 키를 생성해야 합니다.

1.  [빗썸 API 관리](https://www.bithumb.com/react/api-support/management-api) 페이지로 이동합니다.
2.  **`자산 조회`, `주문 조회`** 권한을 체크하여 API 키를 생성합니다. **보안을 위해 다른 모든 권한은 반드시 해제하세요.**
3.  **IP 주소 설정:**
    - **팁:** IP 주소는 특정 IP에서만 API를 사용하도록 제한하는 보안 기능입니다. 현재 사용 중인 PC의 IP를 입력해야 합니다.
    - IP를 모르는 경우
    - API/Secret Key를 api_keys.json 에 입력후 프로그램을 실행하면, 카카오/SMS 로 접속 IP 알림오니 참조 하세요.
4.  **`Secret Key`는 발급 시 한 번만 표시되므로, 즉시 안전한 곳에 복사**해두세요.

### 3. 코인 목록 설정: `config.json` (선택 사항)

프로그램을 처음 실행하면, 시가총액 상위 30개 코인이 포함된 `config.json` 파일이 `~/.debate300/` 폴더에 자동으로 생성됩니다.

`api_keys.json`을 사용하면 보유한 코인은 자동으로 목록에 추가되므로, 이 파일에는 **보유하고 있지 않지만 시세를 추적하고 싶은 코인**만 추가하면 됩니다.

원하는 코인 목록으로 변경하려면 아래와 같이 `coins` 배열을 수정하세요. (예: 비트코인, 이더리움, 리플만 추적)

```json
{
  "coins": [
    {
      "symbol": "BTC",
      "icon": "₿",
      "averagePurchasePrice": 0,
      "unit_currency": "KRW"
    },
    {
      "symbol": "ETH",
      "icon": "Ξ",
      "averagePurchasePrice": 0,
      "unit_currency": "KRW"
    },
    {
      "symbol": "XRP",
      "icon": "✕",
      "averagePurchasePrice": 0,
      "unit_currency": "KRW"
    }
  ]
}
```

---

## 메뉴 사용법

프로그램 실행 시 다음과 같은 옵션을 사용할 수 있습니다.

### 실행 옵션

- `--sort-by`: 정렬 기준을 선택합니다.

  - `my` (**`pro` 브랜치 기본값**): 보유 코인을 평가금액이 높은 순으로 정렬합니다.
  - `rate`: 등락률 기준 내림차순 정렬.
  - `name`: 코인 이름(심볼) 기준 오름차순 정렬.

- `--limit`: 표시할 코인의 최대 개수를 지정합니다. (예: `--limit 10`)

### 인터랙티브 명령어

프로그램 실행 중 다음 명령어를 입력하여 화면을 전환할 수 있습니다.

- `/1` 또는 `/시세`: 실시간 시세 화면으로 전환합니다. (기본값)
- `/2` 또는 `/미체결`: 미체결 주문 내역 화면으로 전환합니다.
- `/exit`: 프로그램을 종료합니다.

---

## 출력 예시 (`pro` 브랜치)

Bithumb 실시간 시세 (Ctrl+C to exit)

> 전체 시장: 하락세 📉 | 체결강도: 88.45 | 총 매수: 15,000,000 KRW | 총 평가: 14,500,000 KRW | 총 손익: <span style="color:blue">-500,000 KRW</span> | 보유원화: 1,234,567 KRW

| 코인           | 현재가     | 전일대비 | 전일대비금액 | 체결강도 | 평가손익                                   | 수익률  | 보유수량 | 평균매수가 | 매수금액  | 평가금액   | 전일종가   | 고가       | 저가       |
| :------------- | :--------- | :------- | :----------- | :------- | :----------------------------------------- | :------ | :------- | :--------- | :-------- | :--------- | :--------- | :--------- | :--------- |
| ₿ BTC 비트코인 | 91,000,000 | -0.55%   | -500,000     | 95.23    | <span style="color:red">+1,000,000</span>  | +10.00% | 0.11     | 90,000,000 | 9,900,000 | 10,010,000 | 91,500,000 | 92,000,000 | 90,500,000 |
| Ξ ETH 이더리움 | 4,500,000  | -1.10%   | -50,000      | 85.10    | <span style="color:blue">-1,500,000</span> | -30.00% | 1.00     | 6,000,000  | 6,000,000 | 4,500,000  | 4,550,000  | 4,600,000  | 4,450,000  |

## 라이선스

이 프로젝트는 ISC 라이선스를 따릅니다.