CCXT로 빗썸 API 사용하기

CCXT를 설치하고 JavaScript와 Python으로 빗썸 API를 호출하는 방법을 안내합니다.

CCXT는 여러 가상자산 거래소의 API를 같은 방식으로 호출할 수 있는 오픈소스 라이브러리입니다. 거래소마다 다른 요청 형식과 인증 처리를 CCXT가 대신 맡고, 응답도 같은 형식으로 맞춰 줍니다.

CCXT는 외부 라이브러리이며, 설치 버전에 따라 빗썸 API 지원 범위가 다를 수 있습니다. 공통 메서드와 응답 구조는 CCXT 매뉴얼에서 확인하세요.

1. CCXT 설치하기

사용할 언어에 맞게 패키지를 설치합니다. 빗썸 API 2.0을 호출하려면 CCXT 4.5.77 이상을 사용하세요.

Node.js와 npm이 설치된 환경에서 다음 명령을 실행하세요.

npm install ccxt

설치한 버전을 확인합니다.

npm list ccxt

출력된 버전이 4.5.77 이상인지 확인하세요.


2. 거래 대상 페어 확인하기

CCXT는 거래 대상 페어를 기준 자산/결제 자산 형식으로 표현합니다. 비트코인을 원화로 거래하는 페어는 BTC/KRW입니다.

구분심볼 예시사용 위치
CCXT 통합 심볼BTC/KRWCCXT의 통합 메서드
빗썸 REST API 2.0 거래 대상 페어KRW-BTC빗썸 REST API 2.0 직접 호출

거래 대상 페어 목록 조회하기

ccxt.bithumb()으로 빗썸 API를 호출할 객체를 만들어 exchange 변수에 저장합니다. 이후 exchange.loadMarkets()(Python: exchange.load_markets())처럼 이 객체의 메서드로 API를 호출합니다. 거래 대상 페어 목록 조회는 Public API라서 API Key가 필요하지 않습니다.

다음 코드를 markets.cjs로 저장합니다.

const ccxt = require('ccxt');

async function main() {
  const exchange = new ccxt.bithumb();
  const markets = await exchange.loadMarkets();

  for (const symbol of Object.keys(markets).sort()) {
    console.log(symbol);
  }
}

main().catch((error) => {
  console.error(`거래 대상 페어 조회 실패 [${error.name}]: ${error.message}`);
  process.exitCode = 1;
});

실행합니다.

node markets.cjs

실행 결과

예제를 실행하면 CCXT 통합 심볼 형식의 거래 대상 페어가 알파벳순으로 출력됩니다. 다음은 출력의 일부입니다.

...
BTC/KRW
...
ETH/KRW
...

3. 현재가 조회하기

BTC/KRW의 현재가를 조회합니다. 거래 대상 페어 정보는 CCXT가 자동으로 불러오므로 loadMarkets()(Python: load_markets())를 먼저 호출하지 않아도 됩니다. 현재가 조회도 Public API라서 API Key가 필요하지 않습니다.

다음 코드를 ticker.cjs로 저장합니다.

const ccxt = require('ccxt');

async function main() {
  const exchange = new ccxt.bithumb();
  const ticker = await exchange.fetchTicker('BTC/KRW');

  if (ticker.last == null) {
    throw new Error('응답에 현재가가 없습니다.');
  }

  console.log(JSON.stringify({
    symbol: ticker.symbol,
    last: ticker.last,
  }, null, 2));
}

main().catch((error) => {
  console.error(`현재가 조회 실패 [${error.name}]: ${error.message}`);
  process.exitCode = 1;
});

실행합니다.

node ticker.cjs

실행 결과

예제를 실행하면 다음과 같이 출력됩니다. 현재가는 조회 시점에 따라 달라집니다.

{
  "symbol": "BTC/KRW",
  "last": 110047000.0
}
필드타입설명
symbolstringCCXT 통합 심볼
lastnumber최근 체결 가격. BTC/KRW에서는 원화 단위

예제에서는 CCXT 응답 중 symbol과 last만 출력합니다. CCXT 응답은 필드 이름과 구조가 빗썸 REST API 원본 응답과 다릅니다.

4. 계좌 잔고 조회하기

계좌 잔고를 조회하려면 API Key와 Secret Key가 필요합니다.

API Key 준비하기

  1. API 관리에서 2.0 API Key와 Secret Key를 발급받습니다.
  2. 자산조회 권한을 활성화합니다.
  3. 코드를 실행하는 환경의 외부 IP 주소를 허용 목록에 등록합니다.
  4. BITHUMB_ACCESS_KEY와 BITHUMB_SECRET_KEY 환경 변수에 발급받은 키를 설정합니다.

발급 절차는 빠른 시작 가이드를 참고하세요.

아래 예제에서는 환경 변수에 저장한 키를 사용합니다. 잔고 조회 예제를 실행할 터미널에서 다음 명령을 입력하세요. 발급받은_API_Key와 발급받은_Secret_Key는 실제 키로 바꿔 입력합니다.

export BITHUMB_ACCESS_KEY='발급받은_API_Key'
export BITHUMB_SECRET_KEY='발급받은_Secret_Key'

키를 설정한 터미널에서 잔고 조회 예제를 실행하세요. 터미널을 닫으면 환경 변수를 다시 설정해야 합니다.

