Financial-API 딥다이브
— 데이터 회사가 직접 만든 “에이전트용 창구”

1프로젝트 한줄 요약

Financial-API(패키지명 hithink-finance)는 중국 A주 금융 데이터를 여섯 가지 방법으로 꺼내 쓰게 해 주는 공식 클라이언트 모노레포입니다. 데이터 자체는 fuyao.aicubes.cn이라는 원격 서버에 있고, 이 저장소에 담긴 것은 그 서버를 부르는 클라이언트들과 계약 문서입니다.

여기서 오해하기 쉬운 지점을 먼저 정리합니다. 이름이 “Financial-API”라서 API 서버 코드가 들어 있을 것 같지만, 서버 코드는 없습니다. 저장소를 clone하면 나오는 것은 ① REST 계약을 적은 마크다운 문서, ② Node.js로 짠 CLI, ③ 파이썬 SDK와 로컬 DuckDB 도구, ④ MCP 서버에 붙는 설정과 도구 목록, ⑤ AI 에이전트용 스킬 문서입니다. MCP 서버 구현조차 원격에 호스팅돼 있어 이 저장소에는 URL과 도구 계약만 있습니다.

2왜 주목받는가

2026년 6월 9일 첫 공개, 두 달 반 만에 별 1.48k. 중국어 문서 일색인 저장소치고는 빠른 속도입니다. 이유는 셋으로 갈립니다.

① 비공식 스크레이퍼 생태계에 공식 사업자가 들어왔다. A주 데이터는 오래도록 akshare·tushare·baostock 같은 커뮤니티 프로젝트가 여기저기서 긁어모아 채우던 영역입니다. 소스가 바뀌면 조용히 깨지고, 품질 보증도 없습니다. 통화순은 중국 증권 단말기 시장의 주요 사업자이고, README는 “官方提供和維護(공식 제공·유지보수)”를 반복해서 강조합니다.

② MCP와 Agent Skill을 처음부터 1급 시민으로 뒀다. 기존 금융 데이터 라이브러리에도 서드파티 MCP 래퍼는 있지만, 사업자가 직접 MCP 엔드포인트 4개·도구 55개를 운영하는 사례는 드뭅니다.

③ 접근 경로를 여섯 개 깔아 두고 “고르지 말라”고 한다. README의 권장 진입점은 CLI도 SDK도 아니고 Agent Skill입니다. 사용자는 “귀주모태 오늘 가격 알려줘”라고만 말하고, 어느 문으로 갈지는 에이전트가 고르라는 설계입니다.

커뮤니티 대안과의 실제 차이

범위도 정직하게 좁혀 놨습니다. README가 지원하지 않는다고 명시한 것은 분봉·틱 데이터, 홍콩/미국 시장, 거시경제 지표, 뉴스·공시 원문, 리서치 리포트 원문입니다. akshare가 커버하는 영역 일부를 의도적으로 비워 둔 셈이라, “akshare를 대체한다”가 아니라 “A주 코어 데이터를 계약 있는 형태로 준다”가 정확한 위치입니다.

3기술 스택 전체 지도

모노레포지만 워크스페이스 도구(pnpm workspace, turborepo 등)를 쓰지 않습니다. 독립적인 두 서브프로젝트가 나란히 놓여 있고, 둘을 묶는 것은 빌드 도구가 아니라 docs/의 계약 문서입니다.

① Node.js CLI — hithink-finance-cli/

② Python — python/

③ CI — .github/workflows/ 4개

live-canary는 흔치 않은 장치입니다. 보통 CI는 목(mock)을 씁니다. 이 저장소는 그 위에 “주 1회 진짜 서버를 찔러 보는” 잡을 하나 더 얹었습니다. 클라이언트 라이브러리는 내 코드가 멀쩡해도 상대가 바뀌면 깨진다는 특성이 있고, 그걸 테스트로 잡으려는 시도입니다.

4아키텍처 심화 분석

전체 구조도

패턴 ① — 능력을 코드가 아니라 “데이터”로 적는다

이 저장소에서 가장 배울 만한 대목입니다. CLI가 지원하는 원격 명령은 32개(market snapshot, financials indicators, special limit-up-pool …). 보통이라면 명령마다 핸들러 함수를 하나씩 짭니다. 여기서는 그러지 않습니다.

src/contracts/remote-capabilities.ts(1,514줄) 안에 서술자(descriptor) 배열이 있고, 항목 하나가 명령 하나입니다.

