hunch-cup 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,7 @@
 # hunch-cup
 
 One-line CLI + typed SDK to play the **Hunch Cup** — a risk-free, **paper-trading**
-prediction-market tournament. Claim **1,000 $pHUNCH** (paper money, zero real-funds
+prediction-market tournament. Claim **10,000 $pHUNCH** (paper money, zero real-funds
 risk), trade the live Hunch catalog, run a 24/7 agent, and climb a public leaderboard
 scored on realized PnL. The top 50 wallets split a real **$5,000**.
 
@@ -11,7 +11,7 @@ scored on realized PnL. The top 50 wallets split a real **$5,000**.
 ## CLI
 
 ```bash
-# 1. Generate a wallet and claim 1,000 $pHUNCH (prints a private key — save it!)
+# 1. Generate a wallet and claim 10,000 $pHUNCH (prints a private key — save it!)
 npx hunch-cup wallet new
 
 export HUNCH_CUP_PRIVATE_KEY=0x...   # the key it printed
@@ -30,13 +30,32 @@ npx hunch-cup trade <slug> yes 25
 
 # 4. Or let an agent do it — momentum | contrarian | news-reactive
 npx hunch-cup run momentum 25            # dry-run (simulated)
-npx hunch-cup run contrarian 25 --live   # actually place trades
+npx hunch-cup run contrarian 25 --live   # one round, actually place trades
 
+# 24×7, built in — no shell loop needed. It reads your balance first, skips
+# markets you already hold, caps each round to a fraction of your bankroll, and
+# stops before it goes broke (the old `while true` loop went insolvent in ~20m).
+npx hunch-cup run momentum 25 --live --loop --interval 300
+
+npx hunch-cup positions   # balance + open/realized positions (watch for insolvency)
+npx hunch-cup balance     # just the $pHUNCH number
 npx hunch-cup board
 ```
 
+### Run a fleet (one person, many agents)
+
+```bash
+npx hunch-cup fleet new 10        # mint 10 wallets, claim each, save to ~/.hunch-cup/fleet.json
+npx hunch-cup fleet run momentum  # run all 10 concurrently, 24×7 (each with a strategy)
+npx hunch-cup fleet board         # every wallet's live rank
+```
+
+`fleet new` assigns a rotating strategy (momentum / contrarian / news-reactive) per
+wallet so a demo fleet is visibly diverse. Keys live only in the local file.
+
 Env: `HUNCH_CUP_PRIVATE_KEY`, `HUNCH_CUP_BASE_URL` (default `https://www.playhunch.xyz`),
-`HUNCH_CUP_SIZE` (default 25), `HUNCH_CUP_SENTIMENT` (for `news-reactive`).
+`HUNCH_CUP_SIZE` (default 25), `HUNCH_CUP_SENTIMENT` (for `news-reactive`),
+`HUNCH_CUP_FLEET_FILE` (default `~/.hunch-cup/fleet.json`).
 
 ## SDK
 
@@ -45,15 +64,24 @@ import { CupClient, fromPrivateKey } from "hunch-cup";
 
 const client = new CupClient({ signer: fromPrivateKey(process.env.HUNCH_CUP_PRIVATE_KEY!) });
 
-await client.createWallet();                       // claim 1,000 $pHUNCH (once)
-const markets = await client.listMarkets();
+await client.createWallet();                       // claim 10,000 $pHUNCH (once)
+const markets = await client.listMarkets(25, 0);   // paginated: limit, offset
 await client.simulateTrade(markets[0].slug, "yes", 25);   // dry run, no signature
 await client.trade({ slug: markets[0].slug, side: "yes", sizePhunch: 25 }); // signed
-await client.getPositions();
+await client.getWallet();                          // balance + positions (typed)
 await client.getLeaderboard({ wallet: client.address });
 
-// Built-in strategy templates (pure deciders, you control execution):
+// Built-in strategy templates (pure deciders, you control execution). N-way
+// markets (ladders, THE FLIP) pick a real outcome key, never phantom yes/no.
 await client.runStrategy({ strategy: "momentum", sizePhunch: 25, live: true });
+
+// Bankroll-managed 24×7 loop (survives insolvency + transient errors):
+await client.runLoop({ strategy: "momentum", sizePhunch: 25, intervalMs: 300_000, live: true });
+
+// A whole fleet from one process:
+import { fleetNew, fleetRun } from "hunch-cup";
+await fleetNew(10);
+await fleetRun({ defaultStrategy: "momentum", sizePhunch: 25, intervalMs: 300_000 });
 ```
 
 ## How auth works

package/dist/cli.js

@@ -2,18 +2,25 @@
 /**
  * `npx hunch-cup` — one-line Hunch Cup paper-trading agent (S8, scope §8.2.3).
  *
- *   hunch-cup wallet new              generate a wallet + claim 1,000 $pHUNCH
- *   hunch-cup markets                 list tradable paper markets
- *   hunch-cup quote <slug> <side> <n> price a paper trade
- *   hunch-cup trade <slug> <side> <n> place a REAL signed paper trade
- *   hunch-cup run <strategy> [n]      run momentum|contrarian|news-reactive
- *   hunch-cup board                   show the leaderboard
+ *   hunch-cup wallet new                generate a FRESH wallet + claim 10,000 $pHUNCH
+ *   hunch-cup markets [n] [offset]      list tradable paper markets
+ *   hunch-cup quote <slug> <side> <n>   price a paper trade
+ *   hunch-cup trade <slug> <side> <n>   place a REAL signed paper trade
+ *   hunch-cup run <strategy> [n] [--live] [--loop] [--interval <sec>]
+ *   hunch-cup positions                 your balance + open/realized positions
+ *   hunch-cup balance                   just your $pHUNCH balance
+ *   hunch-cup board [n]                  show the leaderboard
+ *   hunch-cup fleet new <n>             mint N wallets + claim each (→ ~/.hunch-cup/fleet.json)
+ *   hunch-cup fleet run <strategy> [--interval <sec>]   run all fleet wallets 24×7
+ *   hunch-cup fleet board               every fleet wallet's rank
  *
  * Config via env: HUNCH_CUP_PRIVATE_KEY (0x…), HUNCH_CUP_BASE_URL,
  * HUNCH_CUP_SIZE (default 25). `run` simulates by default; pass --live to trade.
  */
 import { CupClient } from "./client.js";
 import { fromPrivateKey, newWallet } from "./signer.js";
+import { fleetNew, fleetRun, fleetBoard } from "./fleet.js";
+const STRATEGIES = ["momentum", "contrarian", "news-reactive"];
 function baseUrl() {
     return process.env.HUNCH_CUP_BASE_URL;
 }
@@ -25,6 +32,22 @@ function size(arg) {
     const n = Number(arg ?? process.env.HUNCH_CUP_SIZE ?? 25);
     return Number.isFinite(n) && n > 0 ? n : 25;
 }
+/** Read `--flag value` (or `--flag=value`) from an args array. */
+function flagValue(args, flag) {
+    const eq = args.find((a) => a.startsWith(`${flag}=`));
+    if (eq)
+        return eq.slice(flag.length + 1);
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+function intervalMs(args) {
+    const sec = Number(flagValue(args, "--interval") ?? 300);
+    return (Number.isFinite(sec) && sec > 0 ? sec : 300) * 1000;
+}
+/** The first positional (non-flag) arg after index 0. */
+function firstPositional(args) {
+    return args.find((a, i) => i > 0 && !a.startsWith("--"));
+}
 function out(value) {
     console.log(typeof value === "string" ? value : JSON.stringify(value, null, 2));
 }
@@ -34,34 +57,36 @@ async function main(argv) {
         out([
             "hunch-cup — paper-trade the Hunch Cup from your terminal.",
             "",
-            "  wallet new                 generate a wallet + claim 1,000 $pHUNCH",
-            "  markets                    list tradable paper markets",
-            "  quote <slug> <side> <n>    price a paper trade",
-            "  trade <slug> <side> <n>    place a REAL signed paper trade",
-            "  run <strategy> [n] [--live]  momentum | contrarian | news-reactive",
-            "  board                      show the leaderboard",
+            "  wallet new                   generate a FRESH wallet + claim 10,000 $pHUNCH",
+            "  markets [n] [offset]         list tradable paper markets",
+            "  quote <slug> <side> <n>      price a paper trade",
+            "  trade <slug> <side> <n>      place a REAL signed paper trade",
+            "  run <strategy> [n] [--live] [--loop] [--interval <sec>]",
+            "  positions                    your balance + open/realized positions",
+            "  balance                      just your $pHUNCH balance",
+            "  board [n]                    show the leaderboard",
+            "  fleet new <n>                mint N wallets + claim each",
+            "  fleet run <strategy> [--interval <sec>]   run all fleet wallets 24×7",
+            "  fleet board                  every fleet wallet's rank",
             "",
+            "Strategies: momentum | contrarian | news-reactive",
             "Env: HUNCH_CUP_PRIVATE_KEY, HUNCH_CUP_BASE_URL, HUNCH_CUP_SIZE",
         ].join("\n"));
         return 0;
     }
     if (cmd === "wallet" && args[0] === "new") {
-        let signer = signerFromEnv();
-        let privateKey = process.env.HUNCH_CUP_PRIVATE_KEY;
-        if (!signer) {
-            const w = newWallet();
-            signer = w.signer;
-            privateKey = w.privateKey;
-            out(`Generated a new wallet. SAVE THIS PRIVATE KEY:\n  ${privateKey}`);
-            out(`export HUNCH_CUP_PRIVATE_KEY=${privateKey}`);
-        }
+        // Always mint a FRESH wallet so `wallet new` xN builds a roster (the old
+        // behavior silently re-claimed the env key). Use `fleet new` for many.
+        const { privateKey, signer } = newWallet();
+        out(`Generated a new wallet. SAVE THIS PRIVATE KEY:\n  ${privateKey}`);
+        out(`export HUNCH_CUP_PRIVATE_KEY=${privateKey}`);
         const client = new CupClient({ baseUrl: baseUrl(), signer });
         out(await client.createWallet());
         return 0;
     }
     if (cmd === "markets") {
         const client = new CupClient({ baseUrl: baseUrl() });
-        out(await client.listMarkets(Number(args[0] ?? 25)));
+        out(await client.listMarkets(Number(args[0] ?? 25), Number(args[1] ?? 0)));
         return 0;
     }
     if (cmd === "quote") {
@@ -83,23 +108,43 @@ async function main(argv) {
         out(await client.trade({ slug, side, sizePhunch: size(n) }));
         return 0;
     }
+    if (cmd === "positions" || cmd === "balance") {
+        const signer = signerFromEnv();
+        const addr = args[0] ?? signer?.address;
+        if (!addr)
+            return usage(`${cmd} [address]  (or set HUNCH_CUP_PRIVATE_KEY)`);
+        const client = new CupClient({ baseUrl: baseUrl() });
+        const wallet = await client.getWallet(addr);
+        out(cmd === "balance" ? { balancePhunch: wallet.balancePhunch } : wallet);
+        return 0;
+    }
     if (cmd === "run") {
         const strategy = args[0];
-        if (!strategy || !["momentum", "contrarian", "news-reactive"].includes(strategy)) {
-            return usage("run <momentum|contrarian|news-reactive> [size] [--live]");
+        if (!strategy || !STRATEGIES.includes(strategy)) {
+            return usage("run <momentum|contrarian|news-reactive> [size] [--live] [--loop] [--interval <sec>]");
         }
         const live = args.includes("--live");
-        const n = args.find((a, i) => i > 0 && !a.startsWith("--"));
+        const loop = args.includes("--loop");
+        const n = firstPositional(args);
         const signer = signerFromEnv();
         if (live && !signer)
             return usage("set HUNCH_CUP_PRIVATE_KEY to run --live");
         const client = new CupClient({ baseUrl: baseUrl(), signer });
-        out(await client.runStrategy({
-            strategy,
-            sizePhunch: size(n),
-            sentiment: Number(process.env.HUNCH_CUP_SENTIMENT ?? 0),
-            live,
-        }));
+        const sentiment = Number(process.env.HUNCH_CUP_SENTIMENT ?? 0);
+        if (loop) {
+            out(`Looping ${strategy} every ${intervalMs(args) / 1000}s (Ctrl-C to stop)…`);
+            await client.runLoop({
+                strategy,
+                sizePhunch: size(n),
+                intervalMs: intervalMs(args),
+                sentiment,
+                live,
+                onRound: (round, receipts) => out(`round ${round}: ${receipts.length} trade(s)`),
+                onError: (round, err) => console.error(`round ${round} error: ${err instanceof Error ? err.message : err}`),
+            });
+            return 0;
+        }
+        out(await client.runStrategy({ strategy, sizePhunch: size(n), sentiment, live }));
         return 0;
     }
     if (cmd === "board") {
@@ -107,6 +152,37 @@ async function main(argv) {
         out(await client.getLeaderboard({ limit: Number(args[0] ?? 50) }));
         return 0;
     }
+    if (cmd === "fleet") {
+        const sub = args[0];
+        if (sub === "new") {
+            const count = Number(args[1] ?? 0);
+            if (!Number.isFinite(count) || count < 1)
+                return usage("fleet new <count>");
+            const created = await fleetNew(count, baseUrl());
+            out(`Minted ${created.length} wallet(s) + claimed each. Saved to ~/.hunch-cup/fleet.json`);
+            out(created.map((w) => ({ name: w.name, address: w.address, strategy: w.strategy })));
+            return 0;
+        }
+        if (sub === "run") {
+            const strategy = args[1] ?? "momentum";
+            if (!STRATEGIES.includes(strategy))
+                return usage("fleet run <strategy> [--interval <sec>]");
+            out(`Running the fleet on ${strategy} every ${intervalMs(args) / 1000}s (Ctrl-C to stop)…`);
+            await fleetRun({
+                defaultStrategy: strategy,
+                sizePhunch: size(process.env.HUNCH_CUP_SIZE),
+                intervalMs: intervalMs(args),
+                baseUrl: baseUrl(),
+                onEvent: (line) => out(line),
+            });
+            return 0;
+        }
+        if (sub === "board") {
+            out(await fleetBoard(baseUrl()));
+            return 0;
+        }
+        return usage("fleet <new|run|board>");
+    }
     return usage(`unknown command: ${cmd}`);
 }
 function usage(message) {

package/dist/client.d.ts

@@ -5,6 +5,13 @@ export interface CupSigner {
     address: string;
     signMessage: (message: string) => Promise<string>;
 }
+/** A tradeable outcome key + its live paper pool-implied odds. */
+export interface CupOutcome {
+    key: string;
+    label: string;
+    shortLabel: string;
+    impliedPct: number;
+}
 export interface CupMarket {
     slug: string;
     marketId: string;
@@ -12,11 +19,31 @@ export interface CupMarket {
     shortTitle: string;
     tokenSymbol: string;
     direction: boolean;
+    /** True only for a real binary YES/NO market (drives yesCents/noCents). */
+    binary: boolean;
     deadlineAt: string;
-    yesCents: number;
-    noCents: number;
+    /** Binary cents; `null` for N-way markets (use `outcomes` instead). */
+    yesCents: number | null;
+    noCents: number | null;
     poolPhunch: number;
     tradeCount: number;
+    /** Every tradeable side (keys + odds) — the source of truth for N-way `side`. */
+    outcomes: CupOutcome[];
+}
+export interface CupPosition {
+    marketId: string;
+    side: string;
+    costPhunch: number;
+    status: "open" | "resolved";
+    realizedPnlPhunch: number;
+    projectedPayoutPhunch: number;
+}
+export interface CupWalletView {
+    walletAddress: string;
+    balancePhunch: number;
+    realizedPnlPhunch: number;
+    openCount: number;
+    positions: CupPosition[];
 }
 export interface CupTradeReceipt {
     simulated: boolean;
@@ -42,13 +69,13 @@ export declare class CupClient {
     get address(): string | undefined;
     private json;
     private requireSigner;
-    /** Claim 1,000 $pHUNCH once for the signer's wallet. */
+    /** Claim 10,000 $pHUNCH once for the signer's wallet. */
     createWallet(): Promise<{
         walletAddress: string;
         balancePhunch: number;
         minted: boolean;
     }>;
-    listMarkets(limit?: number): Promise<CupMarket[]>;
+    listMarkets(limit?: number, offset?: number): Promise<CupMarket[]>;
     getQuote(slug: string, side: string, sizePhunch: number): Promise<{
         shares: number;
         projectedPayoutPhunch: number;
@@ -63,16 +90,27 @@ export declare class CupClient {
         sizePhunch: number;
         tradeId?: string;
     }): Promise<CupTradeReceipt>;
-    getPositions(address?: string): Promise<unknown>;
+    /** Typed wallet summary: balance + realized PnL + positions, all in $pHUNCH. */
+    getWallet(address?: string): Promise<CupWalletView>;
+    /** @deprecated use {@link getWallet}. Kept for back-compat. */
+    getPositions(address?: string): Promise<CupWalletView>;
     getLeaderboard(opts?: {
         limit?: number;
         week?: number;
         wallet?: string;
     }): Promise<unknown>;
     /**
-     * One round of a built-in strategy: pick a side per market and place a trade
-     * (simulated unless `live`). Returns the receipts. The decision is pure
-     * ({@link pickFor}); placement is deterministic code.
+     * One round of a built-in strategy WITH bankroll survival — the un-managed
+     * loop in the hosting docs went insolvent in ~20 minutes (250 $pHUNCH/round from
+     * a finite no-top-up grant). This:
+     *   • reads the live balance + open positions first (a `live` run);
+     *   • skips markets the wallet is ALREADY positioned in (no re-piling);
+     *   • caps the round to `min(size, maxRoundFraction × balance)` per market and
+     *     stops when the balance can't cover another ticket;
+     *   • uses a STABLE tradeId (`cup:<roundBucket>:<slug>:<side>`) so an accidental
+     *     double-fire in the same 5-min bucket is idempotent, not a double-spend;
+     *   • picks over the market's REAL outcome keys (N-way safe).
+     * The decision is pure ({@link pickFor}); placement is deterministic code.
      */
     runStrategy(opts: {
         strategy: CupStrategy;
@@ -80,5 +118,24 @@ export declare class CupClient {
         limit?: number;
         sentiment?: number;
         live?: boolean;
+        /** Max fraction of the current balance to deploy per round (default 25%). */
+        maxRoundFraction?: number;
     }): Promise<CupTradeReceipt[]>;
+    /**
+     * Run a strategy on a fixed interval, forever (or `rounds` times), catching
+     * per-round errors so a transient failure never kills the agent — the built-in
+     * 24×7 loop the CLI/hosting docs previously punted to a `while true` shell hack.
+     */
+    runLoop(opts: {
+        strategy: CupStrategy;
+        sizePhunch: number;
+        intervalMs: number;
+        limit?: number;
+        sentiment?: number;
+        live?: boolean;
+        maxRoundFraction?: number;
+        rounds?: number;
+        onRound?: (round: number, receipts: CupTradeReceipt[]) => void;
+        onError?: (round: number, err: unknown) => void;
+    }): Promise<void>;
 }

package/dist/client.js

@@ -2,7 +2,7 @@
  * Hunch Cup — thin typed SDK client over `/api/cup/v1/*` (S8).
  *
  * Wallet-native + keyless: pass a viem `LocalAccount` (or any `CupSigner`) and
- * the client claims your 1,000 $pHUNCH, lists/quotes paper markets, and — for a
+ * the client claims your 10,000 $pHUNCH, lists/quotes paper markets, and — for a
  * REAL trade — signs the canonical message for you (the only thing that proves
  * wallet ownership on the paper path). Reads need no signer. Uses global `fetch`
  * (Node ≥ 20). `viem` is an optional peer used only by {@link fromPrivateKey}.
@@ -36,7 +36,7 @@ export class CupClient {
             throw new Error("A signer is required for this action (claim/trade).");
         return this.signer;
     }
-    /** Claim 1,000 $pHUNCH once for the signer's wallet. */
+    /** Claim 10,000 $pHUNCH once for the signer's wallet. */
     async createWallet() {
         const signer = this.requireSigner();
         return this.json("/api/cup/v1/wallet", {
@@ -45,8 +45,11 @@ export class CupClient {
             body: JSON.stringify({ walletAddress: signer.address }),
         });
     }
-    async listMarkets(limit = 25) {
-        const out = await this.json(`/api/cup/v1/markets?limit=${limit}`);
+    async listMarkets(limit = 25, offset = 0) {
+        const qs = new URLSearchParams({ limit: String(limit) });
+        if (offset > 0)
+            qs.set("offset", String(offset));
+        const out = await this.json(`/api/cup/v1/markets?${qs}`);
         return out.markets;
     }
     async getQuote(slug, side, sizePhunch) {
@@ -97,12 +100,17 @@ export class CupClient {
         });
         return out.receipt;
     }
-    async getPositions(address) {
+    /** Typed wallet summary: balance + realized PnL + positions, all in $pHUNCH. */
+    async getWallet(address) {
         const addr = address ?? this.signer?.address;
         if (!addr)
             throw new Error("No wallet address (pass one or construct with a signer).");
         return this.json(`/api/cup/v1/wallet/${addr}`);
     }
+    /** @deprecated use {@link getWallet}. Kept for back-compat. */
+    async getPositions(address) {
+        return this.getWallet(address);
+    }
     async getLeaderboard(opts = {}) {
         const qs = new URLSearchParams();
         if (opts.limit)
@@ -115,27 +123,101 @@ export class CupClient {
         return this.json(`/api/cup/v1/leaderboard${suffix}`);
     }
     /**
-     * One round of a built-in strategy: pick a side per market and place a trade
-     * (simulated unless `live`). Returns the receipts. The decision is pure
-     * ({@link pickFor}); placement is deterministic code.
+     * One round of a built-in strategy WITH bankroll survival — the un-managed
+     * loop in the hosting docs went insolvent in ~20 minutes (250 $pHUNCH/round from
+     * a finite no-top-up grant). This:
+     *   • reads the live balance + open positions first (a `live` run);
+     *   • skips markets the wallet is ALREADY positioned in (no re-piling);
+     *   • caps the round to `min(size, maxRoundFraction × balance)` per market and
+     *     stops when the balance can't cover another ticket;
+     *   • uses a STABLE tradeId (`cup:<roundBucket>:<slug>:<side>`) so an accidental
+     *     double-fire in the same 5-min bucket is idempotent, not a double-spend;
+     *   • picks over the market's REAL outcome keys (N-way safe).
+     * The decision is pure ({@link pickFor}); placement is deterministic code.
      */
     async runStrategy(opts) {
         const markets = await this.listMarkets(opts.limit ?? 10);
         const receipts = [];
+        // Bankroll snapshot (live only — a simulate run writes nothing, so it can
+        // fan out over every market without spending).
+        let balance = Infinity;
+        const held = new Set();
+        if (opts.live && this.signer) {
+            try {
+                const wallet = await this.getWallet();
+                balance = wallet.balancePhunch;
+                for (const p of wallet.positions)
+                    if (p.status === "open")
+                        held.add(p.marketId);
+            }
+            catch {
+                /* fail-soft: no snapshot → behave like the unmanaged run but still capped below */
+            }
+        }
+        const fraction = opts.maxRoundFraction ?? 0.25;
+        let roundBudget = opts.live ? Math.max(0, balance * fraction) : Infinity;
+        const bucket = roundBucket();
         for (const m of markets) {
+            if (opts.live && held.has(m.marketId))
+                continue; // already positioned
+            const size = opts.sizePhunch;
+            if (opts.live && (balance < size || roundBudget < size))
+                break; // insolvent / budget spent
             const card = {
                 slug: m.slug,
-                yesCents: m.yesCents,
-                noCents: m.noCents,
+                yesCents: m.yesCents ?? 50,
+                noCents: m.noCents ?? 50,
                 direction: m.direction,
+                outcomes: m.outcomes?.map((o) => ({ key: o.key, impliedPct: o.impliedPct })),
             };
             const pick = pickFor(opts.strategy, card, opts.sentiment ?? 0);
-            receipts.push(opts.live
-                ? await this.trade({ slug: pick.slug, side: pick.side, sizePhunch: opts.sizePhunch })
-                : await this.simulateTrade(pick.slug, pick.side, opts.sizePhunch));
+            if (opts.live) {
+                const receipt = await this.trade({
+                    slug: pick.slug,
+                    side: pick.side,
+                    sizePhunch: size,
+                    tradeId: `cup:${bucket}:${pick.slug}:${pick.side}`,
+                });
+                receipts.push(receipt);
+                if (typeof receipt.balancePhunch === "number")
+                    balance = receipt.balancePhunch;
+                else
+                    balance -= size;
+                roundBudget -= size;
+                held.add(m.marketId);
+            }
+            else {
+                receipts.push(await this.simulateTrade(pick.slug, pick.side, size));
+            }
         }
         return receipts;
     }
+    /**
+     * Run a strategy on a fixed interval, forever (or `rounds` times), catching
+     * per-round errors so a transient failure never kills the agent — the built-in
+     * 24×7 loop the CLI/hosting docs previously punted to a `while true` shell hack.
+     */
+    async runLoop(opts) {
+        for (let round = 1; !opts.rounds || round <= opts.rounds; round += 1) {
+            try {
+                const receipts = await this.runStrategy(opts);
+                opts.onRound?.(round, receipts);
+            }
+            catch (err) {
+                opts.onError?.(round, err);
+            }
+            if (opts.rounds && round >= opts.rounds)
+                break;
+            await sleep(opts.intervalMs);
+        }
+    }
+}
+/** A 5-minute time bucket, so a same-bucket re-run reuses the same tradeIds. */
+function roundBucket() {
+    return Math.floor(Date.now() / (5 * 60 * 1000)).toString(36);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function randomId() {
     // Best-effort unique id; the server idempotency key is the full tradeId.

package/dist/fleet.d.ts

@@ -0,0 +1,43 @@
+import type { CupStrategy } from "./strategy.js";
+export interface FleetWallet {
+    name: string;
+    privateKey: string;
+    address: string;
+    /** Optional per-wallet strategy override (else the fleet default is used). */
+    strategy?: CupStrategy;
+}
+export interface Fleet {
+    wallets: FleetWallet[];
+}
+export declare function fleetFilePath(): string;
+export declare function loadFleet(): Fleet;
+export declare function saveFleet(fleet: Fleet): string;
+/**
+ * Mint `count` fresh wallets, claim each one's 10,000 $pHUNCH, and append them to
+ * the fleet file with a rotating strategy. Idempotent claim (the server grants
+ * once), so re-running only tops up the roster.
+ */
+export declare function fleetNew(count: number, baseUrl?: string): Promise<FleetWallet[]>;
+/**
+ * Run a strategy loop across every fleet wallet concurrently. Each wallet uses
+ * its own per-wallet `strategy` if set, else `defaultStrategy`. Rounds are
+ * staggered so N wallets don't all fire on the exact same instant. Never throws —
+ * per-round errors are reported via `onEvent`.
+ */
+export declare function fleetRun(opts: {
+    defaultStrategy: CupStrategy;
+    sizePhunch: number;
+    intervalMs: number;
+    baseUrl?: string;
+    limit?: number;
+    rounds?: number;
+    onEvent?: (line: string) => void;
+}): Promise<void>;
+/** Each fleet wallet's live rank + balance + realized PnL, best rank first. */
+export declare function fleetBoard(baseUrl?: string): Promise<Array<{
+    name: string;
+    address: string;
+    rank: number | null;
+    balancePhunch: number;
+    realizedPnlPhunch: number;
+}>>;

package/dist/fleet.js

@@ -0,0 +1,129 @@
+/**
+ * Hunch Cup — run a FLEET of agents from one machine (founder goal 2: "one
+ * person spins up 5–10 agents easily").
+ *
+ * A fleet is a set of throwaway wallets persisted to `~/.hunch-cup/fleet.json`
+ * (override with `HUNCH_CUP_FLEET_FILE`). `fleetNew` mints N fresh wallets and
+ * claims each one's 10,000 $pHUNCH; `fleetRun` runs a (possibly per-wallet mixed)
+ * strategy loop across all of them concurrently; `fleetBoard` shows each wallet's
+ * live rank. Keys never leave the local file.
+ *
+ * SECURITY: the file holds real (paper-only) private keys in plaintext — same
+ * trust model as `HUNCH_CUP_PRIVATE_KEY`. These wallets only ever touch paper
+ * $pHUNCH, never real funds.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { CupClient } from "./client.js";
+import { fromPrivateKey, newWallet } from "./signer.js";
+export function fleetFilePath() {
+    return process.env.HUNCH_CUP_FLEET_FILE ?? join(homedir(), ".hunch-cup", "fleet.json");
+}
+export function loadFleet() {
+    const path = fleetFilePath();
+    if (!existsSync(path))
+        return { wallets: [] };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return { wallets: Array.isArray(parsed.wallets) ? parsed.wallets : [] };
+    }
+    catch {
+        return { wallets: [] };
+    }
+}
+export function saveFleet(fleet) {
+    const path = fleetFilePath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(fleet, null, 2), { mode: 0o600 });
+    return path;
+}
+/** A rotation of the built-in strategies, so a demo fleet is visibly diverse. */
+const STRATEGY_CYCLE = ["momentum", "contrarian", "news-reactive"];
+/**
+ * Mint `count` fresh wallets, claim each one's 10,000 $pHUNCH, and append them to
+ * the fleet file with a rotating strategy. Idempotent claim (the server grants
+ * once), so re-running only tops up the roster.
+ */
+export async function fleetNew(count, baseUrl) {
+    const fleet = loadFleet();
+    const created = [];
+    for (let i = 0; i < count; i += 1) {
+        const { privateKey, signer } = newWallet();
+        const idx = fleet.wallets.length + created.length;
+        const wallet = {
+            name: `bot-${idx + 1}`,
+            privateKey,
+            address: signer.address,
+            strategy: STRATEGY_CYCLE[idx % STRATEGY_CYCLE.length],
+        };
+        try {
+            await new CupClient({ baseUrl, signer }).createWallet();
+        }
+        catch {
+            /* claim is dormant/closed or offline — the wallet is saved regardless */
+        }
+        created.push(wallet);
+    }
+    saveFleet({ wallets: [...fleet.wallets, ...created] });
+    return created;
+}
+/**
+ * Run a strategy loop across every fleet wallet concurrently. Each wallet uses
+ * its own per-wallet `strategy` if set, else `defaultStrategy`. Rounds are
+ * staggered so N wallets don't all fire on the exact same instant. Never throws —
+ * per-round errors are reported via `onEvent`.
+ */
+export async function fleetRun(opts) {
+    const fleet = loadFleet();
+    if (fleet.wallets.length === 0) {
+        opts.onEvent?.("No fleet wallets. Run `hunch-cup fleet new <n>` first.");
+        return;
+    }
+    const stagger = Math.floor(opts.intervalMs / Math.max(1, fleet.wallets.length));
+    await Promise.all(fleet.wallets.map(async (w, i) => {
+        await sleep(stagger * i); // spread the first fire across the interval
+        const client = new CupClient({ baseUrl: opts.baseUrl, signer: fromPrivateKey(w.privateKey) });
+        const strategy = w.strategy ?? opts.defaultStrategy;
+        await client.runLoop({
+            strategy,
+            sizePhunch: opts.sizePhunch,
+            intervalMs: opts.intervalMs,
+            limit: opts.limit,
+            live: true,
+            rounds: opts.rounds,
+            onRound: (round, receipts) => opts.onEvent?.(`[${w.name}·${strategy}] round ${round}: ${receipts.length} trade(s)`),
+            onError: (round, err) => opts.onEvent?.(`[${w.name}] round ${round} error: ${err instanceof Error ? err.message : String(err)}`),
+        });
+    }));
+}
+/** Each fleet wallet's live rank + balance + realized PnL, best rank first. */
+export async function fleetBoard(baseUrl) {
+    const fleet = loadFleet();
+    const rows = await Promise.all(fleet.wallets.map(async (w) => {
+        const client = new CupClient({ baseUrl });
+        let balancePhunch = 0;
+        let realizedPnlPhunch = 0;
+        let rank = null;
+        try {
+            const wallet = await client.getWallet(w.address);
+            balancePhunch = wallet.balancePhunch;
+            realizedPnlPhunch = wallet.realizedPnlPhunch;
+        }
+        catch {
+            /* dormant/offline */
+        }
+        try {
+            const board = (await client.getLeaderboard({ wallet: w.address, limit: 1 }));
+            rank = board.you?.rank ?? null;
+        }
+        catch {
+            /* no rank yet */
+        }
+        return { name: w.name, address: w.address, rank, balancePhunch, realizedPnlPhunch };
+    }));
+    return rows.sort((a, b) => (a.rank ?? 1e9) - (b.rank ?? 1e9));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export { CupClient, DEFAULT_BASE_URL } from "./client.js";
-export type { CupClientOptions, CupSigner, CupMarket, CupTradeReceipt, } from "./client.js";
+export type { CupClientOptions, CupSigner, CupMarket, CupOutcome, CupPosition, CupWalletView, CupTradeReceipt, } from "./client.js";
 export { fromViemAccount, fromPrivateKey, newWallet } from "./signer.js";
 export { buildCupTradeMessage } from "./message.js";
 export type { CupTradeMessageParams } from "./message.js";
 export { pickFor, momentumPick, contrarianPick, newsReactivePick, } from "./strategy.js";
-export type { CupStrategy, StrategyCard, StrategyPick } from "./strategy.js";
+export type { CupStrategy, StrategyCard, StrategyOutcome, StrategyPick, } from "./strategy.js";
+export { fleetNew, fleetRun, fleetBoard, loadFleet, saveFleet, fleetFilePath, } from "./fleet.js";
+export type { Fleet, FleetWallet } from "./fleet.js";

package/dist/index.js

@@ -2,3 +2,4 @@ export { CupClient, DEFAULT_BASE_URL } from "./client.js";
 export { fromViemAccount, fromPrivateKey, newWallet } from "./signer.js";
 export { buildCupTradeMessage } from "./message.js";
 export { pickFor, momentumPick, contrarianPick, newsReactivePick, } from "./strategy.js";
+export { fleetNew, fleetRun, fleetBoard, loadFleet, saveFleet, fleetFilePath, } from "./fleet.js";

package/dist/strategy.d.ts

@@ -3,8 +3,16 @@
  *
  * Pure, deterministic deciders. The LLM (if any) NEVER executes — a strategy
  * maps a market card to a concrete `{ side }` and order placement is plain code.
- * Direction markets resolve to UP/DOWN; binary markets to YES/NO.
+ * Binary markets resolve to YES/NO, direction markets to UP/DOWN, and N-way
+ * markets (ladders, outperform books, THE FLIP: heads/tails/tie) pick over their
+ * REAL outcome keys — never yes/no, which on an N-way market records a bet that
+ * can never win (the server now 422s it; the strategy must not emit it).
  */
+/** One tradeable outcome with its live pool-implied probability (0–100). */
+export interface StrategyOutcome {
+    key: string;
+    impliedPct: number;
+}
 export interface StrategyCard {
     slug: string;
     /** Implied paper-pool probability of the positive outcome, in cents (0–100). */
@@ -13,20 +21,28 @@ export interface StrategyCard {
     noCents: number;
     /** True → the positive/negative outcomes are UP/DOWN, not YES/NO. */
     direction: boolean;
+    /**
+     * The market's real outcome keys + odds. Present for N-way markets (and
+     * optionally binary); when set, strategies pick over THESE keys so an
+     * N-way bet never lands on a phantom yes/no side.
+     */
+    outcomes?: StrategyOutcome[];
 }
 export interface StrategyPick {
     slug: string;
     side: string;
 }
 export type CupStrategy = "momentum" | "contrarian" | "news-reactive";
-/** Momentum: trade WITH the crowd — back the pool's favorite. */
+/** Momentum: trade WITH the crowd — back the pool's favorite (max odds). */
 export declare function momentumPick(card: StrategyCard): StrategyPick;
-/** Contrarian: fade the crowd — back the underdog. */
+/** Contrarian: fade the crowd — back the longest-odds outcome. */
 export declare function contrarianPick(card: StrategyCard): StrategyPick;
 /**
  * News-reactive: trade off an external sentiment signal in [-1, 1] (e.g. a
- * headline classifier). Positive → back the positive outcome; negative → the
- * negative; a neutral 0 falls back to the pool favorite.
+ * headline classifier). On a binary/direction market positive → the positive
+ * outcome (YES/UP), negative → the negative (NO/DOWN); neutral 0 → momentum.
+ * N-way markets have no natural positive pole, so a signal maps onto the
+ * crowd favorite (positive) or underdog (negative) — always a real key.
  */
 export declare function newsReactivePick(card: StrategyCard, sentiment: number): StrategyPick;
 /** Dispatch a named strategy. `news-reactive` uses `sentiment` (default 0). */

package/dist/strategy.js

@@ -3,9 +3,31 @@
  *
  * Pure, deterministic deciders. The LLM (if any) NEVER executes — a strategy
  * maps a market card to a concrete `{ side }` and order placement is plain code.
- * Direction markets resolve to UP/DOWN; binary markets to YES/NO.
+ * Binary markets resolve to YES/NO, direction markets to UP/DOWN, and N-way
+ * markets (ladders, outperform books, THE FLIP: heads/tails/tie) pick over their
+ * REAL outcome keys — never yes/no, which on an N-way market records a bet that
+ * can never win (the server now 422s it; the strategy must not emit it).
  */
-/** The outcome label for a pole on this card (UP/DOWN vs YES/NO). */
+/** Is this an N-way market we should pick over its own outcome keys? */
+function isNway(card) {
+    return (Array.isArray(card.outcomes) &&
+        card.outcomes.length > 0 &&
+        // A true binary yes/no pair is handled by the yesCents/noCents path below.
+        !(card.outcomes.length === 2 &&
+            card.outcomes.some((o) => o.key === "yes") &&
+            card.outcomes.some((o) => o.key === "no")));
+}
+/** The outcome key with the highest / lowest implied odds (ties → first listed). */
+function extreme(outcomes, want) {
+    return outcomes.reduce((best, o) => want === "max"
+        ? o.impliedPct > best.impliedPct
+            ? o
+            : best
+        : o.impliedPct < best.impliedPct
+            ? o
+            : best).key;
+}
+/** The outcome label for a binary/direction pole (UP/DOWN vs YES/NO). */
 function sideFor(card, pole) {
     if (card.direction)
         return pole === "pos" ? "up" : "down";
@@ -15,21 +37,32 @@ function sideFor(card, pole) {
 function favorite(card) {
     return card.yesCents >= card.noCents ? "pos" : "neg";
 }
-/** Momentum: trade WITH the crowd — back the pool's favorite. */
+/** Momentum: trade WITH the crowd — back the pool's favorite (max odds). */
 export function momentumPick(card) {
+    if (isNway(card))
+        return { slug: card.slug, side: extreme(card.outcomes, "max") };
     return { slug: card.slug, side: sideFor(card, favorite(card)) };
 }
-/** Contrarian: fade the crowd — back the underdog. */
+/** Contrarian: fade the crowd — back the longest-odds outcome. */
 export function contrarianPick(card) {
+    if (isNway(card))
+        return { slug: card.slug, side: extreme(card.outcomes, "min") };
     const pole = favorite(card) === "pos" ? "neg" : "pos";
     return { slug: card.slug, side: sideFor(card, pole) };
 }
 /**
  * News-reactive: trade off an external sentiment signal in [-1, 1] (e.g. a
- * headline classifier). Positive → back the positive outcome; negative → the
- * negative; a neutral 0 falls back to the pool favorite.
+ * headline classifier). On a binary/direction market positive → the positive
+ * outcome (YES/UP), negative → the negative (NO/DOWN); neutral 0 → momentum.
+ * N-way markets have no natural positive pole, so a signal maps onto the
+ * crowd favorite (positive) or underdog (negative) — always a real key.
  */
 export function newsReactivePick(card, sentiment) {
+    if (isNway(card)) {
+        if (sentiment < 0)
+            return contrarianPick(card);
+        return momentumPick(card);
+    }
     if (sentiment > 0)
         return { slug: card.slug, side: sideFor(card, "pos") };
     if (sentiment < 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hunch-cup",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "One-line CLI + typed SDK to paper-trade the Hunch Cup tournament: claim 1,000 $pHUNCH, trade live markets with zero real-funds risk, run momentum/contrarian/news-reactive agents, and climb the public leaderboard.",
   "keywords": [
     "hunch",