PlayHunch docs.

Hunch turns prediction markets into a feed you can swipe. Back YES or NO on live markets — token milestones, up/down rounds, launchpad races, head-to-heads and more — with tickets small enough for fast discovery.

Every bet settles in USDC on Base with gas sponsored, so you sign once and a relayer pays the network fee. An agent rides under each market to route the best odds and keep proof attached to the trade. The same markets are bettable by humans and by autonomous agents over a keyless x402 rail.

A bet on Hunch is a single signed USDC payment on Base. You never need ETH for gas — a relayer pays the network fee and moves your USDC with an EIP-3009 authorized transfer, so the whole thing is one signature.

Markets are parimutuel: your stake joins a pool, and when the market resolves the whole pool (net of a small fee) is split among the winning side. There is no order book and no house taking the other side.

1. 1

   Pick a market — From the swipe feed, the explorer, or a shared link.

2. 2

   Sign once — Authorize the USDC transfer. Gas is sponsored by the relayer.

3. 3

   Settle on Base — The relayer broadcasts the EIP-3009 transfer; your stake joins the pool.

4. 4

   Market resolves — An automated resolver (or a human, for manual markets) decides the outcome from real data.

5. 5

   Auto-payout — Winners are paid straight to their wallet — no claim step.

You can browse every market signed out. To bet, you need a wallet and a little USDC on Base — both take seconds to set up.

1. 1

   Sign in — Connect a wallet or use the embedded wallet — an account is created for you on first sign-in.

2. 2

   Add USDC — Add funds to the same Base address you bet from. Tickets start small, so a few dollars is plenty to explore.

3. 3

   Find a market — Swipe the feed or search the explorer for a token or theme you have a view on.

4. 4

   Size and confirm — Choose YES or NO, set a ticket, and sign once. Your bet is live the moment it settles.

The swipe feed is a Tinder-style deck of the markets we built. Swipe right for YES, left for NO, or open a card for the full chart, snapshot, and a sized bet.

Tickets stay small by design so you can explore breadth quickly. Closing-soonest markets lead the deck, then milestones and flips by deadline.

• Swipe right → YES · swipe left → NO · tap a card to open the full detail page.
• Inline $1 bets settle over the same audited trade route the explorer and agents use.
• The deck is ranked by how soon each market closes, so time-sensitive calls surface first.

The explorer lists every live market with probability-forward cards. Search instantly by token ($BNKR, $HUNCH), chain (Base, Solana), or any keyword, and filter by status and market type.

Open any card for the detail page: live odds, the total bet so far, charts, a market snapshot, and related markets for the same token and type.

• Search by cashtag, chain, or free text — results update as you type.
• Filter by status (open, locked, resolved) and by market type.
• Cards show live odds and trailing-24h volume; lists paginate with a cursor so large catalogues stay fast.

Your balance, deposits, withdrawals, and receipts are built around USDC on Base so the money path is always legible. Add funds to the same address you bet from, and withdraw to any Base address.

Bets and payouts are relayed — you never need ETH for gas — and every settlement carries an on-chain proof link you can verify on BaseScan. If you use the embedded wallet, you can export your own key at any time.

1. 1

   Add funds — Top up USDC on Base to the address you bet from.

2. 2

   Withdraw — Send USDC to any Base address; the same relayer covers gas.

3. 3

   Export key — Own the embedded wallet outright — export the private key whenever you want.

Every market — whatever it predicts — shares one shape. It has a subject (a token, a chain, an event), a set of outcomes you bet on, a deadline, a parimutuel fee, and a settlement rail. It moves through the same lifecycle from draft to paid.

• Outcomes are binary (YES/NO, or UP/DOWN for direction markets) or N-way (a ladder of ranges, or a field of named candidates).
• A small parimutuel fee (2% by default) is the only cut; the rest of the pool flows to winners.
• Markets settle on a rail — Base USDC by default, with Sui and an Arbitrum vault as parallel rails.

Hunch runs more than twenty distinct market types. They look different on the surface — a price ladder, a head-to-head, an up/down round — but they reduce to a handful of families that share resolution and payout machinery.

The chart groups every type by family; the table below is the complete reference. "Early-lock" means the market can resolve the instant the outcome is locked, rather than waiting for the deadline.

Milestone markets ask a single yes-or-no question: will a token, a chain, or a metric cross a line by a date? They settle YES the instant the line is crossed (early-lock) and NO if the deadline arrives untouched.

This family covers token market-cap targets, top-N rank milestones (excluding stablecoins), chain TPS / TVL / stablecoin-supply milestones, and arbitrary on-chain usage metrics read from Dune.

A ladder splits a range into N bands and asks which one a token will close in. Market-cap ladders (token_mcap_range) and price-strike ladders (token_price_range) share one engine; only the metric differs.

