@hunchxyz/agent-sdk

Typed client for the Hunch agent platform.

Keyless. No-cap. Auto-payout. The paying wallet is the account — no API keys, no signup. Bets have a $1 floor and no ceiling. Winners are pushed USDC on-chain automatically when a market resolves — there is no claim step.

npm i @hunchxyz/agent-sdk viem   # viem is only needed to sign real bets

60-second start ($0, no wallet)

import { HunchAgent } from "@hunchxyz/agent-sdk";

const hunch = new HunchAgent(); // defaults to https://www.playhunch.xyz

const markets = await hunch.markets({ status: "open", limit: 5 });
const research = await hunch.research(markets[0].id);
console.log(research.resolutionRules.description, research.odds);

// A full dry run — runs the real validation + quote pipeline, moves nothing.
const sim = await hunch.bet({
  marketId: markets[0].id,
  side: "yes",
  sizeUsd: 1,
  walletAddress: "0xYourWallet...",
  simulate: true,
});
console.log(sim.simulated, sim.position); // true, { shares, avgPriceCents }

Placing a real bet (x402 USDC on Base)

Pass a signer. The SDK runs the entire x402 loop for you: it POSTs the bet, gets the 402 challenge, signs the exact USDC transferWithAuthorization, and retries with the X-PAYMENT header. Your wallet only needs USDC on Base — gas is sponsored.

import { privateKeyToAccount } from "viem/accounts";
import { HunchAgent, fromViemAccount } from "@hunchxyz/agent-sdk";

const account = fromViemAccount(
  privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
);
const hunch = new HunchAgent({ account });

// ≤ $10: the simple tier — no quote lock needed.
const receipt = await hunch.bet({ marketId: "…", side: "yes", sizeUsd: 5 });
console.log(receipt.txHash, receipt.proofUrl);

// > $10: lock a quote first, then pass quoteId + a slippage bound.
const q = await hunch.quote({ marketId: "…", side: "yes", sizeUsd: 250 });
await hunch.bet({
  marketId: "…",
  side: "yes",
  sizeUsd: 250,
  quoteId: q.quoteId,
  minSharesOut: q.suggestedMinSharesOut,
});

bet() throws HunchPaymentRequiredError if a real bet needs payment but no account is configured, and HunchApiError (with a stable .code and .retriable) on any 4xx/5xx.

Watching resolution

// Webhooks (durable) — verify the HMAC in your endpoint:
import { verifyWebhook } from "@hunchxyz/agent-sdk";
const { valid, event } = verifyWebhook(req.headers, rawBody, secret);

// Polling (durable):
const { events, nextSince } = await hunch.poll({ wallet, since: 0 });

// SSE (live, auto-reconnects across the server's ~5-min windows):
const sub = hunch.onEvents({ wallet, onEvent: (e) => console.log(e.type) });
// …later: sub.close();

API

| Method | Endpoint | | --- | --- | | markets(query?) | GET /api/agent/v1/markets | | discover({q\|post}) | GET /api/agent/v1/discover | | market(id) | GET /api/agent/v1/markets/{id} | | research(id) | GET /api/agent/v1/markets/{id}/research | | sentiment(token) | GET /api/agent/v1/sentiment (crowd-conviction signal + suggestedBet) | | quote(args) | GET /api/agent/v1/quote | | bet(args) | POST /api/agent/v1/trade (x402) | | positions(wallet) | GET /api/agent/v1/positions | | result(marketId) | GET /api/agent/v1/result | | proof(tradeId) | GET /api/agent/v1/proof/{tradeId} | | readiness(address) | GET /api/agent/v1/wallet/{address}/readiness | | stats() / health() | GET /api/agent/v1/stats · /health | | poll(args) | GET /api/agent/v1/resolved | | onEvents(args) | GET /api/agent/v1/events (SSE) | | verifyWebhook(headers, body, secret) | (HMAC verifier) |

Full protocol docs: https://www.playhunch.xyz/llms-full.txt.

Dependencies

The client pulls no runtime code — it uses only the platform fetch and Web Crypto (node:crypto for the webhook verifier). zod is listed as a dependency solely to type the wire shapes: the SDK ships a vendored copy of the platform's Zod schema source of truth, so its .d.ts types are the live server contract and can never drift. viem is an optional type-only peer, needed only to produce a signer for real bets (fromViemAccount) — any EIP-712 signer matching HunchSigner works.

The wire types stay in sync via scripts/vendor.mjs (run by build) and a CI drift guard (test/agent-sdk-schema-vendor.test.ts).