10분 퀵스타트

이 가이드를 따라가면 10분 안에 quant-ai에 가입하고, BTC 페이퍼(모의) 봇을 돌려 첫 거래 시그널을 받게 됩니다.

사전 준비

quant-ai 접속 URL (기본: http://localhost:3000)
이메일 주소
Binance Spot Testnet API 키 (Step 3 시작 전에 페이퍼 트레이딩 셋업 참고)

절대 룰

모든 봇은 페이퍼 모드로만 시작합니다. 거래당 리스크 1-2% / 일일 -5% 자동 중단 룰이 항상 적용됩니다.

Step 1: 회원가입 (1분)

브라우저에서 quant-ai URL에 접속하면 로그인 화면이 나타납니다.

Don't have an account? Register 링크 클릭
Username (3자 이상), Email, Password (8자 이상) 입력
Create Account 클릭

📸 회원가입 화면 (추후 자동 캡처 예정)

API는 다음 엔드포인트를 호출합니다:

POST /api/auth/register
Content-Type: application/json

{
  "username": "trader01",
  "email": "trader01@example.com",
  "password": "********"
}

성공하면 201 Created + UserResponse 가 반환되고, 폼은 자동으로 로그인 화면으로 전환됩니다.

팁

이메일/사용자명이 이미 존재하면 409 CONFLICT 가 반환됩니다. 다른 사용자명으로 다시 시도하세요.

Step 2: 로그인 + 대시보드 (1분)

방금 만든 계정으로 로그인합니다.

Sign In 화면에서 Username/Password 입력
Sign In 버튼 클릭 → JWT access/refresh 토큰이 발급되어 브라우저에 저장됩니다.

📸 로그인 후 첫 대시보드 (추후 자동 캡처 예정)

대시보드 상단에서 다음 카드를 확인합니다:

Account Equity — 페이퍼 계좌 잔고 (초기값은 broker별 설정)
Daily P&L — 오늘의 누적 손익
Open Positions — 열린 포지션 수
Bot Status — STOPPED (아직 봇이 없습니다)

좌측 사이드바에서 Settings, Equity, Backtest 등 5개 페이지에 접근할 수 있습니다.

Step 3: BTC 페이퍼 봇 시작 (3분)

3-1. Binance Spot Testnet 키 등록

사이드바 Settings → Crypto (Binance) 탭으로 이동
Exchange: binance, Label: binance-testnet 입력
Testnet API Key / Secret 붙여넣기 (발급 절차는 페이퍼 트레이딩 셋업 참조)
Paper mode 토글이 ON 인지 확인 (Phase 3는 페이퍼 전용)
Save 클릭

📸 Binance 페이퍼 키 등록 폼 (추후 자동 캡처 예정)

API 동작:

POST /api/exchange-keys
Authorization: Bearer <access_token>

{
  "asset_class": "crypto",
  "exchange": "binance",
  "api_key": "<testnet_key>",
  "api_secret": "<testnet_secret>",
  "label": "binance-testnet",
  "paper_mode": true
}

키는 Fernet으로 암호화되어 저장됩니다. UI에는 마스킹된 형태(abcd****wxyz) 로만 표시됩니다.

3-2. 봇 시작

Dashboard 페이지로 이동
우측 상단 Start Bot 버튼 클릭
Asset Class: crypto / Strategy: momentum 선택 → Confirm

봇이 시작되면 대시보드 좌측 상단에 Bot Status: RUNNING 가 표시됩니다.

봇이 하는 일

1분마다 BTC/USDT OHLCV 캔들을 조회
전략(momentum 등)이 매수/매도 시그널을 생성
RiskManager.validate_signal_v2가 1-2% 리스크 / 일일 -5% 룰을 검증
통과 시 페이퍼 주문이 Binance Testnet에 전송됨

Step 4: 첫 거래 확인 (2분)

좌측 사이드바 Trades 페이지로 이동합니다.

봇이 시그널을 발생시키면 1~5분 안에 첫 거래가 채워집니다.

📸 Trades 페이지의 첫 페이퍼 거래 (추후 자동 캡처 예정)

각 행에서 확인할 수 있는 정보:

컬럼	의미
`submitted_at`	주문 접수 시각 (UTC)
`symbol`	`BTC/USDT`
`side`	`buy` / `sell`
`qty` / `filled_qty`	요청 / 체결 수량
`avg_fill_price`	평균 체결가
`status`	`filled` / `partially_filled` / `canceled` / `rejected`
`strategy`	시그널을 만든 전략 이름

Positions 페이지에서 현재 열린 포지션과 미실현 손익(unrealized_pnl)을 확인할 수 있습니다.

거래가 발생하지 않을 때

시장이 횡보 구간일 수 있습니다 — 1~10분 더 기다려보세요.
Settings → Risk Management의 max_open_positions가 0인지 확인하세요.
키 검증 실패라면 POST /api/exchange-keys/test 가 401을 반환합니다 → Binance Testnet 키 재발급.

Step 5: 알림 설정 (옵션, 3분)

거래/에러를 Telegram으로 받고 싶다면:

Telegram에서 @BotFather에게 /newbot 으로 봇 생성 → Bot Token 획득
본인의 봇과 1회 대화 후 https://api.telegram.org/bot<TOKEN>/getUpdates 로 Chat ID 확인
quant-ai Settings → Notifications 탭에 토큰/Chat ID 입력 → Test → Save

# config/notifications.yaml 예시
telegram:
  enabled: true
  bot_token: "<TELEGRAM_BOT_TOKEN>"
  chat_id: "<YOUR_CHAT_ID>"
  events:
    - order_filled
    - daily_loss_breach
    - bot_stopped

자세한 설정은 모니터링 / Telegram 알림 가이드를 참고하세요.

요약

단계	결과물
Step 1	quant-ai 계정 + JWT 토큰
Step 2	대시보드에서 계좌 0 USDT 확인
Step 3	Binance Testnet 페이퍼 봇 RUNNING
Step 4	Trades 페이지에서 첫 페이퍼 거래 fill 확인
Step 5	Telegram으로 거래/장애 알림 수신

축하합니다! quant-ai의 페이퍼 트레이딩 루프를 한 바퀴 완주했습니다.

다음 단계: 페이퍼 트레이딩 셋업에서 미국/한국 주식 페이퍼 키까지 등록하고 멀티자산 환경을 갖춰봅니다.

Step 1: 회원가입 (1분)​

Step 2: 로그인 + 대시보드 (1분)​

Step 3: BTC 페이퍼 봇 시작 (3분)​

3-1. Binance Spot Testnet 키 등록​

3-2. 봇 시작​

Step 4: 첫 거래 확인 (2분)​

Step 5: 알림 설정 (옵션, 3분)​

요약​