Ladders are end-state markets: they read the closing value at the deadline, so they don't early-lock. Each band is its own outcome, and the parimutuel pool is split among everyone who picked the winning band.

• Bands are usually centred on the live value so the current reading sits mid-ladder.
• Exactly one band wins; it's an N-way market, not YES/NO.
• Resolution reads the latest value at or before the deadline.

Head-to-heads pit two or more subjects against each other. Will token A out-return token B? Will A flip B in market cap? Which chain does more DEX volume? Which token reaches a top-N rank first?

Flips and rank races early-lock the moment the cross is confirmed; return comparisons are end-state and settle at the deadline. Flips resolve by mint address via a chain-agnostic search, so any two tokens — including Solana pump.fun launches — work with no resolver changes.

• token_outperform — best performer among a field over a window (N-way).
• token_return_compare — A vs B on return (binary, end-state).
• token_mcap_flip — A passes B in market cap (binary, early-lock by address).
• chain_dex_volume_compare — chain vs chain on DEX volume.
• token_rank_race — first token into the top-N by market cap (N-way, no deadline).

Up/Down markets (price_direction) are recurring rounds on whether a token closes a window up or down. They run on cadences from every few minutes to weekly and monthly, and a tick resolves and pays each round as its window closes.

These markets label their outcomes UP and DOWN — never YES/NO. A round where the open and close are exactly equal is a flat tie: it resolves to a VOID sentinel and refunds everyone in full, closing the one-sided-book trap.

Count-the-days markets ask whether a threshold number of qualifying days will occur inside a window: days a chain's DEX volume closes over a line (dex_volume_days), days a launchpad token leads by volume, or how many launches clear a market-cap bar.

They're early-lockable count-ups: as soon as the required number of days banks, the market resolves YES — it doesn't need to wait for the window to end.

A volume_crossing_date market asks not whether but when: in which window does a metric first cross a line? Outcomes are date windows, and the market resolves to the window containing the first confirmed crossing.

The source is pluggable — a Dune cumulative total, a Dune level series, a daily-peak count, a CoinGecko supply or price, or a DeFiLlama total. Non-monotonic sources (price, on-chain supply) are safe because a first crossing needs two readings at least 30 minutes apart, so a single flash wick can't settle it.

A token_basket_mcap market sums the market caps of a set of tokens and asks whether the combined figure reaches a target. It's a milestone over many subjects at once — handy for an ecosystem or a launchpad cohort.

Members without a tradable pair are excluded up front so a missing price can't brick settlement. The combined cap is read from DexScreener for each member and summed.

Some questions have no automated feed: the outcome of a real-world event (event_outcome) or the winner of a named head-to-head contest (event_versus). These stay pending until a human records the resolution out-of-band, with proof links attached.

The trading and payout machinery is identical to the automated markets — event_versus reuses the same parimutuel book and payout authority as the on-chain head-to-heads. Only the resolution step is manual.

Resolution is deterministic. A resolver is a pure function: given a market and a set of timestamped observations, it returns an outcome (or stays pending). Nothing about the result depends on who runs it or when, beyond the clock it compares the deadline against.

Readings come from a small set of sources, land in an observation store, and the resolver reads from there. Threshold markets resolve the instant the outcome is locked; end-state markets refuse to resolve until the deadline.

Hunch is parimutuel: with two or more participants, the entire net pool — every stake on both sides, net of the entry fee — is split among the winning side pro-rata by net stake. A payout can never exceed the pool the market collected, so the house carries zero exposure.

All of this comes from one pure function, computeMarketPayouts, which is the single source of truth for every rail. The lib runner is the only thing that touches the database or the chain.

• Two or more participants → parimutuel split, pro-rata by net stake, minus the 2% fee.
• Single participant → full gross refund (the fee is returned), whichever way it resolved — there's no counterparty to win from.
• Flat-tie VOID round → every participant refunded in full gross.
• Payouts are pushed automatically on resolution; there is no claim transaction.

Your Stack is every position you hold and everything you've settled. Open positions show the realizable payout if the market resolved now — computed from the same parimutuel logic that pays you — so a sole $9 bet shows $9, not an imaginary multiple.

Settled markets show what you actually won or got back, with a link to the on-chain receipt.

There's no off-chain ledger to trust. Every bet and every payout is a USDC transfer on Base, and each one carries a proof link you can open on BaseScan. Shared proof pages let anyone verify a specific result.

Because settlement is on-chain, the money path is legible end to end: stake in, pool, payout out.

The leaderboard ranks the sharpest callers, and streaks reward consistency. It's a lightweight social layer on top of real, settled results — not vanity metrics.

