Upbit Strategy Toolkit

본 도구는 백테스트(과거 데이터 시뮬레이션) 전용이며, 실시간 주문이나 실제 자금 이동은 발생하지 않습니다. 실시간 주문·계좌 변경·자동 매매가 필요한 경우 별도의 방법(Upbit Skills 등)을 이용하길 권장드립니다.

본 도구는 베타(Beta)로 제공됩니다. 정식 출시 전까지 기능·사양 및 전략 JSON 스키마가 사전 예고 없이 변경될 수 있으며, 이용 중 일부 동작이 원활하지 않을 수 있는 점 양해 부탁드립니다.

주요 용어

• 백테스트(Backtest): 매매 규칙을 과거 시세에 적용해, 해당 규칙으로 거래했다면 결과가 어땠을지 계산하는 과정입니다.
• 전략(Strategy): 매수·매도 시점을 정의한 매매 규칙으로, JSON 형식의 파일로 저장됩니다.
• 에이전트(Agent): Claude Code·Cursor 등 AI 코딩 도구를 의미하며, 본 도구는 그 위에서 대화 방식으로 동작합니다.

1. 사전 준비

본 툴킷을 실행하려면 uv와 Node.js / npm이 필요합니다.

• uv는 Python 프로그램을 설치하고 실행하는 도구이며, 본 툴킷 구동에 사용됩니다.
• npm은 Node.js와 함께 설치되는 패키지 관리 도구입니다.

아래 명령어는 최초 1회만 실행하면 됩니다. 이미 설치되어 있다면 해당 단계는 생략하셔도 됩니다.

터미널이 처음이신가요? 터미널은 명령어를 입력하는 검은 창입니다. 아래 방법으로 열 수 있습니다.

• macOS: Spotlight(⌘ + Space)에서 "터미널" 또는 "Terminal" 검색 후 실행
• Windows: 시작 메뉴에서 "PowerShell" 검색 후 실행

이후에는 아래 명령어를 한 줄씩 복사해 붙여넣고 Enter를 누르면 됩니다.

1-1. uv 설치

운영체제에 맞는 명령어를 터미널에 입력해 설치합니다.

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치가 완료되면 터미널을 새로 열고 아래 명령어로 정상 설치 여부를 확인합니다.

uv --version

버전 번호가 출력되면 정상적으로 설치된 것입니다.

1-2. Node.js / npm 설치

npm은 Node.js 설치 시 함께 설치됩니다. 가장 간단한 방법은 공식 인스톨러를 내려받는 것입니다.

nodejs.org/en/download 에 접속해 LTS 버전 인스톨러를 내려받아 실행합니다.

• macOS: .pkg 파일을 실행하고 안내에 따라 설치합니다.
• Windows: .msi 파일을 실행하고 안내에 따라 설치합니다. (설치 시 npm이 함께 포함됩니다.)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash && \
export NVM_DIR="$HOME/.nvm" && \
[ -s "$NVM_DIR/nvm.sh" ] && \
. "$NVM_DIR/nvm.sh" && \
nvm install --lts

node --version
npm --version

v22.11.0
10.9.0

winget install OpenJS.NodeJS.LTS

node --version
npm --version

v22.11.0
10.9.0

nvm_dir="${NVM_DIR:-$HOME/.nvm}"

nvm unload 2>/dev/null || true

rm -rf "$nvm_dir"

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

node --version
npm --version

winget uninstall OpenJS.NodeJS.LTS

node --version
npm --version

node : The term 'node' is not recognized as the name of a cmdlet, function, script file, or operable program.

'node' is not recognized as an internal or external command,
operable program or batch file.

설치가 완료되면 터미널을 새로 열고 아래 명령어로 정상 설치 여부를 확인합니다.

node --version
npm --version

이미 uv, node, npm이 설치되어 있는 경우에는 별도로 재설치하지 않아도 됩니다. 터미널에서 아래 명령어를 실행했을 때 버전 번호가 출력되면 바로 사용 가능합니다.

uv --version
node --version
npm --version

2. 설치 및 실행

에이전트(Claude Code / Cursor / Codex)에 아래 명령으로 설치한 뒤, 대화하듯 전략을 요청합니다.

