Charlie API를 사용하여 Python으로 AI 시장 브리핑 구축하기

시장 준비 과정은 반복적일 수 있습니다. 차트를 보기 전에, 많은 트레이더와 분석가들은 매일 스스로에게 같은 질문을 던집니다: 현재 시장의 분위기(tone)는 어떠한가? 시장이 추세(trending)를 보이고 있는가, 박스권(ranging)인가, 아니면 소음(noisy)이 많은가? 관련 신호나 리스크 요인이 있는가? 결정을 내리기 전에 무엇에 주의를 기울여야 하는가? 나는 이 워크플로우의 일부를 작은 Python 스크립트로 자동화하고 싶었습니다. 트레이딩 봇(trading bot)이 아닙니다. 맹목적인 신호 생성기도 아닙니다. 금융 조언도 아닙니다. 그저 API를 호출하여 구조화된 시장 브리핑을 반환하는 간단한 명령줄 도구(command-line tool)일 뿐입니다. 이 글에서 나는 darwintIQ Charlie API를 호출하고 읽기 쉬운 시장 브리핑을 출력하는 최소한의 Python 예제를 보여줄 것입니다. 전체 예제 스크립트는 여기에서 확인할 수 있습니다: GitHub 예제 스크립트

우리가 구축하는 것
스크립트는 다섯 가지 작업을 수행합니다:

1. 환경 변수 또는 명령줄 인자에서 API 토큰을 읽습니다.
2. 시장 브리핑 요청을 생성합니다.
3. Charlie API에 POST 요청을 보냅니다.
4. 기본적인 HTTP 및 네트워크 오류를 처리합니다.
5. 전체 JSON 응답 또는 포맷팅된 요약을 출력합니다.

기본적인 사용 사례는 DAX 시장 브리핑입니다:
python charlie_market_briefing_example.py

다른 심볼(symbol)을 요청할 수도 있습니다:
python charlie_market_briefing_example.py --symbol XAUUSD

또는 더 구체적인 질문을 할 수도 있습니다:
python charlie_market_briefing_example.py \
--symbol EURUSD \
--prompt "EURUSD에 대한 트레이더 데스크 브리핑을 제공해줘. 현재 분위기를 주도하는 것은 무엇인가?"

왜 시장 브리핑인가?
대부분의 트레이딩 도구는 가공되지 않은 데이터(raw data)나 최종 매수/매도 신호에 집중합니다. 하지만 그 사이에는 유용한 계층이 있습니다: 바로 구조화된 시장 맥락(structured market context)입니다.
시장 브리핑은 다음을 요약하는 데 도움을 줄 수 있습니다:

• 현재 분위기 (current tone)
• 방향성 편향 (directional bias)
• 신뢰도 (confidence)
• 주요 리스크 (main risks)
• 관련 관찰 사항 (relevant observations)
• 뒷받침 근거 (supporting evidence)

이는 여러분의 분석을 대체하는 것이 아니라 구조화된 시작점을 제공하기 때문에 인간의 의사결정에 유용합니다. 나는 이것을 정량적 맥락(quantitative context)으로부터 생성된 트레이더 데스크 브리핑이라고 생각합니다.

외부 Python 의존성 없음
이 예제는 의도적으로 외부 패키지를 사용하지 않습니다. 오직 Python의 표준 라이브러리만을 사용합니다:

import argparse
import json
import os
import sys
import urllib.error
import urllib.request
from typing import Any

이를 통해 거의 모든 Python 환경에서 스크립트를 쉽게 실행할 수 있습니다. 가상 환경(virtual environment)이 필요하지 않습니다. pip install requests를 할 필요도 없습니다. API 토큰 외에 추가적인 설정도 필요하지 않습니다.

기본 설정
스크립트는 몇 가지 기본값을 정의합니다:

DEFAULT_BASE_URL = "https://api.darwintiq.com/v1/charlie"
DEFAULT_SYMBOL = "DAX"
DEFAULT_WORKFLOW_ID = "market_briefing"
DEFAULT_PROMPT = (
"DAX에 대한 트레이더 데스크 브리핑을 제공해줘. "
"현재의 분위기를 실제로 주도하고 있는 것은 무엇인가?"
)

기본 워크플로(workflow)는 market_briefing입니다. 기본 심볼(symbol)은 DAX입니다. 기본 프롬프트(prompt)는 Charlie에게 현재 시장 분위기를 주도하는 요인이 무엇인지 설명하도록 요청합니다. 이 모든 설정은 명령줄(command line)에서 재정의할 수 있습니다.

인증 (Authentication)
스크립트는 API 토큰을 필요로 합니다. 다음과 같이 환경 변수(environment variable)로 설정하거나:

export DARWINTIQ_API_TOKEN = "your_api_token_here"

