# 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, "daily_full_refresh_beijing": "14:16" }
}
```

## When to poll
Data refreshes **3x/day, Beijing time (UTC+8): ~09:40 / ~14:16 / ~21:30**. The **14:16**
run is the day's fullest — KOFIA posts T+2 credit around then. Poll **once a day, shortly
after 14:20 Beijing (06:20 UTC)**. The `generated` field is Beijing time. Rarely moves intraday.

## 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` | current state + alert level (agents poll this) |
| `GET /api/v1/health` | liveness + freshness (stale_days, level) |
| `GET /api/v1/meta` | KPI snapshot + data range (meta.json) |
| `GET /api/v1/thermo` | thermometer detail + ETF universe (~38) |
| `GET /api/v1/series` | R2 full history 7,100+ days; ?fields=d,r2&since=YYYYMMDD to filter |
| `GET /data/{series,meta,etf}.json` | raw front-end payloads (backward compat) |

## Monitoring recipe (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, after 14:20 Beijing (06:20 UTC)** — see "When to poll" above.

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