trader-broker

trader-broker은(는) 무엇을 하나요?

주문 실행기는 이 팩에서 유일하게 실제 주문으로 이어질 수 있는 스킬이므로 가장 엄격하게 작동합니다. 주문이 시장에 도달하려면 매번 모든 주문에 대해 세 가지 별도의 관문을 통과해야 합니다.

1. trader-risk가 오늘 이 정확한 주문을 통과시킴 (지문(fingerprint)으로 일치 확인).
2. 사용자가 채팅에서 이 하나의 주문에 대해 명시적인 '예'를 입력함.
3. 사용자가 Claude 자체 권한 카드에서 '한 번 허용'을 클릭함. 이 카드는 주문 도구가 "승인 필요"로 설정되어 있기 때문에 나타납니다.

사용자의 '예' 두 번, 규칙의 '통과(PASS)' 한 번. '예'가 없으면 주문도 없습니다.

${CLAUDE_SKILL_DIR} 는 이 스킬의 폴더(이 SKILL.md가 있는 곳)를 나타냅니다.

python3 "${CLAUDE_SKILL_DIR}/ticket.py" show                     # 모든 명세서 표시, 준비 여부와 관계없이
python3 "${CLAUDE_SKILL_DIR}/ticket.py" approve --index 1 --reply "yes"
python3 "${CLAUDE_SKILL_DIR}/ticket.py" result --index 1 --status placed --broker-id ID --filled-qty 8 --filled-price 364.20
python3 "${CLAUDE_SKILL_DIR}/ticket.py" fill --symbol TSLA --side sell --qty 8 --price 370.04
python3 "${CLAUDE_SKILL_DIR}/ticket.py" flatten --symbol TSLA --qty 8
python3 "${CLAUDE_SKILL_DIR}/ticket.py" log

ticket.py 는 절대 브로커와 통신하지 않습니다. 명세서를 렌더링하고, 응답이 해당 주문에 대한 진짜 '예'인지 확인하며, 청산 명세서를 작성하고, 로그를 trader/state/broker.json 에 유지합니다. --now "2026-10-19 10:15" 옵션으로 시간을 고정할 수 있습니다(뉴욕 시간).

읽고 쓰는 파일

파일	내용
trader/orders.json	제안된 주문 (trader-budget이 작성, flatten이 대체)
trader/state/risk.json	trader-risk의 판정. 오늘의 'PASS'만이 '준비(READY)' 상태가 됩니다.
trader/state/broker.json	모든 '예', '아니오', 체결됨, 실패, 채움 기록과 각 항목의 최대 손실
trader/portfolio.json	현금 및 보유 주식. fill과 result --filled-qty로 업데이트됩니다.
trader/plan.json	flatten을 위한 마감 시간 정보

설정 A: Alpaca (공식 MCP 서버, Claude Desktop)

Alpaca 자체 서버는 github.com/alpacahq/alpaca-mcp-server (MIT 라이선스)입니다. 사용자의 컴퓨터에서 Claude Desktop 내에서 실행됩니다. Claude의 커넥터 디렉토리에 있지 않습니다. 별도로 지정하지 않는 한 모의 거래(paper) 계정에서 거래합니다. 출처를 기준으로 2026-10-20 (버전 2.4.0)에 확인되었습니다.

1. 사용자는 Alpaca 계정을 만들고 Alpaca 대시보드에서 모의 거래 API 키를 생성합니다. 모의 거래 키는 실제 거래 키와 별개입니다.
2. 사용자는 uv를 설치합니다(uvx를 제공, docs.astral.sh/uv).
3. Claude Desktop에서: 설정 > 개발자 > 설정 편집. claude_desktop_config.json 파일이 열립니다(macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\). 사용자는 다음 블록(여기 claude_desktop_config.example.json에도 있음)을 추가하고 파일에 자신의 키를 직접 입력합니다.

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "여기에 모의 거래 키를 붙여넣으세요, 이 파일에만 저장됩니다",
        "ALPACA_SECRET_KEY": "여기에 모의 거래 시크릿을 붙여넣으세요, 이 파일에만 저장됩니다",
        "ALPACA_PAPER_TRADE": "true",
        "ALPACA_TOOLSETS": "account,trading,stock-data"
      }
    }
  }
}

env 블록은 환경 변수로 키를 서버에 전달합니다. 키는 절대 채팅에 입력되지 않습니다. 키를 절대 요청하지 말고, 이 파일을 다시 대화로 읽어들이지 마십시오. 사용자가 실수로 키를 붙여넣으면, 해당 메시지를 삭제하고 Alpaca 대시보드에서 새 키를 만들도록 지시하십시오. ALPACA_PAPER_TRADE 는 이미 기본적으로 true이지만, 명시적으로 작성하면 눈에 띄게 됩니다. ALPACA_TOOLSETS 는 선택 사항이며 필요하지 않은 도구를 숨깁니다. 4. Claude Desktop을 다시 시작합니다. 5. 도구 권한을 설정합니다. Customize > Connectors (구버전의 경우 Settings > Connectors)에서 alpaca를 열고 각 도구에 대해 '항상 허용', '승인 필요' 또는 '차단'을 선택합니다.

