---
updatedAt: 2026-07-09T08:19:11.000Z
agentTools:
  projectIndex: https://apidocs.bithumb.com/llms.txt
---

# CLI

터미널에서 bithumb 명령으로 빗썸 API를 호출합니다.

## CLI란?

터미널에서 `bithumb` 명령 한 줄로 빗썸 v2.1.5 API를 호출하는 도구입니다. 별도의 코드 작성 없이 시세 조회, 주문, 입출금을 실행할 수 있고, 셸 스크립트, cron, CI에 넣어 자동화하거나 API 응답을 빠르게 검증할 때 유용합니다.

## 설치

CLI는 AI 에이전트로 설치하거나 직접 설치할 수 있습니다. Claude Code, Codex 같은 에이전트를 이미 쓰고 있다면 아래 **AI 에이전트로 설치**가 가장 빠릅니다.

### AI 에이전트로 설치

Claude Code, Codex처럼 에이전트 기능을 지원하는 도구를 쓰고 있다면, 빗썸이 제공하는 에이전트 전용 설치 가이드를 그대로 전달해 Node.js 점검, CLI 설치, Skill 등록까지 한 번에 맡길 수 있습니다.

에이전트에 다음 프롬프트를 입력하세요.

```
`https://github.com/bithumb-official/bithumb-ai-trade-kit/blob/main/setup-cli-skills.md`을 읽고, 빗썸 CLI와 Skill을 설치, 설정해줘
```

에이전트가 페이지를 읽고 Node.js 버전 점검, CLI 전역 설치, Skill 설치를 순서대로 수행합니다. 인증이 필요한 작업을 사용하려면 [인증 설정](#인증-설정)에서 API Key를 등록한 뒤 [정상 동작 확인](#정상-동작-확인)으로 이동하세요. 에이전트가 처리에 실패하면 아래 **수동 설치**를 따르세요.

### 수동 설치

Node.js 18 이상이 필요합니다. `node -v`로 버전을 확인하고, 설치되어 있지 않다면 [nodejs.org](https://nodejs.org/ko/download)에서 LTS 버전을 설치하세요.

Node.js가 준비되면 npm으로 CLI를 전역 설치하고 버전을 확인합니다.

```bash
npm install -g @bithumb-official/bithumb-cli
bithumb --version
```

인증이 필요한 작업을 사용하려면 이어서 아래 **인증 설정**에서 API Key를 등록하세요. AI 에이전트에게 자연어로 여러 단계 작업을 맡기려면 [Skills 페이지](skills#수동-설치)에서 스킬도 함께 설치하세요.

## 인증 설정

시세 조회는 인증 없이 사용할 수 있습니다. 잔고 조회, 주문, 입출금은 API Key가 필요합니다. 해당 기능을 사용하려면 빗썸 [API 관리 페이지](https://www.bithumb.com/react/api-support/management-api)에서 발급하세요.

<Tabs>
  <Tab title="macOS / Linux">
    ```bash
    export BITHUMB_ACCESS_KEY="발급받은_액세스_키"
    export BITHUMB_SECRET_KEY="발급받은_시크릿_키"
    ```

    위 명령은 현재 세션에만 적용됩니다. 터미널을 새로 열 때마다 자동으로 적용하려면 `~/.zshrc` 또는 `~/.bashrc`에 추가하세요.
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell
    $env:BITHUMB_ACCESS_KEY="발급받은_액세스_키"
    $env:BITHUMB_SECRET_KEY="발급받은_시크릿_키"
    ```

    위 명령은 현재 세션에만 적용됩니다. 영구 등록하려면 아래처럼 `setx`를 사용하세요. 적용하려면 새 터미널을 열어야 합니다.

    ```powershell
    setx BITHUMB_ACCESS_KEY "발급받은_액세스_키"
    setx BITHUMB_SECRET_KEY "발급받은_시크릿_키"
    ```
  </Tab>

  <Tab title="Windows CMD">
    ```cmd
    set BITHUMB_ACCESS_KEY=발급받은_액세스_키
    set BITHUMB_SECRET_KEY=발급받은_시크릿_키
    ```

    위 명령은 현재 세션에만 적용됩니다. 영구 등록하려면 아래처럼 `setx`를 사용하세요. 적용하려면 새 터미널을 열어야 합니다.

    ```cmd
    setx BITHUMB_ACCESS_KEY "발급받은_액세스_키"
    setx BITHUMB_SECRET_KEY "발급받은_시크릿_키"
    ```
  </Tab>
</Tabs>

환경 변수 대신 `~/.bithumb/config.toml`에 프로필 단위로 키를 보관할 수도 있습니다. 프로필을 사용하면 매매용, 조회 전용 등 용도별로 키를 분리해 관리할 수 있습니다.

