검색 결과 수 (기본 10, 최대 20)
Prerequisites
없음. 사용자는
KRX_API_KEY
를 준비할 필요가 없다. upstream key는 proxy 서버에서만 주입한다.
Default path
추가 client API 레이어는 불필요하다. 그냥 프록시 서버에 HTTP 요청만 넣으면 된다.
KSKILL_PROXY_BASE_URL
환경변수가 있으면 그 값을 사용하고, 없으면 기본 경로
https://k-skill-proxy.nomadamas.org
를 사용한다.
Supported endpoints
종목 검색
GET /v1/korean-stock/search?q={검색어}&bas_dd={YYYYMMDD}
종목 기본정보
GET /v1/korean-stock/base-info?market={KOSPI|KOSDAQ|KONEX}&code={종목코드}&bas_dd={YYYYMMDD}
종목 일별 시세
GET /v1/korean-stock/trade-info?market={KOSPI|KOSDAQ|KONEX}&code={종목코드}&bas_dd={YYYYMMDD}
Example requests
종목 검색:
curl
-fsS
--get
'https://k-skill-proxy.nomadamas.org/v1/korean-stock/search'
\
--data-urlencode
'q=삼성전자'
\
--data-urlencode
'bas_dd=20260408'
종목 기본정보:
curl
-fsS
--get
'https://k-skill-proxy.nomadamas.org/v1/korean-stock/base-info'
\
--data-urlencode
'market=KOSPI'
\
--data-urlencode
'code=005930'
\
--data-urlencode
'bas_dd=20260408'
종목 일별 시세:
curl
-fsS
--get
'https://k-skill-proxy.nomadamas.org/v1/korean-stock/trade-info'
\
--data-urlencode
'market=KOSPI'
\
--data-urlencode
'code=005930'
\
--data-urlencode
'bas_dd=20260408'
Response shape
검색 응답
{
"items"
:
[
{
"market"
:
"KOSPI"
,
"code"
:
"005930"
,
"standard_code"
:
"KR7005930003"
,
"name"
:
"삼성전자"
,
"short_name"
:
"삼성전자"
,
"english_name"
:
"Samsung Electronics"
,
"listed_at"
:
"1975-06-11"
}
]
,
"query"
:
{
"q"
:
"삼성전자"
,
"bas_dd"
:
"20260408"
,
"limit"
:
10
}
,
"proxy"
:
{
"name"
:
"k-skill-proxy"
,
"cache"
:
{
"hit"
:
false
,
"ttl_ms"
:
300000
}
}
}
기본정보 응답
{
"item"
:
{
"market"
:
"KOSPI"
,
"code"
:
"005930"
,
"standard_code"
:
"KR7005930003"
,
"name"
:
"삼성전자"
,
"short_name"
:
"삼성전자"
,
"english_name"
:
"Samsung Electronics"
,
"security_group"
:
"주권"
,
"section_type"
:
"대형주"
,
"stock_certificate_type"
:
"보통주"
,
"par_value"
:
100
,
"listed_shares"
:
5969782550
}
,
"query"
:
{
"market"
:
"KOSPI"
,
"code"
:
"005930"
,
"bas_dd"
:
"20260408"
}
,
"proxy"
:
{
"name"
:
"k-skill-proxy"
,
"cache"
:
{
"hit"
:
false
,
"ttl_ms"
:
300000
}
}
}
일별 시세 응답
{
"item"
:
{
"market"
:
"KOSPI"
,
"code"
:
"005930"
,
"standard_code"
:
"KR7005930003"
,
"base_date"
:
"20260408"
,
"name"
:
"삼성전자"
,
"close_price"
:
84000
,
"change_price"
:
1000
,
"fluctuation_rate"
:
1.2
,
"open_price"
:
83000
,
"high_price"
:
84500
,
"low_price"
:
82800
,
"trading_volume"
:
12345678
,
"trading_value"
:
1030000000000
,
"market_cap"
:
500000000000000
}
,
"query"
:
{
"market"
:
"KOSPI"
,
"code"
:
"005930"
,
"bas_dd"
:
"20260408"
}
,
"proxy"
:
{
"name"
:
"k-skill-proxy"
,
"cache"
:
{
"hit"
:
false
,
"ttl_ms"
:
300000
}
}
}
Response policy
종목명이 모호하면 먼저
search
로 시장/종목코드를 좁힌 뒤
base-info
또는
trade-info
로 들어간다.
일부 시장 upstream 이 실패하면
upstream.degraded=true
와
failed_markets
를 보고 부분 장애 여부를 함께 설명한다.
trade-info
결과는 일별 snapshot 이다. 실시간 호가/체결처럼 말하지 않는다.
휴장일/장마감 이전이면 해당
bas_dd
에 데이터가 없을 수 있으니 최근 영업일로 재시도한다. 이 경우
trade-info
는 502 대신
not_found
로 끝날 수 있다.
숫자는 사람이 읽기 쉬운 단위(원, 주, 억/조)로 짧게 풀어주되 원본 숫자도 유지한다.
답변 말미에 "KRX 공식 데이터 기준 / 투자 조언 아님" 을 짧게 남긴다.
Keep the answer compact
종목명 / 시장 / 종목코드
기준일
종가 / 등락률 / 거래량 / 시가총액
필요할 때만 상장일 / 상장주식수 / 액면가
여러 후보가 나오면 상위 3~5개만 보여주고 사용자가 고르게 한다
Failure modes
q
,
market
,
code
,
bas_dd
형식이 잘못되면 400 응답
프록시 서버에
KRX_API_KEY
가 없으면 503 응답
검색 중 일부 시장 upstream 이 실패하면 200 응답이지만
upstream.degraded=true
와
failed_markets
를 함께 반환할 수 있다.
모든 요청 시장에서 upstream KRX 조회가 실패하면 502 응답
해당 기준일/시장에 종목이 없으면 404
not_found
Done when
검색어가 모호하면
search
로 후보를 먼저 좁혔다.
필요한 경우
base-info
와
trade-info
를 호출해 핵심 수치를 정리했다.
사용자가
KRX_API_KEY
없이도 조회 가능하다는 점을 유지했다.
KRX 공식 데이터 기준임을 짧게 남겼다.
Notes
원본 참고:
https://github.com/jjlabsio/korea-stock-mcp
공식 데이터 출처: KRX Open API (
https://openapi.krx.co.kr/contents/OPP/MAIN/main/index.cmd
)
이 스킬은 read-only 조회 전용이다.