HiThink-Tech/Financial-API

HiThink‑Tech / Financial‑API – 통화순 금융 데이터 서비스

무엇인가요 – 중국 시장 데이터 제공업체 통화순(10 Juqka)이 유지 관리하는 상용 수준의 데이터 플랫폼입니다. AI 에이전트, 양적 연구자, 개발자를 위한 A주(중국 메인보드) 시장 데이터를 통합하고 API 키 보호를 제공하는 서비스입니다.

핵심 기능

• 어떤 A주 티커든 실시간 스냅샷, 집합입찰 스냅샷, 일일 K선(OHLCV) 제공.
• 전체 기업 재무제표(손익, 대차대조표, 현금흐름) 및 평가 비율 세트(PE, PB, PS, PCF).
• 메타데이터: 티커 조회, 거래 캘린더, 기업 행위, 스플릿/보너스 요인, 전후 조정 가격.
• 시장 전반 데이터: 지수/섹터 구성 종목, 펀드/매니저 정보, 공개 선물 및 옵션 계약, 한도상승/하락 풀, "총체"(돌파) 풀, 인기주 및 용호방 랭킹 등 특수 리스트.
• 백테스팅 또는 팩터 연구를 위한 대량 시장 덤프 다운로드.
• 로컬 DuckDB 기반의 marketdb로 전체 시장을 증분 동기화 가능하며 일반 SQL로 쿼리 가능.

접근 방법

방법	일반적인 용도	진입점
REST API	웹 서비스, 앱, 어떤 언어에도 통합	https://fuyao.aicubes.cn/api/... (README의 curl 예제 참조)
MCP (Model‑Center‑Protocol)	Claude Desktop, Cursor, Windsurf 등 LLM 기반 도구에 연결	6개의 호스팅 엔드포인트(A주, A주지수, 메타, 펀드, 선물, 옵션)
CLI (@hithink-tech/hithink-finance-cli)	빠른 터미널 쿼리, 대량 다운로드, 데이터 덤프, 로컬 DuckDB 초기화	hithink-finance … 명령어
Python SDK (python/ 패키지)	노트북 탐색, 커스텀 스크립트, pandas/NumPy와 통합	python -m pip install -e ./python 후 toolkit/fuyao 스크립트 사용
에이전트 스킬 (skills/hithink-finance/)	AI 에이전트가 최적의 백엔드(API, MCP, CLI, SDK)를 자동으로 선택 가능	npx skills add …로 설치

일반 워크플로우

1. 웹 포털에서 단일 API 키를 획득하고 안전하게 보관(HITHINK_FINANCE_API_KEY).
2. 가장 편리한 진입점 선택(스킬 → 에이전트, CLI로 즉시 사용, SDK로 노트북, REST로 서비스).
3. 티커를 고유한 thscode(예: 600519.SH)로 해결.
4. 원하는 엔드포인트(스냅샷, K선, 재무제표 등) 호출.
5. 대규모 결과의 경우 시스템은 로컬에 파일(DuckDB 또는 CSV)로 저장하고 호출자에게 경로/요약만 반환.

누가 사용해야 할까

• AI 에이전트 (Claude, Cursor 등): 최신 시장 데이터가 필요한 경우. 스킬을 설치해 API, MCP, CLI 간 자동 전환 가능.
• 양적 연구자 백테스팅, 팩터 모델, 대시보드 구축 시. CLI 또는 marketdb로 로컬 DuckDB 복사본 유지하고 SQL로 쿼리 가능.
• 개발자 거래 중심 웹 또는 모바일 앱 개발 시. 어떤 언어로든 REST API 직접 호출 가능.
• 데이터 엔지니어 데이터 레이크 인제스트를 위한 대량 시장 덤프 필요 시.

보안 및 준수 주의사항

• API 키는 하드코딩하거나 소스 코드 관리에 커밋해서는 안 됨.
• 대규모 결과 세트는 디스크에 쓰여야 함. 서비스는 거대한 JSON 페이로드를 스트리밍하지 않아 컨텍스트 오버플로우를 방지.
• 서비스는 투자 조언을 제공하지 않음. 호출자는 분석 결과에 "비조언" 라벨을 붙여야 함.
• 레이트 제한은 소프트(하드 제한 없음)이지만, 급격한 고병렬 트래픽을 피할 것을 요청.

프로젝트 상태

• 활발히 유지 관리 중인 모노레포(Python + Node.js CLI + 스킬).
• 최근 릴리스에서는 집합입찰 데이터 추가, 펀드 커버리지 확장, 통합 스킬 도입.
• 향후 로드맵에는 출시 예정인 통화순 AI 클라이언트와의 통합이 포함됨.

라이선스 – MIT.

---

위 정보는 리포지토리의 README에서 직접 가져온 것이며, 추가 기능은 추측되지 않음.