From 880c2ecae3d395d92a5b65b5e8a325d97b1b4618 Mon Sep 17 00:00:00 2001 From: jaxperro Date: Thu, 16 Jul 2026 23:32:33 -0400 Subject: [PATCH] =?UTF-8?q?value:=20developer=20README=20+=20architecture-?= =?UTF-8?q?table=20row=20=E2=80=94=20silo=20rules,=20ops,=20verdict=20crit?= =?UTF-8?q?eria?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- README.md | 1 + value/README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 value/README.md diff --git a/README.md b/README.md index 1658cc6d..1d8ee568 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ Three deployed pieces + one static dashboard: | **daily pipeline** (`live/daily.sh`) | this Mac, launchd **08:00** (a `pmset repeat wakeorpoweron` RTC wake at **07:58** makes this run on time even from sleep — set 2026-07-08, undo with `sudo pmset repeat cancel`; job wrapped in `caffeinate -i` so mid-run idle-sleep can't kill it. Heads-up: the wake fires even lid-closed-in-a-bag — cancel it if the Mac travels) | refresh the bet cache → 5-gate skill scan → fee-aware sharp selection → conviction floors → backtest book → publish JSON feeds to GitHub | | **copybot worker** (`copybot.py` via `host/start.sh`) | **Fly.io app `wwf-copybot`, region `arn` (Stockholm), 24/7** — migrated off Railway 2026-07-06: Railway ran it in a US region, which Polymarket's IP geoblock would 403 the moment orders got real; Stockholm is unrestricted AND ~25ms from the CLOB's eu-west-2 primaries. Every boot self-checks the geo-gate (`host/geocheck.py`) and verifies the clone against `git ls-remote` (stale-replica guard) | **T0 = the RTDS trade stream** (gotcha 18): every platform trade, wallet-attributed, **~1s detection** (measured p50 0.8s over 22k msgs), silent-stale guard force-reconnects a quiet socket. Backstops: the Alchemy address-activity webhook (~3s, `POST /alchemy`, signature-verified — **T0b chain seed** 2026-07-14: its tx hashes decode straight from the receipt's OrderFilled logs when the data-api indexer lags, so RTDS-silent markets still copy at push speed), a 5-min backstop poll, and the reconcile janitor. Per-wallet **trade cursor** paginates the activity feed so clip bursts can't scroll past a fetch (H3). 60s heartbeat settles/publishes; paper-copies with real fees/lag/slippage AND live-FAK thin-book reality (**paper FAK parity** 2026-07-16: a quote with no ask inside the protected band books a MISS, not a fill — keeps the live-vs-paper per-signal ratio honest; `live/edge.py` turns it into the daily bankroll-decision verdict in `history/edge.csv` + the Discord digest footer); commits its book back to the repo | | **REAL-MONEY worker** (same code, `COPYBOT_ROLE=live`) | **Fly.io app `wwf-copybot-live`, `arn`, 24/7, ARMED 2026-07-10** — separate app so the two books never share a process, state file, or failure mode. Trades the signer's **Deposit Wallet** `0x455e…45a1` (pUSD collateral) via the unified SDK (`polymarket-client`) | Same T0 RTDS detection (`RTDS_DETECT=1`) + Alchemy/poll backstops; **own-fill push** via the CLOB user channel (`userws` in the heartbeat) makes in-play pending holds adopt the moment they match — ws events only *trigger* the resolver, `get_order` stays the arbiter (gotcha 17). Paper-parity sizing (4% of equity, $1 venue floor, no price floor, hard caps retired — the **depth gate** is the scaling rail: skip spread>0.08 or ask5c<$50, stake ≤10% of 5c depth). Every placement/exit/settle pings Discord. Disarm: `flyctl secrets unset LIVE_CONFIRM -a wwf-copybot-live` | +| **VALUE bot** (separate experiment, [`value/README.md`](value/README.md)) | **Fly.io app `wwf-valuebot`, `arn`, 24/7, PAPER** — a hard SILO: own code (`value/valuebot.py`, zero copybot imports), own state/feed, own image, no shared wallet ever | Systematically buys sub-2¢ contracts (the calibration study's one underpriced bucket — [`value/PLAN.md`](value/PLAN.md)); honest FAK fill model, chain-truth settles, $1 tickets, event cap 1. Verdict at ~2k resolved tickets vs a ~1.05% break-even hit rate | | **Discord digest** (`live/discord_daily.py`) | end of the daily pipeline | one message/day: the sharp list with profile links + 30-day conviction stats (per-trade pings retired 2026-07-04 for PAPER; the LIVE book pings every real placement/exit/settle) | | **dashboard** | [jaxperro.com/trading](https://jaxperro.com/trading) + [jaxperro.com/live](https://jaxperro.com/live) (static, in the `jaxperro` repo) | `/trading` renders the paper book, backtest book and sharp table; `/live` is the REAL MONEY page (reads `live/copybot_live_real.json` — live since 2026-07-10). Both pages share `trading/copybot-section.js` — one renderer, no drift | diff --git a/value/README.md b/value/README.md new file mode 100644 index 00000000..ad9422d0 --- /dev/null +++ b/value/README.md @@ -0,0 +1,84 @@ +# VALUE — the undervalued-market paper bot + +A **silo'd** experiment: can systematically buying sub-2¢ Polymarket contracts +beat their price? Research says yes on paper (~1.24x gross); this bot exists +to find out if the fills are real. It shares **no code path, state, app, or +wallet** with the copy trader — see *Silo rules* before touching anything. + +## Why this exists (30-second version) + +A calibration study over 13.5M trusted resolved bets (2026-07-17, details in +[PLAN.md](PLAN.md)) found Polymarket well-calibrated above 60¢, longshots +2–60¢ systematically OVERpriced — and the tail **below 2¢ UNDERpriced**: +entries at an average 0.82¢ resolved winners 1.02% of the time (1.24x, ≈+20%/$ +net of fees, z≈+12 market-clustered). The effect survives excluding skilled +wallets and refunds, and concentrates near expiry. History can't prove the +asks are actually fillable — that's this bot's one job. + +## How it works (valuebot.py, single file, pure stdlib) + +Every 5 minutes: +1. **Scan** gamma for active markets, soonest-ending first (the edge lives + near expiry; gamma 422s past offset ~2000, which conveniently caps the + scan to exactly that window). Any outcome marked ≤ 2¢ is a candidate. +2. **Fill or honest miss**: fetch the REAL CLOB ask ladder; a $1 FAK either + fully fills inside `min(2¢, best_ask × 1.05)` — the same protected band + the live copy executor sends — or logs a MISS. No phantom fills, ever + (the 2026-07-16 paper-parity lesson, inherited from birth). +3. **Guards**: flat $1/ticket (venue minimum = reality), event cap 1 + (correlated dust resolves together), 300-ticket portfolio cap, 6h + re-check cooldown per token, entry taker fee by category. +4. **Settle at chain truth**: payout vectors from the CTF contract + (`payoutNumerators`) — wins pay 1.0, **0.5 refunds are real**, losses 0. + Never trusts CLOB winner flags or price marks. +5. **Publish**: state + feed + fills committed back to this repo + (`valuebot: paper feed [skip ci]`), same pull-rebase-push discipline as + the copy books. + +## The verdict (what decides paper → real money) + +Break-even hit rate ≈ 1.05% at 1¢ entries. Needs ~2,000 resolved tickets +(2–6 weeks). Pre-registered kill criteria (PLAN.md): fill rate <30%, or +realized multiple <1.1x after 2k tickets, or can't deploy >$50/week. Track: +`stats` + `realized_multiple` + `fill_rate` in the feed. Early losses are +EXPECTED — at ~1% hit rate the first hundreds of tickets are mostly Ls; the +multiple is meaningless until refunds/wins accumulate. + +## File map + +| file | what | +|---|---| +| `valuebot.py` | the whole bot — scan, fill model, settle, publish | +| `PLAN.md` | research findings, strategy spec, rollout gates | +| `valuebot_state.json` | the book (bot-committed; don't hand-edit while it runs) | +| `valuebot.json` | published feed (future jaxperro.com/value reads this) | +| `valuebot_fills.jsonl` | append-only fill ledger | +| `start.sh` | Fly boot: clone main, ls-remote clone-guard, exec bot | +| `fly.Dockerfile` | python:3.12-slim + git; NO pip deps by design | +| `../fly.value.toml` | app `wwf-valuebot` (arn); **no http_service** on purpose — nothing auto-restarts it under a state edit (README gotcha 15) | +| `../tests/test_valuebot.py` | 6 stub tests — fill band, thin-miss, event cap, cooldown, settle math | + +## Ops + +```bash +python3 tests/test_valuebot.py # no-network stub tests +python3 value/valuebot.py --once # one real scan cycle, no publishing +flyctl logs -a wwf-valuebot --no-tail # watch cycles ("book: cash …") +flyctl deploy --remote-only -c fly.value.toml --ha=false -a wwf-valuebot + # image change (start.sh/Dockerfile); + # code changes need only a machine restart +``` + +Secrets on `wwf-valuebot`: `ALCHEMY_RPC_URL` (chain settles), +`GITHUB_TOKEN` (fine-grained PAT, contents-RW this repo — state durability + +feed). Without the token the bot trades but rewinds to the last committed +state on restart (it warns at boot). + +## Silo rules (do not break these) + +1. Nothing under `value/` may import `copybot.py` or `copytrade.py` — the + ~60 lines of book/fee/payout helpers are duplicated here ON PURPOSE. + Read-only research libs (`trust`, `smart_money`, `payouts`) are allowed. +2. Never share: state files, feeds, Fly apps, webhooks, or (when real money + ever comes) the wallet. The copy trader must be un-affectable from here. +3. `bankroll`/stake/cap changes and the paper→real gate are the USER's call.