# Korea Ground-Truth (KGT) — Korean Official Data MCP / Korea Verification API

> Official Korean data for AI agents. One API. One MCP. Instead of integrating five government APIs (NTS, DART, MOIS, MOLIT, MOLEG) separately, give your agent one endpoint. Business registration status (국세청), address normalization + postal/legal-dong codes (행안부), corporation profiles (DART), apartment transaction prices (국토부), current laws (법제처). Prepaid credits, per-call metering, no human required to get started.

## Quick start (agent-only, ~10 seconds)

1. Create an account and key (grants 50 free credits):
   curl -X POST https://kr-groundtruth-mcp.vercel.app/v1/accounts -H 'content-type: application/json' -d '{"email":"you@example.com"}'
2. Use it via MCP (Streamable HTTP):
   claude mcp add --transport http kgt https://kr-groundtruth-mcp.vercel.app/api/mcp --header "Authorization: Bearer kgt_live_..."
   or REST: curl -X POST https://kr-groundtruth-mcp.vercel.app/v1/tools/search_address -H "Authorization: Bearer kgt_live_..." -H 'content-type: application/json' -d '{"keyword":"세종대로 209"}'
3. Every response includes meta.cost and meta.balance_remaining. When you get 402 INSUFFICIENT_CREDITS:
   curl -X POST https://kr-groundtruth-mcp.vercel.app/v1/topups -H "Authorization: Bearer kgt_live_..." -d '{"credits":500}'  → checkout_url → give it to a human to pay by card. (Humans can also pay directly at https://kr-groundtruth-mcp.vercel.app/topup with the API key.)

## Example agent workflows (real traces)
- https://kr-groundtruth-mcp.vercel.app/examples/company-verification — verify a company before signing: business status → corporation → profile → address
- https://kr-groundtruth-mcp.vercel.app/examples/real-estate — apartment name → address → lawd_code → transaction prices
- https://kr-groundtruth-mcp.vercel.app/examples/legal — confirm the current statute and enforcement date before answering

## Tools
- [verify_business_registration](https://kr-groundtruth-mcp.vercel.app/tools/verify_business_registration) — Cost: 2 credits/call (cache hit: 1). 국세청 사업자등록번호 상태(계속사업자/휴업/폐업/미등록)와 과세유형을 조회합니다. 대표자명(representative_name)과 개업일(opened_date, YYYYMMDD)을 함께 주면 등록정보 진위확인까지 수행합니다. 한 번에 최대 100건. 결과 status: active | suspended | closed | not_registered.
- [search_address](https://kr-groundtruth-mcp.vercel.app/tools/search_address) — Cost: 1 credit/call (cache hit: 1). 도로명주소·지번주소·건물명 키워드로 공식 주소를 검색해 정규화합니다. 우편번호(postal_code), 행정구역코드(adm_code), 아파트 실거래가 조회용 법정동코드 5자리(lawd_code), 영문주소를 반환합니다. 예: '세종대로 209', '역삼동 736-1', '삼성전자 본사'.
- [search_corporation](https://kr-groundtruth-mcp.vercel.app/tools/search_corporation) — Cost: 1 credit/call (cache hit: 1). 법인명으로 금융감독원 DART 등록 법인을 검색해 corp_code(8자리 고유번호)를 찾습니다. 상장사는 stock_code가 함께 반환됩니다. lookup_corporation의 corp_code 입력으로 사용하세요.
- [lookup_corporation](https://kr-groundtruth-mcp.vercel.app/tools/lookup_corporation) — Cost: 2 credits/call (cache hit: 1). DART corp_code로 기업개황을 조회합니다: 정식 법인명, 대표자, 법인등록번호, 사업자등록번호, 주소, 업종코드, 설립일, 상장시장. corp_code를 모르면 먼저 search_corporation을 호출하세요.
- [apartment_trade_prices](https://kr-groundtruth-mcp.vercel.app/tools/apartment_trade_prices) — Cost: 3 credits/call (cache hit: 1). 국토교통부 아파트 매매 실거래가를 시군구(법정동코드 5자리) + 계약월(YYYYMM) 단위로 조회합니다. lawd_code는 search_address 결과의 lawd_code를 사용하세요 (예: 강남구 11680). deal_amount_krw는 원 단위 정수입니다.
- [search_law](https://kr-groundtruth-mcp.vercel.app/tools/search_law) — Cost: 2 credits/call (cache hit: 1). 법제처 국가법령정보센터에서 현행 법령(법률·시행령·시행규칙)을 검색합니다. 법령ID, 소관부처, 공포/시행일, 상세 링크를 반환합니다. 예: '개인정보 보호법', '주택임대차보호법'.
- [get_balance](https://kr-groundtruth-mcp.vercel.app/tools/get_balance) — Cost: free. 현재 API 키 계정의 크레딧 잔액과 충전 URL 안내를 반환합니다.
- [get_pricing](https://kr-groundtruth-mcp.vercel.app/tools/get_pricing) — Cost: free. 툴별 크레딧 비용, 크레딧 단가(KRW), 충전 방법을 반환합니다.

## Pricing
1 credit = 10 KRW. Live table: https://kr-groundtruth-mcp.vercel.app/pricing.json

## Specs
- OpenAPI: https://kr-groundtruth-mcp.vercel.app/openapi.json
- MCP endpoint: https://kr-groundtruth-mcp.vercel.app/api/mcp (Streamable HTTP, bearer API key)
- Account: GET https://kr-groundtruth-mcp.vercel.app/v1/me (balance, usage, ledger)
- Upstream failures are refunded automatically.