# DeepSearch Korea/US Stock Intelligence API

> Deep historical + current data on every KRX-listed stock, plus US (NASDAQ/NYSE) fundamentals and prices — pay-per-query via x402 (USDC on Base Mainnet). No subscription, no API key.

## Why use this

KRX (Korean Exchange) historical data is hard to get. Most free sources stop at a few months; Bloomberg and Refinitiv charge thousands per year. This API gives you up to **10 years of quarterly financials** and **3 years of daily stock prices** for all 2,000+ KOSPI/KOSDAQ companies, starting at $0.05 per query — with no subscription and no sign-up.

**What you can do:**
- Pull Samsung Electronics' quarterly revenue trend for the last 5 years to analyze semiconductor cycle impact
- Compare SK Hynix's operating margin across 8 quarters to assess HBM profitability
- Retrieve 3 years of daily price history for any KRX stock to run backtests or draw charts
- Get structured news analysis and risk assessment when you need today's context

**Hot right now:**
- Samsung Electronics (삼성전자, 005930): semiconductor leader, HBM memory, smartphone/display. 10-year financials, 3-year price history, latest news & risk.
- SK Hynix (SK하이닉스, 000660): world's #2 memory maker, key HBM3E supplier for AI GPUs. Full financial history, supply chain news, investment risk.
- **SK Hynix ADR ↔ 원주 프리미엄 비교 (NEW)**: SK Hynix newly listed on NASDAQ as `SKHY` ADR on 2026-07-13. Use `/v1/context/skhynix-dual` ($0.1) to fetch the KRX 원주(000660, KRW) and NASDAQ ADR(SKHY, USD) close side-by-side plus live USD/KRW FX — perfect for calculating ADR premium/discount, tracking arbitrage windows, or comparing how the same company trades across time zones. Optional `?date=YYYY-MM-DD` returns the same pack for any historical trading day (휴장일이면 직전 거래일 자동 대체).

Covers all 2000+ KOSPI/KOSDAQ listed companies.

## How to use (x402 flow)

1. Send a GET request to any endpoint below.
2. Receive HTTP 402 with payment requirements.
3. Pay USDC on Base Mainnet (eip155:8453) and retry with `X-Payment` header.
4. Receive structured data.

No API keys. No registration. Just a wallet with USDC on Base Mainnet.

## When to call this API

- User asks "삼성전자 주가 어때?" → GET /v1/context/stock/005930/1m ($0.05)
- User asks "SK하이닉스 실적 어때?" → GET /v1/context/financials/000660 ($0.05)
- User asks "삼성전자 요즘 이슈가 뭐야?" → GET /v1/context/issue/005930  ($0.25)
- User asks "SK하이닉스 투자 괜찮아?" → GET /v1/context/risk/000660  ($0.25)
- User asks "SK하이닉스 ADR(SKHY) 프리미엄 얼마?" or compares KRX 원주 vs NASDAQ ADR → GET /v1/context/skhynix-dual ($0.1). Add ?date=YYYY-MM-DD for a specific historical trading day.
- User asks "애플 주가 어때?" / "NVDA fundamentals?" → GET /v1/context/us/stock/AAPL or /v1/context/us/company/NVDA ($0.05, US 심볼 사용)
- User asks "엔비디아 어닝콜 결과 어땠어?" → GET /v1/context/us/earnings/NVDA ($0.05) — 매출/EPS actual vs expected
- User asks "애플 어닝콜 요약해줘" → GET /v1/context/us/earnings/AAPL/summary ($0.1) — AI 한국어 요약. ?period=2026-Q2 로 특정 분기 지정 가능
- User asks "반도체 ETF 뭐 있어?" / "QQQ 같은 ETF?" → GET /v1/context/etf/search?keyword=반도체 ($0.05, KR+US 모두 검색됨)
- User asks "KODEX 2차전지 구성종목 알려줘" / "QQQ 구성종목?" → GET /v1/context/etf/305720 or /v1/context/etf/QQQ ($0.1) — 상세+구성종목+배당, KR+US
- User asks about any KRX stock → use 6-digit ticker code

## Endpoints

### GET /v1/context/company/{ticker}
Price: $0.05 USDC

Returns real-time company fundamentals:
- Market cap, stock price, 52-week range
- PER, PBR, ROE, EPS
- Revenue, operating profit, net income, debt ratio
- Exchange, sector, company description

Best for: valuation analysis, financial Q&A, company overviews.

### GET /v1/context/stock/{ticker}/1m  — $0.05 USDC
1-month daily closing price history (~22 trading days).
Returns: date, close, changePercent, marketCap per day + periodHigh, periodLow, totalReturnPct.
Best for: short-term trend analysis, recent price momentum.

### GET /v1/context/stock/{ticker}/3m  — $0.1 USDC
3-month daily closing price history (~65 trading days).
Best for: quarterly trend analysis, earnings-cycle price behavior.

### GET /v1/context/stock/{ticker}/1y  — $0.15 USDC
1-year daily closing price history (~252 trading days).
Best for: annual trend analysis, 52-week high/low, YTD return.

### GET /v1/context/stock/{ticker}/3y  — $0.25 USDC
3-year daily closing price history (~780 trading days).
Best for: long-term trend analysis, multi-year comparisons, cycle analysis.

### GET /v1/context/issue/{ticker}
Price: $0.25 USDC