npx skills add upbit-official/upbit-strategy-toolkit -s '*' -a claude-code -a codex -a cursor -y --copy

설치가 완료되면 에이전트에 다음과 같이 요청합니다.

사용자:   "RSI 과매도에 진입하고 볼린저 중간선에서 청산하는 전략, 2024년으로 백테스트해줘"
에이전트: 전략 정리 → 백테스트 실행 → 결과 출력

아래와 같은 결과가 출력됩니다. 각 숫자의 의미는 4. 결과 지표 안내에서 설명합니다.

Period       2024-01-01 ~ 2024-12-31
Total Return +18.32%     ← 전략의 수익률
Benchmark    +62.45%     ← 단순 보유(buy & hold) 시 수익률
MDD          -7.21%      ← 최대 낙폭 (절대값이 작을수록 안정적)
Sharpe        1.34       ← 위험 대비 수익 (통상 1 이상이면 양호)
Win Rate      60%

두 가지 설치 모드

설치 방식은 두 가지입니다. 대부분의 경우 위의 npx skills add(Agent Skills 모드)로 충분하며, 도구의 내부 코드를 직접 확인하거나 수정하려는 경우에만 Clone 모드를 사용합니다. 두 모드는 전략·결과 파일이 저장되는 위치만 다릅니다.

Agent Skills 모드 (권장)

레포지토리 클론 없이 현재 프로젝트에 에이전트 스킬만 설치합니다. 출력 파일은 홈 폴더 아래 $HOME/.upbit-strategy-toolkit에 저장되므로, 작업 중인 프로젝트 폴더에 영향을 주지 않습니다.

npx skills add upbit-official/upbit-strategy-toolkit -s '*' -a claude-code -a codex -a cursor -y --copy

$HOME/.upbit-strategy-toolkit/
├── strategies/   # 저장된 전략 JSON
├── reports/      # 백테스트 결과 CSV
└── cache/
    └── upbit/    # 캔들 데이터 캐시

Clone 모드

레포지토리를 내려받아(클론) 그 폴더 안에서 실행합니다. 출력 파일도 그 폴더 안에 저장됩니다.

git clone https://github.com/upbit-official/upbit-strategy-toolkit.git
cd upbit-strategy-toolkit
uv sync
uv run upbit-strategy-toolkit --help

upbit-strategy-toolkit/
├── strategies/   # 저장된 전략 JSON
├── reports/      # 백테스트 결과 CSV
└── cache/
    └── upbit/    # 캔들 데이터 캐시

어떤 모드든 결과물의 종류는 같습니다. 만든 전략은 strategies/, 백테스트 리포트는 reports/에 쌓입니다.

3. 기본 사용 방법

사용 흐름은 ① 전략 생성 → ② 백테스트 → ③ 결과 검토 및 수정이며, 세 단계를 반복하며 전략을 다듬는 것이 핵심입니다. 모든 단계는 대화로 진행됩니다.

① 전략 생성 — 매매 아이디어를 전달하면, 에이전트가 매수·매도·손절(stop-loss)·익절(take-profit) 조건을 정리해 전략 파일로 생성합니다. 전문 용어를 사용하지 않아도 다음과 같이 요청할 수 있습니다.

"하락장에서도 단기 반등을 잡는 전략을 만들어줘"
"RSI 과매도 진입, 볼린저 밴드 중간선 청산 전략"
"SMA 5/20 골든크로스, 손절 3% 익절 8% 전략"

② 백테스트 실행 — 전략을 적용할 과거 기간을 지정하면, 해당 기간의 실제 시세로 시뮬레이션합니다.

"방금 만든 전략을 2024년 한 해 백테스트해줘"

③ 결과 검토 및 수정 — 결과에 따라 조건을 바꿔 다시 실행합니다. 값 하나만 변경해 비교하는 방식으로 전략을 빠르게 검증할 수 있습니다.

"진입 조건을 RSI 25 이하로 낮추고 다시 백테스트해줘"
"손절을 3%로 줄이면 결과가 어떻게 달라지는지 비교해줘"

이렇게 만든 전략은 strategies/ 폴더에, 백테스트 결과 CSV는 reports/ 폴더에 자동으로 저장됩니다.

