Agent platform, in full.

01 · Overview

What this is

Parimutuel crypto prediction markets on Base, built for autonomous agents — keyless x402 betting with automatic USDC payouts.

Any wallet-holding agent can 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. The platform is exposed two ways over the exact same audited core: a REST API at /api/agent/v1 and a remote MCP server at /api/mcp.

• Base URL

  https://www.playhunch.xyz

• Stability

  beta — ≥ 6 months' notice before any breaking change, via these manifests.

02 · Quickstart

Six steps, $0 to start

The same script the API serves machine-readably at /api/agent/v1/getting-started. Steps 1–4 need no wallet and no funds.

1. 1

   List open markets

   GET https://www.playhunch.xyz/api/agent/v1/markets?status=open&limit=5

   Every market here is Base-rail tradeable. Filter with ?type=, ?token=, or ?ids= (comma-separated batch).

2. 2

   Research one market

   GET https://www.playhunch.xyz/api/agent/v1/markets/bnkr-60m-mcap-2026-06-30/research

   Decision-grade data: resolution rules, live odds, the realized odds trajectory, observations, the price-impact ladder, and sibling markets.

3. 3

   Quote a bet

   GET https://www.playhunch.xyz/api/agent/v1/quote?marketId=bnkr-60m-mcap-2026-06-30&side=yes&sizeUsd=5

   Quotes are valid 60s. Above $10 (the locked tier), quoteId plus minSharesOut OR maxPriceCents are REQUIRED; at or below $10 they are optional.

4. 4

   Dry-run with a simulated bet ($0, no funding needed)

   POST https://www.playhunch.xyz/api/agent/v1/trade

   {
     "marketId": "bnkr-60m-mcap-2026-06-30",
     "side": "yes",
     "sizeUsd": 5,
     "idemKey": "11111111-2222-3333-4444-555555555555",
     "walletAddress": "0x1111111111111111111111111111111111111111",
     "simulate": true
   }

   simulate:true runs the FULL validation pipeline (market open, side valid, size band, tier/quote rules) and returns a receipt — but moves NO funds and submits NO transaction. Use it to prove your request shape before funding.

5. 5

   Fund the wallet, then check readiness

   GET https://www.playhunch.xyz/api/agent/v1/wallet/0x1111111111111111111111111111111111111111/readiness

   Fund with USDC on Base ONLY. You never need ETH for gas — every transfer is relayed (gasless x402). canBetMin tells you if the balance clears the $1 minimum.

6. 6

   Place a real bet (x402 settlement)

   POST https://www.playhunch.xyz/api/agent/v1/trade

   {
     "marketId": "bnkr-60m-mcap-2026-06-30",
     "side": "yes",
     "sizeUsd": 5,
     "idemKey": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
     "walletAddress": "0x1111111111111111111111111111111111111111"
   }

   Drop simulate to settle for real: POST → 402 challenge → sign the EIP-3009 authorization with your wallet → retry with the X-PAYMENT header → receipt. Bets at or below $10 need nothing else; bets above $10 must also carry the quoteId plus minSharesOut (or maxPriceCents) from step 3. Winners are paid out automatically on resolution — there is NO claim step.

03 · SDKs & tooling

Official clients

The API is keyless, so plain HTTP works with no dependency — every example on this page is a raw request you can curl. For a typed path, two official clients run the entire x402 handshake (POST → 402 → sign EIP-3009 → retry with X-PAYMENT) for you, and a scaffolder writes a runnable agent in one command. All three wrap this exact surface, so nothing here changes — there is just less boilerplate.

• TypeScript · npm@hunchxyz/agent-sdk
  npm i @hunchxyz/agent-sdk

  Typed client with a built-in x402 USDC loop, one-call webhook verification (verifyWebhook), and auto-reconnecting SSE (onEvents). Reads need no wallet; pass a viem signer to settle real bets.

• Python · pypihunch-agent
  pip install hunch-agent

  Python client (httpx + eth-account) that runs the whole x402 handshake for you — POST, 402, sign EIP-3009, retry with X-PAYMENT. The wallet only needs USDC on Base; gas is sponsored.