• place_stock_order: 승인 필요로 설정합니다. 절대 '항상 허용'으로 설정하지 마십시오.
• 주문을 넣거나, 변경하거나, 취소하거나, 청산하는 모든 기타 도구(cancel_order_by_id, replace_order_by_id, close_position, update_account_config): '승인 필요'로 설정합니다.
• place_option_order, place_crypto_order, close_all_positions, cancel_all_orders, exercise_options_position, do_not_exercise_options_position: 사용자가 특별한 이유를 가지고 직접 요청하지 않는 한 차단합니다.
• 읽기 전용 도구(get_account_info, get_all_positions, get_open_position, get_orders, get_clock, get_stock_snapshot, get_stock_latest_quote): '항상 허용'이 적절합니다.

6. 확인: Claude에게 Alpaca 계정 정보(읽기 전용)를 요청하고 Alpaca 대시보드에서 모의 거래 계정임을 확인합니다.

Claude Desktop 대신 Claude Code를 사용하는 경우, .claude/settings.json 파일에서 주문 도구를 ask로 유지하십시오: "permissions": {"ask": ["mcp__alpaca__place_stock_order"]}, 그리고 절대 allow에 주문 도구를 넣지 마십시오.

Alpaca의 브래킷 주문. place_stock_order 는 take_profit_limit_price 와 stop_loss_stop_price (그리고 선택적으로 stop_loss_limit_price)를 받습니다. 이 중 하나라도 있으면 서버가 자동으로 order_class를 "bracket"으로 설정합니다. trader-budget은 명세서에 표시하기 위해 이를 명시적으로 작성합니다. 브래킷 주문은 'time_in_force'가 'day' 또는 'gtc'인 정수 주식에만 가능합니다. 진입 주문이 체결된 후, 손절매와 이익 실현 주문은 브로커에 두 개의 상호 취소 가능한 주문으로 대기합니다. 이 또한 데이 주문이므로 장 마감 시 종료됩니다. 따라서 마감 시간까지 포지션을 청산해야 하는 또 다른 이유가 됩니다.

설정 B: Interactive Brokers (Claude 디렉토리의 커넥터)

