Guides / Quickstart

빠른 시작

API 키를 받고 첫 요청을 보내기까지의 순서입니다. Data API(기업용)와 PRO API는 주소와 키가 다릅니다. 예시는 curl, JavaScript fetch, Python requests만 씁니다.

MCP는 PRO API 전용입니다

원격 MCP 서버(Claude · ChatGPT · Cursor 연결)는 PRO API 키(ck_pers_…)나 OAuth로만 붙습니다. Data API 키(ck_live_…)로 연결하면 401 WRONG_KEY_SCOPE를 받습니다. → MCP 연결

1. 쓸 API 고르기

Data API와 PRO API 비교
	Data API	PRO API
대상	기업·기관(PoC · 유료 등급)	PRO 플랜 이용자
베이스 URL	`https://api.chickstockfi.com/openapi/v1`	`https://api.chickstockfi.com/openapi/pro/v1`
키	`ck_live_…`	`ck_pers_…`
플랜	PoC(기본 7일) · Launch · Business · Scale · Enterprise	Data · Ask · Bundle
레퍼런스	Data API 레퍼런스	PRO API 레퍼런스

두 API 모두 www.chickstockfi.com 주소(https://www.chickstockfi.com/openapi/v1, https://www.chickstockfi.com/openapi/pro/v1)로도 같은 응답을 받습니다.

2. 계정 받고 키 만들기

계정은 신청을 받아 발급합니다. 이용 신청을 보내면 검토 후 계정 ID와 초기 비밀번호를 전달합니다. 따로 가입하는 절차는 없습니다.
받은 계정으로 개발자 콘솔에 로그인합니다.
새 키 만들기에서 이름과 범위(Data API 또는 PRO API)를 고릅니다. PRO API 키는 PRO 플랜이 있는 계정만 만들 수 있습니다.
키 전체 값은 만든 직후 한 번만 보입니다. 바로 환경 변수나 비밀 저장소에 넣으세요.

bash

export PHOENIX_API_KEY="ck_live_…"   # Data API
export PHOENIX_PRO_KEY="ck_pers_…"   # PRO API

3. 첫 요청: Data API

뉴스 엔드포인트로 연결을 확인합니다. 응답 헤더의 X-Quota-Remaining으로 오늘 남은 호출 수를 봅니다.

삼성전자 · 005930

bash

curl -sG "https://api.chickstockfi.com/openapi/v1/news" \
  -H "Authorization: Bearer $PHOENIX_API_KEY" \
  --data-urlencode "symbol=005930" \
  --data-urlencode "limit=2"

javascript

// Node.js 18 이상(내장 fetch). 키는 서버에서만 씁니다.
const url = new URL("https://api.chickstockfi.com/openapi/v1/news");
url.search = new URLSearchParams({ symbol: "005930", limit: "2" }).toString(); // 값을 인코딩합니다
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.PHOENIX_API_KEY}` },
});
const body = await res.json();
if (!res.ok) {
  throw new Error(`${res.status} ${body.error?.code ?? ""} ${body.error?.message ?? ""}`);
}
console.log(body.meta.count, body.data[0]?.title);
console.log("오늘 남은 호출:", res.headers.get("X-Quota-Remaining"));

python

import os
import requests

res = requests.get(
    "https://api.chickstockfi.com/openapi/v1/news",
    params={"symbol": "005930", "limit": 2},
    headers={"Authorization": f"Bearer {os.environ['PHOENIX_API_KEY']}"},
    timeout=10,
)
body = res.json()
if not res.ok:
    err = body.get("error", {})
    raise RuntimeError(f"{res.status_code} {err.get('code')} {err.get('message')}")
print(body["meta"]["count"], body["data"][0]["title"] if body["data"] else None)
print("오늘 남은 호출:", res.headers.get("X-Quota-Remaining"))

응답 예시 — 값은 설명용입니다

json

HTTP/2 200
content-type: application/json
x-ratelimit-limit: 3000
x-ratelimit-remaining: 2999
x-quota-limit: 500000
x-quota-remaining: 499999
x-quota-period: 2026-10-21

{
  "data": [
    {
      "id": "art_5k2x9q",
      "symbol": "005930",
      "market": "kr",
      "lang": "ko",
      "title_ko": null,
      "title": "삼성전자 관련 기사 제목",
      "summary": null,
      "publisher": "연합뉴스",
      "published_at": "2026-10-21T00:12:00.000Z",
      "url": "https://www.chickstockfi.com/openapi/v1/articles/art_5k2x9q/read"
    }
  ],
  "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjFUMDA6MTI6MDAuMDAwWiIsMTIzNDVdfQ",
  "has_more": true,
  "meta": { "count": 1, "symbol": "005930", "as_of": "2026-10-21T00:15:02.418Z" }
}

같은 키로 시세·브리핑·공시도 부릅니다. 예: GET /quotes/005930, GET /disclosures?symbol=005930. PoC 기간이 끝난 계정의 키는403 POC_ENDED를 받습니다.

회사 단위 데이터는 /companies/{symbol}/… 아래에 있습니다. 재무 비율·밸류에이션·성장률은 GET /companies/005930/metrics, 재무제표 계정은 GET /companies/005930/financials입니다. 쿼리 값은 -G --data-urlencode로 보내세요. 계정·기간은 영문 코드(revenue, FY2025)를 쓰면 인코딩 걱정이 없습니다.

삼성전자 · 005930

bash

curl -sG "https://api.chickstockfi.com/openapi/v1/companies/005930/financials" \
  -H "Authorization: Bearer $PHOENIX_API_KEY" \
  --data-urlencode "account=revenue,operating_income" \
  --data-urlencode "period=FY2025"

curl -sG "https://api.chickstockfi.com/openapi/v1/companies/005930/metrics" \
  -H "Authorization: Bearer $PHOENIX_API_KEY" \
  --data-urlencode "cagr_years=3"

한국어 값(account=매출액, period=2025 연간)도 받지만, 인코딩하지 않은 한국어 쿼리는 엣지에서 본문 없는 400으로 거절될 수 있습니다.

응답 예시 — 재무제표(값은 설명용입니다)

json

{
  "data": {
    "symbol": "005930",
    "name": "삼성전자",
    "market": "KR",
    "currency": "KRW",
    "rows": [
      {
        "account": "매출액",
        "account_code": "revenue",
        "fiscal_year": 2025,
        "fiscal_quarter": null,
        "period": "2025 연간",
        "period_code": "FY2025",
        "period_type": "annual",
        "period_end": "2025-12-31",
        "fs": "CFS",
        "fs_code": "CFS",
        "value": 3008709,
        "unit": "억원",
        "unit_code": "KRW_EOK",
        "source": "DART",
        "report": "사업보고서 (2025.12)",
        "report_code": "annual_report",
        "filed_date": "2026-03-11",
        "source_url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20260311001234"
      }
    ]
  },
  "next_cursor": null,
  "has_more": false,
  "meta": { "symbol": "005930", "market": "KR", "count": 2, "total": 2, "limit": 100, "as_of": "2026-10-21T06:30:00.000Z", "disclaimer": "…", "unit_note": "…" }
}

응답 모양

한 문서: { data, meta } — 예: /companies/005930/metrics
목록: { data, next_cursor, has_more, meta } — 다음 페이지는 next_cursor를 같은 필터로 그대로 보냅니다.
재무제표: 줄 목록은 data.rows에 있고 next_cursor·has_more는 맨 위에 붙습니다(기본 100줄, 최대 200줄).
meta에는 늘 as_of가 있고, 회사 엔드포인트는 disclaimer·unit_note도 줍니다.
GET /quotes/{symbol}는 data·meta와 함께 예전 최상위 칸을 그대로 둡니다(예전 칸은 deprecated — data를 읽으세요).

5. 첫 요청: PRO API

GET /me로 내 플랜과 오늘 사용량을 먼저 확인합니다. /me는 하루 호출 수에 넣지 않습니다.

bash

curl -s "https://api.chickstockfi.com/openapi/pro/v1/me" \
  -H "Authorization: Bearer $PHOENIX_PRO_KEY"

javascript

const res = await fetch("https://api.chickstockfi.com/openapi/pro/v1/me", {
  headers: { Authorization: `Bearer ${process.env.PHOENIX_PRO_KEY}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error?.code}`);
const { plan, usage } = body.data;
console.log(plan.products, `${usage.calls_today} / ${usage.daily_calls}`);

python

import os
import requests

res = requests.get(
    "https://api.chickstockfi.com/openapi/pro/v1/me",
    headers={"Authorization": f"Bearer {os.environ['PHOENIX_PRO_KEY']}"},
    timeout=10,
)
res.raise_for_status()
data = res.json()["data"]
print(data["plan"]["products"], data["usage"]["calls_today"], "/", data["usage"]["daily_calls"])

응답 예시 — Data 플랜 계정, 값은 설명용입니다

json

{
  "data": {
    "plan": {
      "products": ["data"],
      "daily_calls": 1000,
      "per_second": 2,
      "summary_daily": 50,
      "ask_monthly_included": 0,
      "ask_daily_max": 0,
      "ask_overage_krw": 0,
      "monthly_cost_cap_usd": 30,
      "starts_at": "2026-10-01T00:00:00.000Z",
      "expires_at": "2026-10-31T15:00:00.000Z"
    },
    "usage": {
      "day": "2026-10-21",
      "month": "2026-10",
      "calls_today": 12,
      "daily_calls": 1000,
      "summaries_generated_today": 1,
      "summary_daily": 50,
      "ask_today": 0,
      "ask_daily_max": 0,
      "ask_month": 0,
      "ask_monthly_included": 0,
      "ask_overage_month": 0,
      "ask_overage_krw_each": 0,
      "api_ask_month": 0,
      "llm_cost_month_usd": 0.03,
      "llm_reserved_usd": 0,
      "monthly_cost_cap_usd": 30,
      "budget_remaining_usd": 29.97
    }
  },
  "as_of": "2026-10-21T01:02:03.000Z",
  "sources": [],
  "disclaimer": "…",
  "meta": { "note": "질문 수(ask_*)는 웹 PRO와 API를 합친 값입니다." }
}

다음으로 PRO API의 GET https://api.chickstockfi.com/openapi/pro/v1/quotes/005930(시세), GET https://api.chickstockfi.com/openapi/pro/v1/metrics/005930(재무 비율·밸류에이션), GET https://api.chickstockfi.com/openapi/pro/v1/disclosures?symbol=005930(공시)를 불러 보세요. PRO API 데이터 응답은 { data, as_of, sources, disclaimer, meta } 모양입니다. 주소가 Data API와 다릅니다 — Data API에서 같은 지표는 GET /companies/005930/metrics입니다.

6. OpenAPI 명세로 클라이언트 만들기

두 API는 OpenAPI 3.1 명세로 공개합니다. 명세 JSON을 내려받아 openapi-generator, oapi-codegen 같은 OpenAPI 도구로 원하는 언어의 클라이언트를 만들 수 있습니다. 도구마다 OpenAPI 3.1 지원 범위가 달라 생성 결과는 한 번 확인하세요. API 레퍼런스의 각 엔드포인트에서도 언어별 요청 코드를 볼 수 있습니다.

bash

# 명세 JSON 내려받기
curl -sO https://openapi.chickstockfi.com/openapi.json
curl -sO https://openapi.chickstockfi.com/openapi-pro.json

# 예: openapi-generator로 Python 클라이언트 만들기
openapi-generator generate -i openapi.json -g python -o ./phoenix-data-client

# 예: oapi-codegen으로 Go 타입·클라이언트 만들기
oapi-codegen -generate types,client -package phoenix openapi.json > phoenix.gen.go

다음에 읽을 문서

인증과 API 키 · 호출 한도와 쿼터 · 오류 코드 · 데이터 규약 · MCP 연결 · llms.txt · llms-full.txt(AI 에이전트용 요약)

1. 쓸 API 고르기

2. 계정 받고 키 만들기

3. 첫 요청: Data API

4. 회사 데이터 부르기: 재무제표·지표

응답 모양

5. 첫 요청: PRO API

6. OpenAPI 명세로 클라이언트 만들기