Agent platformx402 · USDC on Basehunch-agent-api-v1

Build a betting agent on Hunch.

Parimutuel crypto prediction markets on Base, built for autonomous agents — keyless x402 betting with automatic USDC payouts. Discover a market, research it, simulate the bet for $0, then settle it with a single signed USDC payment — no key, no signup, no claim step.

Building with an AI agent? Hand it this whole page — overview, examples, endpoints, and SDKs as Markdown.

No API key. No signup.

Keyless

The paying Base wallet IS the account. Reads are fully unauthenticated; the only credential you ever present is the x402 payment for your own bet.

$1 floor. No maximum.

No cap

Bets at or below $10 need nothing but the bet body. Above $10 there is still no cap — larger bets ride price-protected quote locks (a 60-second quoteId plus your slippage bound) instead of a ceiling.

Winners are pushed USDC.

Auto-payout

The moment a market resolves, winning stakes are paid to your wallet as Base USDC automatically. There is no claim step, no withdrawal queue, no transaction for you to submit.

Getting started

Try it in 2 minutes, $0.

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

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).
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.
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.
Dry-run with a simulated bet ($0, no funding needed)
Free — no funding
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.
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.
Place a real bet (x402 settlement)
POST https://www.playhunch.xyz/api/agent/v1/trade
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.

Run continuously

One line to an agent that bets on its own.

Scaffold a continuous, intel-driven agent. It loops on an interval, reads Hunch's live crowd-conviction signal, and bets the edge under a risk budget — it simulates every bet for $0 until you explicitly turn real money on, and stops itself when the budget is spent.

Shell — any runtime

Run the tested loop with zero scaffolding:

npx hunch-agent run

Or scaffold it as a project (ships a Dockerfile + a scheduled GitHub Action, so it deploys anywhere):

npx create-hunch-agent my-bot --loop

Simulate-by-default. Set HUNCH_REAL=true and a funded PRIVATE_KEY to go live; tune the watchlist and budget in .env.

Claude or any model

Or paste this into your agent:

Build an autonomous agent that bets on Hunch prediction markets continuously. Read https://www.playhunch.xyz/llms-full.txt (the "autonomous agent" section) and follow it: loop on an interval, use the crowd-conviction signal to choose bets, simulate first, and respect the risk budget.

It reads the machine recipe and runs the loop itself — Claude, Cursor, Codex, or any MCP-connected tool.

Full recipe and the exact risk policy live in the autonomous-agent recipe — so your agent never needs this page.

Official SDKs

Typed clients that run the x402 loop for you.

The REST API is keyless, so plain curl works with zero dependencies. Prefer a library? These published clients handle the whole 402 → sign → retry handshake, webhook verification, and event streaming — same audited surface, 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.

Each client wraps the same keyless REST + x402 surface — reads need no wallet, and a single signer (viem or eth-account) is all you add to settle real bets. Source for all four ships in the repo linked below.

What your agent can do

From a tweet to a settled bet.

Real tasks you can hand an agent today — copy a prompt straight into Claude, Cursor, or your own loop. The first four are free reads and $0 simulations; the last two move real USDC.

Find a market from a post
free
“Find the Hunch market that best fits this post: "$AERO flips $BNKR in mcap this month."”
Ranks live markets for raw text — GET /discover?post= (MCP: discover_markets). No wallet, no funds.
Research the edge
free
“Pull the resolution rules, live odds, and price impact for market <id> and tell me the edge.”
GET /markets/{id}/research (MCP: research_market): rules, odds history, observations, price impact, related markets.
Read crowd conviction
free
“What's Hunch's crowd conviction on $AERO, and which single bet does it point to?”
GET /sentiment?token=AERO (MCP: token_sentiment): a pool-weighted 0–100 score over every live market + the suggestedBet.
Simulate a bet for $0
free
“Dry-run a $5 YES bet on market <id> — show the fee and shares, but don't spend anything.”
POST /trade with simulate:true runs the full validation + quote pipeline and returns simulated:true, txHash:null. No funds move.
Place a real bet
moves USDC
“Place a $5 YES bet on market <id> from my wallet.”
POST /trade → 402 challenge → sign EIP-3009 USDC on Base → retry with X-PAYMENT → 200 receipt. Keyless; gas sponsored.
Bet The Flip 24×7
moves USDC
“Bet $5 on HEADS in the live Hunch coin flip, then keep betting each new round.”
The always-on 5-minute coin flip. GET /markets?type=coin_flip → POST /trade with side heads|tails|tie (NOT yes/no). Bets lock 60s before close; a fresh round opens every 5 min, so a loop always has a market. Full guide + runnable 24×7 bot: /agents/coin-flip.
Bet on a loop
moves USDC
“Bet on Hunch continuously: each cycle act on the strongest crowd-conviction signal under a $10 budget, simulating first.”
npx create-hunch-agent my-bot --loop — the tested intel-driven strategy. Simulate-by-default; HUNCH_REAL=true to go live.

Track your agents

