본문으로 건너뛰기

페이퍼 트레이딩 셋업

quant-ai는 3개 자산군 × 페이퍼 모드를 지원합니다. 신규 사용자는 라이브 모드를 사용하기 전 최소 90일 / 50거래 동안 페이퍼로 검증해야 하므로, 먼저 페이퍼 키를 등록합니다.

자산군거래소/증권사페이퍼 환경권장
CryptoBinanceSpot Testnet (testnet.binance.vision)필수
US EquityAlpacaPaper Trading (paper-api.alpaca.markets)권장
KR EquityKIS (한국투자증권)모의투자 계좌 (openapivts.koreainvestment.com:29443)선택
절대 룰
  • Phase 3 ~ 라이브 게이트 통과 전까지는 모든 키를 paper_mode=true 로만 등록할 수 있습니다.
  • API는 paper_mode=false 로 들어온 요청을 422 로 거절합니다.
  • 자세한 룰: 부록 / 리스크 룰, 라이브 승격 절차: 페이퍼 → 라이브.

Binance Spot Testnet 키 발급​

1. Testnet 계정 생성​

  1. https://testnet.binance.vision/ 접속
  2. 우측 상단 Log In with GitHub (Testnet은 GitHub OAuth만 지원)
  3. 우측 상단 사용자 메뉴 → Generate HMAC_SHA256 Key
  4. Description: quant-ai paper 입력 → Generate
  5. API Key / Secret Key 를 안전한 곳에 복사 (Secret은 다시 볼 수 없음)

2. quant-ai에 등록​

Settings → Crypto (Binance) 탭에서:

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

{
  "asset_class": "crypto",
  "exchange": "binance",
  "api_key": "<testnet_api_key>",
  "api_secret": "<testnet_secret>",
  "label": "binance-testnet",
  "paper_mode": true,
  "permissions": ["spot_trade", "read"]
}

성공 시 201 Created + ExchangeKeyResponse(마스킹된 응답)를 반환합니다.

CCXT 키 검증

크립토 키는 등록 시점에 비차단 dry-run을 하지 않고, 봇이 처음 주문을 낼 때 CCXT가 검증합니다. 키가 잘못되었으면 첫 주문에서 401이 떨어지고 broker 401 트러블슈팅 으로 이어집니다.

Alpaca Paper API 키 발급​

1. Alpaca 계정​

  1. https://alpaca.markets/ 가입 → 로그인
  2. 좌측 사이드바 Paper Trading 토글 ON
  3. 우측 패널 API Keys → Generate New Key
  4. API Key ID / Secret 복사
  5. 페이퍼 엔드포인트는 항상 https://paper-api.alpaca.markets

2. quant-ai에 등록 + 검증​

Settings → US (Alpaca) 탭에서 폼을 채우고 Test connection 을 먼저 클릭하세요:

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

{
  "asset_class": "us_equity",
  "exchange": "alpaca",
  "api_key": "<key_id>",
  "api_secret": "<secret>",
  "base_url": "https://paper-api.alpaca.markets",
  "paper_mode": true
}

dry-run 결과:

응답 필드의미
ok: true인증 성공, equity / buying_power 가 함께 반환됨
ok: false + error키 오류, IP 화이트리스트 누락, 시장 비공개 등 → 메시지 기준으로 재발급

검증이 통과하면 Save 를 클릭해 영구 저장합니다.

POST /api/exchange-keys
{
  "asset_class": "us_equity",
  "exchange": "alpaca",
  "api_key": "<key_id>",
  "api_secret": "<secret>",
  "base_url": "https://paper-api.alpaca.markets",
  "paper_mode": true,
  "label": "alpaca-paper"
}

KIS 모의투자 계좌 발급​

KIS(한국투자증권)는 모의투자 계좌가 일반 계좌와 분리되어 있어 별도 신청 + 별도 앱 키 발급 이 필요합니다.

1. 모의투자 계좌 신청​

  1. KIS HTS/MTS 로그인 → 모의투자 → 모의투자 신청
  2. 종목 유형 국내주식 선택, 초기 자금 (보통 1억 원) 신청
  3. 계좌번호 (8자리-2자리) 와 상품코드 메모
    • 일반적으로 국내 주식 위탁계좌는 상품코드 01
    • VTS 환경에서 상품코드 01 외 값을 사용하면 422가 반환됩니다.

2. KIS Open API 모의투자 앱 키 발급​

  1. https://apiportal.koreainvestment.com/ 로그인
  2. API 신청 → 모의투자 환경 선택
  3. App Key / App Secret 발급 → 안전한 곳에 보관
  4. 모의투자 base URL: https://openapivts.koreainvestment.com:29443

3. quant-ai에 등록 + 검증​

Settings → KR (KIS) 탭:

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

{
  "asset_class": "kr_equity",
  "exchange": "kis",
  "api_key": "<app_key>",
  "api_secret": "<app_secret>",
  "account_no": "12345678-01",
  "account_product_code": "01",
  "base_url": "https://openapivts.koreainvestment.com:29443",
  "paper_mode": true
}

검증 성공 시 equity, buying_power, currency: "KRW" 가 반환됩니다.

KIS 토큰 만료

KIS의 access token은 24시간 유효합니다. 만료 후 자동 재발급되지만, 종일 실패가 누적되면 KIS 토큰 만료 트러블슈팅 절차로 강제 재발급하세요.

등록된 키 확인 / 삭제​

# 본인 키 목록 (마스킹된 응답)
GET /api/exchange-keys
Authorization: Bearer <access_token>

# 키 삭제 (다른 사용자의 키는 404)
DELETE /api/exchange-keys/<id>
Authorization: Bearer <access_token>

UI Settings → Exchange Keys 카드에서 동일하게 작동합니다.

보안 메모​

ENCRYPTION_SALT / AUTH_SECRET_KEY 회전

거래소 키는 서버의 AUTH_SECRET_KEY(+ENCRYPTION_SALT)로 Fernet 암호화되어 저장됩니다. 이 값을 회전하면 기존 암호문은 더 이상 복호화되지 않으므로 키를 다시 등록해야 합니다. 회전 절차와 영향 범위는 secret rotation 가이드를 반드시 먼저 읽으세요.

  • 키 입력 후 응답은 항상 마스킹됩니다 (abcd****wxyz).
  • 키 등록은 사용자별 격리됩니다 (WHERE user_id = current_user.id); 타 사용자의 키는 404로 응답합니다.
  • 라이브 키 등록은 라이브 모드 게이트 가 통과된 사용자만 가능합니다.

다음 단계: 첫 AI 분석에서 LLM 키를 연결하고 AAPL/005930 종목 리포트를 생성합니다.