Referrals turn a shared link into attribution: invite friends and earn from the volume they bring. Referral links route into the same one-tap market pages as any other entrypoint, with attribution preserved.

Links shared on X and Telegram route straight into one-tap market pages with attribution preserved, so a tag becomes a bet in a single step.

Tag @bankrbot on a token and Hunch surfaces the related markets to back — the same markets you'd find in the explorer, discoverable from the conversation.

Hunch ships as a Mini App inside the Base App using the standard web-app model. Inside the Base App your wallet auto-connects, so discovery and betting work without a separate connect step.

It's the same app and the same markets — just embedded where Base users already are.

Markets settle on a rail. Base USDC is the default and the live money path. Sui runs a live mainnet Move vault with user-pays-gas betting. An Arbitrum parimutuel vault runs as a parallel rail behind a flag.

Whatever the rail, payouts are computed by the same pure logic — the rail only changes where value moves, never how winners are decided.

Two rules anchor the system. First, pricing and resolution are deterministic — the agent never invents a market or a price, and an LLM's output never settles a bet or moves money. Second, the payout math lives in one audited function shared by every rail.

On the surface, the app respects reduced-motion preferences and is built mobile-first with accessible controls.

• LLM use is confined behind a client port and never trusted into a money path.
• Pricing is deterministic; the agent only routes within markets Hunch already lists.
• Animations back off for users who ask for reduced motion (WCAG 2.3.3).

The agent platform lets any wallet-holding agent discover a market, research it, simulate a bet for $0, place a real one with a single x402 USDC payment on Base, and get paid automatically on resolution — with no API key, no signup, and no claim step.

It's exposed two ways over the same audited core: a REST API at /api/agent/v1 and a remote MCP server at /api/mcp.

• Keyless: identity is the wallet that signs the x402 payment — no key, no signup.
• Simulate for $0 before risking funds; place_bet defaults to a simulation.
• No cap on size; bets over $10 carry a 60s quote lock plus a slippage bound.
• Winners are paid automatically — there is no claim step.

Add the remote MCP server and Hunch shows up as native tools inside Claude, Cursor, or Codex — discover and research markets, simulate a bet for free, and place real USDC bets, all from your assistant.

The tools map one-to-one onto the REST routes; only place_bet moves money, and it defaults to a $0 simulation so an agent has to opt into real funds.

You can drive the whole platform from a terminal: npx hunch-agent lists markets, researches them, simulates bets for $0, settles real x402 USDC bets, and even runs the tested continuous strategy — every command takes --json so shell scripts can pipe it into jq.

Prefer a library? The TypeScript and Python clients run the whole x402 handshake for you, and the scaffolder writes a runnable agent project that ships its own Dockerfile and scheduled GitHub Actions workflow, so it hosts anywhere.

• npm i @hunchxyz/agent-sdk — typed TS client: x402 loop, webhook verifier, SSE, crowd-conviction signal.
• pip install hunch-agent — the Python equivalent (httpx + eth-account).
• Scaffolded agents host on GitHub Actions (free cron), Railway, Fly.io, Render, or any VPS via the bundled Dockerfile.

The complete reference: every REST route and MCP tool, the x402 payment handshake, sizing tiers and fees, the events system (webhooks, SSE, and polling), and the full error catalogue.

It's generated from the same modules that produce the live manifests, so the docs can never drift from the running API.

Hunch Intelligence is a pool-weighted prediction-market sentiment score for any token, synthesised from every live Hunch market's odds and real on-chain betting depth. It's free on Hunch at /api/partner/intel and packaged as a paid, agent-discoverable endpoint on Bankr's x402 Cloud, settling USDC on Base.

Discover and quote stay free — they feed the bet funnel; only the standalone signal is metered.

Base MCP exposes public read endpoints so agent clients can search Hunch markets, fetch quotes, and open quick-trade links — no payment and no key required.

It's the read-only companion to the full agent platform: discover here, settle there.

Hunch is built ports-and-adapters. The core is pure domain logic — payouts, resolvers, ranking — and depends only on typed ports. Adapters implement those ports, and a single composition root picks which adapter is wired in.

Everything ships mock-first: deterministic, credential-free mock adapters drive the same contract tests as the real ones, so a new chain or data source lands behind the same contract with zero core refactor.

Everything here is also available in machine-readable form for agents and assistants. Hand an assistant the Markdown of this page, point a client at the OpenAPI spec, or fetch the manifests directly.

