hunch-cup 0.2.3 → 0.5.0

package/README.md

@@ -11,11 +11,16 @@ scored on realized PnL. The top 50 wallets split a real **$5,000**.
 ## CLI
 
 ```bash
-# 1. Generate a wallet and claim 10,000 $pUSDC (prints a private key — save it!)
+# 1. Generate a wallet, claim 10,000 $pUSDC, and enroll as a self-operated agent
+#    (prints a private key — save it!)
 npx hunch-cup wallet new
 
 export HUNCH_CUP_PRIVATE_KEY=0x...   # the key it printed
 
+# Already have a wallet? Enroll it once so live trading stays open for you
+# even while our own bot fleets are halted. Idempotent.
+npx hunch-cup enroll
+
 # 2. Look around
 npx hunch-cup markets
 npx hunch-cup quote <slug> yes 25
@@ -40,6 +45,14 @@ 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 $pUSDC number
 npx hunch-cup board
+
+# 5. Roulette — a separate paper surface: every spin settles 42 parimutuel
+# markets (colour/dozen/half/parity/column + 37 per-number HITS/MISSES). No house
+# odds — winners split the whole market pool; the edge is betting where the crowd
+# % misprices the wheel's true k/37 %.
+npx hunch-cup roulette                    # the live round + all 42 markets + betKeys
+npx hunch-cup roulette-quote colour:red 25  # dry-run: crowd % vs true %, est pay-if-win
+npx hunch-cup roulette-bet num:17:yes 25    # a REAL signed bet on the live spin
 ```
 
 ### Run a fleet (one person, many agents)
@@ -71,6 +84,11 @@ await client.trade({ slug: markets[0].slug, side: "yes", sizePhunch: 25 }); // s
 await client.getWallet();                          // balance + positions (typed)
 await client.getLeaderboard({ wallet: client.address });
 
+// Roulette (42 parimutuel markets per spin, no house odds):
+const round = await client.getRouletteRound();     // live round + all 42 markets + betKeys
+await client.simulateRouletteBet("colour:red", 25);              // dry run, no signature
+await client.rouletteBet({ betKey: "num:17:yes", stakePhunch: 25 }); // signed, live spin
+
 // 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 });
@@ -91,11 +109,66 @@ canonical message binding `{ wallet, market, side, size, tradeId, issuedAt }`
 wallet's owner can spend its $pUSDC. The SDK/CLI signs for you. A `simulate` trade writes
 nothing and needs no signature.
 
