@sureshotlabs/hunch-agent-tools 0.1.1

package/skills/hunch-trading/references/tools.md

@@ -0,0 +1,125 @@
+# Hunch Agent Tools
+
+## MCP Tools
+
+- `hunch_search_discovery`: search events or markets by text/entity query and
+  filters. Results are event-shaped rows even when `view=markets`; use
+  `hunch_get_market_detail` for one flat market object.
+- `hunch_browse_discovery`: browse ranked discovery feeds without a required
+  query; any query is only a secondary filter. Results are event-shaped rows
+  even when `view=markets`.
+- `hunch_get_discovery_top_lists`: ranked discovery top lists/sidebar data for
+  trending, volume movers, liquidity movers, price movers, and optional
+  sparklines. Use for sidebars/leaderboards, not general search.
+- `hunch_get_discovery_map`: semantic discovery map nodes and previews.
+  `level` starts at `1`; `0` is invalid. Use `hunch_get_signals` with
+  `scope=node` and `targetId` for node explanations.
+- `hunch_get_market_detail`: detailed public market data, canonical market ID,
+  and Hunch app link.
+- `hunch_get_event_detail`: event-level public data and related markets. Use
+  `marketsPreviewLimit` to keep compact responses small.
+- `hunch_get_arbitrage_clusters`: Hunch cross-venue arbitrage/mispricing
+  clusters; useful for broad opportunity discovery, not guaranteed exact
+  matches for one requested market.
+- `hunch_get_market_alternatives`: exact cross-venue alternatives for one
+  Hunch market ID, including midpoint comparison, icons, and Hunch links.
+- `hunch_get_similar_markets`: strict market-level semantic similar markets for
+  one market ID. It can exclude same-event or same-series matches and return
+  fewer results. If coverage is empty or sparse, inspect `eventFallback` or
+  call `hunch_get_similar_events`.
+- `hunch_get_similar_events`: semantic similar events, optionally anchored to a
+  selected market ID.
+- `hunch_get_market_holders`: public holder leaderboard for one market.
+- `hunch_get_market_price_history`: normalized YES/NO chart history for one
+  market. `startTs`/`endTs` are Unix seconds; `sides` wins over `side`.
+- `hunch_get_event_price_history`: normalized chart history for an event's top
+  markets. `startTs`/`endTs` are Unix seconds; `sides` wins over `side`.
+- `hunch_get_tracking_overview`: the public tracking page read model. Compact
+  mode uses small defaults and one leaderboard by default. Use `sections`,
+  `topWalletSections`, and `topMarketsLimit` to control payload size.
+- `hunch_get_wallet_intel`: public wallet profile plus optional sections.
+- `hunch_get_wallet_activity`: public wallet activity rows. Pass `walletId` as
+  a Hunch UUID, or pass `address` plus optional `chain` to resolve first.
+- `hunch_get_wallet_positions`: current or historical public wallet positions.
+  Pass `walletId` as a Hunch UUID, or pass `address` plus optional `chain` to
+  resolve first.
+- `hunch_get_wallet_series`: public wallet activity, performance, and PnL time
+  series. Pass `walletId` as a Hunch UUID, or pass `address` plus optional
+  `chain`; `limit` trims returned point arrays.
+- `hunch_get_wallet_signals`: public wallet activity signals. Pass `walletId`
+  as a Hunch UUID, or pass `address` plus optional `chain` to resolve first.
+- `hunch_get_signals`: global, event, market, or map-node signals. Use
+  `marketId`, `eventId`, or `targetId` according to `scope`.
+- `hunch_get_trades`: recent public trade tape.
+
+All tools accept `responseMode` when supported:
+
+- `compact`: default, small payloads for agent reasoning.
+- `standard`: descriptions, metadata, and larger previews.
+- `full`: raw backend payload.
+
+## CLI Commands
+
+```bash
+scripts/hunch discovery-browse --venues polymarket,kalshi --sort totalvol --limit 10 --json
+scripts/hunch discovery-search "election" --limit 10 --json
+scripts/hunch market-detail <market-id> --standard --json
+scripts/hunch event-detail <event-id> --standard --json
+scripts/hunch discovery-map --venues polymarket,kalshi,limitless --json
+scripts/hunch discovery-top-lists --trending-limit 10 --volume-movers-sort-by absolute --json
+scripts/hunch arbitrage-clusters --min-liquidity 1000 --limit 10 --json
+scripts/hunch market-alternatives polymarket:553828 --venues polymarket,kalshi,limitless --json
+scripts/hunch similar-markets <market-id> --limit 10 --json
+scripts/hunch similar-events <event-id> --market-id <market-id> --limit 10 --json
+scripts/hunch market-holders <market-id> --limit 20 --json
+scripts/hunch market-price-history <market-id> --range 1d --sides BOTH --json
+scripts/hunch event-price-history <event-id> --range 1d --limit 5 --json
+scripts/hunch tracking-overview --window-hours 24 --json
+scripts/hunch wallet-intel <address> --chain polygon --include-signals --json
+scripts/hunch wallet-activity --wallet-id <uuid> --limit 50 --json
+scripts/hunch wallet-positions --wallet-id <uuid> --history --json
+scripts/hunch wallet-series <wallet-id> --window-hours 168 --json
+scripts/hunch wallet-signals --wallet-id <uuid> --limit 50 --json
+scripts/hunch signals --event-id <event-id> --include-similar-markets --json
+scripts/hunch trades --market-id <market-id> --limit 25 --json
+```
+
+`HUNCH_API_BASE_URL` controls the target API. `HUNCH_APP_BASE_URL` controls app
+links in compact/standard responses. Both default to production. No auth token
+is required or used by this public package.
+
+Useful filters:
+
+- Discovery: `--venues`, `--view`, `--sort`, `--sort-dir`, `--category`,
+  `--min-volume24h`, `--min-liquidity`, `--max-spread`.
+- Discovery top lists: per-list limits, volume/liquidity floors, absolute or
+  percent mover sort modes, and optional volume/liquidity/movement sparklines.
+- Arbitrage: `--min-liquidity`, `--min-venue-count`, `--min-spread`,
+  `--sort-by`.
+- Market alternatives: `--venues`, `--limit`, and `--source-limit`.
+- Similar/event page: `--limit`, `--venue`, `--active-only`, `--cutoff`,
+  `--market-id`, `--include-details`, `--include-event-fallback`,
+  `--range`, `--bucket-minutes`, `--side`, `--sides`.
+- Tracking and wallet intel: `--window-hours`, `--scope`, `--wallet-id`,
+  `--include-signals`, `--include-activity`, `--include-positions`,
+  `--include-series`, labels, categories, tags, and attribution filters.
+
+When answering users, show titles, venues, odds/metrics, and Hunch links first.
+Use stable Hunch IDs only as secondary technical references. Link formats:
+
+- Event: `https://app.hunch.trade/events/<eventId>`
+- Market: `https://app.hunch.trade/events/<eventId>?market=<marketId>`
+- Tracking wallet:
+  `https://app.hunch.trade/tracking/wallet/<address>?chain=<chain>`
+- Tracking overview: `https://app.hunch.trade/tracking?...`
+- Arbitrage: `https://app.hunch.trade/arbitrage`
+
+For event-page questions, use event detail first, then add specific context as
+needed: `market-alternatives <selected-market-id>`, `signals --event-id`,
+`similar-events`, `event-price-history`, `trades --event-id`, and
+`market-holders <selected-market-id>`. Discovery-map node insights use
+`signals --scope node --target-id <node-id>`; request `discovery-map --standard`
+when signal previews are needed.
+
+Price history uses `range` for the requested time window and `bucketMinutes`
+for candle size. `interval` is still accepted as a legacy alias for `range`.

package/skills/hunch-trading/scripts/hunch

@@ -0,0 +1,28 @@
+#!/usr/bin/env sh
+set -eu
+
+if [ -n "${HUNCH_AGENT_BIN:-}" ]; then
+  exec "$HUNCH_AGENT_BIN" "$@"
+fi
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+SKILL_ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)
+PLUGIN_ROOT=$(CDPATH= cd -- "$SKILL_ROOT/../.." && pwd)
+
+SKILL_CLI="$SKILL_ROOT/bin/hunch-agent.js"
+PLUGIN_CLI="$PLUGIN_ROOT/plugin-dist/hunch-agent.js"
+DEV_CLI="$PLUGIN_ROOT/apps/mcp-hunch/dist/cli.js"
+
+if [ -f "$SKILL_CLI" ]; then
+  exec node "$SKILL_CLI" "$@"
+fi
+
+if [ -f "$PLUGIN_CLI" ]; then
+  exec node "$PLUGIN_CLI" "$@"
+fi
+
+if [ -f "$DEV_CLI" ]; then
+  exec node "$DEV_CLI" "$@"
+fi
+
+exec hunch-agent "$@"