4. 결과 지표 안내

백테스트를 실행하면 아래와 같은 요약이 출력됩니다. 항목이 많지만, 처음에는 굵게 표시한 세 가지(Total Return · MDD · Benchmark)를 중심으로 보면 됩니다.

Period       2024-01-01 ~ 2024-12-31 (trading bars: 366, warmup bars: 30)
Benchmark    +62.45%
Total Return +18.32%
CAGR         +18.11%
MDD          -7.21%
Sharpe       1.34  (portfolio / full equity curve)
Sharpe       1.11  (trades / position holding periods only)
Trades       23  Win Rate 60% (before fees)
Profit Factor  2.14 (before fees)
SL 4 / TP 9 / Sell 8 / Final bar 2
Total Fees   12,345

각 지표의 의미는 다음과 같습니다.

결과 읽는 법

위 예시는 +18.32% 수익을 냈으나 같은 기간 단순 보유(+62.45%)보다 낮은 결과입니다.
즉 수익이 발생했다는 것이 곧 좋은 전략을 의미하지는 않습니다.

항상 Benchmark와 비교하고, MDD(최대 손실 폭)를 함께 확인합니다. Sharpe가 두 줄로 출력되는 것은 계산 기준이 다르기 때문입니다. portfolio는 전체 자산 흐름, trades는 개별 거래 기준입니다.

체결·수수료가 결과에 어떻게 반영되는지 등 백테스트의 정확한 계산 방식은 레퍼런스의 "백테스트 해석"에서 확인할 수 있습니다.

결과 분석이 어렵다면

지표가 많아 결과를 판단하기 어렵다면, 여러 전략을 백테스트한 뒤 그 결과를 모아 AI 에이전트에게 비교·분석을 맡길 수 있습니다.

1. 조건을 바꿔가며 여러 전략을 백테스트합니다. 결과 CSV는 reports/ 폴더에 순차적으로 저장됩니다.
2. 저장된 리포트를 하나의 전략집(예: strategy-report.md)으로 정리합니다. 파일마다 전략 설정과 성과 요약(Total Return·Benchmark·MDD·Win Rate 등)을 함께 담습니다.
3. 정리한 전략집을 에이전트에 전달하고 분석을 요청합니다.

예시 프롬프트:

"reports/ 폴더의 백테스트 결과들을 비교해서 전략집 strategy-report.md로 정리해줘.
각 전략의 설정, Total Return, Benchmark, MDD, Win Rate를 표로 만들고,
벤치마크 대비 초과 성과 기준으로 정렬해줘."

"strategy-report.md를 읽고, 어떤 전략이 하락장에서 손실을 잘 방어했는지,
어떤 전략이 과최적화로 의심되는지 분석해줘. 지표만 보고 단정하지 말고
거래 횟수와 MDD도 함께 근거로 들어줘."

이때 에이전트의 분석은 참고 의견이며, 투자 판단의 근거가 되지 않습니다. AI는 결과를 잘못 해석할 수 있으므로 원본 리포트 수치를 함께 확인하세요.

유의사항

• 백테스트 결과는 투자 조언이 아닙니다. 수익률·승률·Profit Factor·Sharpe는 과거 데이터 기반 참고 수치이며, 미래 수익을 보장하지 않습니다.
• 전략 JSON만 지원합니다. 임의 Python 코드 실행은 지원하지 않습니다. 새로운 전략 표현이 필요한 경우 Pydantic 모델과 명시적 스키마로 정의합니다.
• 실전 매매는 지원하지 않습니다. 실시간 주문·계좌 변경·자동 매매가 필요한 경우 upbit-agent-skills를 사용합니다.
• 모든 계산은 IEEE 754 배정밀도(float64)를 사용하며, 실거래 주문 실행이나 정산 목적이 아닌 백테스트 참고용 근삿값입니다.

다음으로

• 전략을 직접 편집하거나 CLI를 쓰고 싶다면 → Upbit Strategy Toolkit — 레퍼런스

• 설치 문제 해결이나 스킬·도구 제거 방법이 필요하다면 → Upbit Strategy Toolkit — FAQ