Interactive Brokers는 검증된 커넥터를 제공합니다: claude.ai/directory/interactive-brokers (커넥터 URL https://api.ibkr.com/v1/api/mcp). Customize > Connectors > Browse connectors에서 추가하고 채팅이 아닌 해당 화면에서 IBKR에 로그인하십시오. 해당 페이지 설명에 따르면, Claude는 거래 지침을 초안하여 사용자의 검토 및 승인을 위해 IBKR 계정으로 전송할 수 있으며, Claude는 절대 직접 시장에 주문을 제출하지 않는다고 명시되어 있습니다. 따라서 IBKR의 경우 최종 승인은 IBKR 내에서도 이루어집니다. trader/config.json에 "broker": "ibkr"를 설정하십시오. 주문을 초안 작성하는 도구들도 '승인 필요'로 설정하십시오.

절차: 진입(Entry)

1. ticket.py show 를 실행합니다. 준비(READY) 상태인 명세서만 사용자에게 표시됩니다. READY 또는 BLOCKED 상태가 아닌 명세서는 /trader-risk로 돌아갑니다.
2. 하나의 명세서를 보여주고 "이 주문을 실행할까요? 예 또는 아니오로 답변해 주세요."라고 물어봅니다. 질문당 하나의 주문만 처리합니다. 절대 "모두 예"를 제안하지 마십시오.
3. ticket.py approve --index N --reply "<사용자의 응답, 단어 그대로>" 를 실행합니다. 만약 "기록되지 않음(Not recorded)"이 출력되면, 해당 응답이 이 주문에 대한 명시적인 '예'가 아니었다는 뜻입니다(예: "그래", "모두 예", 또는 다른 종목이나 수량을 언급한 '예'). 다시 질문하십시오. 스스로 응답을 '예'로 바꾸지 마십시오.
4. "귀하의 '예'가 기록되었습니다(Recorded your yes)"가 출력된 후에만, 명세서에 출력된 정확한 JSON으로 place_stock_order 를 호출하십시오. Claude의 카드가 나타납니다: '한 번 허용(Allow once)' 또는 '거부(Deny)'.
5. 발생한 일을 기록합니다: ticket.py result --index N --status placed --broker-id <id> --filled-qty Q --filled-price P (응답 또는 get_open_position에서 받은 체결 정보), 또는 --status denied, 또는 --status failed --note <메모>. 실패한 주문은 새로운 확인과 새로운 '예' 없이 재시도되지 않습니다. 로그는 trader-risk의 일일 한도 관리를 위해 진입 시의 최대 손실을 유지합니다.

절차: 포지션 보유 중 및 장 마감 전 청산

• trader-alerts는 손절매, 목표가, 마감 시간을 감시합니다(alerts.py add --from-plan). 브래킷 주문 자체의 주문이 손절매/이익실현을 처리합니다.
• 손절매 또는 이익 실현이 체결되면 기록합니다: ticket.py fill --symbol TSLA --side sell --qty 8 --price 358.32.
• flat_by (뉴욕 시간 15:55)까지, 아직 열려 있는 모든 포지션을 청산합니다.
  1. Alpaca에 보유 주식 수를 확인합니다: get_open_position (읽기 전용).
  2. ticket.py flatten --symbol TSLA --qty 8 로 해당 주식에 대한 시장 매도 주문을 trader/orders.json에 작성합니다.
  3. /trader-risk를 실행합니다. 사용자가 보유한 주식만 청산하는 매도는 일일 한도나 진입 윈도우에 의해 차단되지 않습니다.
  4. ticket.py show 및 위와 동일한 절차로 해당 주문에 대한 사용자의 '예'를 받습니다.
  5. 브래킷 주문의 손절매와 이익실현 주문이 여전히 해당 주식을 보유하고 있으므로, Alpaca는 해당 주문이 취소될 때까지 새로운 매도를 거부합니다. get_orders (상태 open, nested true)로 해당 주문들을 확인하고; cancel_order_by_id 로 각각을 취소합니다 (승인 필요). 그런 다음 명세서의 JSON으로 place_stock_order 를 호출하고, result 로 결과를 기록합니다.

예시: 실제 흐름

ORDER 1 of 1, PAPER account, Alpaca
  BUY 8 TSLA, market, good for today
  stop-loss 358.32
  take-profit 370.04
  max loss 약 $46.88 (손절가 358.32에 체결 시, 빠른 시장에서는 더 나쁘게 체결될 수 있음)
  이유: TSLA 장중 돌파 전략: 8주, 거래당 최대 손실 $50 제한 (8 x 5.86 = $46.88, 손절가 기준)
  READY: trader-risk 통과(PASS), 당신의 '예'를 기다리는 중
  Claude가 place_stock_order를 다음 JSON으로 호출합니다:
    {"symbol": "TSLA", "side": "buy", "qty": "8", "type": "market", "time_in_force": "day",
     "order_class": "bracket", "take_profit_limit_price": "370.04", "stop_loss_stop_price": "358.32"}

사용자가 "예"라고 응답합니다. Claude가 이를 기록하고, place_stock_order를 호출하며, 카드에는 "Claude가 주식 매수 주문을 사용하려고 합니다"라는 메시지와 함께 해당 JSON과 두 개의 버튼(한 번 허용, 거부)이 표시됩니다. '한 번 허용'을 클릭하면 모의 거래 계정으로 주문이 전송됩니다. why 항목과 계획은 파일에 그대로 유지되며 절대 전송되지 않습니다.

절대 하지 않는 일

• 세 가지 관문을 모두 통과하지 않고는 절대 주문을 실행하지 않으며, 하나의 '예'로 두 개의 주문을 실행하지 않습니다.
• 예약된 작업이나 백그라운드 태스크에서 주문을 실행하지 않습니다. '예'라고 대답해 줄 사람이 없기 때문입니다.
• API 키나 비밀번호를 요청하거나, 읽거나, 저장하거나, 반복하지 않습니다.
• ALPACA_PAPER_TRADE 또는 "paper"를 라이브로 변경하지 않습니다. 이는 사용자가 직접 수행합니다.
• close_all_positions, cancel_all_orders, 옵션이나 암호화폐 주문 도구를 스스로 호출하지 않습니다.
• 체결 가격을 약속하지 않습니다. 시장가 주문과 손절 주문은 시장이 주는 가격대로 체결됩니다.

안전

• 교육 및 도구 목적이며, 재정적 조언이 아닙니다. '통과(PASS)'는 규칙 준수 확인일 뿐, 추천이 아닙니다.
• 기본적으로 모의 거래 사용 ("paper": true). 실제 거래 전환은 전적으로 사용자의 결정이며, 사용자 자신의 설정에서 이루어집니다.
• 이 팩에서 주문을 실행하는 유일한 스킬은 trader-broker이며, 다음 세 가지 조건을 모두 충족할 때만 실행됩니다: trader-risk가 오늘 해당 정확한 주문을 통과시켰고, 사용자가 채팅에서 해당 하나의 주문에 대해 명시적인 '예'를 입력했으며, 사용자가 주문 도구를 "승인 필요"로 설정했기 때문에 나타난 Claude 자체 카드에서 '한 번 허용'을 클릭했습니다. (Customize > Connectors > 도구 권한). 주문 도구를 절대 "항상 허용"으로 설정하지 마십시오.
• 설정에서 명시적으로 허용하고 사용자가 확인하지 않는 한, 옵션, 마진, 공매도 또는 레버리지는 거래하지 않습니다.
• 브로커 키는 환경 변수나 Claude Desktop 설정 파일에만 저장되며, 절대 채팅에 입력되지 않습니다.