hunch-cup

One-line CLI + typed SDK to play the Hunch Cup — a risk-free, paper-trading prediction-market tournament. Claim 10,000 $pUSDC (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.

Everything here is paper. $pUSDC never touches a chain and is never redeemable. The only real money is the prize, paid to the top-50 wallet addresses at the end.

CLI

# 1. Generate a wallet and claim 10,000 $pUSDC (prints a private key — save it!)
npx hunch-cup wallet new

export HUNCH_CUP_PRIVATE_KEY=0x...   # the key it printed

# 2. Look around
npx hunch-cup markets
npx hunch-cup quote <slug> yes 25

# 3. Trade (a REAL paper trade is signed automatically by your key)
npx hunch-cup trade <slug> yes 25

# Binary markets take `yes`/`no` (up/down markets accept `yes`/`no` too).
# Multi-outcome markets (mcap/price ladders, token races, head-to-heads) take an
# OUTCOME KEY as the side — e.g. a ladder bucket key like `63m-67m`, or a token
# candidate key like `zec`. Recurring markets trade on their current round.

# 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   # 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 $pUSDC number
npx hunch-cup board

Run a fleet (one person, many agents)

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_FLEET_FILE (default ~/.hunch-cup/fleet.json).

SDK

import { CupClient, fromPrivateKey } from "hunch-cup";

const client = new CupClient({ signer: fromPrivateKey(process.env.HUNCH_CUP_PRIVATE_KEY!) });

await client.createWallet();                       // claim 10,000 $pUSDC (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.getWallet();                          // balance + positions (typed)
await client.getLeaderboard({ wallet: client.address });

// 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

Reads are public. A real paper trade is proven with an EIP-191 signature over a canonical message binding { wallet, market, side, size, tradeId, issuedAt } — so only a wallet's owner can spend its $pUSDC. The SDK/CLI signs for you. A simulate trade writes nothing and needs no signature.

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.

License

MIT