Alpaca 거래 스킬은(는) 무엇을 하나요?
scripts/alpaca.sh를 사용하여 Alpaca의 REST API를 통해 포트폴리오를 거래하고 관리합니다.
설정
필수 환경 변수
| 변수 | 설명 |
|---|---|
APCA_API_KEY_ID | Alpaca API 키 |
APCA_API_SECRET_KEY | Alpaca API 시크릿 |
선택적 환경 변수
| 변수 | 기본값 | 설명 |
|---|---|---|
APCA_API_BASE_URL | https://paper-api.alpaca.markets | 거래 엔드포인트. 실사용 시 https://api.alpaca.markets로 설정 |
APCA_DATA_API_BASE_URL | https://data.alpaca.markets | 시장 데이터 엔드포인트 |
페이퍼 트레이딩이 기본값입니다. 실계좌로 전환하기 전에 항상 사용자 확인을 받으세요.
도우미 스크립트
이 스킬 디렉토리에서 scripts/alpaca.sh를 소스(Source)하세요. 사용법:
alpaca METHOD PATH [JSON_BODY]
# 시장 데이터:
ALPACA_DATA=1 alpaca METHOD PATH
빠른 참조
계정 및 포트폴리오
alpaca GET /v2/account # 잔고, 자기자본, 매수력
alpaca GET /v2/account/configurations # 거래 설정
alpaca GET '/v2/account/portfolio/history?period=1M&timeframe=1D' # 포트폴리오 차트
alpaca GET '/v2/account/activities?activity_types=FILL,DIV' # 거래/배당 내역
alpaca GET /v2/clock # 시장 개장/폐장
alpaca GET '/v2/calendar?start=2026-03-01&end=2026-03-31' # 거래일
주문 — 주식 및 암호화폐
# 시장가 매수 (수량 또는 금액 기준)
alpaca POST /v2/orders '{"symbol":"AAPL","qty":"10","side":"buy","type":"market","time_in_force":"day"}'
alpaca POST /v2/orders '{"symbol":"AAPL","notional":"1000","side":"buy","type":"market","time_in_force":"day"}'
# 암호화폐 (24/7)
alpaca POST /v2/orders '{"symbol":"BTC/USD","qty":"0.001","side":"buy","type":"market","time_in_force":"gtc"}'
# 지정가 / 스탑 / 스탑-리밋 / 트레일링 스탑 / 브래킷 / OTO / OCO — 참조: references/api.md
# 주문 목록 조회 / 조회 / 변경 / 취소
alpaca GET /v2/orders
alpaca GET /v2/orders/ORDER_ID
alpaca PATCH /v2/orders/ORDER_ID '{"qty":"20","limit_price":"190.00"}'
alpaca DELETE /v2/orders/ORDER_ID
alpaca DELETE /v2/orders # 전체 취소
주문 — 옵션
# 콜 매수 (레벨 2 이상)
alpaca POST /v2/orders '{"symbol":"AAPL260418C00260000","qty":"1","side":"buy","type":"market","time_in_force":"day"}'
# 커버드콜 매도 (레벨 1 이상, 계약 당 100주 보유 필요)
alpaca POST /v2/orders '{"symbol":"AAPL260418C00270000","qty":"1","side":"sell","type":"limit","limit_price":"2.00","time_in_force":"day"}'
# 풋 매수/매도, 현금담보 풋, 스프레드 (레벨 3) — 참조: references/api.md
# 옵션 행사
alpaca POST /v2/positions/AAPL260418C00260000/exercise
# 계약 조회
alpaca GET '/v2/options/contracts?underlying_symbols=AAPL&expiration_date_gte=2026-04-01&type=call&limit=10'
alpaca GET /v2/options/contracts/AAPL260418C00260000
포지션
alpaca GET /v2/positions # 전체 미결제 포지션
alpaca GET '/v2/positions?asset_class=us_option' # 옵션만
alpaca GET /v2/positions/AAPL # 단일 주식
alpaca GET /v2/positions/NVDA260417C00220000 # 단일 옵션
alpaca DELETE /v2/positions/AAPL # 청산
alpaca DELETE '/v2/positions/AAPL?qty=5' # 부분 청산
alpaca DELETE '/v2/positions?cancel_orders=true' # 전체 청산
시장 데이터 — 주식
ALPACA_DATA=1 alpaca GET /v2/stocks/AAPL/snapshot # 호가 + 체결 + 봉
ALPACA_DATA=1 alpaca GET '/v2/stocks/snapshots?symbols=AAPL,MSFT,GOOGL' # 다중 스냅샷
ALPACA_DATA=1 alpaca GET '/v2/stocks/AAPL/bars?timeframe=1Day&start=2026-03-01&limit=30'
ALPACA_DATA=1 alpaca GET /v1beta1/screener/stocks/most-actives
ALPACA_DATA=1 alpaca GET '/v1beta1/screener/stocks/movers?top=10'
ALPACA_DATA=1 alpaca GET '/v1beta1/news?symbols=AAPL&limit=5'
시장 데이터 — 옵션
ALPACA_DATA=1 alpaca GET '/v1beta1/options/snapshots/AAPL?feed=indicative&limit=10' # 옵션 체인
ALPACA_DATA=1 alpaca GET '/v1beta1/options/bars?symbols=NVDA260417C00220000&timeframe=1Day&limit=10'
ALPACA_DATA=1 alpaca GET '/v1beta1/options/quotes/latest?symbols=NVDA260417C00220000'
ALPACA_DATA=1 alpaca GET '/v1beta1/options/trades/latest?symbols=NVDA260417C00220000'
# feed: indicative (무료/지연) 또는 opra (구독 필요)
시장 데이터 — 암호화폐
ALPACA_DATA=1 alpaca GET '/v1beta3/crypto/us/latest/quotes?symbols=BTC/USD'
ALPACA_DATA=1 alpaca GET '/v1beta3/crypto/us/bars?symbols=BTC/USD&timeframe=1Day&limit=30'
ALPACA_DATA=1 alpaca GET '/v1beta3/crypto/us/snapshots?symbols=BTC/USD,ETH/USD'
기업 액션
ALPACA_DATA=1 alpaca GET '/v1/corporate-actions?symbols=AAPL&types=cash_dividend'
# 유형: forward_split, reverse_split, cash_dividend, stock_dividend, spin_off 등
자산 및 관심목록
alpaca GET /v2/assets/AAPL # 자산 정보
alpaca GET '/v2/assets?status=active&attributes=has_options' # 옵션 거래 가능 주식
alpaca GET /v2/watchlists # 관심목록 조회
alpaca POST /v2/watchlists '{"name":"Tech","symbols":["AAPL","MSFT","GOOGL"]}'
전체 API 참조
references/api.md에서 전체 엔드포인트 문서를 확인하세요:
- 모든 주문 유형 (지정가, 스탑, 스탑-리밋, 트레일링 스탑, 브래킷, OCO, OTO)
- 주문 필드 참조 (side, type, time_in_force, order_class)
- 관심목록 CRUD
- 옵션 계약
- 과거 봉/체결/호가 (모든 쿼리 파라미터 포함)
- 암호화폐 엔드포인트
- 시장 달력
안전 규칙
- 기본적으로 페이퍼 트레이딩 사용. 명시적인 사용자 확인 없이
APCA_API_BASE_URL을 실계좌로 설정하지 마세요. - 주문 JSON을 제출하기 전에 먼저 표시하세요. 사용자가 종목, 수량, 매매방향, 유형을 확인할 수 있게 하세요.
- 주문 전에 시장 시계를 확인하세요. 주식은 시장 시간(동부 기준 9:30-16:00)에만 거래되며, 지정가 주문의
extended_hours: true설정이 필요할 수 있습니다. - 대량 주문 전에
GET /v2/account로 매수력을 확인하세요. - 절대 금융 조언을 제공하지 마세요. 데이터를 제시하고 사용자가 결정하게 하세요.
- 되돌릴 수 없는 작업(전체 포지션 청산, 전체 주문 취소)에 대해 경고하세요.
문제 해결
| 증상 | 해결 방법 |
|---|---|
HTTP 401 | APCA_API_KEY_ID / APCA_API_SECRET_KEY가 설정되어 있고 유효한지 확인 |
HTTP 403 | 페이퍼 키가 실계좌 URL에 사용되었거나 그 반대; APCA_API_BASE_URL 확인 |
HTTP 422 (수량 부족) | 매수력, 분할 매수 지원 여부 또는 종목 유효성 확인 |
HTTP 429 | 속도 제한 — 대기 후 재시도; Alpaca는 분당 200개 요청 허용 |
| 장 외 시간 주문 거부 | "extended_hours":true 추가 (지정가 주문만 가능) 또는 시장 개장까지 대기 |
jq: command not found | 스크립트는 python3 -m json.tool로 대체됨; 더 나은 출력을 위해 jq 설치 |