Hunch Agent Tools

Public read-only Hunch tools for agents. Use this package to search Hunch prediction markets, inspect events and markets, compare cross-venue context, read public wallet intelligence, and fetch public price/trade/signal data.

This is a read-only research package. It does not include account, wallet, trading, signing, or transaction-execution workflows.

Install

Codex MCP

codex mcp add hunch -- npx -y @sureshotlabs/hunch-agent-tools@latest

Claude Code MCP

claude mcp add --transport stdio hunch -- npx -y @sureshotlabs/hunch-agent-tools@latest

CLI

Run without global install:

npm exec --yes --package @sureshotlabs/hunch-agent-tools@latest -- hunch-agent discovery-search "election" --json

Or install globally:

npm install -g @sureshotlabs/hunch-agent-tools
hunch-agent discovery-browse --venues polymarket,kalshi --limit 10 --json

Binaries

• hunch-agent-tools: MCP stdio server. This is the default npx entrypoint.
• hunch-mcp: same MCP stdio server, explicit alias.
• hunch-agent: CLI for public Hunch research commands.

Configuration

• HUNCH_API_BASE_URL: target Hunch API. Defaults to https://api.hunch.trade.
• HUNCH_APP_BASE_URL: app link base used in compact/standard responses. Defaults to https://app.hunch.trade.

No auth token is required or used by this public package.

MCP Tools

• hunch_search_discovery
• hunch_browse_discovery
• hunch_get_discovery_top_lists
• hunch_get_discovery_map
• hunch_get_market_detail
• hunch_get_event_detail
• hunch_get_arbitrage_clusters
• hunch_get_market_alternatives
• hunch_get_similar_markets
• hunch_get_similar_events
• hunch_get_market_holders
• hunch_get_market_price_history
• hunch_get_event_price_history
• hunch_get_tracking_overview
• hunch_get_wallet_leaderboard
• hunch_get_tracked_positioning
• hunch_get_wallet_intel
• hunch_get_wallet_activity
• hunch_get_market_wallet_activity
• hunch_get_wallet_positions
• hunch_get_wallet_series
• hunch_get_wallet_signals
• hunch_get_signals
• hunch_get_trades

Most tools support responseMode:

• compact: default, small payloads for agent reasoning. Omits media/raw-heavy fields and caps event market previews at 3.
• standard: includes descriptions, metadata, and larger previews.
• full: unmodified API JSON for exact-data checks.

CLI Examples

hunch-agent discovery-search "up or down" --venues polymarket,kalshi --limit 10 --json
hunch-agent discovery-browse --sort totalvol --limit 10 --json
hunch-agent market-detail polymarket:123 --standard --json
hunch-agent event-detail polymarket:456 --standard --json
hunch-agent arbitrage-clusters --min-liquidity 1000 --limit 10 --json
hunch-agent market-alternatives polymarket:123 --venues polymarket,kalshi,limitless --json
hunch-agent market-price-history polymarket:123 --range 1d --sides BOTH --json
hunch-agent trades --market-id polymarket:123 --limit 25 --json
hunch-agent wallet-leaderboard --sort edge_z_score --min-resolved-edge-sample-count 5 --min-resolved-stake-usd 1000 --json
hunch-agent tracked-positioning --rollup events --query "world cup" --sort avg_edge_z_score --holder-sort edge_z_score --min-contested-market-count 1 --shape graph --json
hunch-agent market-wallet-activity polymarket:123 --min-size-usd 100 --json
hunch-agent wallet-intel <wallet-address> --chain polygon --json

For trader-quality discovery, pair edge_z_score, stake_weighted_edge, or brier_score with sample/stake filters. brier_score is lower-is-better and should not be used alone because one tiny resolved trade can look perfectly calibrated.

Agent Usage Notes

Use discovery search or browse first, then fetch event or market detail for a stable page object. Use alternatives for exact cross-venue versions of the same market. Use similar markets/events for broader semantic discovery. Use arbitrage clusters for broad mispricing discovery.

When answering users, show titles, venues, odds or metrics, and Hunch links first. Keep raw IDs as secondary technical references.

Bundled Skill

The npm package includes a portable Skill folder at:

skills/hunch-trading/

That folder contains SKILL.md, references, and a bundled CLI wrapper. It can be copied into an agent skills directory when a Skill install surface is preferred. The npm package root remains the MCP/CLI package root, so npx -y @sureshotlabs/hunch-agent-tools@latest continues to launch the MCP server.

License

MIT