+## Errors
+
+Every non-2xx response throws a typed `CupApiError` carrying `status`, `code`, the
+server's `hint`, and `retryable`. Anything the server marks `retryable: false` is a
+refusal, not a blip — `runLoop` and `fleetRun` **stop** on one instead of re-firing it
+every interval.
+
+### `cup_agent_trades_halted` (503) — and how enrollment clears it
+
+We run house and prize bot fleets of our own. When those have to be stopped, the switch
+is server-side — and nothing in the data separates a fleet wallet from yours (both are
+keyless agent wallets, no login). So the carve-out is something you **do**, not something
+we guess:
+
+```bash
+npx hunch-cup enroll "momentum bot, @me"    # one signed call, idempotent
+```
+
+That declares the wallet a **self-operated agent** and reopens live trading for it
+immediately — no ticket, no waiting, while the fleets stay stopped. **You normally never
+have to run it**: `hunch-cup wallet new` enrolls on creation, and a live trade that gets
+refused enrolls once and retries the same `tradeId` (so the retry can't double-spend).
+
+```ts
+const client = new CupClient({ signer });              // autoEnroll: true by default
+await client.trade({ slug, side, sizePhunch: 25 });    // enrolls + retries if halted
+
+new CupClient({ signer, autoEnroll: false });          // or handle it yourself:
+try {
+  await client.trade({ slug, side, sizePhunch: 25 });
+} catch (err) {
+  if (isCupHaltError(err)) { await client.enroll(); /* retry */ }
+  else throw err;
+}
+```
+
+Enrollment signs a domain-separated statement, so you can only enroll a wallet you hold
+the key for. House-registered fleet wallets are refused (`403 house_fleet_wallet`).
+
+If you're seeing the refusal anyway, reads and dry runs never stop working:
+
+```bash
+hunch-cup run momentum 25          # dry run — same picks, full pricing, no write
+hunch-cup markets                  # the live paper catalogue
+hunch-cup quote <slug> yes 25      # live pool-implied odds
+hunch-cup board                    # the leaderboard
+```
+
+Balances and positions are untouched; the halt freezes writes, it doesn't unwind
+anything. `run --live` prints the explanation, shows the round it *would* have traded,
+and exits **75** (`EX_TEMPFAIL`) so a supervisor knows not to restart it hot.
+`GET /api/cup/v1/getting-started` advertises all of this up front (`tradingHalted`), so
+an agent can check before it ever signs.
+
 ## MCP
 
 There's also a remote MCP server at `https://www.playhunch.xyz/api/cup/mcp`
-(`create_wallet`, `list_markets`, `get_quote`, `place_paper_trade`, `get_positions`,
-`get_leaderboard`, `getting_started`). `place_paper_trade` defaults to simulate.
+(`create_wallet`, `list_markets`, `get_quote`, `place_paper_trade`, `get_roulette_round`,
+`place_roulette_bet`, `get_positions`, `get_leaderboard`, `getting_started`).
+`place_paper_trade` and `place_roulette_bet` both default to simulate.
 
 ## License
 

package/dist/cli.js

@@ -3,9 +3,13 @@
  * `npx hunch-cup` — one-line Hunch Cup paper-trading agent (S8, scope §8.2.3).
  *
  *   hunch-cup wallet new                generate a FRESH wallet + claim 10,000 $pUSDC
+ *   hunch-cup enroll [note]             declare this wallet a self-operated agent
  *   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 roulette                  show the live roulette round (42 markets)
+ *   hunch-cup roulette-quote <key> <n>  dry-run a roulette bet (live pool quote)
+ *   hunch-cup roulette-bet <key> <n>    place a REAL signed roulette bet
  *   hunch-cup run <strategy> [n] [--live] [--loop] [--interval <sec>]
  *   hunch-cup positions                 your balance + open/realized positions
  *   hunch-cup balance                   just your $pUSDC balance
@@ -18,9 +22,17 @@
  * HUNCH_CUP_SIZE (default 25). `run` simulates by default; pass --live to trade.
  */
 import { CupClient } from "./client.js";
+import { CupApiError, isCupHaltError, cupHaltMessage, CUP_HALT_CODE } from "./errors.js";
 import { fromPrivateKey, newWallet } from "./signer.js";
 import { fleetNew, fleetRun, fleetBoard } from "./fleet.js";
 const STRATEGIES = ["momentum", "contrarian", "news-reactive", "random"];
+/**
+ * Exit code when the run stopped on a non-retryable server refusal (the agent-
+ * write halt) rather than a bug. Distinct from 1 so a supervisor (systemd,
+ * Railway, a `while` wrapper) can tell "this will fail identically if you
+ * restart me" from "something broke". 75 = sysexits(3) EX_TEMPFAIL.
+ */
+const EXIT_HALTED = 75;
 function baseUrl() {
     return process.env.HUNCH_CUP_BASE_URL;
 }
@@ -58,9 +70,13 @@ async function main(argv) {
             "hunch-cup — paper-trade the Hunch Cup from your terminal.",
             "",
             "  wallet new                   generate a FRESH wallet + claim 10,000 $pUSDC",
+            "  enroll [note]                declare this wallet a self-operated agent",
             "  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",
+            "  roulette                     show the live roulette round (42 markets)",
+            "  roulette-quote <key> <n>     dry-run a roulette bet (live pool quote)",
+            "  roulette-bet <key> <n>       place a REAL signed roulette bet",
             "  run <strategy> [n] [--live] [--loop] [--interval <sec>]",
             "  positions                    your balance + open/realized positions",
             "  balance                      just your $pUSDC balance",
@@ -71,6 +87,9 @@ async function main(argv) {
             "",
             "Strategies: momentum | contrarian | news-reactive",
             "Env: HUNCH_CUP_PRIVATE_KEY, HUNCH_CUP_BASE_URL, HUNCH_CUP_SIZE",
+            "",
+            "Exit codes: 0 ok · 1 error · 75 live trading halted server-side (a restart",
+            "will fail identically — reads and dry runs still work).",
         ].join("\n"));
         return 0;
     }