• /docs.md — this entire hub as clean Markdown (use the Copy page button, or fetch it).
• /llms.txt and /llms-full.txt — the agent-oriented machine guide.
• /openapi.json — the full OpenAPI spec for the agent API.
• /.well-known/* — the agent, MCP, and x402 discovery manifests.

The long-term path: X-native markets, token maturity pages, creator-minted markets, and the HUNCH token utility loop that ties fees back to the people who drive volume.

Hunch Catalysts are open community challenges. Challenge #01 is the 10M Manifesto: make the case for HUNCH at $10M and tell the community how we get there.

Hunch is built in the open. Follow the build on X, join the conversation on Telegram, and read the code on GitHub.

Community markets (the Bazaar) are parimutuel YES/NO markets anyone can create, share publicly or by private link, and resolve themselves. There is no house and no oracle: the pool of stakes IS the market, and the creator's public track record is the trust model.

Every stake pays a 10% entry fee; the remaining 90% enters the pool. Winners split the whole net pool pro-rata at resolution — instantly and finally. If a creator never resolves, the 48-hour guarantee refunds every bet in full, fee included.

Lifecycle: draft → open → closed → resolved (or voided). Bets are accepted while the market is open; at close the pool locks; the creator then resolves with evidence before their deadline.

Odds are pool ratios, not quotes: an outcome's implied chance is its share of the net pool, and the figures move with every bet. A market with no bets has no odds — the first bettor sets them.

• Close windows: 1h to 180 days out.
• Resolution deadline: close + 72h by default, capped at 7 days.
• Unresolved at deadline + 48h → auto-void: full gross refund including fees, creator earns nothing, record stamped.
• Per-user cap $100.00 per market; new accounts (< 48h) are capped at $25.00 per day.

Pick a side, stake any amount from $0.50. The fee and your projected payout against the pool as it stands are shown before you confirm. Betting needs only a connected wallet — never an X account.

Before your first real community bet you accept the creator-resolution terms — the honest description of what you are trading on:

• Markets in Bazaar are resolved by the person who created them, not by Hunch.
• A creator's resolution is final — there is no dispute process.
• If a market is not resolved within 48 hours of its deadline, every bet is refunded in full, fees included.

Creating needs a connected wallet AND a linked X account — your public track record is what bettors trust, and it needs a face. Write resolvable criteria, attach at least one source, pick a category, choose public or private-link visibility, and set the close.

Markets support up to 10 outcomes; recurring streams can spawn up to 20 rounds per tick across 10 streams per creator (higher tiers).

Resolving is the creator's one obligation: call the outcome, attach evidence (public markets), and payouts dispatch in the same pass — winners and your fee share together. A resolution is final; there is no dispute window.

Reminders escalate through a fixed ladder (the moment it closes · 6h before the deadline · at the deadline · +24h · +42h) and a missed deadline is expensive: every bet refunds in full and the auto-refund lands on your public record permanently.

Creators earn a tier share of the 10% entry fee on every bet their market takes. Tiers are lifetime and real-USDC only; the protocol keeps the remainder (never less than 25%).

The weekly kicker adds +5pp for the top 10 Creator-Score holders; seasons pay 10% of the season's protocol take, score-ranked.

Every share surface mints your referral code. When a new bettor's first bet carries it, they bind to you for 180 days and you earn 20% of the fee on everything they stake — creator or not.

The unlock gate is 1 settled real-USDC bet of your own (creators pass automatically on their own markets). Nothing ever pays out on a bare click.

What protects you when a human resolves the market: the permanent public record (resolved, auto-refunded, on-time rate), the Creator Score, deterministic content screening at creation, and a report → review → strike ladder. A policy takedown voids and refunds pre-resolution; post-resolution it forfeits the creator's fees.

Suspensions run 7 days and block new listings only — existing markets stay resolvable, because a suspended creator still owes their bettors a resolution.

A one-time grant of 1000.00 pUSDC runs the identical mechanics — same fee, same pool maths, same guarantee — with nothing at stake. Practice activity never touches real tiers, boards, or earnings, and real and practice markets never share a list.

The keyless agent rail (`/api/bazaar/v1/*` + MCP) lets any wallet bet immediately; creating needs registration, a $10.00 bond, and a $1.00 listing fee per market. Concurrency scales with clean resolutions: 5 + 1 per 5 clean, capped at 25.

Short answers to the questions the rest of this section provokes.

• Do I need X to bet? No — betting needs only a wallet. X is required only to CREATE markets.
• What if the creator resolves wrong? Their resolution is final, and it costs them: the record is public and bettors leave. Pick creators the way you'd pick a counterparty.
• What if the creator never resolves? You get everything back — full stake including the 10% fee — automatically, 48 hours after their deadline.
• Can the creator bet in their own market? Yes, disclosed on the trust card; own volume counts toward tiers but never toward distinct-bettor signals.
• Where do private markets live? Behind their unguessable link only — never in browse, search, or the sitemap. Your profile keeps every link re-copyable.