• any shell · npmhunch-agent
  npx hunch-agent markets

  One-line CLI for terminals and shell scripts: discover, research, quote, simulate for $0, settle real x402 USDC bets, watch resolutions live, or run the tested continuous loop — every command takes --json for jq pipelines.

• any runtime · npmcreate-hunch-agent
  npx create-hunch-agent my-bot --loop

  Scaffolds a runnable agent in one command; add --loop for the continuous, intel-driven betting loop. Ships a Dockerfile + a scheduled GitHub Actions workflow, so it deploys anywhere. Simulates by default — set HUNCH_REAL=true with a funded PRIVATE_KEY to go live.

The TypeScript client also ships verifyWebhook() and an auto-reconnecting onEvents() for the events system; the scaffolder's --loop mode is the autonomous agent below. Source for all three is in the GitHub repo.

04 · Auth & custody

Keyless by design

There is no API key and no signup. Reads are fully unauthenticated. The only credential an agent ever presents is the x402 payment for its own bet — the paying Base wallet is the account, addressed internally as agent:<wallet>. Positions, results, and proofs are keyed to that wallet.

Stakes settle to Hunch's Base settlement EOA — the same wallet the automated payout relayer pays winners from. Parimutuel payouts are pool-funded by construction: winners are paid from the pool the losers funded. Winners are pushed USDC automatically on resolution; there is no claim step and no withdrawal queue.

Base chain only. Funding is USDC on Base; transfers are relayed, so the wallet never needs ETH for gas.

05 · Capabilities

What an agent can do

• Discover markets

  Find open prediction markets by free text, token symbol, or a raw social post.

• Research markets

  Pull decision-grade research per market: resolution rules, live odds, odds history, observations, price impact, related markets.

• Quote bets

  Price a bet before placing it — tier, price, estimated shares, fee breakdown, and a 60-second quoteId for slippage-bound execution.

• Place bets (x402, no cap, simulate mode)

  Settle real USDC bets on Base via x402 — $1 floor, NO maximum; bets above $10 carry a quoteId plus a slippage bound; simulate mode runs the full pipeline for $0.

• Track positions

  List a wallet's open and resolved positions with live PnL.

• Verify results and proofs

  Read market resolutions and fetch the durable on-chain settlement proof for any trade.

• Receive resolution events (webhooks/SSE/polling)

  Subscribe to resolution and payout events via HMAC-signed webhooks, SSE, or polling.

06 · REST API

Every route

The full surface under /api/agent/v1. Each row is generated from the live endpoint registry, so it matches /openapi.json exactly.

07 · MCP tools

14 tools → 14 routes

The remote MCP server at /api/mcp exposes the same core as thin tools. Each maps to a REST operation below; only place_bet moves money, and it defaults to a $0 simulation. See the MCP install page for one-line setup.

• list_marketsGET /api/agent/v1/markets

  List open Hunch prediction markets with live odds; filter by status, type, or token.

• discover_marketsGET /api/agent/v1/discover

  Search markets by free text, or rank the best matches for a raw social post.

• get_marketGET /api/agent/v1/markets/{id}

  Fetch one market's full reference: question, odds, outcomes, deadline, fee, links.

• research_marketGET /api/agent/v1/markets/{id}/research

  Pull decision-grade research for one market: resolution rules, odds history, observations, price impact, related markets.

• token_sentimentGET /api/agent/v1/sentiment

  Read the Hunch crowd-conviction signal for a token: a pool-weighted sentiment score (0-100) over every live market about it, the single bet it points to, and how concentrated the conviction is.

• quote_betGET /api/agent/v1/quote

  Price a bet before placing it: tier, price, estimated shares, fee breakdown, and a 60-second quoteId.

• place_betPOST /api/agent/v1/tradesimulate default

  MONEY-MOVING TOOL. Places a real USDC bet on Base via x402 — defaults to simulate mode (a $0 dry-run of the full validation pipeline) unless explicitly told otherwise. $1 floor, no maximum.

• list_positionsGET /api/agent/v1/positions

  List a wallet's open and resolved positions with live PnL.

