# Introduction

Alpha Lenz is not just a data API — it’s an AI-native financial infrastructure layer that enables you to create financial services that didn’t exist before.

With fully modular components and end-to-end customization, you can design unique research workflows, personalized investment experiences, and new product categories without being limited by traditional market data interfaces.

We unify global market data, semantic research indexing, chart and consensus analysis engines, and AI agents into one programmable API layer.

This allows you to:

* Build fully customized financial applications and user experiences
* Integrate AI-driven insights and reasoning into any workflow
* Automate and scale research and decision support
* Deliver zero-latency, high-accuracy data across multiple markets

Trusted by analysts, fintech platforms, and asset managers, Alpha Lenz empowers you to move beyond pre-built screens and static reports to create the financial product you envision.


# Table of contents

* [Introduction](/)

## API reference

* [Authentication](/en/api-reference/public-api/authentication)
* [API Playground](/en/api-reference/public-api/api-playground)
* [Alpha Lenz API](/en/api-reference/public-api)
  * [Basic Financial API](/en/api-reference/public-api/basic-financial-api)
  * [Financial](/en/api-reference/public-api/financial)
  * [Stock](/en/api-reference/public-api/stock)
  * [News](/en/api-reference/public-api/news)
  * [Research](/en/api-reference/public-api/research)
* [Company](/en/api-reference/company)
  * [Company Tabs API](/en/api-reference/company/page-5)


# api-reference


# Agents


# Orchestration


# Page 4


# Screener


# Page 2


# Company


# Company Tabs API

The company detail page uses a tab-based layout with 7 tabs, each powered by dedicated API endpoints.

## Tab Overview

| Tab        | ID           | Primary Endpoint                          | Description                                |
| ---------- | ------------ | ----------------------------------------- | ------------------------------------------ |
| Overview   | `overview`   | `/companies/{id}`                         | Company profile, stats, and summary cards  |
| Financials | `financials` | `/companies/{id}/financials`              | Income statement, balance sheet, cash flow |
| Chart      | `chart`      | TradingView widget                        | Interactive price chart                    |
| Disclosure | `disclosure` | `/companies/{id}/dart`                    | Korean corporate filings (DART)            |
| Insider    | `insider`    | `/companies/{id}/insider`                 | Insider trading data                       |
| Analysis   | `analysis`   | `/companies/{id}/snapshot` + `/technical` | Technical signals and AI analysis          |
| Consensus  | `consensus`  | `/companies/{id}/consensus`               | Expert forecasts and target prices         |

***

## Company Detail

Returns full company profile including financial metrics, valuation, growth, and health indicators.

```
GET /v1/financial_v4/companies/{company_id}
```

### Path Parameters

| Parameter    | Type    | Description |
| ------------ | ------- | ----------- |
| `company_id` | integer | Company ID  |

### Response

```json
{
  "id": 1,
  "name": "Samsung Electronics",
  "alias_name": "삼성전자",
  "symbol": "005930",
  "exchange": "KRX",
  "currency": "KRW",
  "current_price": 58000,
  "price_change": 1200,
  "price_change_percent": 2.11,
  "description": "Samsung Electronics Co., Ltd. ...",
  "ceo": "Jong-Hee Han",
  "website": "https://www.samsung.com",
  "sector": "Technology",
  "industry": "Semiconductors",
  "employees": 267800,
  "fiscal_year": 2024,
  "fiscal_date": "2024-12-31",
  "profile": {
    "market_cap": 346000000000000,
    "revenue": 258935000000000,
    "shares_outstanding": 5969783000,
    "employees": 267800
  },
  "margins": {
    "gross_margin": 32.8,
    "ebitda_margin": 18.5,
    "operating_margin": 2.54,
    "pretax_margin": 3.12,
    "net_margin": 5.98
  },
  "valuation": {
    "pe_ratio": 37.4,
    "pb_ratio": 1.03,
    "ps_ratio": 1.34,
    "ev_ebitda": 7.22,
    "pfcf_ratio": 11.5
  },
  "growth": {
    "sales_growth_3y_cagr": -2.1,
    "sales_growth_5y_cagr": 3.8,
    "operating_income_growth_3y_cagr": -15.2,
    "operating_income_growth_5y_cagr": -8.4,
    "net_income_growth_3y_cagr": -10.5,
    "net_income_growth_5y_cagr": -5.1
  },
  "returns": {
    "roa": 3.4,
    "roe": 4.6,
    "roic": 3.9
  },
  "financial_health": {
    "cash": 65000000000000,
    "net_debt": -20000000000000,
    "debt_to_equity_ratio": 0.36,
    "interest_coverage_ratio": 8.5
  }
}
```

**Used by:** Overview tab — company header, stats grid, financial metrics cards

***

## Resolve Company Slug

Convert a URL slug or ticker symbol to a company ID. Used for routing.

```
GET /v1/financial_v4/companies/by-slug/{slug}
```

### Path Parameters

| Parameter | Type   | Description                                                    |
| --------- | ------ | -------------------------------------------------------------- |
| `slug`    | string | Company slug or ticker (e.g., `samsung-electronics`, `005930`) |

### Response

```json
{
  "id": 1,
  "name": "Samsung Electronics",
  "symbol": "005930",
  "exchange": "KRX"
}
```

***

## Company Financials

Returns time-series financial statements (income statement, balance sheet, cash flow).

```
GET /v1/financial_v4/companies/{company_id}/financials
```

### Query Parameters

| Parameter | Type    | Default    | Description                 |
| --------- | ------- | ---------- | --------------------------- |
| `period`  | string  | `"Annual"` | `"Annual"` or `"Quarterly"` |
| `years`   | integer | `5`        | Number of years to retrieve |

### Response

```json
{
  "statements": [
    {
      "fiscal_date": "2024-12-31",
      "year": 2024,
      "quarter": null,
      "period": "Annual",
      "currency": "KRW",
      "sales": 258935000000000,
      "operating_income": 6570000000000,
      "net_income": 15490000000000,
      "total_assets": 455000000000000,
      "free_cash_flow": 30000000000000
    }
  ]
}
```

