Hyean
The Truth Layer for Korean Financial Data

Clarity, Verified.

v1.0.0

DART 사업보고서에서 5소스 교차검증으로 추출한 한국 상장기업 재무 데이터. 모든 수치에 원문 출처(URL + 행·열)와 신뢰도 등급이 포함됩니다.

2,800+
상장기업
570+
표준화 항목
~90%
Verified 비율
129
엔드포인트
💡 Base URL: https://api.hyean.io ·  로컬: http://localhost:8000

MCP로 시작하기

Financial Harness는 Claude Code가 Hyean 데이터로 기업분석 보고서를 생성하는 스킬입니다. 분석 방법론은 Hyean MCP 서버가 런타임에 제공하고, 로그인은 브라우저에서 한 번 — API 키와 .env가 필요 없습니다.

설치 — 터미널에서 30초
bash
mkdir my-analysis && cd my-analysis
git clone https://github.com/twiw49/financial-harness.git .claude/skills/financial-harness
cp .claude/skills/financial-harness/settings.template.json .claude/settings.json
claude mcp add --transport http hyean https://api.hyean.io/mcp
첫 분석
bash
claude

> 삼성전자 분석해줘

# 첫 분석 시 브라우저 창이 한 번 뜹니다 — 이메일 인증으로 로그인/가입.
# 계정이 없어도 그 자리에서 생성됩니다 (무료 1,000크레딧/월, 카드 불필요).
# 이후엔 다시 묻지 않습니다. 표준 보고서 1건 ≈ 17크레딧.
방법론 자동 최신화
분석 플랜·에이전트 정의를 MCP 서버가 매 런 제공 — 업데이트 불필요
원문 추적 (Citation Drawer)
보고서 모든 수치 클릭 → DART 원문 문장. AI 생성값과 공시값이 구분됩니다
AI 비용 $0
사용자의 AI가 분석. Hyean은 데이터 크레딧만 과금
MCP 도구 6종 — preflight(상태/크레딧) · get_plan(분석 플레이북) · get_reference(방법론 문서) · call_api/call_api_batch(데이터) · log_run(텔레메트리)
CI·헤드리스(브라우저 없는 환경): claude mcp add --transport http hyean https://api.hyean.io/mcp --header "Authorization: Bearer <API_KEY>"— 키는 대시보드에서.  구 버전(git clone+.env) 사용자: 스킬 폴더에서 git pull 후 위 claude mcp add 1회 — .env의 키는 삭제해도 됩니다.

인증

인증은 두 갈래입니다 — 둘은 같은 계정, 같은 크레딧 풀을 씁니다.
① OAuth (Claude Code · MCP): 브라우저 로그인 1회, 키 관리 불필요. 토큰은 자동 갱신되며 대시보드 키 목록에 표시되지 않습니다.
② API 키 (REST · SDK · CI): 아래 3방식 — 대시보드에서 발급.

HTTP
# Bearer 인증 (권장)
curl -H "Authorization: Bearer hyn_live_xxxx" https://api.hyean.io/api/companies

# 헤더 인증
curl -H "X-API-Key: hyn_live_xxxx" https://api.hyean.io/api/companies

# 쿼리 파라미터
curl https://api.hyean.io/api/companies?api_key=hyn_live_xxxx
API 키 입력 (Try It 기능에 사용)

Python SDK

pandas 네이티브 SDK. 한 줄로 교차검증된 재무 데이터를 DataFrame으로 받습니다. 모든 행에 confidence · source_url이 포함됩니다.

설치 & 기본 사용
bash
pip install hyean
python
import hyean as hy
hy.set_api_key("hyn_live_xxxx")   # 또는 export HYEAN_API_KEY=...

# 스마트 식별자: 종목코드 / corp_code / 기업명
df = hy.load_balance("삼성전자")        # → pandas DataFrame
is_ = hy.load_income("005930", min_confidence="high")
cf  = hy.load_cashflow("00126380")
Point-in-time (as_of)
python
# 특정 시점에 공시된 재무만 — look-ahead / survivorship 차단
df = hy.load_balance("005930", as_of="2023-03-31")
# → 공시일(filing date) 기준으로 필터링된 시계열
원문 출처 추적
python
hy.source_url(df, item_id="IS_REV")
# → 'dart.fss.or.kr/dsaf001/...'
스마트 식별자
종목코드 · corp_code · 기업명 자동 인식
as_of 시점고정
공시일 기준 필터 — 백테스트 룩어헤드 방지
source_url()
DataFrame 어느 셀이든 DART 원문까지 1줄

기업 정보

GET/api/companies기업 목록Core1C
GET/api/companies/{corp_code}기업 상세Core1C
GET/api/companies/{corp_code}/coverageFnGuide 커버리지Core1C
GET/api/companies/{corp_code}/discover데이터 카탈로그AI2C

재무 데이터

GET/api/companies/{corp_code}/financials재무제표 시계열Core3C
GET/api/companies/{corp_code}/benchmark벤치마크 비교3C
GET/api/companies/{corp_code}/dividend-declared최신 확정 배당3C
GET/api/companies/{corp_code}/dividend-disclosures배당 공시 통합 리스트2C
GET/api/companies/{corp_code}/leading-indicators선행지표3C

