1# Operating the FinData client23- **Key**: `FINDATA_API_KEY` (value) or `FINDATA_API_KEY_FILE` (path). The owner's Claude Code key file is4 `~/Desktop/Cluster/secrets/findata/api-key-claude-code.txt`; a least-privilege key (read:market, export) is preferable5 for benchmarks. The client keeps the key in memory only; logs redact `Bearer …`; manifests record a 12-hex6 `key_fingerprint` (SHA-256 prefix), never the key.7- **Base URL**: `FINDATA_URL` (default `https://findata.spboucher.ai/api/v1`); from M3U96a use `http://127.0.0.1:8600`.8- **Cache**: `RAID_CACHE_DIR` (default `datasets/cache`, git-ignored). Bars pages are stored as CSV + `.meta.json`9 (sha256, dataset version, request ids, fetched_at); exports as Parquet + `.meta.json`. A cache hit is only used when10 the file's SHA-256 matches its manifest. Cache keys include the dataset version when pinned (`version=`); otherwise11 "latest" at fetch time is recorded in the manifest — experiments must pin the version they report.12- **Limits honoured**: 600 req/min (token bucket 5 req/s, burst 10, `RAID_FINDATA_RPS` to lower it), 1m ≤ 31 days per13 call (chunked), 5m ≤ 186 d, 1d ≤ 10 y, pages ≤ 10 000 rows via `X-Next-Cursor`, exports ≤ 12 y per request (caller14 chunks), query ≤ 100 000 rows / 30 s. Retries: 429/502/503/504/network with exponential backoff (1→30 s), honouring15 `Retry-After`, 5 retries.16- **Offline / CI**: `RAID_OFFLINE=1` refuses any network call (cache only); CI uses synthetic fixtures. Live tests are17 opt-in: `RAID_LIVE=1 FINDATA_API_KEY_FILE=… ./raid_tests "[live]"`.18- **Conventions verified live (2026-11-02, AAPL 2024-11-25…29)**: pages == export rows; `expected_bars` == RAID calendar19 (391 / 211); RAID extended-policy 1m→5m aggregation == FinData derived 5m on the regular window (280/280 bars,20 OHLCV exact); RAID regular-policy closing bin = the 16:00 print only (FinData's derived 16:00 bin adds 16:01–16:0421 post-close minutes: volume and close differ in that single bin per session).22- **License**: FirstRate private use — cache directories must not be shared or committed; only aggregates are published.23- CLI: `raid data catalog | health | sessions SYM --start --end | coverage [--min-sessions N] | bars SYM --start --end24 [--interval] [--adjustment] [--out csv] | export SYMS --start --end [--dataset] [--out parquet] | fund ENTITY --as-of ISO | query "SQL"`.25