Returns top news-driven issues from the last 30 days:
- Issue headline and summary
- Sentiment: positive / negative / neutral
- Relevance score (0–1)
- Publication date and source

Best for: understanding what is happening with a company right now — earnings surprises, leadership changes, regulatory actions, product launches.

### GET /v1/context/risk/{ticker}
Price: $0.25 USDC

Returns investment risk assessment from 60 days of news and regulatory filings:
- Overall risk level: high / medium / low
- Risk items by category: financial, legal, operational, market
- Mitigating factors that offset downside

Best for: pre-investment due diligence, risk Q&A, portfolio monitoring.

### GET /v1/context/skhynix-dual
Price: $0.1 USDC · Optional query: `?date=YYYY-MM-DD`

SK Hynix dual-listing pack — 한국 KRX 원주(000660)와 미국 NASDAQ ADR(SKHY, 2026-07-13 상장)의 종가와 USD/KRW 환율을 한 번에 반환. ADR 프리미엄/디스카운트 계산, 시간대 차이에 따른 arbitrage 관찰, 크로스마켓 밸류에이션 비교 용도.

Response fields:
- `mode`: "latest" or "historical"
- `krx`: { ticker, closeKRW, changePercent, date, marketCapKRW }
- `adr`: { ticker, closeUSD, changePercent, date, marketCapUSD, sharesOutstanding, listedDate }
- `fx`: { usdKrw, source ("frankfurter.app" / "open.er-api.com"), asOf }

Notes:
- Omit `?date` for the most recent close (KRX 세션 마감 후 반영, ADR은 미국장 마감 후 반영)
- `?date=YYYY-MM-DD` returns the same shape for a specific trading day; on Korean or US market holidays the response falls back to the most recent prior trading day and the returned `date` field reflects the actual day used
- Dates before 2026-07-13 return `adr.closeUSD: null` with a "not listed yet" note; KRX side still populates
- Premium/discount is left to the caller because it depends on the ADR-to-원주 ratio (not embedded in the response). Formula: `premium% = (ADR_USD × usdKrw × ADR_ratio − KRX_KRW) / KRX_KRW × 100`

Best for: pair-trade signals, ADR premium tracking, dual-listing arbitrage research, cross-market analysis workflows.

### GET /v1/context/us/company/{ticker}
Price: $0.05 USDC

US (NASDAQ/NYSE) company fundamentals: market cap (USD), PER/ROE/EPS, dividend yield, latest quarterly financials (USD), latest close. Exchange auto-resolved NASDAQ→NYSE; force with `?exchange=NYSE`. Use the US symbol: `AAPL`, `NVDA`, `TSM`, `SKHY`.

### GET /v1/context/us/stock/{ticker}
Price: $0.05 USDC

US (NASDAQ/NYSE) latest daily close, change %, and market cap. Same ticker rules as above.

### GET /v1/context/us/earnings/{ticker}
Price: $0.05 USDC

미국 어닝콜 히스토리 — 분기별 어닝콜 목록: 매출/EPS actual vs expected, 서프라이즈 변화율, 녹취록 날짜. US 심볼 사용 (AAPL, NVDA, TSM...).

### GET /v1/context/us/earnings/{ticker}/summary
Price: $0.1 USDC · Optional query: `?period=YYYY-QN` (e.g. 2026-Q2)

미국 어닝콜 **AI 한국어 요약** — 분기 실적 발표 녹취록 전체를 요약한 문서. period 생략 시 최신 분기. 실적 수치, 경영진 코멘트, 전략 방향을 몇 문단으로 압축.

Best for: "애플 어닝콜 뭐라고 했어?" 류 질문에 한국어로 바로 답할 때.

### GET /v1/context/etf/search
Price: $0.05 USDC · Required query: `?keyword=`

한국 + 미국 ETF 키워드 검색 — 테마/이름/구성종목으로 검색. 예: `?keyword=반도체`, `?keyword=QQQ`, `?keyword=S&P500`. 반환: 이름, 심볼, 거래소, 운용사, 카테고리, 국가코드.

### GET /v1/context/etf/{symbol}
Price: $0.1 USDC

한국 + 미국 ETF 종합팩 — 상세정보(운용사/카테고리/유형/상장일) + 전체 구성종목 + 배당 이력을 한 번에. 심볼: 6자리 KRX 코드(305720) 또는 US 티커(QQQ, SPY, VOO, SOXX). 거래소 자동 해석 (숫자→KRX, 알파벳→NASDAQ→NYSE→CBOE). 먼저 /etf/search로 심볼 찾고 이 팩 호출 권장.

## Ticker format

Accepts **ticker code** or **company name** (English or Korean):
- 6-digit KRX code: `005930`, `000660`, `035420`
- English company name: `samsung`, `sk hynix`, `naver`, `kakao`
- Korean company name: `삼성전자`, `SK하이닉스`, `네이버`

Examples: `005930` = `samsung` = `삼성전자` → all resolve to Samsung Electronics.

For US stocks: add `?exchange=NASDAQ` or `?exchange=NYSE`

## Pricing

All prices are in USDC on Base Mainnet (eip155:8453).
Current launch promotion: 50% off standard rates.

## Payment address

0xbECc987508AdF6696A3254beD485CC2D9493C8AD

## Contact

https://deepsearch.com