CLI

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에서 LTS 버전을 설치하세요.

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

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

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

인증 설정

시세 조회는 인증 없이 사용할 수 있습니다. 잔고 조회, 주문, 입출금은 API Key가 필요합니다. 해당 기능을 사용하려면 빗썸 API 관리 페이지에서 발급하세요.

export BITHUMB_ACCESS_KEY="발급받은_액세스_키"
export BITHUMB_SECRET_KEY="발급받은_시크릿_키"

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

환경 변수 대신 ~/.bithumb/config.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 명령으로 같은 작업을 할 수 있습니다.

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 프로필

정상 동작 확인

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

bithumb market ticker KRW-BTC

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

bithumb account assets

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

bithumb system diagnose

문제가 발생했다면 문제 해결을 참고하세요.

기능 모듈

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

시세 조회(market)

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

# 거래 가능 페어 목록 조회
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 목록과 만료일을 조회합니다.

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

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

주문(trade)

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

# 지정가 매수
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) 알고리즘 분할 주문을 생성, 조회, 취소합니다.

# 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)

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

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차 인증이 필요합니다.

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

출금(withdraw)

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

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차 인증이 필요합니다.

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

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

⚠️
원화 입금(deposit krw)과 원화 출금(withdraw krw)은 빗썸의 2차 인증이 필요합니다. 실행 전에 API Key에 해당 권한이 있는지 확인하세요.

유틸리티

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

config

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

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

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

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

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

실행 로그

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

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

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를 추가하세요.

출력 형식과 데이터 처리

기본 출력

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

bithumb market ticker KRW-BTC
bithumb account assets

JSON 출력

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

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

데이터 필터링

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

# 일봉 종가만 추출
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

페이지네이션

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

# 개수 기반(캔들, 공지)
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는 네트워크, 인증, 설정, 모듈 상태를 한 번에 점검합니다. 문제가 생겼을 때 가장 먼저 실행하세요.

bithumb system diagnose

정상 출력 예시:

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로 출력합니다. 응답이 예상과 다를 때 어떤 요청이 어떻게 처리됐는지 확인하는 용도로 사용하세요.

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	—

더 알아보기

MCP

Claude Desktop, Cursor 같은 MCP 클라이언트에서 자연어로 빗썸 도구를 호출합니다.

Skills

Claude Code, Codex 같은 AI 에이전트에 빗썸 Skill을 등록해 여러 단계 작업을 자동으로 처리합니다.

AI 트레이드 킷 시작하기

AI 트레이드 킷의 개요와 시작 가이드를 안내합니다.