직접 전달할 수 있습니다:

python charlie_market_briefing_example.py --token your_api_token_here

로컬 개발 시에는 환경 변수를 사용하는 것이 대개 더 깔끔합니다. 스크립트는 다음과 같이 이를 읽습니다:

parser.add_argument(
"--token",
default=os.getenv("DARWINTIQ_API_TOKEN"),
help="API token. Defaults to DARWINTIQ_API_TOKEN.",
)

토큰을 사용할 수 없는 경우, 스크립트는 명확한 에러 메시지와 함께 종료됩니다:

if not args.token:
parser.error("missing API token. Set DARWINTIQ_API_TOKEN or pass --token.")

API 페이로드(payload) 구축
요청 페이로드에는 세 가지 필수 항목이 포함됩니다:
symbol, workflowId, messages

def build_payload(args: argparse.Namespace) -> dict[str, Any]:
payload: dict[str, Any] = {
"symbol": args.symbol,
"workflowId": args.workflow_id,
"messages": [
{
"role": "user",
"content": args.prompt,
}
],
}
if args.timeframe:
payload["timeframe"] = args.

timeframe
if args.signal_mode:
payload["signalMode"] = args.signal_mode
return payload

이러한 구조는 스크립트를 유연하게 만듭니다. 기본 브리핑 워크플로 (workflow)를 사용할 수도 있지만, CLI (Command Line Interface)를 통해 프롬프트 (prompt), 심볼 (symbol), 타임프레임 (timeframe) 또는 시그널 모드 (signal mode)를 조정할 수 있습니다. 예를 들어:

python charlie_market_briefing_example.py
--symbol DAX
--timeframe H1
--prompt "Give me a short briefing for the next trading session."

API 호출하기

API 요청은 JSON 바디 (body)와 Bearer 토큰 (Bearer token) 인증을 사용하는 일반적인 HTTP POST 요청입니다:

request = urllib.request.Request(
url,
data=body,
method="POST",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
"Accept": "application/json",
},
)

응답은 JSON으로 디코딩 및 파싱됩니다:

with urllib.request.urlopen(request, timeout=timeout) as response:
raw = response.read().decode("utf-8")
return json.loads(raw)

스크립트는 또한 일반적인 에러 케이스 (error cases)를 처리합니다:

except urllib.error.HTTPError as exc:
raw = exc.read().decode("utf-8", errors="replace")
try:
detail = json.loads(raw)
except json.JSONDecodeError:
detail = {"error": raw or exc.reason}
raise SystemExit(
f"HTTP {exc.code} calling Charlie API:\n"
f"{json.dumps(detail, indent=2, ensure_ascii=False)}"
) from exc
except urllib.error.URLError as exc:
raise SystemExit(f"Network error calling Charlie API: {exc.reason}") from exc

이 과정은 매우 유용합니다. 왜냐하면 API 예제들은 종종 성공적인 경로 (happy path)만을 보여주는 경우가 많기 때문입니다. 실제 상황에서는 명확한 에러 메시지가 중요합니다.

읽기 쉬운 브리핑 출력하기

API 응답은 가공되지 않은 JSON 형태로 출력할 수 있습니다:

python charlie_market_briefing_example.py --json

하지만 매일 사용하는 용도로는 포맷팅된 요약본이 읽기에 더 쉽습니다. 스크립트는 다음과 같은 필드들을 추출합니다:

symbol, workflowLabel, language, summary, answer, evidence

def print_formatted_response(data: dict[str, Any]) -> None:
answer = data.

만약 요약(summary)이 제공되면 가장 중요한 필드를 출력합니다: bottom_line = summary . get ( "bottomLine" ) bias = summary . get ( "bias" ) confidence = summary . get ( "confidence" ) main_risk = summary . get ( "mainRisk" ) 그 결과 브리핑에 깔끔한 구조를 부여합니다: Symbol: DAX Workflow: Market Briefing Language: en Bottom line: ... Bias: ... Confidence: ... Main risk: ... Answer: ... Evidence: - ... - ... 이렇게 하면 출력을 커맨드라인 브리핑, 저널 항목 또는 다른 자동화의 입력으로 유용하게 만들 수 있습니다. 사용 예시 기본 DAX 브리핑: python charlie_market_briefing_example.py 다른 심볼에 대한 브리핑: python charlie_market_briefing_example.py --symbol XAUUSD 사용자 지정 프롬프트: python charlie_market_briefing_example.py \ --symbol DAX \ --prompt "유럽장 개시 전 간결한 트레이더 데스크 브리핑을 제공해 주세요." 시간대 재정의: python charlie_market_briefing_example.py \ --symbol EURUSD \ --timeframe H1 전체 JSON 응답: python charlie_market_briefing_example.py --symbol DAX --json 예시 출력 형식화된 응답은 다음과 같을 수 있습니다: Symbol: DAX Workflow: Market Briefing Language: en Bottom line: 시장 분위기는 신중하며, 방향성은 여전히 후속 조치에 달려 있습니다. Bias: 중립에서 약간 강세 Confidence: 보통 Main risk: 거시 경제 헤드라인 주변의 변동성 Answer: 현재 DAX 분위기는 단기 모멘텀, 위험 심리 및 다가오는 거시 촉매제에 대한 불확실성의 혼합으로 주도되는 것으로 보입니다. Evidence: - 최근 모델 컨텍스트는 혼재되지만 개선되고 있는 상황을 보여줍니다. - 모멘텀은 존재하지만 하방 위험을 제거하기에는 충분하지 않습니다.