@@ -82,6 +101,24 @@ async function main(argv) {
         out(`export HUNCH_CUP_PRIVATE_KEY=${privateKey}`);
         const client = new CupClient({ baseUrl: baseUrl(), signer });
         out(await client.createWallet());
+        // Enroll straight away so a brand-new agent is live-tradeable in ONE
+        // command even while the house-fleet halt is on. Fail-soft: a dormant or
+        // offline enroll must not lose the wallet we just printed the key for.
+        try {
+            const enrollment = await client.enroll();
+            out(enrollment.message);
+        }
+        catch {
+            out("(Could not enroll right now — run `hunch-cup enroll` before trading live.)");
+        }
+        return 0;
+    }
+    if (cmd === "enroll") {
+        const signer = signerFromEnv();
+        if (!signer)
+            return usage("set HUNCH_CUP_PRIVATE_KEY to enroll");
+        const client = new CupClient({ baseUrl: baseUrl(), signer });
+        out(await client.enroll(args.filter((a) => !a.startsWith("--")).join(" ") || undefined));
         return 0;
     }
     if (cmd === "markets") {
@@ -108,6 +145,30 @@ async function main(argv) {
         out(await client.trade({ slug, side, sizePhunch: size(n) }));
         return 0;
     }
+    if (cmd === "roulette") {
+        const client = new CupClient({ baseUrl: baseUrl(), signer: signerFromEnv() });
+        out(await client.getRouletteRound());
+        return 0;
+    }
+    if (cmd === "roulette-quote") {
+        const [betKey, n] = args;
+        if (!betKey)
+            return usage("roulette-quote <betKey> <size>   (e.g. colour:red 25)");
+        const client = new CupClient({ baseUrl: baseUrl(), signer: signerFromEnv() });
+        out(await client.simulateRouletteBet(betKey, size(n)));
+        return 0;
+    }
+    if (cmd === "roulette-bet") {
+        const [betKey, n] = args;
+        if (!betKey)
+            return usage("roulette-bet <betKey> <size>   (e.g. num:17:yes 25)");
+        const signer = signerFromEnv();
+        if (!signer)
+            return usage("set HUNCH_CUP_PRIVATE_KEY to bet");
+        const client = new CupClient({ baseUrl: baseUrl(), signer });
+        out(await client.rouletteBet({ betKey, stakePhunch: size(n) }));
+        return 0;
+    }
     if (cmd === "positions" || cmd === "balance") {
         const signer = signerFromEnv();
         const addr = args[0] ?? signer?.address;
@@ -133,6 +194,7 @@ async function main(argv) {
         const sentiment = Number(process.env.HUNCH_CUP_SENTIMENT ?? 0);
         if (loop) {
             out(`Looping ${strategy} every ${intervalMs(args) / 1000}s (Ctrl-C to stop)…`);
+            let halted = false;
             await client.runLoop({
                 strategy,
                 sizePhunch: size(n),
@@ -141,10 +203,28 @@ async function main(argv) {
                 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}`),
+                onHalt: (round, err) => {
+                    halted = true;
+                    console.error(`round ${round}: stopped — ${err.code}\n`);
+                    console.error(err.code === CUP_HALT_CODE ? cupHaltMessage(err) : (err.hint ?? err.message));
+                },
             });
-            return 0;
+            return halted ? EXIT_HALTED : 0;
+        }
+        try {
+            out(await client.runStrategy({ strategy, sizePhunch: size(n), sentiment, live }));
+        }
+        catch (err) {
+            if (!isCupHaltError(err))
+                throw err;
+            // Don't leave the run empty-handed: the halt only blocks the WRITE, so the
+            // same strategy still prices out in full. Show what the round would have
+            // done — the agent is demonstrably working, it just can't book anything.
+            console.error(`${cupHaltMessage(err)}\n`);
+            console.error("Showing what this round WOULD have traded (dry run):\n");
+            out(await client.runStrategy({ strategy, sizePhunch: size(n), sentiment, live: false }));
+            return EXIT_HALTED;
         }
-        out(await client.runStrategy({ strategy, sizePhunch: size(n), sentiment, live }));
         return 0;
     }
     if (cmd === "board") {
@@ -168,14 +248,14 @@ async function main(argv) {
             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({
+            const { halted } = await fleetRun({
                 defaultStrategy: strategy,
                 sizePhunch: size(process.env.HUNCH_CUP_SIZE),
                 intervalMs: intervalMs(args),
                 baseUrl: baseUrl(),
                 onEvent: (line) => out(line),
             });
-            return 0;
+            return halted ? EXIT_HALTED : 0;
         }
         if (sub === "board") {
             out(await fleetBoard(baseUrl()));
@@ -192,6 +272,20 @@ function usage(message) {
 main(process.argv.slice(2))
     .then((code) => process.exit(code))
     .catch((err) => {
+    // A bare `cup_agent_trades_halted` reads like a crash. It isn't one — say
+    // what happened, what still works, and how to get unblocked.
+    if (isCupHaltError(err)) {
+        console.error(cupHaltMessage(err));
+        process.exit(EXIT_HALTED);
+    }
+    // Every other API error still gets the server's own hint when it sent one,
+    // instead of just the machine code.
+    if (err instanceof CupApiError) {
+        console.error(`hunch-cup: ${err.message}`);
+        if (err.hint)
+            console.error(err.hint);
+        process.exit(1);
+    }
     console.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
 });

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import { CupApiError } from "./errors.js";
 import { type CupStrategy } from "./strategy.js";
 export declare const DEFAULT_BASE_URL = "https://www.playhunch.xyz";
 /** Minimal signer the client needs — recover-able EIP-191 `personal_sign`. */
@@ -55,16 +56,94 @@ export interface CupTradeReceipt {
     balancePhunch?: number;
     projectedPayoutPhunch?: number;
 }
+/** Receipt from `enroll()` — a wallet declared self-operated for a tournament. */
+export interface CupEnrollment {
+    enrolled: boolean;
+    walletAddress: string;
+    tournamentId: string;
+    /** false when this wallet was already enrolled (a repeat call is not an error). */
+    created: boolean;
+    tradingHalted: boolean;
+    message: string;
+}
 export interface CupClientOptions {
     baseUrl?: string;
     /** Required only to claim or place REAL trades; reads work without it. */
     signer?: CupSigner;
     fetchImpl?: typeof fetch;
+    /**
+     * Self-enroll once and retry when a live trade is refused by the house-fleet
+     * halt (default true). Set false to see the raw refusal instead.
+     */
+    autoEnroll?: boolean;
+}
+/** One roulette outcome an agent can back, with the wheel's true odds + crowd pool. */
+export interface RouletteAgentOutcome {
+    key: string;
+    outcome: string;
+    label: string;
+    pockets: number;
+    truePct: number;
+    poolPhunch: number;
+    crowdPct: number | null;
+}
+/** One of a spin's 42 parimutuel markets. */
+export interface RouletteAgentMarket {
+    id: string;
+    question: string;
+    short: string;
+    poolPhunch: number;
+    outcomes: RouletteAgentOutcome[];
+}
+/** The live roulette round as an agent sees it (from `getRouletteRound`). */
+export interface RouletteRoundView {
+    roundNo: number;
+    phase: "bet" | "spin" | "result";
+    betOpenAt: number;
+    spinStartAt: number;
+    resultAt: number;
+    nextRoundAt: number;
+    secondsToClose: number;
+    pocket: number | null;
+    bounds: {
+        minBet: number;
+        maxBet: number;
+        maxRoundTotal: number;
+    };
+    bettors: number;
+    stakedPhunch: number;
+    markets: RouletteAgentMarket[];
+    history: Array<{
+        roundNo: number;
+        pocket: number;
+    }>;
+}
+/** A roulette bet receipt — a simulate quote or a settled real placement. */
+export interface RouletteBetReceipt {
+    simulated: boolean;
+    roundNo: number;
+    betKey: string;
+    stakePhunch: number;
+    /** Real bets: balance after the debit. */
+    balancePhunch?: number;
+    /** Real bets: idempotent replay of an already-placed (wallet, round, key). */
+    replay?: boolean;
+    /** Simulate: the phase the quote was taken in. */
+    phase?: "bet" | "spin" | "result";
+    /** Simulate: the whole market pool + crowd/true % + self-diluting estimate. */
+    marketPoolPhunch?: number;
+    keyStakePhunch?: number;
+    crowdPct?: number | null;
+    truePct?: number;
+    estPayoutIfWinPhunch?: number;
 }
 export declare class CupClient {
     private readonly baseUrl;
     private readonly signer?;
     private readonly fetchImpl;
+    private readonly autoEnroll;
+    /** One self-enroll attempt per client — never loop against a refusing server. */
+    private enrollTried;
     constructor(opts?: CupClientOptions);
     get address(): string | undefined;
     private json;
@@ -75,6 +154,14 @@ export declare class CupClient {
         balancePhunch: number;
         minted: boolean;
     }>;
+    /**
+     * Declare this wallet a SELF-OPERATED agent (one signed call, idempotent).
+     *
+     * While the house-fleet halt is on, real trades 503 unless the wallet has
+     * enrolled. This is the self-serve way past it: no ticket, no waiting, and it
+     * works before the halt exists too (enroll once and never think about it).
+     */
+    enroll(note?: string): Promise<CupEnrollment>;
     listMarkets(limit?: number, offset?: number): Promise<CupMarket[]>;
     getQuote(slug: string, side: string, sizePhunch: number): Promise<{
         shares: number;
@@ -83,13 +170,44 @@ export declare class CupClient {
     }>;
     /** A dry run — full pricing, no signature, no write. */
     simulateTrade(slug: string, side: string, sizePhunch: number): Promise<CupTradeReceipt>;
-    /** Place a REAL signed paper trade. Idempotent by the generated/own tradeId. */
+    /**
+     * Place a REAL signed paper trade. Idempotent by the generated/own tradeId.
+     *
+     * If the write is refused by the house-fleet halt and this wallet has not
+     * enrolled yet, enrolls once and retries the SAME tradeId (so the retry can
+     * never double-spend). That is the whole point of self-enrollment: a person
+     * running their own agent should not have to know the halt exists. Opt out
+     * with `autoEnroll: false`.
+     */
     trade(args: {
         slug: string;
         side: string;
         sizePhunch: number;
         tradeId?: string;
     }): Promise<CupTradeReceipt>;
+    private placeTrade;
+    /**
+     * Read the live roulette round: phase, seconds-to-close, stake bounds, and all
+     * 42 parimutuel markets with their bet keys, the wheel's true k/37 %, and the
+     * live crowd pools. Pass `wallet` to include that wallet's bets on the round.
+     * Public — no signer needed.
+     */
+    getRouletteRound(wallet?: string): Promise<RouletteRoundView>;
+    /**
+     * Dry-run a roulette bet: a live pool quote (crowd % vs true %, plus a
+     * self-diluting pay-if-win estimate). No signature, no write.
+     */
+    simulateRouletteBet(betKey: string, stakePhunch: number, roundNo?: number): Promise<RouletteBetReceipt>;
+    /**
+     * Place a REAL signed roulette bet on the live spin. Learns the current
+     * `roundNo` if you don't pass one, signs the canonical roulette message, and
+     * posts it. Idempotent by the natural (wallet, round, betKey) key.
+     */
+    rouletteBet(args: {
+        betKey: string;
+        stakePhunch: number;
+        roundNo?: number;
+    }): Promise<RouletteBetReceipt>;
     /** Typed wallet summary: balance + realized PnL + positions, all in $pUSDC. */
     getWallet(address?: string): Promise<CupWalletView>;
     /** @deprecated use {@link getWallet}. Kept for back-compat. */
@@ -129,6 +247,12 @@ export declare class CupClient {
      * 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.
+     *
+     * Catching everything is right for a blip and wrong for a refusal: when the
+     * server says `retryable: false` (the agent-write halt), re-firing every
+     * interval forever is pure waste on both sides — it bills us for the 503s the
+     * halt exists to avoid, and it buries the one message the operator needs to
+     * read. Such a round reports via `onHalt` (or `onError`) and ENDS the loop.
      */
     runLoop(opts: {
         strategy: CupStrategy;
@@ -143,5 +267,7 @@ export declare class CupClient {
         rounds?: number;
         onRound?: (round: number, receipts: CupTradeReceipt[]) => void;
         onError?: (round: number, err: unknown) => void;
+        /** Called instead of `onError` when the run stops on a non-retryable refusal. */
+        onHalt?: (round: number, err: CupApiError) => void;
     }): Promise<void>;
 }

package/dist/client.js

@@ -7,17 +7,22 @@
  * 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}.
  */
-import { buildCupTradeMessage } from "./message.js";
+import { buildCupTradeMessage, buildRouletteBetMessage, buildCupEnrollMessage, } from "./message.js";
+import { CupApiError, isCupHaltError } from "./errors.js";
 import { pickFor } from "./strategy.js";
 export const DEFAULT_BASE_URL = "https://www.playhunch.xyz";
 export class CupClient {
     baseUrl;
     signer;
     fetchImpl;
+    autoEnroll;
+    /** One self-enroll attempt per client — never loop against a refusing server. */
+    enrollTried = false;
     constructor(opts = {}) {
         this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
         this.signer = opts.signer;
         this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.autoEnroll = opts.autoEnroll ?? true;
     }
     get address() {
         return this.signer?.address;
@@ -26,8 +31,12 @@ export class CupClient {
         const res = await this.fetchImpl(`${this.baseUrl}${path}`, init);
         const body = (await res.json().catch(() => null));
         if (!res.ok) {
-            const err = (body && body.error) || `http_${res.status}`;
-            throw new Error(`Hunch Cup ${path} failed: ${err}`);
+            throw new CupApiError({
+                status: res.status,
+                code: (body && body.error) || `http_${res.status}`,
+                path,
+                body: body ?? null,
+            });
         }
         return body;
     }
@@ -45,6 +54,28 @@ export class CupClient {
             body: JSON.stringify({ walletAddress: signer.address }),
         });
     }
+    /**
+     * Declare this wallet a SELF-OPERATED agent (one signed call, idempotent).
+     *
+     * While the house-fleet halt is on, real trades 503 unless the wallet has
+     * enrolled. This is the self-serve way past it: no ticket, no waiting, and it
+     * works before the halt exists too (enroll once and never think about it).
+     */
+    async enroll(note) {
+        const signer = this.requireSigner();
+        const issuedAt = nowIso();
+        const signature = await signer.signMessage(buildCupEnrollMessage({ walletAddress: signer.address, issuedAt }));
+        return this.json("/api/cup/v1/agent/enroll", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                walletAddress: signer.address,
+                issuedAt,
+                signature,
+                ...(note ? { note } : {}),
+            }),
+        });
+    }
     async listMarkets(limit = 25, offset = 0) {
         const qs = new URLSearchParams({ limit: String(limit) });
         if (offset > 0)
@@ -71,10 +102,31 @@ export class CupClient {
         });
         return out.receipt;
     }
-    /** Place a REAL signed paper trade. Idempotent by the generated/own tradeId. */
+    /**
+     * Place a REAL signed paper trade. Idempotent by the generated/own tradeId.
+     *
+     * If the write is refused by the house-fleet halt and this wallet has not
+     * enrolled yet, enrolls once and retries the SAME tradeId (so the retry can
+     * never double-spend). That is the whole point of self-enrollment: a person
+     * running their own agent should not have to know the halt exists. Opt out
+     * with `autoEnroll: false`.
+     */
     async trade(args) {
-        const signer = this.requireSigner();
         const tradeId = args.tradeId ?? `cup:${args.slug}:${args.side}:${randomId()}`;
+        try {
+            return await this.placeTrade({ ...args, tradeId });
+        }
+        catch (err) {
+            if (!isCupHaltError(err) || !this.autoEnroll || this.enrollTried)
+                throw err;
+            this.enrollTried = true;
+            await this.enroll(); // throws on its own terms; a failed enroll surfaces as-is
+            return this.placeTrade({ ...args, tradeId });
+        }
+    }
+    async placeTrade(args) {
+        const signer = this.requireSigner();
+        const tradeId = args.tradeId;
         const issuedAt = nowIso();
         const message = buildCupTradeMessage({
             walletAddress: signer.address,
@@ -100,6 +152,66 @@ export class CupClient {
         });
         return out.receipt;
     }
+    /**
+     * Read the live roulette round: phase, seconds-to-close, stake bounds, and all
+     * 42 parimutuel markets with their bet keys, the wheel's true k/37 %, and the
+     * live crowd pools. Pass `wallet` to include that wallet's bets on the round.
+     * Public — no signer needed.
+     */
+    async getRouletteRound(wallet) {
+        const addr = wallet ?? this.signer?.address;
+        const qs = addr ? `?wallet=${addr}` : "";
+        return this.json(`/api/cup/v1/roulette${qs}`);
+    }
+    /**
+     * Dry-run a roulette bet: a live pool quote (crowd % vs true %, plus a
+     * self-diluting pay-if-win estimate). No signature, no write.
+     */
+    async simulateRouletteBet(betKey, stakePhunch, roundNo) {
+        const out = await this.json("/api/cup/v1/roulette/bet", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                walletAddress: this.signer?.address ?? "0x" + "0".repeat(40),
+                betKey,
+                stakePhunch,
+                roundNo,
+                simulate: true,
+            }),
+        });
+        return out.receipt;
+    }
+    /**
+     * Place a REAL signed roulette bet on the live spin. Learns the current
+     * `roundNo` if you don't pass one, signs the canonical roulette message, and
+     * posts it. Idempotent by the natural (wallet, round, betKey) key.
+     */
+    async rouletteBet(args) {
+        const signer = this.requireSigner();
+        const roundNo = args.roundNo ?? (await this.getRouletteRound()).roundNo;
+        const issuedAt = nowIso();
+        const message = buildRouletteBetMessage({
+            walletAddress: signer.address,
+            roundNo,
+            betKey: args.betKey,
+            sizePhunch: args.stakePhunch,
+            issuedAt,
+        });
+        const signature = await signer.signMessage(message);
+        const out = await this.json("/api/cup/v1/roulette/bet", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                walletAddress: signer.address,
+                roundNo,
+                betKey: args.betKey,
+                stakePhunch: args.stakePhunch,
+                issuedAt,
+                signature,
+            }),
+        });
+        return out.receipt;
+    }
     /** Typed wallet summary: balance + realized PnL + positions, all in $pUSDC. */
     async getWallet(address) {
         const addr = address ?? this.signer?.address;
@@ -199,6 +311,12 @@ export class CupClient {
      * 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.
+     *
+     * Catching everything is right for a blip and wrong for a refusal: when the
+     * server says `retryable: false` (the agent-write halt), re-firing every
+     * interval forever is pure waste on both sides — it bills us for the 503s the
+     * halt exists to avoid, and it buries the one message the operator needs to
+     * read. Such a round reports via `onHalt` (or `onError`) and ENDS the loop.
      */
     async runLoop(opts) {
         for (let round = 1; !opts.rounds || round <= opts.rounds; round += 1) {
@@ -207,6 +325,13 @@ export class CupClient {
                 opts.onRound?.(round, receipts);
             }
             catch (err) {
+                if (err instanceof CupApiError && !err.retryable) {
+                    if (opts.onHalt)
+                        opts.onHalt(round, err);
+                    else
+                        opts.onError?.(round, err);
+                    return; // permanent refusal — retrying it every interval helps no one
+                }
                 opts.onError?.(round, err);
             }
             if (opts.rounds && round >= opts.rounds)

package/dist/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Typed API errors for the Hunch Cup rail.
+ *
+ * The SDK used to collapse every non-2xx into `new Error("Hunch Cup <path>
+ * failed: <code>")`, which meant a caller could not tell a transient blip from
+ * a permanent refusal — and the CLI printed the raw code (`cup_agent_trades_
+ * halted`) with no explanation, which reads as a crash. {@link CupApiError}
+ * keeps the status, the machine code and the server's whole JSON body so both
+ * the loop and the CLI can make a real decision.
+ */
+/** A non-2xx response from `/api/cup/v1/*`, with the server's code + body. */
+export declare class CupApiError extends Error {
+    readonly name = "CupApiError";
+    /** HTTP status. */
+    readonly status: number;
+    /** The server's `error` code (e.g. `market_closed`), or `http_<status>`. */
+    readonly code: string;
+    /** The request path, for context in logs. */
+    readonly path: string;
+    /** The full parsed JSON body, when there was one. */
+    readonly body: Record<string, unknown> | null;
+    constructor(args: {
+        status: number;
+        code: string;
+        path: string;
+        body: Record<string, unknown> | null;
+    });
+    /** The server's human-readable hint, when it sent one. */
+    get hint(): string | undefined;
+    /**
+     * `false` when the server explicitly said not to retry. Unknown/transient
+     * failures stay `true` so a network blip never silently kills a long run.
+     */
+    get retryable(): boolean;
+}
+/** The agent-write halt: paper trading is off for everyone not allow-listed. */
+export declare const CUP_HALT_CODE = "cup_agent_trades_halted";
+/** `true` when this error is the agent-write halt (a permanent 503, not a blip). */
+export declare function isCupHaltError(err: unknown): err is CupApiError;
+/**
+ * The message the CLI prints when an agent hits the halt. Written for a human
+ * who just ran `--live` and got refused: say it is not their fault, say what
+ * still works right now, and say how to get unblocked.
+ */
+export declare function cupHaltMessage(err?: CupApiError): string;

package/dist/errors.js

@@ -0,0 +1,83 @@
+/**
+ * Typed API errors for the Hunch Cup rail.
+ *
+ * The SDK used to collapse every non-2xx into `new Error("Hunch Cup <path>
+ * failed: <code>")`, which meant a caller could not tell a transient blip from
+ * a permanent refusal — and the CLI printed the raw code (`cup_agent_trades_
+ * halted`) with no explanation, which reads as a crash. {@link CupApiError}
+ * keeps the status, the machine code and the server's whole JSON body so both
+ * the loop and the CLI can make a real decision.
+ */
+/** A non-2xx response from `/api/cup/v1/*`, with the server's code + body. */
+export class CupApiError extends Error {
+    name = "CupApiError";
+    /** HTTP status. */
+    status;
+    /** The server's `error` code (e.g. `market_closed`), or `http_<status>`. */
+    code;
+    /** The request path, for context in logs. */
+    path;
+    /** The full parsed JSON body, when there was one. */
+    body;
+    constructor(args) {
+        super(`Hunch Cup ${args.path} failed: ${args.code}`);
+        this.status = args.status;
+        this.code = args.code;
+        this.path = args.path;
+        this.body = args.body;
+    }
+    /** The server's human-readable hint, when it sent one. */
+    get hint() {
+        const hint = this.body?.hint;
+        return typeof hint === "string" ? hint : undefined;
+    }
+    /**
+     * `false` when the server explicitly said not to retry. Unknown/transient
+     * failures stay `true` so a network blip never silently kills a long run.
+     */
+    get retryable() {
+        return this.body?.retryable !== false;
+    }
+}
+/** The agent-write halt: paper trading is off for everyone not allow-listed. */
+export const CUP_HALT_CODE = "cup_agent_trades_halted";
+/** `true` when this error is the agent-write halt (a permanent 503, not a blip). */
+export function isCupHaltError(err) {
+    return err instanceof CupApiError && err.code === CUP_HALT_CODE;
+}
+/**
+ * The message the CLI prints when an agent hits the halt. Written for a human
+ * who just ran `--live` and got refused: say it is not their fault, say what
+ * still works right now, and say how to get unblocked.
+ */
+export function cupHaltMessage(err) {
+    const unblock = (typeof err?.body?.unblockUrl === "string" && err.body.unblockUrl) ||
+        "https://x.com/playhunchxyz";
+    const enroll = (typeof err?.body?.enrollCommand === "string" && err.body.enrollCommand) ||
+        "npx hunch-cup enroll";
+    return [
+        "Hunch Cup: live agent trading is HALTED for the house fleets (503).",
+        "",
+        "It is not halted for you. Nothing is wrong with your agent, your wallet, or",
+        "your signature — the switch exists to stop our own bot fleets, and it can't",
+        "tell them apart from you until you say so. One signed call fixes that:",
+        "",
+        `  ${enroll}`,
+        "",
+        "That declares this wallet a self-operated agent and reopens live trading for",
+        "it immediately — no ticket, no waiting. (The CLI normally does this for you",
+        "on the first refusal; you're seeing this because that step didn't complete.)",
+        "",
+        "Working regardless, enrolled or not:",
+        "",
+        "  hunch-cup run momentum 25        dry run — same picks, full pricing, no write",
+        "  hunch-cup markets                the live paper catalogue",
+        "  hunch-cup quote <slug> <side> 25 live pool-implied odds",
+        "  hunch-cup board                  the leaderboard",
+        "",
+        "Your balance and positions are untouched — the halt freezes writes, it does",
+        "not unwind anything.",
+        "",
+        `Still stuck? ${unblock} can allow-list your wallet address directly.`,
+    ].join("\n");
+}

package/dist/fleet.d.ts

@@ -24,6 +24,10 @@ export declare function fleetNew(count: number, baseUrl?: string): Promise<Fleet
  * 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`.
+ *
+ * Resolves `{ halted: true }` when the run ended on a non-retryable server
+ * refusal (the agent-write halt) rather than on its round budget, so a caller
+ * can exit with a code that tells a supervisor not to restart it hot.
  */
 export declare function fleetRun(opts: {
     defaultStrategy: CupStrategy;
@@ -33,7 +37,9 @@ export declare function fleetRun(opts: {
     limit?: number;
     rounds?: number;
     onEvent?: (line: string) => void;
-}): Promise<void>;
+}): Promise<{
+    halted: boolean;
+}>;
 /**
  * Coordinated round loop: instead of every wallet running its own perpetual
  * loop, each ROUND a random subset of `participants()` wallets acts once (via

package/dist/fleet.js

@@ -16,6 +16,7 @@ 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 { CupApiError, isCupHaltError, cupHaltMessage } from "./errors.js";
 import { fromPrivateKey, newWallet } from "./signer.js";
 export function fleetFilePath() {
     return process.env.HUNCH_CUP_FLEET_FILE ?? join(homedir(), ".hunch-cup", "fleet.json");
@@ -73,14 +74,19 @@ export async function fleetNew(count, baseUrl) {
  * 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`.
+ *
+ * Resolves `{ halted: true }` when the run ended on a non-retryable server
+ * refusal (the agent-write halt) rather than on its round budget, so a caller
+ * can exit with a code that tells a supervisor not to restart it hot.
  */
 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;
+        return { halted: false };
     }
     const stagger = Math.floor(opts.intervalMs / Math.max(1, fleet.wallets.length));
+    let halted;
     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) });
@@ -94,8 +100,18 @@ export async function fleetRun(opts) {
             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)}`),
+            // A halt hits every wallet at once; printing the full explainer N times
+            // would bury it. One line each, and the caller prints the explainer.
+            onHalt: (round, err) => {
+                halted ??= err;
+                opts.onEvent?.(`[${w.name}] round ${round} stopped: ${err.code}`);
+            },
         });
     }));
+    if (halted) {
+        opts.onEvent?.(`\n${cupHaltMessage(isCupHaltError(halted) ? halted : undefined)}`);
+    }
+    return { halted: Boolean(halted) };
 }
 /**
  * Coordinated round loop: instead of every wallet running its own perpetual
@@ -111,6 +127,7 @@ export async function fleetRunRounds(opts) {
         opts.onEvent?.("No fleet wallets. Run `hunch-cup fleet new <n>` first.");
         return;
     }
+    let halted;
     for (let round = 1; !opts.rounds || round <= opts.rounds; round += 1) {
         const n = Math.max(1, Math.min(fleet.wallets.length, Math.floor(opts.participants?.() ?? fleet.wallets.length)));
         const chosen = shuffle(fleet.wallets).slice(0, n);
@@ -131,9 +148,18 @@ export async function fleetRunRounds(opts) {
                 opts.onEvent?.(`[${w.name}] round ${round}: ${receipts.length} trade(s)`);
             }
             catch (err) {
+                // A non-retryable refusal (the agent-write halt) applies to the whole
+                // roster, not this wallet — keep looping and every remaining round is
+                // just paid-for 503s. Record it and stop after the round drains.
+                if (err instanceof CupApiError && !err.retryable)
+                    halted ??= err;
                 opts.onEvent?.(`[${w.name}] round ${round} error: ${err instanceof Error ? err.message : String(err)}`);
             }
         }));
+        if (halted) {
+            opts.onEvent?.(`\n${cupHaltMessage(isCupHaltError(halted) ? halted : undefined)}`);
+            return;
+        }
         if (opts.rounds && round >= opts.rounds)
             break;
         await sleep(opts.intervalMs);

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 export { CupClient, DEFAULT_BASE_URL } from "./client.js";
-export type { CupClientOptions, CupSigner, CupMarket, CupOutcome, CupPosition, CupWalletView, CupTradeReceipt, } from "./client.js";
+export type { CupClientOptions, CupSigner, CupMarket, CupOutcome, CupPosition, CupWalletView, CupTradeReceipt, RouletteAgentOutcome, RouletteAgentMarket, RouletteRoundView, RouletteBetReceipt, } from "./client.js";
+export { CupApiError, isCupHaltError, cupHaltMessage, CUP_HALT_CODE } from "./errors.js";
 export { fromViemAccount, fromPrivateKey, newWallet } from "./signer.js";
-export { buildCupTradeMessage } from "./message.js";
-export type { CupTradeMessageParams } from "./message.js";
+export { buildCupTradeMessage, buildRouletteBetMessage } from "./message.js";
+export type { CupTradeMessageParams, RouletteBetMessageParams } from "./message.js";
 export { pickFor, momentumPick, contrarianPick, newsReactivePick, randomPick, } from "./strategy.js";
 export type { CupStrategy, StrategyCard, StrategyOutcome, StrategyPick, } from "./strategy.js";
 export { fleetNew, fleetRun, fleetRunRounds, fleetBoard, loadFleet, saveFleet, fleetFilePath, } from "./fleet.js";
 export type { Fleet, FleetWallet } from "./fleet.js";
+export { buildCupEnrollMessage } from "./message.js";
+export type { CupEnrollMessageParams } from "./message.js";
+export type { CupEnrollment } from "./client.js";

package/dist/index.js

@@ -1,5 +1,7 @@
 export { CupClient, DEFAULT_BASE_URL } from "./client.js";
+export { CupApiError, isCupHaltError, cupHaltMessage, CUP_HALT_CODE } from "./errors.js";
 export { fromViemAccount, fromPrivateKey, newWallet } from "./signer.js";
-export { buildCupTradeMessage } from "./message.js";
+export { buildCupTradeMessage, buildRouletteBetMessage } from "./message.js";
 export { pickFor, momentumPick, contrarianPick, newsReactivePick, randomPick, } from "./strategy.js";
 export { fleetNew, fleetRun, fleetRunRounds, fleetBoard, loadFleet, saveFleet, fleetFilePath, } from "./fleet.js";
+export { buildCupEnrollMessage } from "./message.js";

package/dist/message.d.ts

@@ -15,3 +15,32 @@ export interface CupTradeMessageParams {
     issuedAt: string;
 }
 export declare function buildCupTradeMessage(p: CupTradeMessageParams): string;
+/**
+ * The canonical Hunch Cup ROULETTE-bet signing message.
+ *
+ * MUST stay byte-identical to the server core (`src/core/cup/agent-auth.ts`
+ * `buildRouletteBetMessage`) — a parity test asserts the two agree. Domain-
+ * separated from {@link buildCupTradeMessage} so a trade signature can't be
+ * replayed as a roulette bet. `roundNo` binds the bet to one 60s spin; no
+ * tradeId — roulette idempotency is the natural (wallet, round, betKey) key.
+ */
+export interface RouletteBetMessageParams {
+    walletAddress: string;
+    roundNo: number;
+    betKey: string;
+    sizePhunch: number;
+    issuedAt: string;
+}
+export declare function buildRouletteBetMessage(p: RouletteBetMessageParams): string;
+export interface CupEnrollMessageParams {
+    walletAddress: string;
+    /** ISO-8601 timestamp the agent signed at (freshness-checked server-side). */
+    issuedAt: string;
+}
+/**
+ * The canonical statement a wallet signs to ENROLL as a self-operated agent.
+ * Domain-separated from the trade and roulette statements, and byte-identical to
+ * `buildCupEnrollMessage` in `src/core/cup/agent-auth.ts` — a drift here means a
+ * valid signature that the server refuses.
+ */
+export declare function buildCupEnrollMessage(p: CupEnrollMessageParams): string;

package/dist/message.js

@@ -9,3 +9,27 @@ export function buildCupTradeMessage(p) {
         `Issued: ${p.issuedAt}`,
     ].join("\n");
 }
+export function buildRouletteBetMessage(p) {
+    return [
+        "Hunch Cup roulette bet",
+        `Wallet: ${p.walletAddress.toLowerCase()}`,
+        `Round: ${p.roundNo}`,
+        `Bet: ${p.betKey}`,
+        `Size: ${p.sizePhunch} pUSDC`,
+        `Issued: ${p.issuedAt}`,
+    ].join("\n");
+}
+/**
+ * The canonical statement a wallet signs to ENROLL as a self-operated agent.
+ * Domain-separated from the trade and roulette statements, and byte-identical to
+ * `buildCupEnrollMessage` in `src/core/cup/agent-auth.ts` — a drift here means a
+ * valid signature that the server refuses.
+ */
+export function buildCupEnrollMessage(p) {
+    return [
+        "Hunch Cup agent enrollment",
+        `Wallet: ${p.walletAddress.toLowerCase()}`,
+        "I operate this agent myself.",
+        `Issued: ${p.issuedAt}`,
+    ].join("\n");
+}

package/package.json

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