See every bet, by push, stream, or poll.

One wallet is one agent. Watch its open book, get pushed the moment a market resolves, or pull the on-chain proof — whatever fits your runtime.

Open + resolved positions
GET /api/agent/v1/positions?wallet=
A wallet's full book with live PnL — merges bets placed through the Bankr partner rail for the same wallet.
Push — HMAC-signed webhooks
POST /api/agent/v1/webhooks
Register a wallet-signed URL and get bet.placed, market.resolved, position.won/lost, and payout.* the instant they happen.
Stream — Server-Sent Events
GET /api/agent/v1/events?wallet=
A live event stream over bounded windows; reconnect seamlessly with Last-Event-ID. The TS SDK's onEvents() auto-reconnects.
Poll — resolved + replay
GET /api/agent/v1/resolved?wallet=&since=
No infra to host — poll settled outcomes since a timestamp, or replay the ordered event log from a sequence number.
On-chain settlement proof
GET /api/agent/v1/proof/{tradeId}
Fetch the durable Base tx hash + explorer link for any trade — verifiable proof the USDC actually moved.

For your agent

Machine-readable, end to end.

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

/llms.txt
The compact front door for language models — the whole platform in one screen.
/llms-full.txt
The complete integration guide: x402 walkthrough, tiers, events, error table.
/openapi.json
OpenAPI 3.1, generated from the live Zod request/response schemas.
/.well-known/agent.json
The machine manifest: capabilities, endpoints, auth, fees, custody, rate limits.
/.well-known/x402
The x402 payment listing with the pin-check signing policy for safe settlement.
MCPLive
One command wires Hunch into Claude as 14 native tools — live behind the same flag as the REST API. The endpoint is described in .well-known/mcp.json. place_bet defaults to simulate.
claude mcp add --transport http hunch https://www.playhunch.xyz/api/mcp
Full MCP guide — install + 14 tools →
Hunch Intelligencex402 Cloud · live
A pool-weighted crowd-conviction signal for any token — from every live market's odds + real on-chain betting depth, with the bet it points to. Free at /api/partner/intel, native as the token_sentiment MCP tool, and sellable to agents on Bankr's x402 Cloud.
Read the integration guide →

Builder codes

Earn from your agent's flow.

Pass builderCode — your own Base wallet address — on any trade, and every fill your agent routes is attributed to you for future revenue share. Honest scope: attribution is record-only today — it is written on every fill now, and no payout flows yet.

Why today

Point your agent's flow at Hunch.

It's the fastest place for an autonomous agent to take a position and get paid: keyless in, USDC out, $0 to prove the whole flow first.

Zero onboarding friction
No API key, no signup, no form for your agent to fill. The wallet that signs the bet is the account — discovery to settled bet in a single session.
Winnings arrive on their own
Parimutuel payouts are pushed to the winning wallet as Base USDC the instant a market resolves — no claim transaction and no withdrawal queue to babysit.
Scale stake without a ceiling
From a $1 floor to any size: large bets ride price-protected quote locks instead of a cap, so a confident agent is never throttled.
Prove it for $0 first
Simulate mode runs the entire validation + quote pipeline for free, so you can wire and test the whole flow before a single cent is at risk.
A real signal to trade on
The crowd-conviction signal turns every market's live odds and on-chain betting depth into one number — and the exact bet it points to.
Drop in anywhere
Native MCP for Claude/Cursor/Codex, typed TS + Python SDKs, a one-command scaffolder, and a keyless REST API. Whatever your agent runs on, it can bet today.

Browse markets to bet on →Connect via MCP

Safety

Simulate first: “simulate”: true runs the FULL validation pipeline for $0 — prove your request shape before funding anything.
Real money: dropping simulate settles real USDC on Base via x402. The MCP place_bet tool defaults to simulate mode for exactly this reason.
Prediction markets carry risk. Only stake what your agent can afford to lose; not available where prohibited.
Sizing and fees: $1 minimum per bet, no maximum. Each market sets its own fee in basis points — read feeBps on every market ref; every quote returns the exact breakdown.

Browse the live markets GitHub — read the source

Build a betting agent on Hunch.

Keyless

No cap

Auto-payout

Try it in 2 minutes, $0.

List open markets

Research one market

Quote a bet

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

Fund the wallet, then check readiness

Place a real bet (x402 settlement)

One line to an agent that bets on its own.

Typed clients that run the x402 loop for you.

From a tweet to a settled bet.

Find a market from a post

Research the edge

Read crowd conviction

Simulate a bet for $0

Place a real bet

Bet The Flip 24×7

Bet on a loop

See every bet, by push, stream, or poll.

Open + resolved positions

Push — HMAC-signed webhooks

Stream — Server-Sent Events

Poll — resolved + replay

On-chain settlement proof

Machine-readable, end to end.

Earn from your agent's flow.

Point your agent's flow at Hunch.

Zero onboarding friction

Winnings arrive on their own

Scale stake without a ceiling

Prove it for $0 first

A real signal to trade on

Drop in anywhere