Upbit CLI

Upbit CLI란 무엇인가요?

CLI(Command Line Interface)는 텍스트 기반의 명령줄 인터페이스로, 터미널에서 명령어를 입력하여 기능을 실행하는 방식입니다.
Upbit CLI는 터미널 환경에서 Upbit API를 호출할 수 있도록 제공되는 공식 명령줄 도구입니다.

Upbit CLI를 사용하면 별도의 코드 작성 없이 업비트 개발자센터에서 지원하는 시세 조회, 계좌 조회, 주문 조회 등의 작업을 수행할 수 있습니다. 명령어 기반으로 API를 실행할 수 있어 반복적인 작업을 간단하게 처리할 수 있습니다.

언제 사용하나요?

다음과 같은 경우 Upbit CLI 사용을 권장합니다.

• 터미널에서 업비트 API를 빠르게 호출하고 결과를 확인하고 싶은 경우
• 반복적인 API 호출을 스크립트로 구성하려는 경우
• API 응답을 검증하거나 문제를 디버깅하려는 경우

사전 준비

Upbit CLI를 사용하려면 다음이 필요합니다.

• Node.js 및 npm 또는 Go 환경
• 업비트 Open API Key
  • 인증이 필요한 API를 사용하려면 Access Key와 Secret Key가 필요합니다.
  • 인증이 필요한 API 목록은 Upbit API 이용 준비 문서에서 확인 가능합니다.

어떻게 시작하나요?

npm으로 설치

npm install -g @upbit-official/upbit-cli

Go로 설치

go install github.com/upbit-official/upbit-cli/cmd/upbit@latest

설치 후 바이너리는 Go bin 디렉토리에 생성됩니다.

설치가 완료되면 upbit 실행 파일이 Go에서 사용되는 bin폴더에 생성됩니다. 해당 경로가 PATH에 포함되어 있으면 터미널에서 upbit 명령을 바로 실행할 수 있습니다.

설치 확인

upbit --version

Windows에서도 동일하게 설치할 수 있습니다. 단, 환경변수 설정 방식은 PowerShell 또는 CMD에 따라 다릅니다.

인증 정보 설정

인증이 필요한 API를 사용하려면 API Key를 환경 변수로 설정(권장)합니다.

macOS / Linux

export UPBIT_ACCESS_KEY=<your-access-key>
export UPBIT_SECRET_KEY=<your-secret-key>

Windows PowerShell

$env:UPBIT_ACCESS_KEY="your-access-key"
$env:UPBIT_SECRET_KEY="your-secret-key"

Windows CMD

set UPBIT_ACCESS_KEY=your-access-key
set UPBIT_SECRET_KEY=your-secret-key

명령 실행 시 플래그로 API Key를 직접 전달할 수도 있습니다.

upbit accounts list \
  --access-key "$UPBIT_ACCESS_KEY" \
  --secret-key "$UPBIT_SECRET_KEY"

정상 동작 확인은 어떻게 하나요?

먼저 공개 API를 호출해 CLI가 정상적으로 설치되었는지 확인합니다.

upbit trading-pairs list --is-details=false

정상적으로 실행되면 마켓 목록이 반환됩니다.

이후 인증이 필요한 API를 호출해 인증 정보가 올바른지 확인합니다.

upbit accounts list

정상적으로 설정된 경우 보유 자산 목록을 반환합니다.

어떤 작업을 할 수 있나요?

시세 조회

upbit tickers list-by-trading-pairs --markets "KRW-BTC"

마켓 정보 조회

upbit trading-pairs list

주문 및 계좌 조회

upbit orders list-open --market KRW-BTC
upbit accounts list

입출금 조회

upbit deposits list
upbit withdrawals list

출력 형식과 데이터 처리는 어떻게 하나요?

출력 형식 설정

upbit accounts list --format json
upbit trading-pairs list --format yaml

지원 형식: auto, explore, json, jsonl, pretty, raw, yaml

자동화 스크립트에서는 일반적으로 json 형식을 권장합니다.

데이터 필터링

--transform 옵션과 *GJSON 구문을 사용하여 필요한 데이터만 추출할 수 있습니다.

*GJSON : JSON 데이터에서 원하는 값을 경로(path)로 지정해서 추출하는 문법.

# 마켓 코드만 추출
upbit trading-pairs list --transform "#.market"

# BTC 현재가만 추출(GJSON)
upbit tickers list-by-trading-pairs \
  --markets "KRW-BTC" \
  --transform "0.trade_price"

페이지네이션은 어떻게 동작하나요?

목록 조회 시 --max-items 옵션으로 가져올 항목 수를 지정할 수 있습니다.

upbit orders list-open --max-items 20
upbit deposits list --max-items 20

에러 발생 시 어떻게 확인하나요?

--debug 옵션을 사용하면 HTTP 요청 및 응답 내용을 확인할 수 있습니다.

upbit accounts list --debug

참고

더 많은 명령과 예제는 아래 문서를 참고하세요.

• Upbit CLI ReadMe
• Upbit CLI 예제 코드