API 参考
REST 端点、credits 计量与鉴权
wordradar API（Phase 0）
Base URL：https://YOUR_DOMAIN（本地 http://localhost:8080）
鉴权与计量
- API key：
wr_开头（明文只创建时返回一次）。account 面板已上线（登录 → 用户菜单 → API Keys）；也可直接调接口：POST /api/v1/me/keys（body{name?}，默认 "default"、截 40 字）→ 返回{key}；GET列表；DELETE ?id=<uuid>吊销 - 请求头：
Authorization: Bearer wr_...（或浏览器登录 session） - 限流：每用户 60s 窗口 120 次（/api/v1 与 /mcp 共享），超限 429+Retry-After
- 计量：每端点标注 credits；扣费顺序=校验→查询成功→扣费（失败/400/503 不扣）；余额不足 402。
ledger/pulse免费 - credits 来源：注册赠送已接（
WORDRADAR_REG_CREDITS，deploy.sh 生产默认 50）、每日签到默认关（admin 后台两键）；内测期补发走 admin，详见 docs/pricing.md - 参数校验失败返回 400（如
type不在枚举内），不扣费
REST 端点
| 端点 | 方法 | credits | 参数 |
|---|---|---|---|
/api/v1/ledger/pulse | GET | 免费 | —（最新期新词数） |
/api/v1/ledger/words | GET | 1 | type=新词|二次爆火|长期大词|存量、direction=AI|游戏|工具、site=站名（站群匹配）、limit≤200 |
/api/v1/kd/serp | POST | 1 | body {keyword?, results}（results 为 SERP 数组）（SERP 前十，喂入打分） |
/api/v1/sites/latest | GET | 1 | hosting=free|custom|all、min_points、limit |
/api/v1/trends/:keyword | GET | 2 | 路径参数=关键词（读采集缓存，fetched_at 即新鲜度；无缓存时 items 为空） |
/api/v1/domains/:domain/timeline | GET | 2 | RDAP+Wayback 实时 |
/api/v1/stripe/leaderboard | GET | 1 | month=YYYYMM（缺省最新期） |
/api/v1/me/keys | GET/POST/DELETE | — | key 管理（session 登录） |
/api/v1/config | GET | 免费 | 公开开关（invite_required/reg_credits/email_verification/social） |
/api/healthz | GET | — | 健康+数据新鲜度 |
/ingest/bundle | POST | — | 仅采集机（INGEST_TOKEN） |
MCP（主分发面）
端点: POST https://<域名>/mcp （streamable HTTP；GET→405，通知→202，DELETE→204）
tools: ledger_pulse / ledger_words / proxy_kd_score / site_radar_latest
/ trends_rising / domain_timeline / stripe_leaderboard / get_usage客户端配置（Claude/Cursor 等）：
{ "mcpServers": { "wordradar": {
"type": "http", "url": "https://<域名>/mcp",
"headers": { "Authorization": "Bearer wr_..." } } } }口径注（诚实声明）
- proxy-kd 权重未校准（calibrate 待拟合），只做相对比较；判定线
<20极易 /<40可打 /<60中等 />=60难 - trends 是被动截获的采集缓存，非实时 API
- ledger 首现=suggest 语料第一次出现，非趋势口径；类型判定
<3期降级二分
完整评分权重与数据语义见数据方法论。