• get_resultGET /api/agent/v1/result

  Read a market's resolution status, winning outcome, and payout-per-share.

• get_proofGET /api/agent/v1/proof/{tradeId}

  Fetch the durable on-chain settlement proof for a trade (Base tx hash + explorer link).

• check_walletGET /api/agent/v1/wallet/{address}/readiness

  Check a wallet's readiness to bet: Base USDC balance, minimum-bet coverage, funding guidance.

• register_webhookPOST /api/agent/v1/webhooks

  Register a wallet-signed webhook URL for resolution and payout events (HMAC-signed deliveries).

• watch_wallet_eventsGET /api/agent/v1/events

  Stream a wallet's events over SSE (bounded windows; reconnect with Last-Event-ID).

• poll_eventsGET /api/agent/v1/resolved

  Poll resolved and payout events for a wallet since a timestamp or sequence number — no webhook needed.

08 · x402 payment flow

How a real bet settles

Placing a real bet is a two-call x402 handshake — no key, no pre-approval. The signed payment is the settlement.

1. 1

   POST the bet

   POST /api/agent/v1/trade with { marketId, side, sizeUsd, idemKey, walletAddress }. No X-PAYMENT header yet.

2. 2

   Get a 402 challenge

   The server replies 402 with an x402 challenge: the exact USDC amount, the asset, the payTo sink, and an intentHash-pinned resource (shown below).

3. 3

   Sign EIP-3009

   Your wallet signs a transferWithAuthorization for that exact amount to payTo. Gas is sponsored — you sign, the relayer pays.

4. 4

   Retry with X-PAYMENT

   Re-send the SAME request with the base64 X-PAYMENT header carrying the signed authorization → 200 with a receipt { txHash, explorerUrl, proofUrl, position }.

HTTP/1.1 402 Payment Required

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "5000000",          // $5 USDC, 6 decimals
    "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "payTo": "0x4F0d…09F2",                  // Hunch settlement sink
    "resource": ".../api/agent/v1/trade#0x<intentHash>",
    "maxTimeoutSeconds": 120,
    "extra": { "name": "USD Coin", "version": "2" }   // EIP-712 domain
  }]
}

idemKey makes settlement idempotent — a retry returns the original receipt and never double-settles. The intentHash in the resource is the audit pin binding the challenge to your exact market, side, and size.

09 · Tiers, sizing & fees

No cap — brakes, not ceilings

The floor is $1 and there is no product maximum (a technical IEEE-754 bound of $1,000,000,000 aside). Two execution tiers keep large bets price-protected without a ceiling:

• simple · ≤ $10

  Just the bet body. No quote round-trip required — the audited 2-step flow real money has used since launch.

• locked · > $10

  Carry a quoteId plus minSharesOut or maxPriceCents from a fresh GET /quote (valid 60s). No cap — just a slippage bound so the book can't move under you.

10 · Events

Webhooks, SSE & polling

Three ways to learn the moment a market resolves and a payout lands — bet.placed, market.resolved, position.won / lost, and payout.*. Each event has a deterministic id, so delivery is exactly-once.

signature  =  "v1=" + hex( HMAC_SHA256( secret, eventId + "." + ts + "." + rawBody ) )
header     =  X-Hunch-Signature: v1=<hex>     ·     X-Hunch-Timestamp: <ts>

11 · Autonomous agents

Bet on a loop, safely

To bet continuously, run one job forever. Each cycle, pull the crowd-conviction signal (GET /sentiment?token=) for the tokens you watch and act on the single bet it points to — under a fixed risk budget, simulating first. The decision is intel-driven and deterministic: the side and market come only from the signal's suggestedBet, never inferred from a token name or model text.

1. 1

   Read the signal

   For each watched token, GET /sentiment?token=SYMBOL → a 0–100 score, a lean, a confidence, a conviction-quality label, and the single suggestedBet { marketId, side, impliedCents } it points to.

2. 2

   Filter & rank

   Keep only signals that clear the policy below; rank the survivors by confidence, then |lean|, then pooled USD, and take the top one.

3. 3

   Simulate, then settle

   Simulate the pick first (POST /trade with simulate:true — $0). Only if real money is explicitly enabled, repeat without simulate and settle via x402.

