Alpaca (US) paper-first
ExchangeKeyTabs의 두 번째 탭(blue). 미국 주식 broker인 Alpaca 키를 등록합니다.
📸 Alpaca 키 등록 폼 (추후 자동 캡처 예정)
Paper 우선 정책
기본 base URL은 paper 엔드포인트로 고정됩니다.
https://paper-api.alpaca.markets
서버는 paper_mode=true인 경우 다른 base URL이 들어오면 거부합니다 (live URL을 paper 키로 호출하지 못하도록).
필수 입력
| 필드 | 기본값 | 설명 |
|---|---|---|
| API Key | (없음) | Alpaca paper key (PKTEST... prefix) |
| API Secret | (없음) | Alpaca paper secret |
| Base URL | https://paper-api.alpaca.markets | 변경 권장하지 않음 |
| Label | alpaca-paper | 사용자 식별용 |
Test Connection 버튼
Alpaca는 GET /v2/account를 동기 호출로 검증할 수 있어 폼에 Wifi 아이콘 Test 버튼이 있습니다.
성공 시:
Connection ok — Alpaca paper account verified.
실패 시 (HTTP 401 등):
Connection failed — invalid API key or secret.
POST /api/exchange-keys/test를 호출하며, 결과를 저장 전에 미리 확인할 수 있습니다.
API 호출
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
http://localhost:8000/api/exchange-keys \
-d '{
"asset_class": "us_equity",
"exchange": "alpaca",
"api_key": "PKTEST...",
"api_secret": "...",
"base_url": "https://paper-api.alpaca.markets",
"paper_mode": true,
"label": "alpaca-paper"
}'
Live 활성화
Live 키는 별도 절차가 필요합니다.
- 3개월 paper 거래 + drawdown 기준 충족 (readiness 검증)
POST /api/equity/live/request_confirm→ 이메일/로그로 토큰 수령POST /api/equity/live/enable→ 토큰 검증 + 자산군 활성
UI는 P4-01에서 라이브 토글을 추가할 예정입니다.
절대 룰
Live URL 거부
paper_mode=true이면 base_url은 paper 엔드포인트만 허용됩니다. 서버 측에서 정규식 검사로 거부합니다.
자주 묻는 질문
Q. Alpaca 가입은 어디서?
A. https://app.alpaca.markets/signup → Paper Trading 메뉴에서 키 발급. 무료.
Q. KR 거주자도 가입할 수 있나요?
A. paper는 가능. live는 W-8BEN 등 추가 절차 필요. (이 프로젝트는 paper 위주)
Q. PKTEST가 아니라 PKLIVE prefix면?
A. 라이브 키이므로 paper_mode=true와 호환 안 됩니다. paper key를 새로 발급하세요.