기업 프로필

GET/api/companies/{corp_code}/profile통합 프로필AI2C
GET/api/companies/{corp_code}/risk리스크 종합AI2C
GET/api/companies/{corp_code}/quality데이터 품질AI2C
GET/api/companies/{corp_code}/governance거버넌스 (소액주주·이사회·최대주주)AI2C
GET/api/companies/{corp_code}/capital-allocation자본배분 (조달자금 약속↔이행)AI2C
GET/api/companies/{corp_code}/compensation보상·인력AI2C
GET/api/companies/{corp_code}/capital-structure자본구조AI2C
GET/api/companies/{corp_code}/audit-quality감사품질AI2C
GET/api/companies/{corp_code}/affiliate-investments타법인출자AI2C

이벤트 + 이상변동

GET/api/events/trajectoryL2 궤적 diff 이벤트 피드2C
GET/api/companies/{corp_code}/events주요사항 이벤트3C
GET/api/events/search이벤트 검색3C
GET/api/companies/{corp_code}/anomalies재무 이상변동3C

주석 + 인사이트

GET/api/companies/{corp_code}/notes주석 시계열3C
GET/api/companies/{corp_code}/notes/elements주석 요소 목록3C
GET/api/companies/{corp_code}/insight-contextInsight 컨텍스트AI5C
GET/api/companies/{corp_code}/notes/themes주석 테마 카탈로그3C
GET/api/companies/{corp_code}/notes/themes/{theme}주석 테마 묶음 시계열3C
GET/api/segments/{corp_code}세그먼트AI3C
GET/api/companies/{corp_code}/notes/maturity차입금·리스 만기 ladder3C
GET/api/segments/{corp_code}/axes세그먼트 축 목록AI3C

Insight 컨텍스트

GET/api/context/categoriesInsight 카테고리 목록AI0C
GET/api/context/{corp_code}원문 컨텍스트AI3C
GET/api/context/{corp_code}/available보유 카테고리AI0C
GET/api/context/search컨텍스트 검색AI3C

감사의견

GET/api/companies/{corp_code}/audit감사의견 + KAMDeep2C

Deep 구조화

GET/api/companies/{corp_code}/deepDeep 구조화Deep2C
GET/api/companies/{corp_code}/history회사 이력 통합 타임라인2C

그룹 + 순위

GET/api/companies/{corp_code}/groups기업 분류2C
GET/api/companies/{corp_code}/rank백분위 순위3C

밸류에이션 + 등급

GET/api/companies/{corp_code}/valuation다방법 공정가치 추정AI3C
GET/api/companies/{corp_code}/grades섹터상대 팩터 등급AI2C
GET/api/companies/{corp_code}/forward자체 Forward (EPS·배수·리비전)AI3C
GET/api/forward/sectors섹터 Forward 로테이션AI2C

매크로 경제

GET/api/macro/context/{corp_code}매크로 맥락3C
GET/api/macro/timeseries매크로 시계열3C
GET/api/macro/rates금리·환율·지수 최신값3C
GET/api/macro/indicators매크로 지표 최신값3C
GET/api/macro/glossary경제 통계용어사전Data1C

KRX 지수

GET/api/index/listKRX 지수 목록2C
GET/api/index/{index_name}/timeseries지수 시세2C
GET/api/index/{index_name}/constituents지수 편입 종목 목록2C

정기보고서

GET/api/companies/{corp_code}/filings기업 정기보고서 목록2C
GET/api/companies/{corp_code}/filings/{rcp_no}정기보고서 상세 조회2C

원문 출처

GET/api/source-detail영업이익 출처 추적Core1C
GET/api/source-items/{corp_code}항목별 5소스 원문 추적Core1C

Enhanced (AI Agent)

GET/api/companies/{corp_code}/summary기업 전체 분석 데이터AI5C
GET/api/companies/{corp_code}/quarterly분기별 실적 조회3C
GET/api/companies/{corp_code}/price최근 주가 조회1C
GET/api/companies/{corp_code}/price-stats주가 QuantStats 통계1C
GET/api/companies/{corp_code}/peers업종 내 동종사 비교AI3C
GET/api/prices/bulk복수 종목 수정주가 일괄조회5C
GET/api/screening조건 기반 기업 스크리닝AI3C

메타 + 통계

GET/api/meta/itemsitem_id 메타Meta1C
GET/api/statsDB 통계Meta1C

Compare

GET/api/compare기업군 핵심지표 비교3C

Datasets (벌크 배포)

GET/api/datasets벌크 패널 카탈로그0C
GET/api/datasets/{dataset_id}/download패널 parquet 다운로드25C

Evidence Pack

GET/api/companies/{corp_code}/evidence-pack기업 전수 증거 아카이브 (ZIP)10C

거버넌스·감사·소유