키를 포함한 명령은 셸 명령 기록에 남을 수 있습니다. 명령이나 터미널 화면을 공유할 때 키가 노출되지 않도록 주의하세요.

예제는 .env 파일을 자동으로 읽지 않습니다. Python은 python-dotenv, Node.js는 dotenv 패키지로 .env 파일을 불러올 수 있습니다. .env 파일과 저장소 관리 방법은 개발 환경 설정하기를 참고하세요.

환경 변수CCXT 설정설명
BITHUMB_ACCESS_KEYapiKey빗썸에서 발급받은 API Key
BITHUMB_SECRET_KEYsecret빗썸에서 발급받은 Secret Key

환경 변수에서 읽은 키는 ccxt.bithumb()을 호출할 때 apiKey와 secret으로 전달합니다. CCXT가 인증 토큰 생성과 서명을 처리하므로 JWT 생성 코드는 따로 작성하지 않아도 됩니다.

⚠️

Secret Key를 코드, 저장소, 로그에 남기지 마세요. 잔고 조회 예제에는 주문과 출금 권한이 필요하지 않습니다.

다음 코드를 balance.cjs로 저장합니다.

const ccxt = require('ccxt');

async function main() {
  const apiKey = process.env.BITHUMB_ACCESS_KEY;
  const secret = process.env.BITHUMB_SECRET_KEY;

  if (!apiKey || !secret) {
    throw new Error(
      'BITHUMB_ACCESS_KEY와 BITHUMB_SECRET_KEY 환경 변수를 설정하세요.'
    );
  }

  const exchange = new ccxt.bithumb({
    apiKey,
    secret,
  });

  const balance = await exchange.fetchBalance();
  const krw = balance.KRW;

  if (!krw) {
    console.log('응답에 KRW 잔고가 없습니다.');
    return;
  }

  console.log(JSON.stringify({
    currency: 'KRW',
    free: krw.free ?? null,
    used: krw.used ?? null,
    total: krw.total ?? null,
  }, null, 2));
}

main().catch((error) => {
  console.error(`잔고 조회 실패 [${error.name}]: ${error.message}`);
  process.exitCode = 1;
});

실행합니다.

node balance.cjs

실행 결과

예제를 실행하면 다음과 같은 형식으로 출력됩니다. 아래 잔고는 예시 값입니다.

{
  "currency": "KRW",
  "free": 100000,
  "used": 20000,
  "total": 120000
}
필드타입설명
currencystring조회한 자산 코드
freenumber 또는 null사용 가능한 잔고
usednumber 또는 null미체결 주문 등에 묶여 있는 잔고
totalnumber 또는 null전체 잔고

잔고 항목에 값이 없으면 null을 출력합니다. 값이 없다고 잔고가 0인 것은 아닙니다.

잔고 조회에 실패하면 아래 「문제 해결」에서 오류 메시지별 확인 방법을 참고하세요.

반복해서 조회할 때는 exchange 객체를 새로 만들지 말고 다시 사용하세요. CCXT의 요청 간격 조절은 객체마다 따로 적용됩니다.

문제 해결

API Key가 필요한 요청이 실패하면 오류 메시지를 보고 다음을 확인하세요. 예외 이름과 메시지는 CCXT 버전과 API 응답에 따라 다를 수 있습니다.

오류 메시지확인할 내용
bithumb not allowed client IP실행 환경의 외부 IP가 허용 목록에 등록되어 있는지 확인하세요.
bithumb Jwt 토큰 검증에 실패했습니다.Secret Key가 API Key와 짝이 맞는지 확인하세요.
bithumb Invalid ApikeyCCXT 버전이 4.5.77 이상인지 확인하세요.
TypeError 등 키와 관련 없어 보이는 오류BITHUMB_ACCESS_KEY에 올바른 API Key를 넣었는지 확인하세요.

메시지가 표와 다르면 API Key와 Secret Key, 사용하는 기능의 권한, 허용 IP 설정을 차례로 확인하세요.

CCXT가 지원하는 거래소 목록 확인하기

CCXT는 빗썸 외에도 여러 거래소를 같은 방식으로 호출할 수 있습니다. 지원 거래소 목록은 ccxt.exchanges로 확인할 수 있습니다. 설치된 라이브러리 정보만 읽으므로 API Key와 네트워크 연결이 필요하지 않습니다.

const ccxt = require('ccxt');

console.log(ccxt.exchanges.length); // 지원 거래소 수

for (const exchangeId of ccxt.exchanges) {
  console.log(exchangeId);
}

console.log(ccxt.exchanges.includes('bithumb')); // 빗썸 지원 여부

거래소 수와 목록은 설치한 CCXT 버전에 따라 다릅니다. 마지막 줄에 true(Python: True)가 출력되면 설치한 CCXT에서 빗썸을 사용할 수 있습니다.

참고 자료

  • CCXT 매뉴얼: 설정 방법, 공통 메서드, 응답 구조, 오류 종류
  • CCXT 빗썸 가이드: CCXT로 사용할 수 있는 빗썸 API 메서드와 호출 방법, 파라미터, 반환값 안내
  • CCXT GitHub 저장소: 프로젝트 소개, 릴리스, 이슈
  • CCXT 빗썸 어댑터 소스: 빗썸 요청과 응답을 CCXT 형식으로 바꾸는 코드. master 브랜치는 계속 바뀌므로 설치한 버전의 태그에서 확인하세요.

Did this page help you?