• 다음 세션은 매수세가 압력을 유지할 수 있는지 여부에 크게 좌우될 수 있습니다. 이는 단지 예시일 뿐입니다. 실제 API 출력은 선택된 심볼 (symbol), 시장 상황, 워크플로 (workflow), 그리고 프롬프트 (prompt)에 따라 달라집니다.

가능한 확장 기능
기본적인 CLI 클라이언트를 구축하고 나면, 이를 기반으로 더 유용한 워크플로를 구축할 수 있습니다. 예를 들어:

1. 브리핑을 Markdown으로 저장하기
   각 브리핑을 일일 매매 일지에 저장할 수 있습니다.

from datetime import datetime
date = datetime.utcnow().strftime("%Y-%m-%d")
filename = f"{date}-DAX-briefing.md"

2. 브리핑을 Telegram 또는 Discord로 전송하기
   터미널에 출력하는 대신, 스크립트가 매일 아침 개인 채널로 브리핑을 보낼 수 있습니다.

3. 여러 심볼에 대한 브리핑 생성하기

symbols = ["DAX", "XAUUSD", "EURUSD", "GBPUSD"]
for symbol in symbols:
    # 각 심볼에 대해 API 호출 ...

4. 대시보드의 일부로 사용하기
   동일한 API 응답을 웹 대시보드, 내부 도구 또는 트레이딩 어시스턴트 인터페이스에 표시할 수 있습니다.

5. MetaTrader 워크플로와 연결하기
   이와 같은 Python 스크립트는 외부 분석 API와 MetaTrader 기반 워크플로 사이의 가교 역할을 할 수도 있습니다.

이것이 아닌 것
이러한 종류의 도구를 오해해서는 안 됩니다. 이것은 다음과 같은 것이 아닙니다:

• 트레이딩 봇 (trading bot)
• 보장된 신호 생성기 (signal generator)
• 금융 조언 (financial advice)
• 리스크 관리 (risk management)의 대체제
• 미래 수익에 대한 약속

목표는 시장 컨텍스트 (market context)를 더 쉽게 소비할 수 있도록 만드는 것입니다. 좋은 브리핑은 당신의 사고를 대체하는 것이 아니라, 당신의 사고를 지원해야 합니다.

마치며
저는 시장 브리핑을 API 워크플로로 취급하는 아이디어를 좋아합니다. 서로 다른 대시보드에서 수동으로 정보를 수집하는 대신, 개발자는 API를 호출하여 구조화된 시장 컨텍스트를 요청하고 그 응답을 읽기 쉬운 브리핑으로 변환할 수 있습니다. 이 예제에서는 darwintIQ의 Charlie API를 사용했습니다. Charlie는 개인 퀀트 (Quant) 분석가처럼 작동하도록 설계되었습니다. 즉, 정량적인 시장 컨텍스트를 읽기 쉬운 브리핑으로 변환하여 트레이더가 현재의 분위기를 주도하는 요인이 무엇인지 이해하도록 돕습니다.

핵심은 자동화된 매매 실행 (automated trade execution)이 아닙니다. 핵심은 더 나은 시장 준비 (market preparation)입니다. 만약 여러분이 트레이딩 도구, 대시보드 (dashboards), 저널 (journals), 또는 MetaTrader 워크플로우 (workflows)를 구축하고 있으며 여기에 AI가 생성한 시장 컨텍스트 (market context)를 추가하고 싶다면, Charlie를 API를 통한 브리핑 레이어 (briefing layer)로 사용할 수 있습니다. 이 서비스는 여러분을 대신해 거래를 체결하도록 설계되지 않았습니다. 현재의 시장 분위기 (market tone)를 더 빠르게 이해할 수 있도록 돕기 위해 설계되었습니다. 전체 Python 예제는 여기에서 확인할 수 있습니다: GitHub 예제 스크립트 (GitHub example script) Charlie에 대한 더 자세한 내용은 여기에서 확인하세요: Charlie 문서 (Charlie documentation) 읽어주셔서 감사합니다.