export interface RemoteCapabilityDescriptor {
  id: string;                     // 'market.snapshot'
  command: readonly [string, string];  // ['market', 'snapshot']
  description: string;
  endpoint: string;               // '/api/a-share/prices/snapshot'
  method: 'GET';
  inputSchema: ZodType<Record<string, unknown>>;
  outputSchema: ZodType<unknown>;
  options: readonly RemoteOptionDescriptor[];   // --thscodes 등
  paging: 'none' | 'offset' | 'page';
  pagingEnd?: 'short-page' | 'has-more';
  window: 'none' | 'ten-years' | 'five-years' | 'one-year' | 'today-only';
}

실제 항목 하나는 이렇게 생겼습니다.

{
  id: 'market.snapshot',
  command: ['market', 'snapshot'],
  description: 'Query A-share price snapshots',
  endpoint: '/api/a-share/prices/snapshot',
  method: 'GET',
  inputSchema: z.object({
    thscodes: commaCodes.optional(),
    limit:  z.number().int().min(1).max(10000).default(100),
    offset: z.number().int().nonnegative().default(0),
  }).strict(),
  outputSchema: itemOutput,
  options: [
    { flags: '--thscodes <codes>', description: 'comma-separated A-share thscodes',
      type: 'string' },
    { flags: '--limit <number>',  description: 'page size', type: 'integer',
      defaultValue: 100 },
    { flags: '--offset <number>', description: 'row offset', type: 'integer',
      defaultValue: 0 },
  ],
  paging: 'offset',
  window: 'none',
},

그리고 src/commands/remote.ts(403줄) 단 하나의 제네릭 실행기가 이 배열을 순회하며 commander 명령을 등록하고, 옵션을 파싱하고, 페이징을 돌리고, 결과를 렌더합니다. 새 엔드포인트를 추가하는 작업이 “함수를 짜는 일”에서 “배열에 항목 하나를 넣는 일”로 바뀐 것이 이 설계의 전부이자 핵심입니다.

패턴 ② — 봉투와 내용물을 따로 검증한다

서버 응답은 항상 같은 봉투(envelope)에 담겨 옵니다.

export const fuyaoEnvelopeSchema = z.object({
  code: z.number().int(),      // 0=성공, 1xxx=파라미터, 2xxx=인증, 4xxx/5xxx=서버
  message: z.string(),
  request_id: z.string().optional(),
  data: z.unknown(),           // 여기는 일부러 unknown
});

data를 unknown으로 둔 게 의도적입니다. 봉투 형태가 깨졌는지(UPSTREAM_INVALID_RESPONSE)와 내용물 형태가 깨졌는지(UPSTREAM_INVALID_DATA)를 다른 에러로 구분하기 위해서입니다. 전자는 서버 전체가 이상한 것이고, 후자는 그 엔드포인트 하나의 스키마가 바뀐 것 — 원인이 완전히 다르니 에러도 달라야 합니다.

패턴 ③ — 에러 코드를 종료 코드로 번역한다

src/infrastructure/fuyao/client.ts의 businessError()가 서버 코드 대역을 CLI 종료 코드로 매핑합니다. 스크립트에서 $?만 보고 대응을 나눌 수 있게 하려는 배려입니다.

패턴 ④ — 재시도: 지수 백오프 + 지터 + 서버 지시 존중

// src/infrastructure/fuyao/retry.ts
export const RETRYABLE_BUSINESS_CODES = new Set([4001, 5001, 5002, 5003]);

export function retryDelayMs(attempt: number, random: () => number): number {
  const base = Math.min(1000 * 2 ** attempt, 8000);   // 1s → 2s → 4s → 8s(상한)
  return Math.round(base + base * 0.2 * random());    // +0~20% 지터
}

여기에 parseRetryAfter()가 붙습니다. 서버가 Retry-After 헤더를 주면 그쪽을 우선하고, 헤더는 초 단위 숫자와 HTTP 날짜 두 형식을 모두 받습니다.

패턴 ⑤ — 긴 기간 요청을 자동으로 쪼갠다

서버가 한 번에 10년치까지만 준다면, 30년치를 원하는 사용자는 직접 세 번 불러 합쳐야 합니다. 이 CLI는 그걸 windowing.ts가 대신합니다.

export const TEN_YEARS_MS = Math.floor(10 * 365.25 * 24 * 60 * 60 * 1000);

export function sliceTimeWindow(start: number, end: number,
                                size = TEN_YEARS_MS): TimeSlice[] {
  if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end)
      || end < start || size < 1) throw new RangeError('Invalid time window.');
  const slices: TimeSlice[] = [];
  let cursor = start;
  while (cursor <= end) {
    const sliceEnd = Math.min(cursor + size, end);
    slices.push({ start: cursor, end: sliceEnd });
    cursor = sliceEnd + 1;          // +1 로 경계 중복 방지
  }
  return slices;
}

합칠 때는 deduplicateAndSort()가 Map으로 키 중복을 없애고 정렬합니다. 서술자의 window: 'ten-years' 한 줄이 이 동작을 켜는 스위치입니다 — 패턴 ①과 맞물리는 지점입니다.

