Guides / Quickstart

Quickstart

The steps from getting an API key to your first request. The Data API (enterprise) and the PRO API use different base URLs and keys. Examples use curl, JavaScript fetch and Python requests only. Response text such as headlines and error messages is in Korean.

MCP is PRO API only

The remote MCP server (for Claude, ChatGPT, Cursor) accepts PRO API keys (ck_pers_…) or OAuth only. Data API keys (ck_live_…) can't connect and get 401 WRONG_KEY_SCOPE. → MCP

1. Pick an API

Data API and PRO API
	Data API	PRO API
For	Companies and institutions (PoC · paid tiers)	PRO plan customers
Base URL	`https://api.chickstockfi.com/openapi/v1`	`https://api.chickstockfi.com/openapi/pro/v1`
Key	`ck_live_…`	`ck_pers_…`
Plans	PoC (7 days by default) · Launch · Business · Scale · Enterprise	Data · Ask · Bundle
Reference	Data API reference	PRO API reference

Both APIs return the same responses on www.chickstockfi.com as well (https://www.chickstockfi.com/openapi/v1, https://www.chickstockfi.com/openapi/pro/v1).

2. Get an account and create a key

We issue accounts on request. Send an access request; after review we send you an account ID and an initial password. There is no self sign-up.
Log in to the developer console with that account.
Under Create key, enter a name and choose a scope (Data API or PRO API). Only accounts with a PRO plan can create PRO API keys.
The full key is shown only once, right after you create it. Put it in an environment variable or a secret manager straight away.

bash

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

3. First request: Data API

Check connectivity with the news endpoint. The X-Quota-Remaining response header shows how many calls you have left today.

Samsung Electronics · 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+ (built-in fetch). Keep the key on your server.
const url = new URL("https://api.chickstockfi.com/openapi/v1/news");
url.search = new URLSearchParams({ symbol: "005930", limit: "2" }).toString(); // encodes values
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("Calls left today:", 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("Calls left today:", res.headers.get("X-Quota-Remaining"))

Sample response (illustrative values)

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" }
}

The same key calls quotes, briefings and filings, for example GET /quotes/005930 or GET /disclosures?symbol=005930. Once an account's PoC period has ended, its keys get 403 POC_ENDED.

4. Company data: financials and metrics

Company-level data lives under /companies/{symbol}/…. Ratios, valuation and growth are GET /companies/005930/metrics; financial statement line items are GET /companies/005930/financials. Send query values with -G --data-urlencode. With English codes for accounts and periods (revenue, FY2025) there is nothing to encode.

Samsung Electronics · 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"

Korean values (account=매출액, period=2025 연간) are accepted too, but an unencoded Korean query can be rejected at the edge with an empty-body 400.

Sample response — financial statements (illustrative values)

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": "…" }
}

Response envelope

Single document: { data, meta } — e.g. /companies/005930/metrics
List: { data, next_cursor, has_more, meta } — send next_cursor unchanged with the same filters for the next page.
Financial statements: rows are in data.rows, with next_cursor and has_more at the top level (100 rows by default, 200 max).
meta always carries as_of; company endpoints also carry disclaimer and unit_note.
GET /quotes/{symbol} returns data and meta plus the old top-level fields (deprecated — read data).

5. First request: PRO API

Start with GET /me to see your plan and today's usage. /me does not count toward the daily call quota.

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"])

Sample response (Data plan account, illustrative values)

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를 합친 값입니다." }
}

Next, try the PRO API's GET https://api.chickstockfi.com/openapi/pro/v1/quotes/005930 (quotes), GET https://api.chickstockfi.com/openapi/pro/v1/metrics/005930 (ratios and valuation) and GET https://api.chickstockfi.com/openapi/pro/v1/disclosures?symbol=005930 (filings). PRO API data responses have the shape { data, as_of, sources, disclaimer, meta }. The paths differ from the Data API — there the same metrics are GET /companies/005930/metrics.

6. Generate a client from the OpenAPI spec

Both APIs are published as OpenAPI 3.1 documents. Download the spec JSON and generate a client in your language with an OpenAPI tool such as openapi-generator or oapi-codegen. OpenAPI 3.1 support varies between tools, so review the generated code. Each endpoint in the API reference also shows request code in several languages.

bash

# Download the specs
curl -sO https://openapi.chickstockfi.com/openapi.json
curl -sO https://openapi.chickstockfi.com/openapi-pro.json

# Example: Python client with openapi-generator
openapi-generator generate -i openapi.json -g python -o ./phoenix-data-client

# Example: Go types and client with oapi-codegen
oapi-codegen -generate types,client -package phoenix openapi.json > phoenix.gen.go