개발자

봉투 스키마 · MCP/REST/WS 연동 · 사람과 에이전트 공용 레퍼런스

시작하기 — 5분 안에 첫 호출

① 키 발급 — 무료 가입 즉시② 첫 호출 — 아래 스니펫 그대로③ 응답 — 공통 봉투(JSON)

curlJSPython로그인하면 <API_KEY>가 내 키로 채워집니다

curl https://api.pearlify.io/v1/stocks/005930 \
  -H "Authorization: Bearer <API_KEY>"

연동 방식 — 같은 데이터, 세 가지 통로

MCPAI 에이전트

"mcpServers": { "pearlify": { "url": "https://mcp.pearlify.io" } }

도구 호출로 조회 — 에이전트 권장

REST서버·배치

GET /v1/stocks/:ticker

요청-응답. 스냅샷·백필용

WebSocket실시간 화면

wss://api.pearlify.io/v1/stream?topics=…

이벤트 push. Team 플랜

Pearlify Schema — 공통 봉투

화면·MCP·REST·WS가 공유하는 정규화 스키마. 4개 소스를 공통 봉투로 감쌉니다.

필드	의미
domain / event_type	무슨 종류의 이벤트인가
summary / metrics	사람용 한 줄 + 정규화 수치
mapping	어느 사업부에 어떤 방향의 영향인가 (인과)
importance	critical~low + 근거 한 줄
source / observed_at	출처·원문 링크·관측 시각 (Data Atom)

실제 응답 예시 보기 (삼성전자 공시 1건)

{
  "id": "evt_...",
  "ticker": "005930",
  "company": "삼성전자",
  "sector": "반도체",
  "domain": "disclosure|commodity|news|quote",
  "event_type": "supply_contract",
  "summary": "미국향 HBM 3,000억 공급계약",
  "metrics": { "scale": 3000, "unit": "억원" },
  "mapping": { "business_unit": "DS/메모리", "direction": "positive", "rationale": "분기 매출 대비 2.1%" },
  "importance": { "level": "high", "reason": "신규 대형 고객·HBM 수요 확인" },
  "source": { "name": "dart", "url": "https://dart.fss.or.kr/...", "doc_id": "2026..." },
  "observed_at": "2026-06-07T04:12:00Z",
  "revised_at": null
}

도메인별 event_type

domain	주요 event_type
disclosure	supply_contract · periodic_report · earnings_flash · financing · equity_change
commodity	settlement · spike
news	order · guidance · regulation · mna · macro
quote	quote · financials

인터페이스 매핑

화면	MCP	REST	WS
종목 탐색	list_universe	GET /v1/universe	—
종목 상세	get_stock	GET /v1/stocks/:ticker	subscribe{ticker}
실시간	get_feed	GET /v1/feed	stream?topics=
원자재 렌즈	get_commodity_impact	GET /v1/commodities/:sym/impact	subscribe{commodity}

인증 · 레이트리밋 · 에러

항목	내용
인증	Authorization: Bearer <API_KEY>
한도	Free 60 req/min · Indie 600 · Team 협의 (초과 시 429)
에러	401 invalid_key · 403 plan_required · 429 rate_limited · 5xx retry-after

데이터 소스 · 갱신주기

소스	갱신	신선도
DART 공시	발생 즉시	live
LME/CME 원자재	정산 시	eod
뉴스	수 분 내	live
시세	15분 지연 (Free/Indie)	delayed 15m

에이전트 디스커버리: /.well-known/mcp.json · /v1/schema