**Full field list:** See [Financial Statement Fields](#financial-statement-fields) below.

**Used by:** Financials tab — sub-tabs for Income Statement, Balance Sheet, Cash Flow with annual/quarterly toggle

***

## Company Snapshot

Returns real-time market data from yfinance including analyst recommendations.

```
GET /v1/financial_v4/companies/{company_id}/snapshot
```

**Used by:** Analysis tab — key metrics display, AI signal banner

***

## Company Technical

Returns technical indicators calculated from price data.

```
GET /v1/financial_v4/companies/{company_id}/technical
```

### Response includes

* **RSI** (Relative Strength Index)
* **MACD** (Moving Average Convergence Divergence)
* **Bollinger Bands** (upper, middle, lower)
* **ATR** (Average True Range)
* **SMA** (Simple Moving Averages — 20, 50, 200 day)

**Used by:** Analysis tab — technical signals component

***

## Company News

Returns news articles from Perigon API and Google News RSS.

```
GET /v1/financial_v4/companies/{company_id}/news
```

### Query Parameters

| Parameter | Type    | Default | Description                      |
| --------- | ------- | ------- | -------------------------------- |
| `limit`   | integer | `3`     | Number of articles to return     |
| `locale`  | string  | `"ko"`  | Language locale (`"ko"`, `"en"`) |

**Used by:** Overview tab — news card (lazy-loaded below the fold)

***

## Company DART Disclosures

Returns Korean corporate disclosure filings from the DART system.

```
GET /v1/financial_v4/companies/{company_id}/dart
```

### Query Parameters

| Parameter | Type    | Default | Description                 |
| --------- | ------- | ------- | --------------------------- |
| `limit`   | integer | `3`     | Number of filings to return |

**Used by:** Disclosure tab, Overview tab — DART card

***

## Company Research Highlights

Returns analyst research report summaries.

```
GET /v1/financial_v4/companies/{company_id}/research-highlights
```

### Query Parameters

| Parameter | Type    | Default | Description                 |
| --------- | ------- | ------- | --------------------------- |
| `limit`   | integer | `3`     | Number of reports to return |

**Used by:** Overview tab — research highlights card

***

## Company Sector Analysis

Returns sector-level analysis for the company.

```
GET /v1/sector-analyst/company/{company_id}
```

### Query Parameters

| Parameter | Type   | Default | Description     |
| --------- | ------ | ------- | --------------- |
| `locale`  | string | —       | Language locale |

**Used by:** Overview tab — sector analysis card (lazy-loaded)

***

## Company Consensus

Returns expert forecast consensus including target prices and investment opinions.

```
GET /v1/financial_v4/companies/{company_id}/consensus
```

### Query Parameters

| Parameter | Type    | Default | Description               |
| --------- | ------- | ------- | ------------------------- |
| `months`  | integer | `12`    | Analysis period in months |

### Response

```json
{
  "company_id": 1,
  "company_name": "Samsung Electronics",
  "symbol": "005930",
  "currency": "KRW",
  "has_consensus": true,
  "message": null,
  "current_price": 58000,
  "target_prices": {
    "average": 85000,
    "high": 110000,
    "high_broker": "미래에셋증권",
    "low": 65000,
    "low_broker": "대신증권",
    "std_dev": 12500,
    "expert_count": 25
  },
  "upside_downside": {
    "current_price": 58000,
    "to_high": 89.66,
    "to_average": 46.55,
    "to_low": 12.07
  },
  "investment_opinions": [
    { "opinion": "매수", "count": 18, "percentage": 72.0 },
    { "opinion": "중립", "count": 5, "percentage": 20.0 },
    { "opinion": "매도", "count": 2, "percentage": 8.0 }
  ],
  "target_price_trend": [
    {
      "date": "2024-03-15",
      "target_price": 90000,
      "broker": "삼성증권",
      "opinion": "매수"
    }
  ],
  "price_history": [
    { "date": "2024-01-02", "close": 52000 }
  ],
  "analysis_period_months": 12,
  "last_report_date": "2024-03-20",
  "total_reports": 42
}
```

**Used by:** Consensus tab — target price chart, opinion distribution, broker detail table

***

## Company Insider

Returns insider trading data for the company.

```
GET /v1/financial_v4/companies/{company_id}/insider
```

**Used by:** Insider tab, Disclosure tab — insider trading embed

***

## Financial Statement Fields

The financials endpoint returns these fields for each statement period:

### Income Statement (손익계산서)

| Field                                | Description               |
| ------------------------------------ | ------------------------- |
| `sales`                              | Revenue (매출액)             |
| `cost_of_goods`                      | Cost of goods sold (매출원가) |
| `gross_profit`                       | Gross profit (매출총이익)      |
| `research_and_development`           | R\&D expenses (연구개발비)     |
| `selling_general_and_administrative` | SG\&A expenses (판매관리비)    |
| `operating_income`                   | Operating income (영업이익)   |
| `ebit`                               | EBIT                      |
| `ebitda`                             | EBITDA                    |
| `pretax_income`                      | Pretax income (세전이익)      |
| `net_income`                         | Net income (당기순이익)        |
| `eps_basic`                          | Basic EPS (기본주당순이익)       |
| `eps_diluted`                        | Diluted EPS (희석주당순이익)     |

### Balance Sheet (재무상태표)

| Field                           | Description                        |
| ------------------------------- | ---------------------------------- |
| `total_assets`                  | Total assets (자산총계)                |
| `total_current_assets`          | Current assets (유동자산)              |
| `cash_and_cash_equivalents`     | Cash & equivalents (현금및현금성자산)      |
| `accounts_receivable`           | Accounts receivable (매출채권)         |
| `inventory`                     | Inventory (재고자산)                   |
| `total_non_current_assets`      | Non-current assets (비유동자산)         |
| `properties`                    | Property, plant & equipment (유형자산) |
| `intangible_assets`             | Intangible assets (무형자산)           |
| `goodwill`                      | Goodwill (영업권)                     |
| `total_liabilities`             | Total liabilities (부채총계)           |
| `total_current_liabilities`     | Current liabilities (유동부채)         |
| `total_non_current_liabilities` | Non-current liabilities (비유동부채)    |
| `total_shareholders_equity`     | Total equity (자본총계)                |
| `retained_earnings`             | Retained earnings (이익잉여금)          |

### Cash Flow (현금흐름표)

| Field                  | Description                    |
| ---------------------- | ------------------------------ |
| `operating_cash_flow`  | Operating cash flow (영업활동현금흐름) |
| `investing_cash_flow`  | Investing cash flow (투자활동현금흐름) |
| `financing_cash_flow`  | Financing cash flow (재무활동현금흐름) |
| `capital_expenditures` | CapEx (유형자산취득)                 |
| `free_cash_flow`       | Free cash flow (잉여현금흐름)        |
| `common_dividends`     | Dividends paid (배당금지급)         |

***

## Frontend Hooks Reference

Each API endpoint is wrapped in a React Query hook with optimized caching:

| Hook                     | Endpoint                              | Stale Time | Cache Time |
| ------------------------ | ------------------------------------- | ---------- | ---------- |
| `useCompanyDetail()`     | `/companies/{id}`                     | 5 min      | 10 min     |
| `useCompanyFinancials()` | `/companies/{id}/financials`          | 1 hour     | 2 hours    |
| `useCompanySnapshot()`   | `/companies/{id}/snapshot`            | 1 min      | —          |
| `useCompanyTechnical()`  | `/companies/{id}/technical`           | —          | —          |
| `useCompanyNews()`       | `/companies/{id}/news`                | 1 min      | —          |
| `useCompanyDart()`       | `/companies/{id}/dart`                | 1 min      | —          |
| `useCompanyResearch()`   | `/companies/{id}/research-highlights` | 1 min      | —          |
| `useStockAnalysis()`     | Stock analysis service                | 5 min      | 10 min     |

### Tab Navigation

Tabs use URL hash routing (`#overview`, `#financials`, etc.) with lazy-loaded components via Next.js `dynamic()` imports. Each tab component only fetches data when activated.

```typescript
type TabId = "overview" | "financials" | "chart" | "disclosure" 
           | "insider" | "analysis" | "consensus";
```


# Public API

External API for accessing financial data, stock prices, news, and research reports.

## Authentication

All Public API endpoints require authentication via API key.

### Getting an API Key

1. Log in to your account
2. Navigate to Settings > API Keys
3. Create a new API key with the required scopes
4. Save the key securely (it's only shown once)

### Using the API Key

Include your API key in the `X-API-Key` header:

```bash
curl -H "X-API-Key: ak_your_api_key_here" \
     https://api.alpha-lenz.com/api/public/v1/financial/companies
```

## Available Scopes

| Scope            | Description                   |
| ---------------- | ----------------------------- |
| `read:all`       | Full read access to all APIs  |
| `read:financial` | Access to financial data APIs |
| `read:stock`     | Access to stock price APIs    |
| `read:news`      | Access to news APIs           |

## Rate Limits

Default rate limits: **1,000 requests per hour**

Custom rate limits can be configured per API key.

## Base URL

```
https://api.alpha-lenz.com/api/public/v1
```

## API Endpoints

### Basic Financial API (Twelve Data-style)

Simple and intuitive financial data access:

* `GET /api/v1/financial-v4/time-series` - Historical OHLCV price data
* `GET /api/v1/financial-v4/profile` - Company profile and information
* `GET /api/v1/financial-v4/fundamentals` - Financial ratios and metrics

**Note:** Basic Financial API supports optional authentication (trial mode available)

### Financial Data

* `GET /financial/companies` - List companies
* `GET /financial/companies/{symbol}` - Get company details
* `GET /financial/companies/{symbol}/financials` - Get financial statements

### Stock Prices

* `GET /stock/prices/{symbol}` - Get current prices
* `GET /stock/prices/{symbol}/history` - Get historical prices

### News

* `GET /news/articles` - List news articles
* `GET /news/articles/{id}` - Get article details
* `GET /news/articles/{id}/content` - Get full content

## Error Responses

All errors follow this format:

```json
{
  "detail": "Error message"
}
```

### Common Status Codes

| Code | Description                |
| ---- | -------------------------- |
| 401  | Invalid or missing API key |
| 403  | Insufficient scope         |
| 404  | Resource not found         |
| 429  | Rate limit exceeded        |
| 500  | Server error               |


# API Playground

Interactive API documentation - Try out API requests directly

{% openapi src="/files/NVxISx66hrvshfWvzfqo" path="/api/public/v1/financial/companies" method="get" %}
[public-api-openapi.yaml](https://2139172944-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpqVU4pQOZ49iykr0StXl%2Fuploads%2Fgit-blob-f36a6d26c4a5f0034e00e212200bc280f72677f1%2Fpublic-api-openapi.yaml?alt=media)
{% endopenapi %}

## Quick Start

1. Get your API key from [Settings > API Keys](https://alpha-lenz.com/settings/api-keys)
2. Click "Try it out" on any endpoint above
3. Enter your API key in the `X-API-Key` header
4. Modify parameters and click "Execute"

## Available Endpoints

All Public API endpoints are available for interactive testing in this playground.


# Authentication

## Getting Started

Follow these steps to get your API key and start making requests to Alpha Lenz API.

### Step 1: Create an Account

1. Sign up at <https://alpha-lenz.com>
2. Verify your email address
3. Log in to your dashboard

### Step 2: Generate Your API Key

1. Navigate to **Settings** > **API Keys** in your dashboard
2. Click the **"Create New API Key"** button
3. Give your API key a descriptive name (e.g., "My Production Key")
4. Click **"Create"**

> **⚠️ Important:** Your API key will only be displayed once. Make sure to copy and save it in a secure location immediately. If you lose it, you'll need to create a new key.

### Step 3: Make Your First API Call

Include your API key in the `X-API-Key` header:

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies" \
     -H "X-API-Key: ak_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456"
```

**Example Response:**

```json
{
  "data": [
    {
      "company_id": "KR7005930003",
      "company_name": "Samsung Electronics",
      "ticker": "005930"
    }
  ]
}
```

### Step 4: Integrate into Your Application

**Python Example:**

```python
import requests

API_KEY = "ak_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456"
BASE_URL = "https://api.alpha-lenz.com/api/public/v1"

headers = {
    "X-API-Key": API_KEY
}

response = requests.get(f"{BASE_URL}/financial/companies", headers=headers)
companies = response.json()
```

**JavaScript Example:**

```javascript
const API_KEY = 'ak_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456';
const BASE_URL = 'https://api.alpha-lenz.com/api/public/v1';

const response = await fetch(`${BASE_URL}/financial/companies`, {
  headers: {
    'X-API-Key': API_KEY
  }
});

const companies = await response.json();
```

## API Key Management

### Creating API Keys Programmatically

You can also create API keys programmatically using the API:

**Endpoint:** `POST /api/v1/api-keys`

**Headers:**

```
Authorization: Bearer <your_jwt_token>
Content-Type: application/json
```

**Request Body:**

```json
{
  "name": "My Production Key",
  "scopes": ["read:financial", "read:stock"],
  "expires_at": "2025-12-31T23:59:59Z",
  "rate_limit": 2000,
  "rate_period": 3600
}
```

**Response:**

```json
{
  "id": 1,
  "name": "My Production Key",
  "key": "ak_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
  "key_prefix": "ak_aBcDeFgH",
  "scopes": ["read:financial", "read:stock"],
  "expires_at": "2025-12-31T23:59:59Z",
  "created_at": "2024-01-15T10:30:00Z"
}
```

### Viewing Your API Keys

Navigate to the **API Keys** section in your dashboard to:

* View all your active API keys (only the prefix is shown for security)
* Check when each key was created and last used
* See the current status (Active/Revoked)
* Monitor usage and rate limits

### Revoking API Keys

If your API key is compromised or no longer needed:

1. Go to **Settings** > **API Keys**
2. Find the key you want to revoke
3. Click the **"Revoke"** button
4. Confirm the action

Revoked keys cannot be restored. You'll need to create a new key if needed.

## Rate Limiting

Default: **1,000 requests per hour**

Rate limits are enforced per API key. When exceeded:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "detail": "Rate limit exceeded"
}
```

### Custom Rate Limits

You can set custom rate limits when creating an API key:

* `rate_limit`: Number of requests allowed
* `rate_period`: Time period in seconds (60-86400)

If you need higher limits, please contact us via chatbot.


# Basic Financial API

Twelve Data 스타일의 간단하고 직관적인 금융 데이터 API입니다. 시계열 가격 데이터, 기업 프로필, 펀더멘털 지표를 제공합니다.

**Base URL:** `/api/v1/financial-v4`

**Authentication:** Optional (Trial mode supported)

***

## Time Series

종목의 과거 OHLCV (시가, 고가, 저가, 종가, 거래량) 데이터를 조회합니다.

```
GET /api/v1/financial-v4/time-series
```

### Query Parameters

| Parameter    | Type    | Required | Description                                                |
| ------------ | ------- | -------- | ---------------------------------------------------------- |
| `symbol`     | string  | Yes      | Stock ticker symbol (e.g., "005930")                       |
| `interval`   | string  | No       | Time interval: `1day`, `1week`, `1month` (default: `1day`) |
| `outputsize` | integer | No       | Number of data points (1-5000, default: 30)                |
| `start_date` | string  | No       | Start date filter (YYYY-MM-DD)                             |
| `end_date`   | string  | No       | End date filter (YYYY-MM-DD)                               |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1day&outputsize=100"
```

### Response

```json
{
  "meta": {
    "symbol": "005930",
    "name": "삼성전자",
    "exchange": "KRX",
    "currency": "KRW",
    "interval": "1day",
    "data_points": 100
  },
  "values": [
    {
      "datetime": "2024-01-01T00:00:00",
      "open": 71000.0,
      "high": 72000.0,
      "low": 70500.0,
      "close": 71500.0,
      "volume": 15000000
    },
    {
      "datetime": "2024-01-02T00:00:00",
      "open": 71500.0,
      "high": 72500.0,
      "low": 71000.0,
      "close": 72000.0,
      "volume": 18000000
    }
  ],
  "status": "ok"
}
```

### Response Fields

**meta:**

* `symbol` - Stock ticker symbol
* `name` - Company name
* `exchange` - Exchange code (e.g., KRX)
* `currency` - Trading currency (e.g., KRW)
* `interval` - Time interval of the data
* `data_points` - Number of data points returned

**values (array):**

* `datetime` - ISO 8601 timestamp
* `open` - Opening price
* `high` - Highest price
* `low` - Lowest price
* `close` - Closing price
* `volume` - Trading volume

***

## Profile

기업의 상세 정보, 연락처, 주소, 식별자를 조회합니다.

```
GET /api/v1/financial-v4/profile
```

### Query Parameters

| Parameter | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| `symbol`  | string | Yes      | Stock ticker symbol |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/v1/financial-v4/profile?symbol=005930"
```

### Response

```json
{
  "symbol": "005930",
  "name": "삼성전자",
  "exchange": "KRX",
  "mic_code": "XKRX",
  "sector": "Technology",
  "industry": "Electronics",
  "currency": "KRW",
  "figi_code": "BBG000BCL938",
  "isin": "KR7005930003",
  "cusip": null,
  "description": "삼성전자는 반도체, 디스플레이, IT & 모바일 통신 사업을 영위하는 글로벌 기업입니다.",
  "ceo": "한종희",
  "employees": 270372,
  "website": "https://www.samsung.com",
  "address": "경기도 수원시 영통구 삼성로 129",
  "city": "수원시",
  "state": "경기도",
  "zip_code": "16677",
  "country": "대한민국",
  "phone": "+82-31-200-1114",
  "shares_outstanding": 5969782550,
  "stock_type": "Common Stock",
  "latest_price": 71500.0,
  "market_cap": 426889574325000,
  "status": "ok"
}
```

### Response Fields

**Basic Information:**

* `symbol` - Stock ticker
* `name` - Company name
* `exchange` - Exchange code
* `mic_code` - Market Identifier Code
* `sector` - Business sector
* `industry` - Industry classification

**Identifiers:**

* `currency` - Trading currency
* `figi_code` - Financial Instrument Global Identifier
* `isin` - International Securities Identification Number
* `cusip` - CUSIP number (US securities)

**Company Details:**

* `description` - Business description
* `ceo` - Chief Executive Officer
* `employees` - Number of employees
* `website` - Company website

**Address:**

* `address` - Street address
* `city` - City
* `state` - State/Province
* `zip_code` - Postal code
* `country` - Country
* `phone` - Contact phone

**Share Information:**

* `shares_outstanding` - Total shares
* `stock_type` - Type of stock

**Market Data:**

* `latest_price` - Latest stock price
* `market_cap` - Market capitalization

***

## Fundamentals

재무 비율, 밸류에이션 지표, 성장률 데이터를 조회합니다.

```
GET /api/v1/financial-v4/fundamentals
```

### Query Parameters

| Parameter | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| `symbol`  | string | Yes      | Stock ticker symbol |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/v1/financial-v4/fundamentals?symbol=005930"
```

### Response

```json
{
  "symbol": "005930",
  "name": "삼성전자",
  "exchange": "KRX",
  "currency": "KRW",
  "valuation": {
    "pe_ratio": 15.23,
    "pb_ratio": 1.45,
    "ps_ratio": 1.12,
    "ev_ebitda": 8.45,
    "pfcf_ratio": 12.34
  },
  "growth": {
    "sales_growth_1y": 8.5,
    "sales_growth_3y_cagr": 6.2,
    "sales_growth_5y_cagr": 5.8,
    "operating_income_growth_1y": 12.3,
    "operating_income_growth_3y_cagr": 9.1,
    "operating_income_growth_5y_cagr": 7.5
  },
  "market_data": {
    "market_cap": 426889574325000,
    "latest_price": 71500.0,
    "latest_volume": 15000000,
    "dividend_yield": 2.5,
    "shares_outstanding": 5969782550
  },
  "status": "ok"
}
```

### Response Fields

**valuation (Valuation Ratios):**

* `pe_ratio` - Price-to-Earnings ratio (PER)
* `pb_ratio` - Price-to-Book ratio (PBR)
* `ps_ratio` - Price-to-Sales ratio (PSR)
* `ev_ebitda` - Enterprise Value / EBITDA
* `pfcf_ratio` - Price to Free Cash Flow ratio

**growth (Growth Metrics):**

* `sales_growth_1y` - 1-year sales growth (%)
* `sales_growth_3y_cagr` - 3-year sales CAGR (%)
* `sales_growth_5y_cagr` - 5-year sales CAGR (%)
* `operating_income_growth_1y` - 1-year operating income growth (%)
* `operating_income_growth_3y_cagr` - 3-year operating income CAGR (%)
* `operating_income_growth_5y_cagr` - 5-year operating income CAGR (%)

**market\_data (Market Data):**

* `market_cap` - Market capitalization
* `latest_price` - Latest stock price
* `latest_volume` - Latest trading volume
* `dividend_yield` - Dividend yield (%)
* `shares_outstanding` - Total shares outstanding

***

## Error Responses

All endpoints return standard error responses:

### 404 Not Found

```json
{
  "detail": "Symbol '999999' not found"
}
```

### 422 Validation Error

```json
{
  "detail": [
    {
      "loc": ["query", "outputsize"],
      "msg": "ensure this value is less than or equal to 5000",
      "type": "value_error.number.not_le"
    }
  ]
}
```

### 500 Internal Server Error

```json
{
  "detail": "Internal server error occurred"
}
```

***

## Use Cases

### 1. Building a Stock Price Chart

Get historical price data for visualization:

```bash
# Get 90 days of daily prices
curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1day&outputsize=90"

# Get 52 weeks of weekly prices
curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1week&outputsize=52"
```

### 2. Company Research Dashboard

Combine profile and fundamentals data:

```bash
# Get company information
curl "https://api.alpha-lenz.com/api/v1/financial-v4/profile?symbol=005930"

# Get financial metrics
curl "https://api.alpha-lenz.com/api/v1/financial-v4/fundamentals?symbol=005930"
```

### 3. Multi-Timeframe Analysis

Compare different time periods:

```bash
# Daily data (short-term)
curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1day&outputsize=30"

# Weekly data (medium-term)
curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1week&outputsize=52"

# Monthly data (long-term)
curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1month&outputsize=60"
```

### 4. Historical Period Analysis

Get data for a specific date range:

```bash
# Get Q4 2023 daily prices
curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1day&start_date=2023-10-01&end_date=2023-12-31"
```

***

## Rate Limits

Currently, these endpoints support **trial mode** without rate limits. For production use:

* Standard tier: 100 requests/minute
* Premium tier: 1000 requests/minute
* Enterprise tier: Custom limits

Contact support for API key and tier upgrade.

***

## Comparison with Twelve Data

| Feature              | Twelve Data | Basic Financial API | Notes                   |
| -------------------- | ----------- | ------------------- | ----------------------- |
| Time Series          | ✅           | ✅                   | Similar structure       |
| Company Profile      | ✅           | ✅                   | Full company info       |
| Fundamentals         | ✅           | ✅                   | Valuation & growth      |
| Real-time Quote      | ✅           | ⏳                   | Coming soon             |
| Technical Indicators | ✅           | ❌                   | Use `/stock-prices` API |
| Logo                 | ✅           | ❌                   | Not implemented         |
| WebSocket            | ✅           | ❌                   | Not implemented         |

***

## Related APIs

* [**Stock API**](/en/api-reference/public-api/stock) - Advanced stock price data with technical indicators
* [**Financial API**](/en/api-reference/public-api/financial) - Detailed financial statements and company data
* [**News API**](/en/api-reference/public-api/news) - Company news and market updates

***

## Support

For questions or issues:

* Check [API Documentation](https://github.com/TeamZikto/argo-lng-mono/blob/main/docs/README.md)
* Contact support team
* Visit GitHub repository


# Financial

Access company information and financial statement data.

**Required Scope:** `read:financial` or `read:all`

## List Companies

Get a list of companies with optional filtering.

```
GET /api/public/v1/financial/companies
```

### Query Parameters

| Parameter | Type    | Description                           |
| --------- | ------- | ------------------------------------- |
| `search`  | string  | Search by name or symbol              |
| `sector`  | string  | Filter by sector                      |
| `country` | string  | Filter by country                     |
| `limit`   | integer | Results per page (1-100, default: 50) |
| `offset`  | integer | Pagination offset (default: 0)        |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies?search=samsung&limit=10" \
     -H "X-API-Key: ak_your_key"
```

### Response

```json
{
  "companies": [
    {
      "company_id": 1,
      "symbol": "005930",
      "name": "Samsung Electronics",
      "alias_name": "삼성전자",
      "exchange": "KRX",
      "sector": "Technology",
      "country": "KR"
    }
  ],
  "total": 1
}
```

***

## Get Company by Symbol

Get company information by stock symbol.

```
GET /api/public/v1/financial/companies/{symbol}
```

### Path Parameters

| Parameter | Type   | Description                   |
| --------- | ------ | ----------------------------- |
| `symbol`  | string | Stock symbol (e.g., "005930") |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies/005930" \
     -H "X-API-Key: ak_your_key"
```

### Response

```json
{
  "company_id": 1,
  "symbol": "005930",
  "name": "Samsung Electronics",
  "alias_name": "삼성전자",
  "exchange": "KRX",
  "sector": "Technology",
  "country": "KR"
}
```

***

## Get Company Financials

Get financial statements time series data for a company.

```
GET /api/public/v1/financial/companies/{symbol}/financials
```

### Path Parameters

| Parameter | Type   | Description  |
| --------- | ------ | ------------ |
| `symbol`  | string | Stock symbol |

### Query Parameters

| Parameter | Type    | Description                                    |
| --------- | ------- | ---------------------------------------------- |
| `period`  | string  | "Annual" or "Quarterly" (default: "Annual")    |
| `years`   | integer | Number of years to retrieve (1-20, default: 5) |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies/005930/financials?period=Annual&years=5" \
     -H "X-API-Key: ak_your_key"
```

### Response

```json
{
  "statements": [
    {
      "fiscal_date": "2023-12-31",
      "year": 2023,
      "quarter": null,
      "period": "Annual",
      "currency": "KRW",
      "sales": 258935000000000,
      "gross_profit": 85000000000000,
      "operating_income": 6570000000000,
      "net_income": 15490000000000,
      "total_assets": 455000000000000,
      "total_liabilities": 120000000000000,
      "total_shareholders_equity": 335000000000000,
      "operating_cash_flow": 50000000000000,
      "free_cash_flow": 30000000000000
    }
  ]
}
```

### Financial Statement Fields

**Income Statement:**

* `sales`, `cost_of_goods`, `gross_profit`
* `operating_income`, `net_income`
* `ebit`, `ebitda`
* `eps_basic`, `eps_diluted`

**Balance Sheet:**

* `total_assets`, `total_current_assets`, `total_non_current_assets`
* `total_liabilities`, `total_current_liabilities`, `total_non_current_liabilities`
* `total_shareholders_equity`
* `cash`, `inventory`, `accounts_receivable`

**Cash Flow:**

* `operating_cash_flow`, `investing_cash_flow`, `financing_cash_flow`
* `free_cash_flow`, `capital_expenditures`


# News

Access news articles and market updates.

**Required Scope:** `read:news` or `read:all`

## List News Articles

Get news articles with optional filtering.

```
GET /api/public/v1/news/articles
```

### Query Parameters

| Parameter  | Type    | Description                                  |
| ---------- | ------- | -------------------------------------------- |
| `skip`     | integer | Items to skip (default: 0)                   |
| `limit`    | integer | Max items to return (1-100, default: 50)     |
| `category` | string  | Filter by category                           |
| `priority` | integer | Filter by priority (1=high, 2=medium, 3=low) |

### Headers

| Header     | Description                                 |
| ---------- | ------------------------------------------- |
| `x-locale` | Language code: ko, en, ja, zh (default: en) |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/news/articles?limit=20&category=market_move" \
     -H "X-API-Key: ak_your_key" \
     -H "x-locale: ko"
```

### Response

```json
{
  "articles": [
    {
      "id": 123,
      "title": "Major Market Movement: Tech Stocks Rally",
      "summary": "Technology stocks led the market rally today...",
      "category": "market_move",
      "priority": 1,
      "source_url": "https://example.com/article",
      "published_at": "2024-01-15T14:30:00Z",
      "created_at": "2024-01-15T14:35:00Z"
    }
  ],
  "total": 150,
  "skip": 0,
  "limit": 20
}
```

***

## Get News Article

Get detailed information about a specific news article.

```
GET /api/public/v1/news/articles/{article_id}
```

### Path Parameters

| Parameter    | Type    | Description     |
| ------------ | ------- | --------------- |
| `article_id` | integer | News article ID |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/news/articles/123" \
     -H "X-API-Key: ak_your_key" \
     -H "x-locale: en"
```

### Response

```json
{
  "id": 123,
  "title": "Major Market Movement: Tech Stocks Rally",
  "summary": "Technology stocks led the market rally today...",
  "ai_angle": "AI analysis perspective on the market movement...",
  "risk": "Key risks to watch...",
  "category": "market_move",
  "priority": 1,
  "source_url": "https://example.com/article",
  "trigger": [
    {
      "topic": "Tech Stocks",
      "sentiment": "positive"
    }
  ],
  "published_at": "2024-01-15T14:30:00Z",
  "created_at": "2024-01-15T14:35:00Z"
}
```

***

## Get Article Full Content

Get the full content of a news article.

```
GET /api/public/v1/news/articles/{article_id}/content
```

### Path Parameters

| Parameter    | Type    | Description     |
| ------------ | ------- | --------------- |
| `article_id` | integer | News article ID |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/news/articles/123/content" \
     -H "X-API-Key: ak_your_key" \
     -H "x-locale: ko"
```

### Response

```json
{
  "id": 123,
  "title": "Major Market Movement: Tech Stocks Rally",
  "content_type": "html",
  "full_content": "<div>Full article content here...</div>"
}
```

### Categories

Available news categories:

| Category      | Description                    |
| ------------- | ------------------------------ |
| `eod_summary` | End of day market summary      |
| `fed_policy`  | Federal Reserve policy updates |
| `market_move` | Significant market movements   |
| `earnings`    | Earnings reports               |
| `breaking`    | Breaking news                  |

### Language Support

Use the `x-locale` header to get localized content:

* `ko` - Korean
* `en` - English (default)
* `ja` - Japanese
* `zh` - Chinese


# Research

Access research reports from securities firms.

**Required Scope:** `read:research` or `read:all`

## List Research Reports

Get research reports with filtering and pagination.

```
GET /api/public/v1/research/reports
```

### Query Parameters

| Parameter           | Type    | Description                                                 |
| ------------------- | ------- | ----------------------------------------------------------- |
| `page`              | integer | Page number (default: 1)                                    |
| `page_size`         | integer | Items per page (1-100, default: 20)                         |
| `securities_firm`   | string  | Filter by securities firm                                   |
| `stock_name`        | string  | Filter by stock name                                        |
| `report_type`       | string  | Filter by type: "company\_analysis" or "industry\_analysis" |
| `industry_category` | string  | Filter by industry category                                 |
| `start_date`        | date    | Filter from date (YYYY-MM-DD)                               |
| `end_date`          | date    | Filter to date (YYYY-MM-DD)                                 |
| `title`             | string  | Search in report title                                      |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/research/reports?stock_name=삼성전자&page_size=10" \
     -H "X-API-Key: ak_your_key"
```

### Response

```json
{
  "reports": [
    {
      "id": 456,
      "title": "Samsung Electronics - 4Q23 Preview",
      "report_date": "2024-01-10",
      "report_type": "company_analysis",
      "securities_firm": "미래에셋증권",
      "stock_name": "삼성전자",
      "industry_category": "반도체",
      "cdn_url": "https://static.alpha-lenz.com/reports/2024/01/456.pdf"
    }
  ],
  "total": 125,
  "page": 1,
  "page_size": 10,
  "has_next": true
}
```

***

## Get Research Report

Get detailed information about a specific research report.

```
GET /api/public/v1/research/reports/{report_id}
```

### Path Parameters

| Parameter   | Type    | Description        |
| ----------- | ------- | ------------------ |
| `report_id` | integer | Research report ID |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/research/reports/456" \
     -H "X-API-Key: ak_your_key"
```

### Response

```json
{
  "id": 456,
  "title": "Samsung Electronics - 4Q23 Preview",
  "report_date": "2024-01-10",
  "report_type": "company_analysis",
  "securities_firm": "미래에셋증권",
  "stock_name": "삼성전자",
  "industry_category": "반도체",
  "s3_key": "reports/2024/01/456.pdf",
  "cdn_url": "https://static.alpha-lenz.com/reports/2024/01/456.pdf"
}
```

### Downloading Reports

Use the `cdn_url` field to download the PDF report:

```bash
curl -O "https://static.alpha-lenz.com/reports/2024/01/456.pdf"
```

### Report Types

| Type                | Description                 |
| ------------------- | --------------------------- |
| `company_analysis`  | Individual company analysis |
| `industry_analysis` | Industry/sector analysis    |

### Pagination

Use `page` and `page_size` for pagination. Check `has_next` to see if there are more results:

```bash
# First page
GET /research/reports?page=1&page_size=20

# Second page
GET /research/reports?page=2&page_size=20
```

### Filtering Examples

**By Securities Firm:**

```
GET /research/reports?securities_firm=미래에셋증권
```

**By Date Range:**

```
GET /research/reports?start_date=2024-01-01&end_date=2024-01-31
```

**By Industry:**

```
GET /research/reports?industry_category=반도체
```

**Title Search:**

```
GET /research/reports?title=실적
```


# Stock

Access stock price data including OHLCV (Open, High, Low, Close, Volume).

**Required Scope:** `read:stock` or `read:all`

## Get Stock Prices

Get OHLCV stock price data for a symbol.

```
GET /api/public/v1/stock/prices/{symbol}
```

### Path Parameters

| Parameter | Type   | Description                   |
| --------- | ------ | ----------------------------- |
| `symbol`  | string | Stock symbol (e.g., "005930") |

### Query Parameters

| Parameter  | Type    | Description                                                |
| ---------- | ------- | ---------------------------------------------------------- |
| `interval` | string  | Time interval: "1day", "1week", "1month" (default: "1day") |
| `limit`    | integer | Number of data points (1-500, default: 100)                |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/stock/prices/005930?interval=1day&limit=30" \
     -H "X-API-Key: ak_your_key"
```

### Response

```json
{
  "symbol": "005930",
  "company_name": "Samsung Electronics",
  "interval": "1day",
  "data": [
    {
      "datetime": "2024-01-15T00:00:00",
      "open": 71500.0,
      "high": 72000.0,
      "low": 71000.0,
      "close": 71800.0,
      "volume": 15000000
    },
    {
      "datetime": "2024-01-16T00:00:00",
      "open": 71800.0,
      "high": 72500.0,
      "low": 71500.0,
      "close": 72200.0,
      "volume": 12500000
    }
  ],
  "count": 30
}
```

***

## Get Stock Price History

Get historical stock price data with date filtering and pagination.

```
GET /api/public/v1/stock/prices/{symbol}/history
```

### Path Parameters

| Parameter | Type   | Description  |
| --------- | ------ | ------------ |
| `symbol`  | string | Stock symbol |

### Query Parameters

| Parameter    | Type    | Description                              |
| ------------ | ------- | ---------------------------------------- |
| `interval`   | string  | Time interval: "1day", "1week", "1month" |
| `start_date` | string  | Start date filter (YYYY-MM-DD)           |
| `end_date`   | string  | End date filter (YYYY-MM-DD)             |
| `limit`      | integer | Results per page (1-1000, default: 100)  |
| `offset`     | integer | Pagination offset (default: 0)           |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/stock/prices/005930/history?start_date=2024-01-01&end_date=2024-01-31&limit=100" \
     -H "X-API-Key: ak_your_key"
```

### Response

```json
{
  "symbol": "005930",
  "company_name": "Samsung Electronics",
  "interval": "1day",
  "data": [
    {
      "datetime": "2024-01-02T00:00:00",
      "open": 70000.0,
      "high": 71000.0,
      "low": 69500.0,
      "close": 70500.0,
      "volume": 18000000
    }
  ],
  "count": 22,
  "has_more": false
}
```

### OHLCV Fields

| Field      | Type    | Description       |
| ---------- | ------- | ----------------- |
| `datetime` | string  | ISO 8601 datetime |
| `open`     | float   | Opening price     |
| `high`     | float   | Highest price     |
| `low`      | float   | Lowest price      |
| `close`    | float   | Closing price     |
| `volume`   | integer | Trading volume    |

### Pagination

Use `offset` and `limit` for pagination. Check `has_more` to see if there are more results:

```bash
# First page
GET /stock/prices/005930/history?limit=100&offset=0

# Second page
GET /stock/prices/005930/history?limit=100&offset=100
```


# 소개

Alpha Lenz는 단순한 데이터 API가 아닙니다 — 이전에는 존재하지 않았던 금융 서비스를 만들 수 있게 해주는 AI 네이티브 금융 인프라 레이어입니다.

완전히 모듈화된 컴포넌트와 엔드투엔드 커스터마이징을 통해, 전통적인 시장 데이터 인터페이스의 제약 없이 고유한 리서치 워크플로우, 개인화된 투자 경험, 그리고 새로운 제품 카테고리를 설계할 수 있습니다.

글로벌 시장 데이터, 시맨틱 리서치 인덱싱, 차트 및 컨센서스 분석 엔진, AI 에이전트를 하나의 프로그래밍 가능한 API 레이어로 통합했습니다.

이를 통해 다음을 수행할 수 있습니다:

* 완전히 커스터마이즈된 금융 애플리케이션 및 사용자 경험 구축
* AI 기반 인사이트와 추론을 모든 워크플로우에 통합
* 리서치 및 의사결정 지원 자동화 및 확장
* 여러 시장에 걸쳐 제로 레이턴시, 고정확도 데이터 제공

애널리스트, 핀테크 플랫폼, 자산 운용사의 신뢰를 받는 Alpha Lenz는 사전 구축된 화면과 정적 리포트를 넘어 여러분이 상상하는 금융 제품을 만들 수 있도록 지원합니다.


# 목차

* [소개](/ko)

## API 레퍼런스

* [Public API](/ko/api-reference/public-api)
  * [인증](/ko/api-reference/public-api/authentication)
  * [API 플레이그라운드](/ko/api-reference/public-api/api-playground)
  * [Basic Financial API](/ko/api-reference/public-api/basic-financial-api)
  * [Financial](/ko/api-reference/public-api/financial)
  * [Stock](/ko/api-reference/public-api/stock)
  * [News](/ko/api-reference/public-api/news)
  * [Research](/ko/api-reference/public-api/research)
* [Company](/ko/api-reference/company)
  * [회사 탭 API](/ko/api-reference/company/page-5)
* [Agents](/ko/api-reference/agents)
  * [Screener](/ko/api-reference/agents/screener)
    * [Page 2](/ko/api-reference/agents/screener/page-2)
  * [Orchestration](/ko/api-reference/agents/orchestration)
    * [Page 4](/ko/api-reference/agents/orchestration/page-4)


# api-reference


# Agents


# Orchestration


# Page 4


# Screener


# Page 2


# Company


# 회사 탭 API

회사 상세 페이지는 7개의 탭으로 구성되며, 각 탭은 전용 API 엔드포인트를 사용합니다.

## 탭 구성

| 탭    | ID           | 주요 엔드포인트                                  | 설명                  |
| ---- | ------------ | ----------------------------------------- | ------------------- |
| 개요   | `overview`   | `/companies/{id}`                         | 회사 프로필, 통계, 요약 카드   |
| 재무제표 | `financials` | `/companies/{id}/financials`              | 손익계산서, 재무상태표, 현금흐름표 |
| 차트   | `chart`      | TradingView 위젯                            | 인터랙티브 주가 차트         |
| 공시   | `disclosure` | `/companies/{id}/dart`                    | DART 기업 공시          |
| 내부자  | `insider`    | `/companies/{id}/insider`                 | 내부자 거래 데이터          |
| 분석   | `analysis`   | `/companies/{id}/snapshot` + `/technical` | 기술적 신호 및 AI 분석      |
| 컨센서스 | `consensus`  | `/companies/{id}/consensus`               | 전문가 전망치 및 목표가       |

***

## 회사 상세 정보

회사 프로필, 재무 지표, 밸류에이션, 성장성, 재무 건전성 정보를 반환합니다.

```
GET /v1/financial_v4/companies/{company_id}
```

### 경로 파라미터

| 파라미터         | 타입      | 설명    |
| ------------ | ------- | ----- |
| `company_id` | integer | 회사 ID |

### 응답

```json
{
  "id": 1,
  "name": "Samsung Electronics",
  "alias_name": "삼성전자",
  "symbol": "005930",
  "exchange": "KRX",
  "currency": "KRW",
  "current_price": 58000,
  "price_change": 1200,
  "price_change_percent": 2.11,
  "description": "삼성전자 ...",
  "ceo": "한종희",
  "website": "https://www.samsung.com",
  "sector": "Technology",
  "industry": "Semiconductors",
  "employees": 267800,
  "fiscal_year": 2024,
  "fiscal_date": "2024-12-31",
  "profile": {
    "market_cap": 346000000000000,
    "revenue": 258935000000000,
    "shares_outstanding": 5969783000,
    "employees": 267800
  },
  "margins": {
    "gross_margin": 32.8,
    "ebitda_margin": 18.5,
    "operating_margin": 2.54,
    "pretax_margin": 3.12,
    "net_margin": 5.98
  },
  "valuation": {
    "pe_ratio": 37.4,
    "pb_ratio": 1.03,
    "ps_ratio": 1.34,
    "ev_ebitda": 7.22,
    "pfcf_ratio": 11.5
  },
  "growth": {
    "sales_growth_3y_cagr": -2.1,
    "sales_growth_5y_cagr": 3.8,
    "operating_income_growth_3y_cagr": -15.2,
    "operating_income_growth_5y_cagr": -8.4,
    "net_income_growth_3y_cagr": -10.5,
    "net_income_growth_5y_cagr": -5.1
  },
  "returns": {
    "roa": 3.4,
    "roe": 4.6,
    "roic": 3.9
  },
  "financial_health": {
    "cash": 65000000000000,
    "net_debt": -20000000000000,
    "debt_to_equity_ratio": 0.36,
    "interest_coverage_ratio": 8.5
  }
}
```

**사용처:** 개요 탭 — 회사 헤더, 통계 그리드, 재무 지표 카드

***

## 회사 슬러그 해석

URL 슬러그 또는 티커 심볼을 회사 ID로 변환합니다. 라우팅에 사용됩니다.

```
GET /v1/financial_v4/companies/by-slug/{slug}
```

### 경로 파라미터

| 파라미터   | 타입     | 설명                                                |
| ------ | ------ | ------------------------------------------------- |
| `slug` | string | 회사 슬러그 또는 티커 (예: `samsung-electronics`, `005930`) |

### 응답

```json
{
  "id": 1,
  "name": "Samsung Electronics",
  "symbol": "005930",
  "exchange": "KRX"
}
```

***

## 회사 재무제표

시계열 재무제표 데이터를 반환합니다 (손익계산서, 재무상태표, 현금흐름표).

```
GET /v1/financial_v4/companies/{company_id}/financials
```

### 쿼리 파라미터

| 파라미터     | 타입      | 기본값        | 설명                          |
| -------- | ------- | ---------- | --------------------------- |
| `period` | string  | `"Annual"` | `"Annual"` 또는 `"Quarterly"` |
| `years`  | integer | `5`        | 조회 연도 수                     |

### 응답

```json
{
  "statements": [
    {
      "fiscal_date": "2024-12-31",
      "year": 2024,
      "quarter": null,
      "period": "Annual",
      "currency": "KRW",
      "sales": 258935000000000,
      "operating_income": 6570000000000,
      "net_income": 15490000000000,
      "total_assets": 455000000000000,
      "free_cash_flow": 30000000000000
    }
  ]
}
```

**전체 필드 목록:** 아래 [재무제표 필드](#재무제표-필드) 참조.

**사용처:** 재무제표 탭 — 손익계산서, 재무상태표, 현금흐름표 서브탭 (연간/분기 토글)

***

## 회사 스냅샷

yfinance 기반 실시간 시장 데이터와 애널리스트 추천을 반환합니다.

```
GET /v1/financial_v4/companies/{company_id}/snapshot
```

**사용처:** 분석 탭 — 핵심 지표 디스플레이, AI 시그널 배너

***

## 회사 기술적 지표

주가 데이터로 계산된 기술적 지표를 반환합니다.

```
GET /v1/financial_v4/companies/{company_id}/technical
```

### 응답 포함 항목

* **RSI** (상대강도지수)
* **MACD** (이동평균수렴확산)
* **볼린저 밴드** (상단, 중단, 하단)
* **ATR** (평균실질범위)
* **SMA** (단순이동평균 — 20, 50, 200일)

**사용처:** 분석 탭 — 기술적 신호 컴포넌트

***

## 회사 뉴스

Perigon API 및 Google News RSS 기반 뉴스 기사를 반환합니다.

```
GET /v1/financial_v4/companies/{company_id}/news
```

### 쿼리 파라미터

| 파라미터     | 타입      | 기본값    | 설명                      |
| -------- | ------- | ------ | ----------------------- |
| `limit`  | integer | `3`    | 반환할 기사 수                |
| `locale` | string  | `"ko"` | 언어 로케일 (`"ko"`, `"en"`) |

**사용처:** 개요 탭 — 뉴스 카드 (지연 로딩)

***

## 회사 DART 공시

DART 시스템 기업 공시 정보를 반환합니다.

```
GET /v1/financial_v4/companies/{company_id}/dart
```

### 쿼리 파라미터

| 파라미터    | 타입      | 기본값 | 설명       |
| ------- | ------- | --- | -------- |
| `limit` | integer | `3` | 반환할 공시 수 |

**사용처:** 공시 탭, 개요 탭 — DART 카드

***

## 회사 리서치 하이라이트

증권사 리서치 보고서 요약을 반환합니다.

```
GET /v1/financial_v4/companies/{company_id}/research-highlights
```

### 쿼리 파라미터

| 파라미터    | 타입      | 기본값 | 설명        |
| ------- | ------- | --- | --------- |
| `limit` | integer | `3` | 반환할 보고서 수 |

**사용처:** 개요 탭 — 리서치 하이라이트 카드

***

## 회사 섹터 분석

해당 회사의 섹터 레벨 분석을 반환합니다.

```
GET /v1/sector-analyst/company/{company_id}
```

### 쿼리 파라미터

| 파라미터     | 타입     | 기본값 | 설명     |
| -------- | ------ | --- | ------ |
| `locale` | string | —   | 언어 로케일 |

**사용처:** 개요 탭 — 섹터 분석 카드 (지연 로딩)

***

## 회사 컨센서스

전문가 전망 컨센서스 (목표가, 투자의견 등)를 반환합니다.

```
GET /v1/financial_v4/companies/{company_id}/consensus
```

### 쿼리 파라미터

| 파라미터     | 타입      | 기본값  | 설명         |
| -------- | ------- | ---- | ---------- |
| `months` | integer | `12` | 분석 기간 (개월) |

### 응답

```json
{
  "company_id": 1,
  "company_name": "Samsung Electronics",
  "symbol": "005930",
  "currency": "KRW",
  "has_consensus": true,
  "message": null,
  "current_price": 58000,
  "target_prices": {
    "average": 85000,
    "high": 110000,
    "high_broker": "미래에셋증권",
    "low": 65000,
    "low_broker": "대신증권",
    "std_dev": 12500,
    "expert_count": 25
  },
  "upside_downside": {
    "current_price": 58000,
    "to_high": 89.66,
    "to_average": 46.55,
    "to_low": 12.07
  },
  "investment_opinions": [
    { "opinion": "매수", "count": 18, "percentage": 72.0 },
    { "opinion": "중립", "count": 5, "percentage": 20.0 },
    { "opinion": "매도", "count": 2, "percentage": 8.0 }
  ],
  "target_price_trend": [
    {
      "date": "2024-03-15",
      "target_price": 90000,
      "broker": "삼성증권",
      "opinion": "매수"
    }
  ],
  "price_history": [
    { "date": "2024-01-02", "close": 52000 }
  ],
  "analysis_period_months": 12,
  "last_report_date": "2024-03-20",
  "total_reports": 42
}
```

**사용처:** 컨센서스 탭 — 목표가 차트, 투자의견 분포, 증권사별 상세 테이블

***

## 회사 내부자 거래

내부자 거래 데이터를 반환합니다.

```
GET /v1/financial_v4/companies/{company_id}/insider
```

**사용처:** 내부자 탭, 공시 탭 — 내부자 거래 임베드

***

## 재무제표 필드

재무제표 엔드포인트가 각 기간별로 반환하는 필드 목록입니다:

### 손익계산서

| 필드                                   | 설명      |
| ------------------------------------ | ------- |
| `sales`                              | 매출액     |
| `cost_of_goods`                      | 매출원가    |
| `gross_profit`                       | 매출총이익   |
| `research_and_development`           | 연구개발비   |
| `selling_general_and_administrative` | 판매관리비   |
| `operating_income`                   | 영업이익    |
| `ebit`                               | EBIT    |
| `ebitda`                             | EBITDA  |
| `pretax_income`                      | 세전이익    |
| `net_income`                         | 당기순이익   |
| `eps_basic`                          | 기본주당순이익 |
| `eps_diluted`                        | 희석주당순이익 |

### 재무상태표

| 필드                              | 설명       |
| ------------------------------- | -------- |
| `total_assets`                  | 자산총계     |
| `total_current_assets`          | 유동자산     |
| `cash_and_cash_equivalents`     | 현금및현금성자산 |
| `accounts_receivable`           | 매출채권     |
| `inventory`                     | 재고자산     |
| `total_non_current_assets`      | 비유동자산    |
| `properties`                    | 유형자산     |
| `intangible_assets`             | 무형자산     |
| `goodwill`                      | 영업권      |
| `total_liabilities`             | 부채총계     |
| `total_current_liabilities`     | 유동부채     |
| `total_non_current_liabilities` | 비유동부채    |
| `total_shareholders_equity`     | 자본총계     |
| `retained_earnings`             | 이익잉여금    |

### 현금흐름표

| 필드                     | 설명       |
| ---------------------- | -------- |
| `operating_cash_flow`  | 영업활동현금흐름 |
| `investing_cash_flow`  | 투자활동현금흐름 |
| `financing_cash_flow`  | 재무활동현금흐름 |
| `capital_expenditures` | 유형자산취득   |
| `free_cash_flow`       | 잉여현금흐름   |
| `common_dividends`     | 배당금지급    |

***

## 프론트엔드 Hooks 참조

각 API 엔드포인트는 React Query hook으로 래핑되어 캐싱이 최적화되어 있습니다:

| Hook                     | 엔드포인트                                 | Stale Time | Cache Time |
| ------------------------ | ------------------------------------- | ---------- | ---------- |
| `useCompanyDetail()`     | `/companies/{id}`                     | 5분         | 10분        |
| `useCompanyFinancials()` | `/companies/{id}/financials`          | 1시간        | 2시간        |
| `useCompanySnapshot()`   | `/companies/{id}/snapshot`            | 1분         | —          |
| `useCompanyTechnical()`  | `/companies/{id}/technical`           | —          | —          |
| `useCompanyNews()`       | `/companies/{id}/news`                | 1분         | —          |
| `useCompanyDart()`       | `/companies/{id}/dart`                | 1분         | —          |
| `useCompanyResearch()`   | `/companies/{id}/research-highlights` | 1분         | —          |
| `useStockAnalysis()`     | Stock analysis 서비스                    | 5분         | 10분        |

### 탭 네비게이션

탭은 URL 해시 라우팅(`#overview`, `#financials` 등)을 사용하며, Next.js `dynamic()` import로 지연 로딩됩니다. 각 탭 컴포넌트는 활성화될 때만 데이터를 가져옵니다.

```typescript
type TabId = "overview" | "financials" | "chart" | "disclosure" 
           | "insider" | "analysis" | "consensus";
```


# Public API

금융 데이터, 주가, 뉴스, 리서치 리포트에 액세스하기 위한 외부 API입니다.

## 인증

모든 Public API 엔드포인트는 API 키를 통한 인증이 필요합니다.

### API 키 발급

1. 계정에 로그인
2. 설정 > API 키로 이동
3. 필요한 스코프로 새 API 키 생성
4. 키를 안전하게 저장 (한 번만 표시됨)

### API 키 사용

`X-API-Key` 헤더에 API 키를 포함합니다:

```bash
curl -H "X-API-Key: ak_your_api_key_here" \
     https://api.alpha-lenz.com/api/public/v1/financial/companies
```

## 사용 가능한 스코프

| 스코프              | 설명                   |
| ---------------- | -------------------- |
| `read:all`       | 모든 API에 대한 전체 읽기 액세스 |
| `read:financial` | 금융 데이터 API 액세스       |
| `read:stock`     | 주가 API 액세스           |
| `read:news`      | 뉴스 API 액세스           |

## 요청 제한

기본 요청 제한: **시간당 1,000회 요청**

API 키별로 맞춤 요청 제한을 설정할 수 있습니다.

## Base URL

```
https://api.alpha-lenz.com/api/public/v1
```

## API 엔드포인트

### Basic Financial API (Twelve Data 스타일)

간단하고 직관적인 금융 데이터 액세스:

* `GET /api/v1/financial-v4/time-series` - 과거 OHLCV 가격 데이터
* `GET /api/v1/financial-v4/profile` - 기업 프로필 및 정보
* `GET /api/v1/financial-v4/fundamentals` - 재무 비율 및 지표

**참고:** Basic Financial API는 선택적 인증을 지원합니다 (trial 모드 사용 가능)

### Financial Data

* `GET /financial/companies` - 기업 목록 조회
* `GET /financial/companies/{symbol}` - 기업 상세 정보 조회
* `GET /financial/companies/{symbol}/financials` - 재무제표 조회

### Stock Prices

* `GET /stock/prices/{symbol}` - 현재 주가 조회
* `GET /stock/prices/{symbol}/history` - 과거 주가 조회

### News

* `GET /news/articles` - 뉴스 기사 목록 조회
* `GET /news/articles/{id}` - 기사 상세 정보 조회
* `GET /news/articles/{id}/content` - 전체 콘텐츠 조회

## 오류 응답

모든 오류는 다음 형식을 따릅니다:

```json
{
  "detail": "오류 메시지"
}
```

### 주요 상태 코드

| 코드  | 설명                |
| --- | ----------------- |
| 401 | API 키가 잘못되었거나 누락됨 |
| 403 | 권한 부족             |
| 404 | 리소스를 찾을 수 없음      |
| 429 | 요청 제한 초과          |
| 500 | 서버 오류             |


# API 플레이그라운드

대화형 API 문서 - API 요청을 직접 테스트해보세요

{% openapi src="/files/NVxISx66hrvshfWvzfqo" path="/api/public/v1/financial/companies" method="get" %}
[public-api-openapi.yaml](https://2139172944-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpqVU4pQOZ49iykr0StXl%2Fuploads%2Fgit-blob-f36a6d26c4a5f0034e00e212200bc280f72677f1%2Fpublic-api-openapi.yaml?alt=media)
{% endopenapi %}

## 빠른 시작

1. [설정 > API 키](https://alpha-lenz.com/settings/api-keys)에서 API 키 발급
2. 위 엔드포인트에서 "Try it out" 클릭
3. `X-API-Key` 헤더에 API 키 입력
4. 파라미터 수정 후 "Execute" 클릭

## 사용 가능한 엔드포인트

모든 Public API 엔드포인트를 이 플레이그라운드에서 대화형으로 테스트할 수 있습니다.


# 인증

## 시작하기

다음 단계를 따라 API 키를 발급받고 Alpha Lenz API 요청을 시작하세요.

### 1단계: 계정 생성

1. <https://alpha-lenz.com>에서 회원가입
2. 이메일 주소 인증
3. 대시보드에 로그인

### 2단계: API 키 생성

1. 대시보드에서 **설정** > **API 키**로 이동
2. **"새 API 키 만들기"** 버튼 클릭
3. API 키에 설명적인 이름 지정 (예: "프로덕션 키")
4. **"생성"** 클릭

> **⚠️ 중요:** API 키는 한 번만 표시됩니다. 즉시 안전한 위치에 복사하여 저장하세요. 키를 분실하면 새 키를 생성해야 합니다.

### 3단계: 첫 API 호출하기

`X-API-Key` 헤더에 API 키를 포함합니다:

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies" \
     -H "X-API-Key: ak_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456"
```

**응답 예시:**

```json
{
  "data": [
    {
      "company_id": "KR7005930003",
      "company_name": "Samsung Electronics",
      "ticker": "005930"
    }
  ]
}
```

### 4단계: 애플리케이션에 통합

**Python 예시:**

```python
import requests

API_KEY = "ak_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456"
BASE_URL = "https://api.alpha-lenz.com/api/public/v1"

headers = {
    "X-API-Key": API_KEY
}

response = requests.get(f"{BASE_URL}/financial/companies", headers=headers)
companies = response.json()
```

**JavaScript 예시:**

```javascript
const API_KEY = 'ak_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456';
const BASE_URL = 'https://api.alpha-lenz.com/api/public/v1';

const response = await fetch(`${BASE_URL}/financial/companies`, {
  headers: {
    'X-API-Key': API_KEY
  }
});

const companies = await response.json();
```

## API 키 관리

### 프로그래밍 방식으로 API 키 생성

API를 사용하여 프로그래밍 방식으로 API 키를 생성할 수도 있습니다:

**엔드포인트:** `POST /api/v1/api-keys`

**헤더:**

```
Authorization: Bearer <your_jwt_token>
Content-Type: application/json
```

**요청 본문:**

```json
{
  "name": "프로덕션 키",
  "scopes": ["read:financial", "read:stock"],
  "expires_at": "2025-12-31T23:59:59Z",
  "rate_limit": 2000,
  "rate_period": 3600
}
```

**응답:**

```json
{
  "id": 1,
  "name": "프로덕션 키",
  "key": "ak_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
  "key_prefix": "ak_aBcDeFgH",
  "scopes": ["read:financial", "read:stock"],
  "expires_at": "2025-12-31T23:59:59Z",
  "created_at": "2024-01-15T10:30:00Z"
}
```

### API 키 조회

대시보드의 **API 키** 섹션에서 다음을 수행할 수 있습니다:

* 활성 API 키 전체 보기 (보안상 접두사만 표시)
* 각 키의 생성 시간 및 마지막 사용 시간 확인
* 현재 상태 확인 (활성/취소됨)
* 사용량 및 요청 제한 모니터링

### API 키 취소

API 키가 유출되었거나 더 이상 필요하지 않은 경우:

1. **설정** > **API 키**로 이동
2. 취소할 키 찾기
3. **"취소"** 버튼 클릭
4. 작업 확인

취소된 키는 복원할 수 없습니다. 필요한 경우 새 키를 생성해야 합니다.

## 요청 제한

기본값: **시간당 1,000회 요청**

요청 제한은 API 키별로 적용됩니다. 제한 초과 시:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "detail": "Rate limit exceeded"
}
```

### 맞춤 요청 제한

API 키 생성 시 맞춤 요청 제한을 설정할 수 있습니다:

* `rate_limit`: 허용되는 요청 수
* `rate_period`: 시간(초) (60-86400)

더 높은 제한이 필요한 경우 챗봇을 통해 문의하세요.


# Basic Financial API

Twelve Data 스타일의 간단하고 직관적인 금융 데이터 API입니다. 시계열 가격 데이터, 기업 프로필, 펀더멘털 지표를 제공합니다.

**Base URL:** `/api/v1/financial-v4`

**Authentication:** Optional (Trial mode supported)

***

## Time Series

종목의 과거 OHLCV (시가, 고가, 저가, 종가, 거래량) 데이터를 조회합니다.

```
GET /api/v1/financial-v4/time-series
```

### Query Parameters

| Parameter    | Type    | Required | Description                                                |
| ------------ | ------- | -------- | ---------------------------------------------------------- |
| `symbol`     | string  | Yes      | Stock ticker symbol (e.g., "005930")                       |
| `interval`   | string  | No       | Time interval: `1day`, `1week`, `1month` (default: `1day`) |
| `outputsize` | integer | No       | Number of data points (1-5000, default: 30)                |
| `start_date` | string  | No       | Start date filter (YYYY-MM-DD)                             |
| `end_date`   | string  | No       | End date filter (YYYY-MM-DD)                               |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1day&outputsize=100"
```

### Response

```json
{
  "meta": {
    "symbol": "005930",
    "name": "삼성전자",
    "exchange": "KRX",
    "currency": "KRW",
    "interval": "1day",
    "data_points": 100
  },
  "values": [
    {
      "datetime": "2024-01-01T00:00:00",
      "open": 71000.0,
      "high": 72000.0,
      "low": 70500.0,
      "close": 71500.0,
      "volume": 15000000
    },
    {
      "datetime": "2024-01-02T00:00:00",
      "open": 71500.0,
      "high": 72500.0,
      "low": 71000.0,
      "close": 72000.0,
      "volume": 18000000
    }
  ],
  "status": "ok"
}
```

### Response Fields

**meta:**

* `symbol` - Stock ticker symbol
* `name` - Company name
* `exchange` - Exchange code (e.g., KRX)
* `currency` - Trading currency (e.g., KRW)
* `interval` - Time interval of the data
* `data_points` - Number of data points returned

**values (array):**

* `datetime` - ISO 8601 timestamp
* `open` - Opening price
* `high` - Highest price
* `low` - Lowest price
* `close` - Closing price
* `volume` - Trading volume

***

## Profile

기업의 상세 정보, 연락처, 주소, 식별자를 조회합니다.

```
GET /api/v1/financial-v4/profile
```

### Query Parameters

| Parameter | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| `symbol`  | string | Yes      | Stock ticker symbol |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/v1/financial-v4/profile?symbol=005930"
```

### Response

```json
{
  "symbol": "005930",
  "name": "삼성전자",
  "exchange": "KRX",
  "mic_code": "XKRX",
  "sector": "Technology",
  "industry": "Electronics",
  "currency": "KRW",
  "figi_code": "BBG000BCL938",
  "isin": "KR7005930003",
  "cusip": null,
  "description": "삼성전자는 반도체, 디스플레이, IT & 모바일 통신 사업을 영위하는 글로벌 기업입니다.",
  "ceo": "한종희",
  "employees": 270372,
  "website": "https://www.samsung.com",
  "address": "경기도 수원시 영통구 삼성로 129",
  "city": "수원시",
  "state": "경기도",
  "zip_code": "16677",
  "country": "대한민국",
  "phone": "+82-31-200-1114",
  "shares_outstanding": 5969782550,
  "stock_type": "Common Stock",
  "latest_price": 71500.0,
  "market_cap": 426889574325000,
  "status": "ok"
}
```

### Response Fields

**Basic Information:**

* `symbol` - Stock ticker
* `name` - Company name
* `exchange` - Exchange code
* `mic_code` - Market Identifier Code
* `sector` - Business sector
* `industry` - Industry classification

**Identifiers:**

* `currency` - Trading currency
* `figi_code` - Financial Instrument Global Identifier
* `isin` - International Securities Identification Number
* `cusip` - CUSIP number (US securities)

**Company Details:**

* `description` - Business description
* `ceo` - Chief Executive Officer
* `employees` - Number of employees
* `website` - Company website

**Address:**

* `address` - Street address
* `city` - City
* `state` - State/Province
* `zip_code` - Postal code
* `country` - Country
* `phone` - Contact phone

**Share Information:**

* `shares_outstanding` - Total shares
* `stock_type` - Type of stock

**Market Data:**

* `latest_price` - Latest stock price
* `market_cap` - Market capitalization

***

## Fundamentals

재무 비율, 밸류에이션 지표, 성장률 데이터를 조회합니다.

```
GET /api/v1/financial-v4/fundamentals
```

### Query Parameters

| Parameter | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| `symbol`  | string | Yes      | Stock ticker symbol |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/v1/financial-v4/fundamentals?symbol=005930"
```

### Response

```json
{
  "symbol": "005930",
  "name": "삼성전자",
  "exchange": "KRX",
  "currency": "KRW",
  "valuation": {
    "pe_ratio": 15.23,
    "pb_ratio": 1.45,
    "ps_ratio": 1.12,
    "ev_ebitda": 8.45,
    "pfcf_ratio": 12.34
  },
  "growth": {
    "sales_growth_1y": 8.5,
    "sales_growth_3y_cagr": 6.2,
    "sales_growth_5y_cagr": 5.8,
    "operating_income_growth_1y": 12.3,
    "operating_income_growth_3y_cagr": 9.1,
    "operating_income_growth_5y_cagr": 7.5
  },
  "market_data": {
    "market_cap": 426889574325000,
    "latest_price": 71500.0,
    "latest_volume": 15000000,
    "dividend_yield": 2.5,
    "shares_outstanding": 5969782550
  },
  "status": "ok"
}
```

### Response Fields

**valuation (Valuation Ratios):**

* `pe_ratio` - Price-to-Earnings ratio (PER)
* `pb_ratio` - Price-to-Book ratio (PBR)
* `ps_ratio` - Price-to-Sales ratio (PSR)
* `ev_ebitda` - Enterprise Value / EBITDA
* `pfcf_ratio` - Price to Free Cash Flow ratio

**growth (Growth Metrics):**

* `sales_growth_1y` - 1-year sales growth (%)
* `sales_growth_3y_cagr` - 3-year sales CAGR (%)
* `sales_growth_5y_cagr` - 5-year sales CAGR (%)
* `operating_income_growth_1y` - 1-year operating income growth (%)
* `operating_income_growth_3y_cagr` - 3-year operating income CAGR (%)
* `operating_income_growth_5y_cagr` - 5-year operating income CAGR (%)

**market\_data (Market Data):**

* `market_cap` - Market capitalization
* `latest_price` - Latest stock price
* `latest_volume` - Latest trading volume
* `dividend_yield` - Dividend yield (%)
* `shares_outstanding` - Total shares outstanding

***

## Error Responses

All endpoints return standard error responses:

### 404 Not Found

```json
{
  "detail": "Symbol '999999' not found"
}
```

### 422 Validation Error

```json
{
  "detail": [
    {
      "loc": ["query", "outputsize"],
      "msg": "ensure this value is less than or equal to 5000",
      "type": "value_error.number.not_le"
    }
  ]
}
```

### 500 Internal Server Error

```json
{
  "detail": "Internal server error occurred"
}
```

***

## Use Cases

### 1. Building a Stock Price Chart

Get historical price data for visualization:

```bash
# Get 90 days of daily prices
curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1day&outputsize=90"

# Get 52 weeks of weekly prices
curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1week&outputsize=52"
```

### 2. Company Research Dashboard

Combine profile and fundamentals data:

```bash
# Get company information
curl "https://api.alpha-lenz.com/api/v1/financial-v4/profile?symbol=005930"

# Get financial metrics
curl "https://api.alpha-lenz.com/api/v1/financial-v4/fundamentals?symbol=005930"
```

### 3. Multi-Timeframe Analysis

Compare different time periods:

```bash
# Daily data (short-term)
curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1day&outputsize=30"

# Weekly data (medium-term)
curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1week&outputsize=52"

# Monthly data (long-term)
curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1month&outputsize=60"
```

### 4. Historical Period Analysis

Get data for a specific date range:

```bash
# Get Q4 2023 daily prices
curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1day&start_date=2023-10-01&end_date=2023-12-31"
```

***

## Rate Limits

Currently, these endpoints support **trial mode** without rate limits. For production use:

* Standard tier: 100 requests/minute
* Premium tier: 1000 requests/minute
* Enterprise tier: Custom limits

Contact support for API key and tier upgrade.

***

## Comparison with Twelve Data

| Feature              | Twelve Data | Basic Financial API | Notes                   |
| -------------------- | ----------- | ------------------- | ----------------------- |
| Time Series          | ✅           | ✅                   | Similar structure       |
| Company Profile      | ✅           | ✅                   | Full company info       |
| Fundamentals         | ✅           | ✅                   | Valuation & growth      |
| Real-time Quote      | ✅           | ⏳                   | Coming soon             |
| Technical Indicators | ✅           | ❌                   | Use `/stock-prices` API |
| Logo                 | ✅           | ❌                   | Not implemented         |
| WebSocket            | ✅           | ❌                   | Not implemented         |

***

## Related APIs

* [**Stock API**](/ko/api-reference/public-api/stock) - Advanced stock price data with technical indicators
* [**Financial API**](/ko/api-reference/public-api/financial) - Detailed financial statements and company data
* [**News API**](/ko/api-reference/public-api/news) - Company news and market updates

***

## Support

For questions or issues:

* Check [API Documentation](https://github.com/TeamZikto/argo-lng-mono/blob/main/docs/README.md)
* Contact support team
* Visit GitHub repository


# Financial API

기업 정보 및 재무제표 데이터에 액세스합니다.

**필요 스코프:** `read:financial` 또는 `read:all`

## 기업 목록 조회

선택적 필터링과 함께 기업 목록을 조회합니다.

```
GET /api/public/v1/financial/companies
```

### Query Parameters

| 파라미터      | 타입      | 설명                         |
| --------- | ------- | -------------------------- |
| `search`  | string  | 이름 또는 심볼로 검색               |
| `sector`  | string  | 섹터별 필터링                    |
| `country` | string  | 국가별 필터링                    |
| `limit`   | integer | 페이지당 결과 수 (1-100, 기본값: 50) |
| `offset`  | integer | 페이지네이션 오프셋 (기본값: 0)        |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies?search=samsung&limit=10" \
     -H "X-API-Key: ak_your_key"
```

### 응답

```json
{
  "companies": [
    {
      "company_id": 1,
      "symbol": "005930",
      "name": "Samsung Electronics",
      "alias_name": "삼성전자",
      "exchange": "KRX",
      "sector": "Technology",
      "country": "KR"
    }
  ],
  "total": 1
}
```

***

## 심볼로 기업 조회

주식 심볼로 기업 정보를 조회합니다.

```
GET /api/public/v1/financial/companies/{symbol}
```

### Path Parameters

| 파라미터     | 타입     | 설명                  |
| -------- | ------ | ------------------- |
| `symbol` | string | 주식 심볼 (예: "005930") |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies/005930" \
     -H "X-API-Key: ak_your_key"
```

### 응답

```json
{
  "company_id": 1,
  "symbol": "005930",
  "name": "Samsung Electronics",
  "alias_name": "삼성전자",
  "exchange": "KRX",
  "sector": "Technology",
  "country": "KR"
}
```

***

## 기업 재무제표 조회

기업의 재무제표 시계열 데이터를 조회합니다.

```
GET /api/public/v1/financial/companies/{symbol}/financials
```

### Path Parameters

| 파라미터     | 타입     | 설명    |
| -------- | ------ | ----- |
| `symbol` | string | 주식 심볼 |

### Query Parameters

| 파라미터     | 타입      | 설명                                                |
| -------- | ------- | ------------------------------------------------- |
| `period` | string  | "Annual" (연간) 또는 "Quarterly" (분기) (기본값: "Annual") |
| `years`  | integer | 조회할 연도 수 (1-20, 기본값: 5)                           |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies/005930/financials?period=Annual&years=5" \
     -H "X-API-Key: ak_your_key"
```

### 응답

```json
{
  "statements": [
    {
      "fiscal_date": "2023-12-31",
      "year": 2023,
      "quarter": null,
      "period": "Annual",
      "currency": "KRW",
      "sales": 258935000000000,
      "gross_profit": 85000000000000,
      "operating_income": 6570000000000,
      "net_income": 15490000000000,
      "total_assets": 455000000000000,
      "total_liabilities": 120000000000000,
      "total_shareholders_equity": 335000000000000,
      "operating_cash_flow": 50000000000000,
      "free_cash_flow": 30000000000000
    }
  ]
}
```

### 재무제표 필드

**손익계산서 (Income Statement):**

* `sales`, `cost_of_goods`, `gross_profit` - 매출, 매출원가, 매출총이익
* `operating_income`, `net_income` - 영업이익, 당기순이익
* `ebit`, `ebitda` - 법인세차감전영업이익, EBITDA
* `eps_basic`, `eps_diluted` - 기본주당이익, 희석주당이익

**재무상태표 (Balance Sheet):**

* `total_assets`, `total_current_assets`, `total_non_current_assets` - 자산총계, 유동자산, 비유동자산
* `total_liabilities`, `total_current_liabilities`, `total_non_current_liabilities` - 부채총계, 유동부채, 비유동부채
* `total_shareholders_equity` - 자본총계
* `cash`, `inventory`, `accounts_receivable` - 현금, 재고자산, 매출채권

**현금흐름표 (Cash Flow):**

* `operating_cash_flow`, `investing_cash_flow`, `financing_cash_flow` - 영업활동현금흐름, 투자활동현금흐름, 재무활동현금흐름
* `free_cash_flow`, `capital_expenditures` - 잉여현금흐름, 자본적지출


# News API

뉴스 기사 및 시장 업데이트에 액세스합니다.

**필요 스코프:** `read:news` 또는 `read:all`

## 뉴스 기사 목록 조회

선택적 필터링과 함께 뉴스 기사를 조회합니다.

```
GET /api/public/v1/news/articles
```

### Query Parameters

| 파라미터       | 타입      | 설명                           |
| ---------- | ------- | ---------------------------- |
| `skip`     | integer | 건너뛸 항목 수 (기본값: 0)            |
| `limit`    | integer | 반환할 최대 항목 수 (1-100, 기본값: 50) |
| `category` | string  | 카테고리별 필터링                    |
| `priority` | integer | 우선순위별 필터링 (1=높음, 2=중간, 3=낮음) |

### Headers

| 헤더         | 설명                              |
| ---------- | ------------------------------- |
| `x-locale` | 언어 코드: ko, en, ja, zh (기본값: en) |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/news/articles?limit=20&category=market_move" \
     -H "X-API-Key: ak_your_key" \
     -H "x-locale: ko"
```

### 응답

```json
{
  "articles": [
    {
      "id": 123,
      "title": "Major Market Movement: Tech Stocks Rally",
      "summary": "Technology stocks led the market rally today...",
      "category": "market_move",
      "priority": 1,
      "source_url": "https://example.com/article",
      "published_at": "2024-01-15T14:30:00Z",
      "created_at": "2024-01-15T14:35:00Z"
    }
  ],
  "total": 150,
  "skip": 0,
  "limit": 20
}
```

***

## 뉴스 기사 조회

특정 뉴스 기사의 상세 정보를 조회합니다.

```
GET /api/public/v1/news/articles/{article_id}
```

### Path Parameters

| 파라미터         | 타입      | 설명       |
| ------------ | ------- | -------- |
| `article_id` | integer | 뉴스 기사 ID |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/news/articles/123" \
     -H "X-API-Key: ak_your_key" \
     -H "x-locale: en"
```

### 응답

```json
{
  "id": 123,
  "title": "Major Market Movement: Tech Stocks Rally",
  "summary": "Technology stocks led the market rally today...",
  "ai_angle": "AI analysis perspective on the market movement...",
  "risk": "Key risks to watch...",
  "category": "market_move",
  "priority": 1,
  "source_url": "https://example.com/article",
  "trigger": [
    {
      "topic": "Tech Stocks",
      "sentiment": "positive"
    }
  ],
  "published_at": "2024-01-15T14:30:00Z",
  "created_at": "2024-01-15T14:35:00Z"
}
```

***

## 기사 전문 조회

뉴스 기사의 전체 콘텐츠를 조회합니다.

```
GET /api/public/v1/news/articles/{article_id}/content
```

### Path Parameters

| 파라미터         | 타입      | 설명       |
| ------------ | ------- | -------- |
| `article_id` | integer | 뉴스 기사 ID |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/news/articles/123/content" \
     -H "X-API-Key: ak_your_key" \
     -H "x-locale: ko"
```

### 응답

```json
{
  "id": 123,
  "title": "Major Market Movement: Tech Stocks Rally",
  "content_type": "html",
  "full_content": "<div>Full article content here...</div>"
}
```

### 카테고리

사용 가능한 뉴스 카테고리:

| 카테고리          | 설명             |
| ------------- | -------------- |
| `eod_summary` | 장 마감 시장 요약     |
| `fed_policy`  | 연방준비제도 정책 업데이트 |
| `market_move` | 주요 시장 움직임      |
| `earnings`    | 실적 발표          |
| `breaking`    | 속보             |

### 언어 지원

`x-locale` 헤더를 사용하여 현지화된 콘텐츠를 받을 수 있습니다:

* `ko` - 한국어
* `en` - 영어 (기본값)
* `ja` - 일본어
* `zh` - 중국어


# Research API

증권사 리서치 리포트에 액세스합니다.

**필요 스코프:** `read:research` 또는 `read:all`

## 리서치 리포트 목록 조회

필터링 및 페이지네이션과 함께 리서치 리포트를 조회합니다.

```
GET /api/public/v1/research/reports
```

### Query Parameters

| 파라미터                | 타입      | 설명                                                   |
| ------------------- | ------- | ---------------------------------------------------- |
| `page`              | integer | 페이지 번호 (기본값: 1)                                      |
| `page_size`         | integer | 페이지당 항목 수 (1-100, 기본값: 20)                           |
| `securities_firm`   | string  | 증권사별 필터링                                             |
| `stock_name`        | string  | 종목명별 필터링                                             |
| `report_type`       | string  | 유형별 필터링: "company\_analysis" 또는 "industry\_analysis" |
| `industry_category` | string  | 산업 카테고리별 필터링                                         |
| `start_date`        | date    | 시작 날짜 필터 (YYYY-MM-DD)                                |
| `end_date`          | date    | 종료 날짜 필터 (YYYY-MM-DD)                                |
| `title`             | string  | 리포트 제목에서 검색                                          |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/research/reports?stock_name=삼성전자&page_size=10" \
     -H "X-API-Key: ak_your_key"
```

### 응답

```json
{
  "reports": [
    {
      "id": 456,
      "title": "Samsung Electronics - 4Q23 Preview",
      "report_date": "2024-01-10",
      "report_type": "company_analysis",
      "securities_firm": "미래에셋증권",
      "stock_name": "삼성전자",
      "industry_category": "반도체",
      "cdn_url": "https://static.alpha-lenz.com/reports/2024/01/456.pdf"
    }
  ],
  "total": 125,
  "page": 1,
  "page_size": 10,
  "has_next": true
}
```

***

## 리서치 리포트 조회

특정 리서치 리포트의 상세 정보를 조회합니다.

```
GET /api/public/v1/research/reports/{report_id}
```

### Path Parameters

| 파라미터        | 타입      | 설명         |
| ----------- | ------- | ---------- |
| `report_id` | integer | 리서치 리포트 ID |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/research/reports/456" \
     -H "X-API-Key: ak_your_key"
```

### 응답

```json
{
  "id": 456,
  "title": "Samsung Electronics - 4Q23 Preview",
  "report_date": "2024-01-10",
  "report_type": "company_analysis",
  "securities_firm": "미래에셋증권",
  "stock_name": "삼성전자",
  "industry_category": "반도체",
  "s3_key": "reports/2024/01/456.pdf",
  "cdn_url": "https://static.alpha-lenz.com/reports/2024/01/456.pdf"
}
```

### 리포트 다운로드

`cdn_url` 필드를 사용하여 PDF 리포트를 다운로드합니다:

```bash
curl -O "https://static.alpha-lenz.com/reports/2024/01/456.pdf"
```

### 리포트 유형

| 유형                  | 설명       |
| ------------------- | -------- |
| `company_analysis`  | 개별 기업 분석 |
| `industry_analysis` | 산업/섹터 분석 |

### 페이지네이션

`page`와 `page_size`를 사용하여 페이지네이션을 구현합니다. `has_next`를 확인하여 추가 결과가 있는지 확인하세요:

```bash
# 첫 페이지
GET /research/reports?page=1&page_size=20

# 두 번째 페이지
GET /research/reports?page=2&page_size=20
```

### 필터링 예시

**증권사별:**

```
GET /research/reports?securities_firm=미래에셋증권
```

**날짜 범위별:**

```
GET /research/reports?start_date=2024-01-01&end_date=2024-01-31
```

**산업별:**

```
GET /research/reports?industry_category=반도체
```

**제목 검색:**

```
GET /research/reports?title=실적
```


# Stock API

OHLCV (시가, 고가, 저가, 종가, 거래량)를 포함한 주가 데이터에 액세스합니다.

**필요 스코프:** `read:stock` 또는 `read:all`

## 주가 조회

종목의 OHLCV 주가 데이터를 조회합니다.

```
GET /api/public/v1/stock/prices/{symbol}
```

### Path Parameters

| 파라미터     | 타입     | 설명                  |
| -------- | ------ | ------------------- |
| `symbol` | string | 주식 심볼 (예: "005930") |

### Query Parameters

| 파라미터       | 타입      | 설명                                             |
| ---------- | ------- | ---------------------------------------------- |
| `interval` | string  | 시간 간격: "1day", "1week", "1month" (기본값: "1day") |
| `limit`    | integer | 데이터 포인트 수 (1-500, 기본값: 100)                    |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/stock/prices/005930?interval=1day&limit=30" \
     -H "X-API-Key: ak_your_key"
```

### 응답

```json
{
  "symbol": "005930",
  "company_name": "Samsung Electronics",
  "interval": "1day",
  "data": [
    {
      "datetime": "2024-01-15T00:00:00",
      "open": 71500.0,
      "high": 72000.0,
      "low": 71000.0,
      "close": 71800.0,
      "volume": 15000000
    },
    {
      "datetime": "2024-01-16T00:00:00",
      "open": 71800.0,
      "high": 72500.0,
      "low": 71500.0,
      "close": 72200.0,
      "volume": 12500000
    }
  ],
  "count": 30
}
```

***

## 주가 히스토리 조회

날짜 필터링 및 페이지네이션과 함께 과거 주가 데이터를 조회합니다.

```
GET /api/public/v1/stock/prices/{symbol}/history
```

### Path Parameters

| 파라미터     | 타입     | 설명    |
| -------- | ------ | ----- |
| `symbol` | string | 주식 심볼 |

### Query Parameters

| 파라미터         | 타입      | 설명                               |
| ------------ | ------- | -------------------------------- |
| `interval`   | string  | 시간 간격: "1day", "1week", "1month" |
| `start_date` | string  | 시작 날짜 필터 (YYYY-MM-DD)            |
| `end_date`   | string  | 종료 날짜 필터 (YYYY-MM-DD)            |
| `limit`      | integer | 페이지당 결과 수 (1-1000, 기본값: 100)     |
| `offset`     | integer | 페이지네이션 오프셋 (기본값: 0)              |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/stock/prices/005930/history?start_date=2024-01-01&end_date=2024-01-31&limit=100" \
     -H "X-API-Key: ak_your_key"
```

### 응답

```json
{
  "symbol": "005930",
  "company_name": "Samsung Electronics",
  "interval": "1day",
  "data": [
    {
      "datetime": "2024-01-02T00:00:00",
      "open": 70000.0,
      "high": 71000.0,
      "low": 69500.0,
      "close": 70500.0,
      "volume": 18000000
    }
  ],
  "count": 22,
  "has_more": false
}
```

### OHLCV 필드

| 필드         | 타입      | 설명            |
| ---------- | ------- | ------------- |
| `datetime` | string  | ISO 8601 날짜시간 |
| `open`     | float   | 시가            |
| `high`     | float   | 고가            |
| `low`      | float   | 저가            |
| `close`    | float   | 종가            |
| `volume`   | integer | 거래량           |

### 페이지네이션

`offset`과 `limit`을 사용하여 페이지네이션을 구현합니다. `has_more`를 확인하여 추가 결과가 있는지 확인하세요:

```bash
# 첫 페이지
GET /stock/prices/005930/history?limit=100&offset=0

# 두 번째 페이지
GET /stock/prices/005930/history?limit=100&offset=100
```


# Page