패턴 ⑥ — 로컬 DB의 3층 스키마 (raw → calc → view)

파이썬 쪽 marketdb는 받아 온 데이터를 DuckDB 파일에 쌓습니다. 테이블 이름 접두사가 곧 계층입니다.

CREATE OR REPLACE VIEW v_daily_qfq AS
SELECT
    k.thscode, k.date,
    k.open  * COALESCE(f.forward_factor, 1.0) AS open,
    k.high  * COALESCE(f.forward_factor, 1.0) AS high,
    k.low   * COALESCE(f.forward_factor, 1.0) AS low,
    k.close * COALESCE(f.forward_factor, 1.0) AS close,
    k.volume, k.turnover,
    COALESCE(f.forward_factor, 1.0) AS forward_factor,
    k.currency, k.interval
FROM raw_kline_daily k
LEFT JOIN calc_adjust_factor_daily f
    ON f.thscode = k.thscode AND f.date = k.date;

COALESCE(..., 1.0)이 이 뷰의 안전장치입니다. 보정 계수가 아직 계산되지 않은 날짜라도 1.0을 곱해 원가격 그대로 나오므로 조회가 통째로 비지 않습니다. 데이터 파이프라인에서 “아직 안 채워진 파생 테이블”을 다루는 정석적인 방법입니다.

패턴 ⑦ — 자격증명 우선순위 사슬

API 키를 찾는 순서가 두 언어에서 각각 구현돼 있는데, 정책은 같습니다.

파일 위치도 OS 규약을 따릅니다 — Windows %APPDATA%\hithink-finance\, macOS ~/Library/Application Support/hithink-finance/, Linux ${XDG_CONFIG_HOME:-~/.config}/hithink-finance/. Linux에서 Secret Service 데몬이 없으면 AUTH_CREDENTIAL_STORE_UNAVAILABLE(exit 3)로 실패하고, 환경변수로 우회하라는 힌트를 띄웁니다.

5디렉토리 구조 해부

읽는 순서 추천

1. docs/api/capability-map.md — 이 서비스가 뭘 주는지 한 장에 정리돼 있음
2. hithink-finance-cli/src/contracts/remote-capabilities.ts — 32개 명령의 정의 전부. 여기만 읽어도 CLI 전체를 안다
3. hithink-finance-cli/src/commands/remote.ts — 위 배열을 실행으로 바꾸는 유일한 실행기
4. hithink-finance-cli/src/infrastructure/fuyao/ — client · retry · envelope · windowing 네 파일. 클라이언트 설계의 정수
5. python/marketdb/sql/schema.sql, views.sql — 데이터 계층 설계
6. skills/hithink-finance/SKILL.md — “에이전트에게 도구를 어떻게 설명할 것인가”의 실물 예제

6학습 포인트

반대로, 여기서 배우면 안 되는 것

7하드웨어 / 시스템 요구사항

8직접 해볼 수 있는 실습 과제

git clone --depth 1 https://github.com/HiThink-Tech/Financial-API
cd Financial-API
grep -oE "id: '[a-z0-9.-]+'" \
  hithink-finance-cli/src/contracts/remote-capabilities.ts

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

이 저장소 · 서비스

• github.com/HiThink-Tech/Financial-API — 저장소 (MIT)
• fuyao.aicubes.cn — 서비스 공식 사이트
• 온라인 API 문서 · API Key 관리
• docs/mcp/capability-map.md — MCP 도구 55개의 의도 라우팅표. MCP 서버를 만들 계획이면 이 파일부터
• skills/hithink-finance/SKILL.md — 잘 쓴 Agent Skill 문서의 실물
• npm: @hithink-tech/hithink-finance-cli — CLI 배포본

비교해 볼 만한 저장소

• akfamily/akshare — 무료 · 최대 커버리지. 이 서비스가 비운 매크로·뉴스 영역을 채움
• waditu/tushare — 포인트제 중국 금융 데이터의 사실상 표준
• OpenBB-finance/OpenBB — 여러 데이터 제공자를 어댑터로 추상화한 반대 접근. 서술자 패턴 비교용
• ranaroussi/yfinance — 비공식 스크레이핑의 대표. “공식 계약”이 왜 다른지 대조하기 좋음

배경 지식

• zod 공식 문서 — 1·2주차 로드맵의 교재
• commander.js — 3주차. 동적 명령 등록 예제를 찾아볼 것
• DuckDB 문서 — 5주차. 특히 Parquet 읽기와 뷰 절
• Model Context Protocol — 6주차. 도구 정의와 transport 종류
• AWS Builders’ Library: Timeouts, retries, and backoff with jitter — 4주차의 정본 문헌