# kimpremium API — Agent Brief

> Public, read-only, **no API key**, CORS-enabled. Korean retail-leverage /
> "kimchi premium" monitor built on official daily statistics
> (KOFIA FreeSIS · KSD SEIBro · Naver Finance).
> Machine manifest: `https://kimpremium.com/api/agent.json` · OpenAPI: `https://kimpremium.com/api/openapi.json`

## What this tracks
The **leverage thermometer** — how much embedded leverage Korean retail has piled
on, = (margin financing balance + leveraged-ETF cumulative net creation at cost)
/ investor cash deposits, anchored to 2024-01-02. Plus the R2 financing ratio,
forced-liquidation (misu / 반대매매) stress, and index context (KOSPI, S&P 500).

## The one endpoint you need
`GET https://kimpremium.com/api/v1/summary` -> JSON. Key field is `alert`:
```json
{
  "asof": "YYYYMMDD",
  "leverage_thermometer": { "value": 50.2, "unit": "percent", "anchor": "2024-01-02" },
  "alert": {
    "level": "critical",
    "value": 50.2,
    "thresholds": { "warning": 40, "critical": 45 },
    "message": "KR杠杆温度计 50.2% — 高位报警(>45) · ETF修正Δ+..pp"
  },
  "freshness": { "stale_days": 1 }
}
```

## Alert rule
- `level == "critical"`  -> thermometer **> 45%** (high-leverage warning)
- `level == "warning"`   -> thermometer **> 40%**
- `level == "normal"`    -> **<= 40%**
Fire when `level == "critical"`, or whenever `level` **changes** from your last poll.
Also flag `freshness.stale_days > 10` (pipeline may be stuck).

## All endpoints
| Endpoint | Purpose |
| --- | --- |
| `GET /api/v1/summary` | 当前状态 + 告警等级（agents 轮询这个） |
| `GET /api/v1/health` | 存活 + 数据新鲜度（stale_days, level） |
| `GET /api/v1/meta` | KPI 快照 + 数据范围（meta.json） |
| `GET /api/v1/thermo` | 杠杆温度计明细 + ETF universe（约 38 只） |
| `GET /api/v1/series` | R2 全历史 7,100+ 交易日；?fields=d,r2&since=YYYYMMDD 可裁剪 |
| `GET /data/{series,meta,etf}.json` | 前端原始载荷（向后兼容） |

## Monitoring recipes
**Avibe harness (recommended on this machine):**
```bash
vibe watch add --name kimpremium-thermo --interval 1d \
  --message 'KR 杠杆温度计进入 critical，见 https://kimpremium.com' \
  -- bash -c 'curl -s https://kimpremium.com/api/v1/summary | jq -e ".alert.level==\"critical\""'
```
**Anywhere (cron + jq):**
```bash
curl -s https://kimpremium.com/api/v1/summary \
  | jq '{asof, level: .alert.level, thermo: .alert.value, msg: .alert.message}'
```
Poll **once a day** — data refreshes ~3x/day (KST) and rarely moves intraday.

_Research visualization of public market statistics. Not investment advice._