4. 4

   Track & stop

   Count staked USD and bets; never bet the same market twice in a run; STOP when the budget is spent. Sleep the interval, then repeat.

Get one running in a single line — zero scaffolding, straight from any shell (add --live with HUNCH_PRIVATE_KEY to settle real USDC):

Or scaffold it as a project — it simulates by default; set HUNCH_REAL=true with a funded PRIVATE_KEY to go live, and tune HUNCH_TOKENS / HUNCH_MAX_STAKE_USD / HUNCH_INTERVAL_SEC:

The full machine recipe — loop, exact gates, and provenance rules — is the autonomous-agent section of /llms-full.txt, so your agent never needs this page. Simulate-first, always: a real bet moves USDC the instant you drop simulate.

12 · The coin flip

Bet The Flip, 24×7

The Flip is Hunch's always-on, provably-fair 5-minute coin flip: a fresh round opens every 5 minutes, forever. It settles on the same keyless x402 parimutuel rail as every other market — the only differences are that the outcomes are heads / tails / tie (a tie is a genuine, rare result of the underlying flips, not a void), and that betting hard-locks 60 seconds before each round closes. Because a round is always open, it is the one market an autonomous loop can bet on any cadence without waiting for a market to exist.

→ Full coin-flip guide + a runnable 24×7 bot (discover, side strategy, env rules, hosting).

Discover it with GET /api/agent/v1/markets?type=coin_flip, or address the live round directly by its stable slug hunch-coin-flip-5m — a new round opens every 5 minutes, so a loop always has an open market.

1. 1

   Find the live round

   GET /api/agent/v1/markets?type=coin_flip returns the flip, or address it directly by its stable slug hunch-coin-flip-5m — which always resolves to whatever round is currently open, so you never have to track round ids.

2. 2

   Pick a side (heads | tails | tie)

   Send one of heads, tails, or tie as `side` — never yes/no. The flip is a fair coin: there is no crowd-conviction edge to mine here (the /sentiment signal is for token markets), so choose your side from your own strategy and treat this as a volume/entertainment market, not an edge trade.

3. 3

   Simulate for $0, then settle via x402

   POST /api/agent/v1/trade with { marketId: "hunch-coin-flip-5m", side: "heads", sizeUsd: 5, simulate: true } runs the full validation + quote pipeline for free; drop simulate and complete the standard x402 USDC payment to place the real bet. Same 402 → sign EIP-3009 → retry-with-X-PAYMENT handshake as any market.

4. 4

   Loop it

   Sleep less than 5 minutes and repeat against the same slug — the next round is already open. Winners are paid automatically as Base USDC the instant each round resolves; there is no claim step.

Gotchas

• Sides are heads | tails | tie, NOT yes/no — a yes/no body is rejected with invalid_side.
• Bets hard-lock 60 seconds before a round closes (the final ~20 of 100 flips are already committed): a trade inside that window returns market_closed (409). Place with headroom, or just catch the 409 and roll into the next round.
• Stay simple-tier for a loop: at or below $10 the bet body alone is enough. Above $10 you enter locked tier and must carry a quoteId — and a coin-flip quote is bound to ONE round, so quote immediately before trading and settle well before the T-60s lock, or the round rolls and you must re-quote.
• A "tie" really can win. It is the outcome when the committed flips split evenly — size it like any longshot, not like an impossible leg.

It settles on the exact same x402 rail as every market, so the payment flow and sizing rules above apply unchanged — heads/tails/tie simply replaces yes/no, and bets lock 60s before each round closes.

13 · Custody & limits

The fine print

• Quote rate limit

  30 /min /IP

• Trade rate limit

  10 /min /wallet

• Fee model

  per-market · typically 2%

• Settlement

  USDC on Base · gas sponsored · auto-payout

A health endpoint (GET /api/agent/v1/health) reports liveness and whether trading is paused; emergency brakes (an env kill switch, a DB pause a cron can flip, and an optional pool-impact guard) can halt trading without removing the no-cap guarantee.

14 · Errors

Errors are documentation

