ntriq

KoFinance API 문서

한국 주식시장 데이터를 REST API로 조회하세요.

Base URL: https://api.ntriq.co.kr/kofinance/api/v1

시작하기

2단계로 바로 시작하세요.

1API 키 발급
회원가입 후 대시보드에서 API 키를 발급받으세요.
무료 API 키 발급 →
2데이터 조회
발급받은 키로 API를 호출하세요.
bash
curl -H "X-YAP-Key: your-api-key" \
  "https://api.ntriq.co.kr/kofinance/api/v1/stocks?search=삼성"

인증

모든 엔드포인트는 X-YAP-Key 헤더로 인증합니다.

헤더 형식
text
X-YAP-Key: yap_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

엔드포인트 레퍼런스

GET/stocks
전 상장사(KOSPI, KOSDAQ, KONEX) 종목 목록 조회. market, search, page, limit 파라미터 지원.
bash
# 전체 종목
curl -H "X-YAP-Key: your-api-key" \
  "https://api.ntriq.co.kr/kofinance/api/v1/stocks?market=KOSPI&limit=10"

# 기업명 검색
curl -H "X-YAP-Key: your-api-key" \
  "https://api.ntriq.co.kr/kofinance/api/v1/stocks?search=삼성&limit=10"

# Response
{
  "count": 1,
  "stocks": [
    {
      "symbol": "005930",
      "name": "삼성전자",
      "market": "KOSPI"
    }
  ]
}
GET/stocks/{symbol}
특정 종목의 기업 기본정보 조회. symbol은 종목코드 (예: 005930). DB 캐시 7일, 이후 DART API 자동 갱신.
bash
curl -H "X-YAP-Key: your-api-key" \
  "https://api.ntriq.co.kr/kofinance/api/v1/stocks/005930"

# Response
{
  "symbol": "005930",
  "name": "삼성전자",
  "market": "KOSPI",
  "ceo": "한종희",
  "established": "1969-01-13",
  "industry_code": "264",
  "address": "경기도 수원시 ...",
  "website": "www.samsung.com",
  "fiscal_month": "12"
}
GET/stocks/{symbol}/financials
재무제표 조회. type (annual/quarterly), period (1y/3y/5y), consolidated (true/false) 파라미터. 손익계산서, 재무상태표, 현금흐름표, 주요 비율, 성장 트렌드 포함.
bash
curl -H "X-YAP-Key: your-api-key" \
  "https://api.ntriq.co.kr/kofinance/api/v1/stocks/005930/financials?period=3y&type=annual"

# Response
{
  "symbol": "005930",
  "name": "삼성전자",
  "financials": [{
    "period": "2025",
    "type": "annual",
    "consolidated": true,
    "income_statement": {
      "revenue": 302231000000000,
      "operating_income": 58490000000000,
      "net_income": 42100000000000
    },
    "balance_sheet": {
      "total_assets": 455280000000000,
      "total_equity": 333940000000000,
      "debt_ratio": 36.3
    },
    "ratios": { "roe": 13.2, "operating_margin": 19.4, "net_margin": 13.9 },
    "cash_flow": { "cash_from_operations": 72340000000000 },
    "per_share": { "eps": 6123 }
  }],
  "trends": {
    "revenue_growth": 15.3,
    "op_growth": 32.1,
    "revenue_cagr_3y": 12.5
  },
  "meta": { "currency": "KRW", "source": "DART XBRL" }
}
GET/stocks/{symbol}/disclosures
DART 공시 목록 + AI 요약. days (최근 N일, 최대 365), type (all/regular/major/equity/other), include_summary (AI 요약 포함 여부) 파라미터.
bash
curl -H "X-YAP-Key: your-api-key" \
  "https://api.ntriq.co.kr/kofinance/api/v1/stocks/005930/disclosures?days=30"

# Response
{
  "symbol": "005930",
  "name": "삼성전자",
  "disclosures": [{
    "id": "20260301000123",
    "title": "사업보고서 (2025.12)",
    "type": "regular",
    "date": "2026-03-01",
    "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20260301000123",
    "summary": "2025년 연결 매출 302.2조원(+15.3%), 영업이익 58.5조원(+32.1%)"
  }]
}
GET/billing/subscription
현재 인증된 클라이언트의 KoFinance 구독 정보 및 사용량 조회.
bash
curl -H "X-YAP-Key: your-api-key" \
  "https://api.ntriq.co.kr/kofinance/api/v1/billing/subscription"

# Response
{
  "customer_id": "cust_abc123",
  "plan": "free",
  "status": "active",
  "api_calls_today": 42,
  "api_calls_limit": 1000
}

Rate Limiting

모든 플랜은 일일 API 호출 한도를 기준으로 합니다.

플랜별 일일 한도
Free일 1,000건
Pro (₩29,000/월)일 10,000건
Enterprise맞춤 한도
응답 헤더
모든 응답에 일일 사용량 정보가 포함됩니다.
text
X-KF-RateLimit-Limit: 1000
X-KF-RateLimit-Used: 124
X-KF-RateLimit-Remaining: 876

에러 코드

코드상태설명
400Bad Request잘못된 요청. 필수 파라미터가 누락되었거나 형식이 올바르지 않습니다.
401UnauthorizedAPI Key가 누락되었거나 잘못되었습니다.
403Forbidden비활성화된 계정이거나 접근 권한이 없습니다.
404Not Found요청한 종목코드 또는 리소스를 찾을 수 없습니다.
429Too Many Requests일일 Rate Limit 초과. 다음 날까지 기다리거나 플랜을 업그레이드하세요.
500Internal Server Error서버 내부 오류. 지속되면 문의해 주세요.
502Bad GatewayDART API 연동 오류. 잠시 후 다시 시도해 주세요.

시작할 준비가 되셨나요?

무료로 API 키를 발급받고 KoFinance를 사용해 보세요.

무료로 시작하기가격 확인하기