GET/api/companies/{corp_code}/people-compensation개인별 보수 궤적 (L2)2C
GET/api/companies/{corp_code}/exec-compensation임원보수 (L2)3C
GET/api/companies/{corp_code}/shareholders주주지분 (L2)3C
GET/api/companies/{corp_code}/audit-fees감사보수 (L2)3C
GET/api/companies/{corp_code}/employees직원 현황 (L2)3C
GET/api/companies/{corp_code}/treasury-holdings자기주식 취득방법 (L2)3C
GET/api/companies/{corp_code}/board이사회 구성 (시계열)2C

결제

GET/api/billing/config결제 위젯 공개 설정Core0C
GET/api/billing/orders구매 내역 + 선불 잔액Core0C

기업 뉴스

GET/api/companies/{corp_code}/news기업 뉴스 목록1C

배당

GET/api/dividends/calendar배당 캘린더 (기준일·지급일)1C

사업 키워드

GET/api/companies/{corp_code}/keywords기업 사업 키워드 + 산업내 순위2C
GET/api/keywords/{keyword}/companies같은 사업분야 기업 (매출순)2C
GET/api/keywords/{keyword}/timeseries산업 궤적 (회사×연도 매출·순위)2C
GET/api/keywords키워드 카탈로그 (산업 탐색)2C
GET/api/keywords/leaderboard산업 리더보드 (성장·수출·밸류)2C
GET/api/keywords/entrants시장 전체 산업 진입 피드2C
GET/api/keywords/map산업 트리맵 (규모·성장·비중)2C
GET/api/keywords/{keyword}/entrants산업 진입·이탈 기업 명단2C
GET/api/keywords/{keyword}/share-check공시 점유율 대사 (주장 vs 계산)2C

사업의 내용

GET/api/companies/{corp_code}/revenue-segments매출 구조 (L2)3C
GET/api/companies/{corp_code}/procurement-segments조달 구조 (L2)3C
GET/api/companies/{corp_code}/customer-segments고객 집중도 (L2)3C
GET/api/companies/{corp_code}/capacity-segments생산능력 (L2)3C
GET/api/companies/{corp_code}/business-tables원본 표 (L3)3C
GET/api/companies/{corp_code}/backlog-segments수주잔고 (L2)3C
GET/api/companies/{corp_code}/capex-segments시설투자 (L2)3C
GET/api/companies/{corp_code}/esg-segmentsESG 환경 KPI (L2)3C
GET/api/companies/{corp_code}/market-share-segments시장점유율 (L2)3C
GET/api/companies/{corp_code}/ppe-segments생산설비/유형자산 (L2)3C
GET/api/companies/{corp_code}/price-segments판매단가 (L2)3C
GET/api/companies/{corp_code}/production-segments생산실적 (L2)3C
GET/api/companies/{corp_code}/rnd-personnel-segmentsR&D 인력 학위분포 (L2)3C
GET/api/companies/{corp_code}/rnd-segments연구개발비 (L2)3C
GET/api/companies/{corp_code}/sales-channel-segments판매경로별 매출 (L2)3C
GET/api/companies/{corp_code}/ip-patent-segments지식재산권 보유 건수 (L2)3C
GET/api/companies/{corp_code}/utilization-segments가동률 (L2)3C

소스오류 카탈로그

GET/api/source-errors우리가 잡은 DART 공시 오류Core1C
GET/api/companies/{corp_code}/source-errors기업별 소스오류Core1C

시그널 스크리너

GET/api/screener시그널 기반 기업 스크리너AI2C
GET/api/screener/columns스크리너 컬럼 메타AI0C
GET/api/companies/{corp_code}/signals단건 기업 시그널AI2C
GET/api/screener/recipes스크리너 레시피 카탈로그0C

자본·부외 구조

GET/api/companies/{corp_code}/investments타법인출자3C
GET/api/companies/{corp_code}/debt-maturity채무 만기래더3C
GET/api/companies/{corp_code}/convertibles전환사채/BW3C
GET/api/companies/{corp_code}/fund-usage자금사용내역3C
GET/api/companies/{corp_code}/guarantees채무보증·우발3C
GET/api/companies/{corp_code}/derivatives파생상품3C
GET/api/companies/{corp_code}/fx-exposure환위험 익스포저3C
GET/api/companies/{corp_code}/sensitivity시장위험 민감도3C
GET/api/companies/{corp_code}/capital-tables원본 표 (L3)3C

통합 공시

GET/api/companies/{corp_code}/disclosures기업 통합 공시 리스트2C
GET/api/disclosures/feed유니버스 중요공시 속보 피드2C
GET/api/disclosures/{rcp_no}공시별 파싱·재계산 데이터1C

회계 수정 이력

GET/api/revisions회계 수정 이력 카탈로그Core1C
GET/api/companies/{corp_code}/revisions기업별 재무 Fact 버전체인Core2C
GET/api/companies/{corp_code}/metric-revisions파생지표 as_of 버전체인Core2C
GET/api/revisions/feed정정 증분 스트림 (커서 피드)1C

에러 코드

코드의미해결방법
400잘못된 파라미터파라미터 타입/범위 확인
401인증 실패API 키/토큰 확인 — MCP는 /mcp 재연결
402크레딧 부족응답의 upgrade_url — /pricing에서 충전
404기업 없음corp_code 확인
429요청 한도 초과120회/분 제한
500서버 오류재시도 또는 문의