```toml
default_profile = "default"

[profiles.default]
access_key = "your-access-key"
secret_key = "your-secret-key"
read_only = false

[profiles.readonly]
access_key = "your-access-key"
secret_key = "your-secret-key"
read_only = true
```

`read_only = true`로 설정한 프로필은 주문, 입출금 같은 쓰기 작업을 차단하고 시세, 잔고 확인 등 읽기 작업만 허용합니다.

응답이 자주 끊긴다면 프로필에 `timeout_ms`(밀리초)를 추가해 HTTP 요청 타임아웃을 조정하세요.

TOML 파일을 직접 편집하는 대신 `bithumb config` 명령으로 같은 작업을 할 수 있습니다.

```bash
bithumb config init                    # 설정 파일 생성(interactive)
bithumb config add-profile     # 새 프로필 추가(interactive)
bithumb config use trading             # default 프로필 변경
```

자세한 `config` 명령은 [유틸리티](#유틸리티) 섹션을 참고하세요.

인증 정보 우선순위는 `--profile` 옵션 사용 여부에 따라 달라집니다. **`--profile`을 명시하면 TOML 프로필이 환경변수보다 우선**되고, **생략하면 환경변수가 TOML의 default 프로필보다 우선**됩니다.

| 상황                       | 사용되는 프로필                    |
| ------------------------ | --------------------------- |
| `--profile <name>` 명시    | TOML의 `<name>` 프로필(환경변수 무시) |
| `--profile` 생략 + 환경변수 있음 | 환경변수                        |
| `--profile` 생략 + 환경변수 없음 | TOML의 default 프로필           |

## 정상 동작 확인

먼저 인증이 필요 없는 시세 조회 명령으로 설치 상태를 확인합니다.

```bash
bithumb market ticker KRW-BTC
```

인증 설정까지 완료됐다면 잔고 조회도 정상적으로 동작하는지 확인합니다.

```bash
bithumb account assets
```

전체 상태를 한 번에 점검하려면 `system diagnose` 명령을 사용하세요. 네트워크 연결, JWT 서명, 활성 모듈, 설정 로드 상태 등을 검사해 결과를 요약해서 보여줍니다.

```bash
bithumb system diagnose
```

문제가 발생했다면 [문제 해결](#문제-해결)을 참고하세요.

## 기능 모듈

CLI는 빗썸 API 기능을 6개의 기능 모듈로 나눠 제공합니다. 전체 명령 구조는 `bithumb --help`로, 모듈별 옵션은 `bithumb <module> --help`로 확인할 수 있습니다.

### 시세 조회(market)

API Key 인증 필요 없이 공개 시세 데이터를 조회할 수 있는 기능입니다.

```bash
# 거래 가능 페어 목록 조회
bithumb market markets

# 현재가 조회(단일 또는 복수)
bithumb market ticker KRW-BTC
bithumb market ticker KRW-BTC,KRW-ETH

# 호가창 조회
bithumb market orderbook KRW-BTC

# 분봉 캔들(OHLCV) 조회 — 단위: 1, 3, 5, 10, 15, 30, 60, 240분
bithumb market candles-minutes KRW-BTC --unit 5 --count 24

# 일봉, 주봉, 월봉 캔들 조회
bithumb market candles-days KRW-BTC --count 30
bithumb market candles-weeks KRW-BTC --count 12
bithumb market candles-months KRW-BTC --count 12

# 최근 체결 내역 조회
bithumb market trades KRW-BTC --count 50

# 입출금 수수료 조회(특정 통화 또는 ALL)
bithumb market fee-inout BTC

# 공지사항 목록 조회
bithumb market notices --count 5

# 투자경보 페어 목록 조회
bithumb market warnings
```

### 자산 조회(account)

잔고, 주문 가능 정보, 입출금 현황, API Key 목록과 만료일을 조회합니다.

```bash
bithumb account assets
bithumb account order-chance --market KRW-BTC  # 주문 가능 정보 조회(가용 잔고, 수수료, 한도)

bithumb account wallet-status                   # 입출금 현황 조회(블록 상태, 가능 여부)
bithumb account api-keys
```

### 주문(trade)

주문 요청, 취소, 조회 등을 처리합니다.

```bash
# 지정가 매수
bithumb trade place \
  --market KRW-BTC --side bid --order-type limit \
  --price 50000000 --volume 0.001

# 시장가 매수
bithumb trade place \
  --market KRW-BTC --side bid --order-type price \
  --price 100000

# 시장가 매도
bithumb trade place \
  --market KRW-BTC --side ask --order-type market \
  --volume 0.001

# 주문 리스트 조회
bithumb trade list --market KRW-BTC --state wait

# 개별 주문 조회 및 취소
bithumb trade get --order-id <order-id>
bithumb trade cancel --order-id <order-id>

# 다건 주문 일괄 생성
bithumb trade batch-place --file ./orders.json

# 다건 주문 일괄 취소
bithumb trade batch-cancel --order-ids id1,id2,id3
```

### TWAP 주문(twap)

TWAP(Time-Weighted Average Price) 알고리즘 분할 주문을 생성, 조회, 취소합니다.

```bash
# 1시간 동안 60초 간격으로 분할 매수
bithumb twap place \
  --market KRW-BTC --side bid \
  --duration 3600 --frequency 60 \
  --price 50000000

bithumb twap list --market KRW-BTC
bithumb twap cancel --algo-order-id <id>
```

### 입금(deposit)

입금 주소 생성·조회, 입금 내역, 원화 입금을 처리합니다.

```bash
bithumb deposit list --currency BTC
bithumb deposit get --currency BTC --deposit-id <deposit-id>
bithumb deposit address --currency BTC --net-type BTC        # 특정 통화·네트워크 입금 주소 조회
bithumb deposit addresses                                     # 전체 입금 주소 조회
bithumb deposit generate-address --currency BTC --net-type BTC  # 입금 주소 생성 요청
bithumb deposit list-krw
```

원화 입금은 2차 인증이 필요합니다.

```bash
# 원화 입금
bithumb deposit krw \
  --amount 10000 \
  --two-factor-type kakao
```

### 출금(withdraw)

가상자산 및 원화 출금을 처리합니다.

```bash
bithumb withdraw chance --currency BTC --net-type BTC    # 출금 가능 정보 조회(잔고, 수수료, 한도)
bithumb withdraw list --currency BTC
bithumb withdraw get --currency BTC --withdrawal-id <withdrawal-id>
bithumb withdraw list-krw
bithumb withdraw addresses                                # 출금 허용 주소 리스트 조회
bithumb withdraw cancel --withdrawal-id <id>
```

원화 출금은 2차 인증이 필요합니다.

```bash
# 가상자산 출금
bithumb withdraw coin \
  --currency BTC --net-type BTC \
  --address <출금주소> \
  --amount 0.001

# 원화 출금
bithumb withdraw krw \
  --amount 10000 \
  --two-factor-type kakao
```

<Callout icon="fa-triangle-exclamation" theme="warning">
  원화 입금(`deposit krw`)과 원화 출금(`withdraw krw`)은 빗썸의 2차 인증이 필요합니다. 실행 전에 API Key에 해당 권한이 있는지 확인하세요.
</Callout>

## 유틸리티

기능 모듈과 별개로, CLI는 시스템 정보 조회, 연결 진단, 설정 관리에 쓰는 유틸리티 명령을 제공합니다.

### config

CLI 설정 파일을 관리합니다. 프로필 단위로 키와 `read_only` 옵션을 관리합니다.

```bash
bithumb config show                                       # 현재 설정 출력
bithumb config show --profile trading                     # 특정 프로필 설정 출력
bithumb config init                                       # 설정 파일 생성(interactive)
bithumb config set                                        # 현재 프로필 편집(interactive)
bithumb config add-profile                                # 새 프로필 추가(interactive)
bithumb config list-profiles                              # 프로필 목록 출력
bithumb config use trading                                # default 프로필 변경
bithumb config path                                       # 설정 파일 경로 출력
```

### system

설정·연결 진단과 로컬 실행 로그를 다룹니다.

```bash
bithumb system diagnose  # 네트워크, 인증, 설정, 모듈 상태 점검
bithumb system audit     # 실행 로그 조회
```

`system diagnose`는 설치 직후 통합 점검이나 오류 발생 시 첫 진단 도구로 사용하세요. 출력 예시는 [문제 해결](#문제-해결)을 참고하세요. `system audit`의 필터 옵션은 [실행 로그](#실행-로그) 섹션을 참고하세요.

## 실행 로그

CLI는 모든 명령 실행 내역을 `~/.bithumb/logs/trade-YYYY-MM-DD.log`에 기록합니다. 명령 이름, 입력값, 응답 요약, 처리 시간이 함께 저장돼 분석·디버깅에 활용할 수 있습니다.

조회는 `bithumb system audit` 명령으로 합니다. 필터 옵션을 지원합니다.

```bash
bithumb system audit --limit 20                            # 최근 20건
bithumb system audit --level ERROR                         # 에러만
bithumb system audit --tool trade_place_order              # 특정 명령만
bithumb system audit --since 2025-05-01T00:00:00+09:00     # 특정 시점 이후
```

같은 파일을 MCP 서버의 `system_get_audit_log` 도구와 Skills도 조회합니다. MCP에서 기록을 비활성화하려면 클라이언트 설정의 `args`에 `--no-log`를 추가하세요.

## 출력 형식과 데이터 처리

### 기본 출력

옵션 없이 실행하면 표 또는 키-값 형태로 출력됩니다.

```bash
bithumb market ticker KRW-BTC
bithumb account assets
```

### JSON 출력

`--json` 옵션을 붙이면 API 원본 응답을 그대로 출력합니다. 자동화 스크립트라면 `--json`을 쓰는 게 좋습니다.

```bash
bithumb market ticker KRW-BTC --json
bithumb account assets --json
```

### 데이터 필터링

`--json` 출력을 `jq` 같은 도구와 조합하면 필요한 필드만 추출할 수 있습니다.

```bash
# 일봉 종가만 추출
bithumb market candles-days KRW-BTC --count 30 --json \
  | jq '.[].trade_price'

# 잔고 중 KRW만 추출
bithumb account assets --json \
  | jq '.[] | select(.currency == "KRW")'

# 페어 심볼만 정렬해서 출력
bithumb market markets --json | jq -r '.[].market' | sort
```

## 페이지네이션

목록 조회는 엔드포인트마다 페이지 처리 방식이 다릅니다.

```bash
# 개수 기반(캔들, 공지)
bithumb market candles-days KRW-BTC --count 200
bithumb market notices --count 5

# 페이지 + 한도 기반(주문, 입출금 내역)
bithumb trade list --market KRW-BTC --state done --limit 100 --page 2
bithumb deposit list --currency BTC --limit 100 --page 1  # --limit 최대 100

# 체결 내역 페이지 넘김
bithumb market trades KRW-BTC --count 100                              # 최신 N건
bithumb market trades KRW-BTC --count 100 --cursor <previous-cursor>   # cursor 기준 이전 페이지
bithumb market trades KRW-BTC --count 100 --days-ago 7                 # N일 전 시점부터 조회

# 과거 캔들 이동(KST naive, 타임존 오프셋 없이)
bithumb market candles-days KRW-BTC --count 200 --to 2025-01-01T00:00:00
```

## 문제 해결

### 연결 진단

`bithumb system diagnose`는 네트워크, 인증, 설정, 모듈 상태를 한 번에 점검합니다. 문제가 생겼을 때 가장 먼저 실행하세요.

```bash
bithumb system diagnose
```

정상 출력 예시:

```text
summary: 5/5 checks passed
checks:
  name: API Reachability
  status: pass
  message: https://api.bithumb.com reachable (HTTP 200)
  name: Authentication
  status: pass
  message: API keys configured (BITHUMB_ACCESS_KEY/BITHUMB_SECRET_KEY env vars or config.toml profile)
  name: TOML Config
  status: pass
  message: Found /Users/<user>/.bithumb/config.toml
  name: Enabled Modules
  status: pass
  message: Active: market, account, trade, twap, withdraw, deposit, system
  name: Auth Validity
  status: pass
  message: API key accepted by server
```

`status: fail`인 항목이 있으면 해당 `message`를 참고해 조치합니다.

### 상세 로깅

`--verbose` 옵션을 붙이면 요청 URL, 응답 시간, 디버그 정보를 stderr로 출력합니다. 응답이 예상과 다를 때 어떤 요청이 어떻게 처리됐는지 확인하는 용도로 사용하세요.

```bash
bithumb account assets --verbose
```

## 전역 옵션

| 옵션                 | 설명                                 | 기본값     |
| ------------------ | ---------------------------------- | ------- |
| `--json`           | 응답을 원본 JSON으로 출력                   | `false` |
| `--verbose`        | 상세 로깅                              | `false` |
| `--profile <name>` | TOML에서 사용할 프로필 지정. 명시 시 환경변수보다 우선됨 | —       |
| `-h, --help`       | 도움말 출력                             | —       |
| `-v, --version`    | 버전 출력                              | —       |

## 환경 변수

| 변수                   | 설명             | 기본값 |
| -------------------- | -------------- | --- |
| `BITHUMB_ACCESS_KEY` | API Access Key | —   |
| `BITHUMB_SECRET_KEY` | API Secret Key | —   |

## 더 알아보기

<Cards>
  <Card title="MCP" href="mcp" icon="fa-plug">
    Claude Desktop, Cursor 같은 MCP 클라이언트에서 자연어로 빗썸 도구를 호출합니다.
  </Card>

  <Card title="Skills" href="skills" icon="fa-wand-magic-sparkles">
    Claude Code, Codex 같은 AI 에이전트에 빗썸 Skill을 등록해 여러 단계 작업을 자동으로 처리합니다.
  </Card>

  <Card title="AI 트레이드 킷 시작하기" href="ai-트레이드-킷-시작하기" icon="fa-rocket">
    AI 트레이드 킷의 개요와 시작 가이드를 안내합니다.
  </Card>
</Cards>