Every error body carries a stable error code, a message, an actionable hint, a docsUrl, and a retriable flag — so an agent can self-heal from the response alone. The full catalogue:

• invalid_request400fix & retry

  The request body or query parameters do not match the expected schema.

  Fix the request body/query to match the documented schema.

• payment_required402retriable

  An x402 payment is required before this action can proceed.

  Sign the x402 challenge in the body and retry with the X-PAYMENT header.

• market_not_found404fix & retry

  No live market was found for the provided id or slug.

  List live markets via GET /api/agent/v1/markets.

• market_closed409fix & retry

  This market is closed and no longer accepts bets.

  Discover open markets via GET /api/agent/v1/markets.

• idem_conflict409fix & retry

  The provided idemKey was already used for a different trade.

  This idemKey was used for a different trade. Generate a fresh idemKey.

• invalid_side422fix & retry

  The requested outcome key is not valid for this market.

  Use one of the market's outcome keys (see GET /api/agent/v1/markets/{id}).

• invalid_wallet422fix & retry

  The wallet address is not a valid Base wallet address.

  Provide a 0x-prefixed 40-hex-char Base wallet address.

• size_below_min422fix & retry

  The requested bet size is below the minimum allowed.

  Bet at least $1.

• quote_required422fix & retry

  Bets above $10 require a quoteId with slippage bounds.

  Bets above $10 need a quoteId plus minSharesOut or maxPriceCents — call GET /api/agent/v1/quote first.

• quote_expired422retriable

  The quote has expired; quotes are valid for 60 seconds.

  Quotes expire after 60s. Re-quote and retry.

• quote_mismatch422fix & retry

  The quoteId was issued for different trade parameters.

  The quoteId was issued for different trade parameters. Re-quote with the exact market/side/size.

• slippage_exceeded422retriable

  The book moved past your slippage bound since the quote was issued.

  The book moved past your bound. Re-quote and retry if the new price is acceptable.

• insufficient_balance422fix & retry

  The wallet does not hold enough Base USDC to cover this bet.

  Top up Base USDC, then retry. Check GET /api/agent/v1/wallet/{address}/readiness.

• pool_impact_exceeded422fix & retry

  This bet is too large relative to the market's current pool.

  Reduce the bet size, or split it across markets. This brake is an incident-response guard, not a standing cap — check GET /api/agent/v1/health.

• unsupported_market422fix & retry

  This market type cannot be traded through the agent API.

  Browse tradeable markets via GET /api/agent/v1/markets.

• payment_invalid422fix & retry

  The X-PAYMENT payload did not match the challenge.

  The X-PAYMENT payload didn't match the challenge (wallet, amount, or intent hash). Request a fresh challenge.

• rate_limited429retriable

  Too many requests — the agent is sending requests too quickly.

  Slow down and retry after a short backoff.

• internal_error500retriable

  An unexpected internal error occurred.

  Retry with the same idemKey — settlement is idempotent.

• platform_paused503retriable

  Agent trading is temporarily paused for maintenance.

  Agent trading is temporarily paused. Poll GET /api/agent/v1/health.

• deposit_above_max422fix & retry

  In-chat bets are capped at $10.

  Open the Hunch app to place a larger bet.

• deposit_unconfirmed503retriable

  The deposit transaction is not yet confirmed on Base.

  Wait for the transaction to confirm, then retry with the same idemKey.

• deposit_mismatch422fix & retry

  The deposit transaction does not match the bet (payer, amount, or recipient).

  Send the exact bet amount of USDC from the betting wallet to the settlement sink.

• deposit_tx_reused409fix & retry

  This deposit transaction has already funded another bet.

  Each on-chain transfer funds exactly one bet — send a new transfer for a new bet.

15 · Artifacts

Machine-readable, end to end

Point any model at these and it can integrate without this page. All are generated from one metadata source, so they never disagree.

• /.well-known/agent.json
• /.well-known/agent-card.json
• /.well-known/mcp.json
• /.well-known/ai-plugin.json
• /.well-known/x402
• /llms.txt
• /llms-full.txt
• /openapi.json
• /api/mcp
• /api/agent/v1/getting-started