2~3단계 튜토리얼에서 Finnhub API로 가격·뉴스를 가져오고, 그걸 Claude API에 넘겨 AI 판단까지 받아봤다. 그 코드에 나온 낯선 개념들을 정리한다.
오늘 나온 개념
쿼리 파라미터
URL 뒤에 ?이름=값 형태로 데이터를 실어 보내는 방식. 예를 들어
https://finnhub.io/api/v1/quote?symbol=AAPL&token=내키
에서 ? 뒤의 symbol=AAPL과 token=내키가 쿼리 파라미터다. “어떤 종목(symbol)을, 무슨 자격(token)으로 달라는지”를 이 방식으로 서버에 전달한다. 여러 개를 보낼 땐 &로 이어 붙인다.
fetch
자바스크립트에 내장된, 인터넷 너머의 데이터를 가져오는 함수. fetch(주소)라고 쓰면 그 주소로 요청을 보내고, 응답이 온다.
await / 비동기 처리
fetch처럼 응답이 올 때까지 시간이 걸리는 작업은, 그 결과가 올 때까지 “기다렸다가” 다음 줄을 실행해야 한다. 코드 앞에 await를 붙이면 “이 줄이 끝날 때까지 기다린 다음 다음 줄로 가라”는 뜻이 된다. 이렇게 기다림이 필요한 처리 방식을 비동기 처리라고 부른다.
가격 데이터 필드
Finnhub의 /quote가 돌려주는 시세 데이터는 이런 약자로 되어 있다.
| 필드 | 뜻 |
|---|---|
c | 현재가 |
d | 전일 대비 변화액 |
dp | 전일 대비 변화율(%) |
h / l / o | 오늘 고가 / 저가 / 시가 |
pc | 전일 종가 |
t | 이 데이터의 기준 시각 |
실제로 확인한 결과
=== 가격 ===
{ c: 336.91, d: 3.89, dp: 1.1681, h: 339.57, l: 334.02, o: 334.54, pc: 333.02, t: 1785182400 }
=== 뉴스 ===
최근 7일간 뉴스 248개
가장 최신 뉴스: SNDK, NVDA, SKHY, ASML Stocks Extend Slide Overnight Amid China's AI Challenge, Tech Rotation
뉴스가 248개나 잡히는 건 회사 관련 전체 뉴스라 범위가 넓어서다. 실제 AI 판단엔 최신 몇 개만 추려서 썼다 (아래 3단계).
3단계 — AI 판단 받기 (구조화된 출력)
가격·뉴스 데이터를 Claude API에 넘겨서 “매수/매도/보유 + 이유”를 받아봤다.
SDK
어떤 서비스를 코드에서 쉽게 쓰게 도와주는, 미리 만들어진 도구 모음. @anthropic-ai/sdk를 설치하면 Claude API를 직접 통신 규약(HTTP 요청 형식 등)을 안 짜고도 짧은 코드로 부를 수 있다.
구조화된 출력 (structured output)
AI에게 그냥 “판단해줘”라고만 하면 답이 매번 조금씩 다른 형태로 올 수 있다. **“이 모양의 JSON으로만 답해줘”**라고 강제하는 기능이 구조화된 출력이다. 이걸 쓰면 { 판단: "매수", 이유: "..." }처럼 항상 똑같은 모양으로 받을 수 있어서, 코드가 그 값을 안정적으로 꺼내 쓸 수 있다.
Zod 스키마
“구조화된 출력”에 정확히 어떤 모양을 원하는지 알려주는 코드 도구. 예:
const DecisionSchema = z.object({
판단: z.enum(['매수', '매도', '보유']),
이유: z.string(),
});
“판단은 매수/매도/보유 중 하나여야 하고, 이유는 글자여야 한다”는 규칙을 이렇게 코드로 적어두면, AI가 이 모양을 지켜서 답하게 된다.
막힘 → 해결: zod 버전 문제
처음 실행했을 때 Cannot read properties of undefined (reading 'def')라는 에러가 났다. 원인은 설치된 zod 라이브러리가 v3에서 v4로 넘어가는 과도기 버전이라, import { z } from 'zod'로 가져오면 옛날(v3) 방식이 되는데, 구조화된 출력 기능은 새(v4) 방식을 기대해서 생긴 충돌이었다. import { z } from 'zod/v4'로 한 줄 고치니 바로 해결됐다.
실제로 확인한 AI 판단 결과
판단: 보유
이유: AAPL이 52주 신고가를 경신하며 상승세를 보이고 있으나, AI 경쟁력에 대한 의구심과 기술주 전반의
조정 압력이 존재해 추가 매수보다는 기존 포지션을 유지하며 추이를 지켜보는 것이 적절해 보입니다.
재사용 자산 — 코드
scripts/fetch-price-news.js— 가격·뉴스만 가져오는 코드 (다른 종목 쓰려면 맨 위symbol값만 변경)scripts/get-decision.js— 그 데이터로 AI 판단까지 받는 코드 (구조화된 출력 예시로 그대로 재사용 가능)