hunch-agent 0.1.0__tar.gz

hunch_agent-0.1.0/.gitignore

@@ -0,0 +1,98 @@
+# dependencies
+/node_modules
+.pnpm-store
+
+# next
+/.next
+/out
+next-env.d.ts
+
+# production
+/build
+
+# test / coverage
+/coverage
+
+# misc
+.DS_Store
+*.tsbuildinfo
+*.log
+
+# env
+.env*
+!.env.example
+*.pem
+*.key
+*.p8
+*.p12
+*.cer
+*.crt
+*.secret
+*.secrets.*
+/secrets/
+
+# editor
+.vscode
+.idea
+.vercel
+.claude/
+.superpowers/
+.burn-rate/
+supabase/.temp/
+
+# local agent/operator notes
+AGENTS.md
+CLAUDE.md
+**/AGENTS.md
+**/CLAUDE.md
+/hunch-scope.md
+/SUBMISSION.md
+/notes/
+/scratch/
+/tmp/
+
+# internal docs; keep the markdown source used by the public roadmap route
+/docs/*
+!/docs/ARBITRUM.md
+!/docs/hunch-catalysts-10m-manifesto.md
+!/docs/playhunch-future-roadmap.md
+# Context Router per-feature docs (committed — the relocated CLAUDE.md context)
+!/docs/context/
+!/docs/context/*.md
+# Hunch-on-Sui docs (committed — runbook + submission notes for the Sui rail)
+!/docs/sui/
+!/docs/sui/*.md
+
+# generated media and local capture artifacts
+/videos/
+/recordings/
+/screenshots/
+/captures/
+/generated_images/
+captures/
+*.mp4
+*.mov
+*.webm
+*.m4v
+*.wav
+*.mp3
+.gstack/
+
+# Foundry (Arbitrum vault)
+contracts/out/
+contracts/cache/
+contracts/broadcast/
+
+# Python agent SDK (sdk/python) + examples
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+sdk/python/dist/
+sdk/python/build/
+
+# Agent SDK build output
+packages/*/dist/
+
+# Move build artifacts (regenerated by `sui move build`)
+move/**/build/

hunch_agent-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: hunch-agent
+Version: 0.1.0
+Summary: Python client for the Hunch agent platform — keyless, no-cap x402 prediction-market betting on Base.
+Project-URL: Homepage, https://www.playhunch.xyz/agents
+Project-URL: Documentation, https://www.playhunch.xyz/llms-full.txt
+License: MIT
+Keywords: agents,base,hunch,prediction-markets,usdc,x402
+Requires-Python: >=3.9
+Requires-Dist: eth-account>=0.10
+Requires-Dist: httpx>=0.24
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# hunch-agent (Python)
+
+Python client for the [Hunch](https://www.playhunch.xyz) agent platform. Keyless,
+no-cap, auto-payout.
+
+```bash
+# PyPI release pending — install from source:
+pip install "git+https://github.com/rajkaria/hunch.git#subdirectory=sdk/python"
+# or from a local clone:  pip install -e sdk/python
+```
+
+## $0 simulation (no wallet)
+
+```python
+from hunch_agent import HunchAgent
+
+hunch = HunchAgent()  # defaults to https://www.playhunch.xyz
+markets = hunch.markets(status="open", limit=5)
+research = hunch.research(markets[0]["id"])
+print(research["resolutionRules"]["description"], research["odds"])
+
+sim = hunch.bet(
+    markets[0]["id"], "yes", 1,
+    wallet_address="0xYourWallet...", simulate=True,
+)
+print(sim["simulated"], sim["position"])  # True, {...}
+```
+
+## Real bet (x402 USDC on Base)
+
+The client runs the whole x402 loop for you — POST, get the 402, sign the exact
+USDC `transferWithAuthorization` with `eth_account`, retry with `X-PAYMENT`. The
+wallet only needs USDC on Base; gas is sponsored. Winners are paid automatically —
+no claim step.
+
+```python
+from eth_account import Account
+from hunch_agent import HunchAgent
+
+account = Account.from_key("0x...")             # a funded Base wallet
+hunch = HunchAgent(account=account)
+
+receipt = hunch.bet("market-id", "yes", 5)      # <= $10: simple tier
+print(receipt["txHash"], receipt["proofUrl"])
+
+# > $10: lock a quote first.
+q = hunch.quote("market-id", "yes", 250)
+hunch.bet("market-id", "yes", 250, quote_id=q["quoteId"], min_shares_out=q["suggestedMinSharesOut"])
+```
+
+## Verifying webhooks
+
+```python
+from hunch_agent import verify_webhook
+
+result = verify_webhook(request.headers, raw_body, secret)
+if result["valid"]:
+    handle(result["event"])
+```
+
+The TypeScript SDK (`@hunchxyz/agent-sdk`) carries the full live-route contract
+tests; this client is the Python convenience surface, tested against recorded
+fixtures. Full protocol docs: <https://www.playhunch.xyz/llms-full.txt>.

hunch_agent-0.1.0/README.md

@@ -0,0 +1,63 @@
+# hunch-agent (Python)
+
+Python client for the [Hunch](https://www.playhunch.xyz) agent platform. Keyless,
+no-cap, auto-payout.
+
+```bash
+# PyPI release pending — install from source:
+pip install "git+https://github.com/rajkaria/hunch.git#subdirectory=sdk/python"
+# or from a local clone:  pip install -e sdk/python
+```
+
+## $0 simulation (no wallet)
+
+```python
+from hunch_agent import HunchAgent
+
+hunch = HunchAgent()  # defaults to https://www.playhunch.xyz
+markets = hunch.markets(status="open", limit=5)
+research = hunch.research(markets[0]["id"])
+print(research["resolutionRules"]["description"], research["odds"])
+
+sim = hunch.bet(
+    markets[0]["id"], "yes", 1,
+    wallet_address="0xYourWallet...", simulate=True,
+)
+print(sim["simulated"], sim["position"])  # True, {...}
+```
+
+## Real bet (x402 USDC on Base)
+
+The client runs the whole x402 loop for you — POST, get the 402, sign the exact
+USDC `transferWithAuthorization` with `eth_account`, retry with `X-PAYMENT`. The
+wallet only needs USDC on Base; gas is sponsored. Winners are paid automatically —
+no claim step.
+
+```python
+from eth_account import Account
+from hunch_agent import HunchAgent
+
+account = Account.from_key("0x...")             # a funded Base wallet
+hunch = HunchAgent(account=account)
+
+receipt = hunch.bet("market-id", "yes", 5)      # <= $10: simple tier
+print(receipt["txHash"], receipt["proofUrl"])
+
+# > $10: lock a quote first.
+q = hunch.quote("market-id", "yes", 250)
+hunch.bet("market-id", "yes", 250, quote_id=q["quoteId"], min_shares_out=q["suggestedMinSharesOut"])
+```
+
+## Verifying webhooks
+
+```python
+from hunch_agent import verify_webhook
+
+result = verify_webhook(request.headers, raw_body, secret)
+if result["valid"]:
+    handle(result["event"])
+```
+
+The TypeScript SDK (`@hunchxyz/agent-sdk`) carries the full live-route contract
+tests; this client is the Python convenience surface, tested against recorded
+fixtures. Full protocol docs: <https://www.playhunch.xyz/llms-full.txt>.

hunch_agent-0.1.0/hunch_agent/__init__.py

@@ -0,0 +1,42 @@
+"""hunch_agent — Python client for the Hunch agent platform.
+
+Keyless, no-cap, auto-payout prediction-market betting. The paying wallet IS the
+account — no API keys. Winners are paid out automatically on resolution.
+
+    from hunch_agent import HunchAgent
+    hunch = HunchAgent()
+    markets = hunch.markets(status="open", limit=5)
+    sim = hunch.bet(markets[0]["id"], "yes", 1, wallet_address="0x...", simulate=True)
+
+Docs: https://www.playhunch.xyz/llms.txt
+"""
+
+from .client import DEFAULT_BASE_URL, HunchAgent
+from .errors import HunchApiError, HunchPaymentRequiredError
+from .webhooks import sign_webhook_payload, verify_webhook
+from .x402 import (
+    BASE_CHAIN_ID,
+    HunchX402Error,
+    build_transfer_authorization,
+    encode_x_payment_header,
+    parse_x402_challenge,
+    random_nonce,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "HunchAgent",
+    "DEFAULT_BASE_URL",
+    "HunchApiError",
+    "HunchPaymentRequiredError",
+    "verify_webhook",
+    "sign_webhook_payload",
+    "parse_x402_challenge",
+    "build_transfer_authorization",
+    "encode_x_payment_header",
+    "random_nonce",
+    "HunchX402Error",
+    "BASE_CHAIN_ID",
+    "__version__",
+]

hunch_agent-0.1.0/hunch_agent/client.py

@@ -0,0 +1,205 @@
+"""HunchAgent — the Python client for the Hunch agent platform.
+
+Mirrors the TypeScript SDK: thin typed GETs that return the wire dicts, and a
+``bet()`` that runs the full x402 loop (POST → 402 → sign EIP-3009 → retry with
+``X-PAYMENT``). ``simulate=True`` needs no wallet. The TS SDK owns the
+live-route contract tests; this client is the convenience surface for Python
+agents and is exercised against recorded fixtures.
+"""
+
+from __future__ import annotations
+
+import secrets
+from typing import Any, Dict, List, Optional, Sequence
+
+import httpx
+
+from .errors import HunchApiError, HunchPaymentRequiredError
+from .x402 import (
+    build_transfer_authorization,
+    encode_x_payment_header,
+    parse_x402_challenge,
+)
+
+DEFAULT_BASE_URL = "https://www.playhunch.xyz"
+
+
+def _clean(params: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _random_idem() -> str:
+    return "sdk-" + secrets.token_hex(16)
+
+
+def _sign_typed_data(account: Any, typed_data: Dict[str, Any]) -> str:
+    """Sign EIP-712 typed data with an ``eth_account`` local account → ``0x``+130 hex."""
+    from eth_account.messages import encode_typed_data
+
+    signable = encode_typed_data(full_message=typed_data)
+    signed = account.sign_message(signable)
+    signature = signed.signature.hex()
+    return signature if signature.startswith("0x") else "0x" + signature
+
+
+class HunchAgent:
+    """A keyless client. Pass ``account`` (an ``eth_account`` LocalAccount) only
+    for real bets; reads and simulations need nothing."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        account: Any = None,
+        client: Optional[httpx.Client] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.account = account
+        self._client = client or httpx.Client(timeout=timeout)
+
+    # -- internals ---------------------------------------------------------
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        res = self._client.get(self.base_url + path, params=params)
+        return self._unwrap(res)
+
+    def _unwrap(self, res: httpx.Response) -> Any:
+        body: Any = res.json() if res.content else {}
+        if res.status_code >= 400:
+            raise HunchApiError(res.status_code, body if isinstance(body, dict) else {})
+        return body
+
+    # -- read surface ------------------------------------------------------
+
+    def markets(
+        self,
+        status: Optional[str] = None,
+        type: Optional[str] = None,
+        token: Optional[str] = None,
+        ids: Optional[Sequence[str]] = None,
+        limit: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        params = _clean(
+            {
+                "status": status,
+                "type": type,
+                "token": token,
+                "ids": ",".join(ids) if ids else None,
+                "limit": limit,
+            }
+        )
+        return self._get("/api/agent/v1/markets", params).get("markets", [])
+
+    def discover(
+        self, q: Optional[str] = None, post: Optional[str] = None, limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        params = _clean({"q": q, "post": post, "limit": limit})
+        return self._get("/api/agent/v1/discover", params).get("matches", [])
+
+    def market(self, market_id: str) -> Dict[str, Any]:
+        return self._get(f"/api/agent/v1/markets/{market_id}").get("market")
+
+    def research(self, market_id: str) -> Dict[str, Any]:
+        return self._get(f"/api/agent/v1/markets/{market_id}/research").get("research")
+
+    def quote(
+        self, market_id: str, side: str, size_usd: float, wallet: Optional[str] = None
+    ) -> Dict[str, Any]:
+        params = _clean(
+            {"marketId": market_id, "side": side, "sizeUsd": size_usd, "wallet": wallet}
+        )
+        return self._get("/api/agent/v1/quote", params).get("quote")
+
+    def positions(self, wallet: str) -> Dict[str, Any]:
+        return self._get("/api/agent/v1/positions", {"wallet": wallet})
+
+    def result(self, market_id: str) -> Dict[str, Any]:
+        return self._get("/api/agent/v1/result", {"marketId": market_id}).get("result")
+
+    def proof(self, trade_id: str) -> Dict[str, Any]:
+        body = self._get(f"/api/agent/v1/proof/{trade_id}")
+        body.pop("meta", None)
+        return body
+
+    def readiness(self, address: str) -> Dict[str, Any]:
+        return self._get(f"/api/agent/v1/wallet/{address}/readiness").get("readiness")
+
+    def stats(self) -> Dict[str, Any]:
+        return self._get("/api/agent/v1/stats").get("stats")
+
+    def health(self) -> Dict[str, Any]:
+        return self._get("/api/agent/v1/health").get("health")
+
+    def poll(self, wallet: str, since: int = 0, limit: Optional[int] = None) -> Dict[str, Any]:
+        body = self._get(
+            "/api/agent/v1/resolved", _clean({"wallet": wallet, "since": since, "limit": limit})
+        )
+        return {
+            "events": body.get("events", []),
+            "nextSince": body.get("nextSince", since),
+            "count": body.get("count", 0),
+        }
+
+    # -- money path --------------------------------------------------------
+
+    def bet(
+        self,
+        market_id: str,
+        side: str,
+        size_usd: float,
+        *,
+        idem_key: Optional[str] = None,
+        wallet_address: Optional[str] = None,
+        quote_id: Optional[str] = None,
+        min_shares_out: Optional[float] = None,
+        max_price_cents: Optional[int] = None,
+        simulate: bool = False,
+        builder_code: Optional[str] = None,
+        ref: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Place a bet. ``simulate=True`` is a $0 dry run (no account needed); a real
+        bet runs the x402 loop automatically. Raises ``HunchPaymentRequiredError`` if a
+        real bet needs payment but no account is set, or ``HunchApiError`` on a 4xx/5xx."""
+        wallet = wallet_address or (self.account.address if self.account else None)
+        if not wallet:
+            raise ValueError("bet() needs wallet_address or a configured account.")
+
+        body = _clean(
+            {
+                "marketId": market_id,
+                "side": side,
+                "sizeUsd": size_usd,
+                "idemKey": idem_key or _random_idem(),
+                "walletAddress": wallet,
+                "quoteId": quote_id,
+                "minSharesOut": min_shares_out,
+                "maxPriceCents": max_price_cents,
+                "simulate": True if simulate else None,
+                "builderCode": builder_code,
+                "ref": ref,
+            }
+        )
+        url = self.base_url + "/api/agent/v1/trade"
+        res = self._client.post(url, json=body)
+
+        if res.status_code == 402:
+            challenge = res.json()
+            if not self.account:
+                raise HunchPaymentRequiredError(challenge)
+            requirements = parse_x402_challenge(challenge)
+            typed_data, authorization = build_transfer_authorization(wallet, requirements)
+            signature = _sign_typed_data(self.account, typed_data)
+            header = encode_x_payment_header({**authorization, "signature": signature})
+            res = self._client.post(url, json=body, headers={"X-PAYMENT": header})
+
+        out = self._unwrap(res)
+        return out.get("receipt")
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HunchAgent":
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()

hunch_agent-0.1.0/hunch_agent/errors.py

@@ -0,0 +1,42 @@
+"""Typed errors for the Hunch agent client."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+
+class HunchApiError(Exception):
+    """Any non-2xx (and non-402-handled) Hunch API response.
+
+    Carries the errors-as-documentation body: ``error`` (a stable machine code),
+    ``message``, ``hint``, ``docsUrl``, ``retriable``, plus machine-actionable
+    fields like ``requiredUsd``.
+    """
+
+    def __init__(self, status: int, body: Dict[str, Any]) -> None:
+        self.status = status
+        self.body = body or {}
+        super().__init__(
+            self.body.get("message")
+            or self.body.get("error")
+            or f"Hunch API error {status}"
+        )
+
+    @property
+    def code(self) -> str:
+        return self.body.get("error", "unknown_error")
+
+    @property
+    def retriable(self) -> bool:
+        return self.body.get("retriable") is True
+
+
+class HunchPaymentRequiredError(Exception):
+    """A real bet hit a 402 but no signing ``account`` was configured to pay."""
+
+    def __init__(self, challenge: Dict[str, Any]) -> None:
+        self.challenge = challenge
+        super().__init__(
+            "This bet requires an x402 USDC payment, but no signing `account` was "
+            "configured. Pass `account=` to HunchAgent, or use simulate=True."
+        )

hunch_agent-0.1.0/hunch_agent/webhooks.py

@@ -0,0 +1,63 @@
+"""Webhook signature verification — the receiving half of Hunch's signed events.
+
+The recipe is byte-identical to the server's ``signEvent`` (src/agent/events.ts)
+and the TS SDK: ``hex(hmacSHA256(secret, eventId + "." + timestamp + "." + body))``,
+sent as ``Hunch-Signature: v1=<hex>`` alongside ``Hunch-Event-Id`` /
+``Hunch-Timestamp``. Verify over the RAW request body.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+from typing import Any, Dict, Optional
+
+
+def _read_header(headers: Any, name: str) -> Optional[str]:
+    # Works for dict-likes and frameworks' case-insensitive header maps.
+    if hasattr(headers, "get"):
+        value = headers.get(name)
+        if value is None:
+            value = headers.get(name.lower())
+        if value is not None:
+            return value if isinstance(value, str) else value[0]
+    try:
+        items = headers.items()
+    except AttributeError:
+        items = dict(headers).items()
+    lower = name.lower()
+    for key, value in items:
+        if str(key).lower() == lower:
+            return value if isinstance(value, str) else value[0]
+    return None
+
+
+def sign_webhook_payload(secret: str, event_id: str, timestamp: str, body: str) -> str:
+    """The bare ``hex(hmacSHA256(secret, eventId + "." + timestamp + "." + body))``."""
+    message = f"{event_id}.{timestamp}.{body}".encode("utf-8")
+    return hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest()
+
+
+def verify_webhook(headers: Any, body: str, secret: str) -> Dict[str, Any]:
+    """Verify a Hunch webhook delivery. Returns ``{valid, event, reason}``; never raises."""
+    event_id = _read_header(headers, "Hunch-Event-Id")
+    timestamp = _read_header(headers, "Hunch-Timestamp")
+    signature = _read_header(headers, "Hunch-Signature")
+    if not event_id or not timestamp or not signature:
+        return {"valid": False, "event": None, "reason": "missing_headers"}
+
+    match = re.match(r"^v1=([0-9a-f]+)$", signature.strip())
+    if not match:
+        return {"valid": False, "event": None, "reason": "bad_signature_format"}
+
+    expected = sign_webhook_payload(secret, event_id, timestamp, body)
+    if not hmac.compare_digest(match.group(1), expected):
+        return {"valid": False, "event": None, "reason": "signature_mismatch"}
+
+    try:
+        event = json.loads(body)
+    except (ValueError, TypeError):
+        event = None
+    return {"valid": True, "event": event, "reason": "ok"}

hunch_agent-0.1.0/hunch_agent/x402.py

@@ -0,0 +1,127 @@
+"""Client-side x402 codec — the payment half of the Hunch agent rail.
+
+Mirrors the TS SDK (`packages/hunch-agent-sdk/src/x402.ts`) and the server codec
+(`src/lib/x402.ts`): parse a 402 challenge, build the EIP-3009
+``transferWithAuthorization`` typed data, and encode the base64 ``X-PAYMENT``
+header the trade route decodes. Pure — signing is done by the caller's
+``eth_account`` account.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import secrets
+import time
+from typing import Any, Dict, Optional, Tuple
+
+#: Base mainnet chain id — the only settlement chain on the agent rail.
+BASE_CHAIN_ID = 8453
+
+_DEFAULT_VALID_SECONDS = 10 * 60
+_CLOCK_SKEW_SECONDS = 60
+
+#: EIP-712 type for USDC's EIP-3009 ``transferWithAuthorization``.
+TRANSFER_WITH_AUTHORIZATION_TYPES = {
+    "TransferWithAuthorization": [
+        {"name": "from", "type": "address"},
+        {"name": "to", "type": "address"},
+        {"name": "value", "type": "uint256"},
+        {"name": "validAfter", "type": "uint256"},
+        {"name": "validBefore", "type": "uint256"},
+        {"name": "nonce", "type": "bytes32"},
+    ],
+}
+
+
+class HunchX402Error(Exception):
+    """Raised when a 402 challenge is missing or not the Base USDC exact scheme."""
+
+
+def parse_x402_challenge(body: Dict[str, Any]) -> Dict[str, Any]:
+    """Return the single usable payment requirement from a 402 challenge body."""
+    accepts = (body or {}).get("accepts")
+    if not isinstance(accepts, list) or not accepts:
+        raise HunchX402Error("402 challenge did not advertise a payment requirement.")
+    first = accepts[0]
+    if first.get("scheme") != "exact":
+        raise HunchX402Error(f"Unsupported x402 scheme: {first.get('scheme')}")
+    if first.get("network") != "base":
+        raise HunchX402Error(f"Unsupported x402 network: {first.get('network')}")
+    if not first.get("payTo") or not first.get("asset") or not first.get("extra"):
+        raise HunchX402Error("402 challenge is missing payTo / asset / domain extra.")
+    return first
+
+
+def random_nonce() -> str:
+    """A fresh, single-use 32-byte EIP-3009 nonce (``0x`` + 64 hex)."""
+    return "0x" + secrets.token_hex(32)
+
+
+def build_transfer_authorization(
+    from_addr: str,
+    requirements: Dict[str, Any],
+    now: Optional[int] = None,
+    nonce: Optional[str] = None,
+    valid_seconds: int = _DEFAULT_VALID_SECONDS,
+) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """Build ``(typed_data, authorization)`` from a parsed challenge requirement."""
+    now = int(now if now is not None else time.time())
+    valid_after = max(0, now - _CLOCK_SKEW_SECONDS)
+    valid_before = now + valid_seconds
+    nonce = nonce or random_nonce()
+    to = requirements["payTo"]
+    value = requirements["maxAmountRequired"]
+
+    authorization = {
+        "from": from_addr,
+        "to": to,
+        "value": value,
+        "validAfter": valid_after,
+        "validBefore": valid_before,
+        "nonce": nonce,
+    }
+    typed_data = {
+        "types": {
+            "EIP712Domain": [
+                {"name": "name", "type": "string"},
+                {"name": "version", "type": "string"},
+                {"name": "chainId", "type": "uint256"},
+                {"name": "verifyingContract", "type": "address"},
+            ],
+            **TRANSFER_WITH_AUTHORIZATION_TYPES,
+        },
+        "domain": {
+            "name": requirements["extra"]["name"],
+            "version": requirements["extra"]["version"],
+            "chainId": BASE_CHAIN_ID,
+            "verifyingContract": requirements["asset"],
+        },
+        "primaryType": "TransferWithAuthorization",
+        "message": {
+            "from": from_addr,
+            "to": to,
+            "value": int(value),
+            "validAfter": valid_after,
+            "validBefore": valid_before,
+            "nonce": nonce,
+        },
+    }
+    return typed_data, authorization
+
+
+def encode_x_payment_header(signed_authorization: Dict[str, Any]) -> str:
+    """Encode a signed authorization into the base64 ``X-PAYMENT`` header value."""
+    payload = {
+        "x402Version": 1,
+        "scheme": "exact",
+        "network": "base",
+        "payload": {
+            "signature": signed_authorization["signature"],
+            "authorization": {
+                k: signed_authorization[k]
+                for k in ("from", "to", "value", "validAfter", "validBefore", "nonce")
+            },
+        },
+    }
+    return base64.b64encode(json.dumps(payload).encode("utf-8")).decode("ascii")

hunch_agent-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hunch-agent"
+version = "0.1.0"
+description = "Python client for the Hunch agent platform — keyless, no-cap x402 prediction-market betting on Base."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["hunch", "prediction-markets", "x402", "agents", "base", "usdc"]
+dependencies = [
+  "httpx>=0.24",
+  "eth-account>=0.10",
+]
+
+[project.urls]
+Homepage = "https://www.playhunch.xyz/agents"
+Documentation = "https://www.playhunch.xyz/llms-full.txt"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["hunch_agent"]

hunch_agent-0.1.0/tests/test_webhooks.py

@@ -0,0 +1,52 @@
+"""Webhook verifier — recorded-fixture tests (no network).
+
+The signing recipe matches the server (`signEvent` in src/agent/events.ts) and
+the TS SDK exactly, so a self-consistent sign→verify round trip proves parity.
+"""
+
+import json
+
+from hunch_agent.webhooks import sign_webhook_payload, verify_webhook
+
+SECRET = "whsec_test_secret_0123456789"
+EVENT_ID = "ev_deadbeef"
+TS = "2026-06-13T00:00:00.000Z"
+
+
+def _delivery(body=None, sig=None):
+    body = body if body is not None else json.dumps(
+        {"eventId": EVENT_ID, "seq": 42, "type": "market.resolved", "payload": {"resolvedSide": "no"}}
+    )
+    sig = sig if sig is not None else "v1=" + sign_webhook_payload(SECRET, EVENT_ID, TS, body)
+    headers = {
+        "Hunch-Event-Id": EVENT_ID,
+        "Hunch-Timestamp": TS,
+        "Hunch-Signature": sig,
+    }
+    return headers, body
+
+
+def test_accepts_a_correctly_signed_delivery():
+    headers, body = _delivery()
+    result = verify_webhook(headers, body, SECRET)
+    assert result["valid"] is True
+    assert result["event"]["type"] == "market.resolved"
+
+
+def test_rejects_tampered_body():
+    headers, body = _delivery()
+    tampered = body.replace('"no"', '"yes"')
+    result = verify_webhook(headers, tampered, SECRET)
+    assert result["valid"] is False
+    assert result["reason"] == "signature_mismatch"
+
+
+def test_rejects_wrong_secret_and_missing_headers():
+    headers, body = _delivery()
+    assert verify_webhook(headers, body, "whsec_wrong")["valid"] is False
+    assert verify_webhook({}, body, SECRET)["reason"] == "missing_headers"
+
+
+def test_rejects_malformed_signature_header():
+    headers, body = _delivery(sig="garbage")
+    assert verify_webhook(headers, body, SECRET)["reason"] == "bad_signature_format"

hunch_agent-0.1.0/tests/test_x402.py

@@ -0,0 +1,84 @@
+"""x402 codec — recorded-fixture tests (no network)."""
+
+import base64
+import json
+
+from hunch_agent.x402 import (
+    BASE_CHAIN_ID,
+    HunchX402Error,
+    build_transfer_authorization,
+    encode_x_payment_header,
+    parse_x402_challenge,
+    random_nonce,
+)
+
+SINK = "0x1111111111111111111111111111111111111111"
+WALLET = "0x2222222222222222222222222222222222222222"
+USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+
+
+def _challenge(amount_atomic):
+    return {
+        "x402Version": 1,
+        "error": None,
+        "accepts": [
+            {
+                "scheme": "exact",
+                "network": "base",
+                "maxAmountRequired": amount_atomic,
+                "resource": "https://www.playhunch.xyz/api/agent/v1/trade#0xabc",
+                "description": "t",
+                "mimeType": "application/json",
+                "payTo": SINK,
+                "maxTimeoutSeconds": 120,
+                "asset": USDC,
+                "extra": {"name": "USD Coin", "version": "2"},
+            }
+        ],
+    }
+
+
+def test_parse_extracts_uncapped_requirement():
+    req = parse_x402_challenge(_challenge("5000000000"))
+    assert req["maxAmountRequired"] == "5000000000"
+    assert req["payTo"] == SINK
+
+
+def test_parse_rejects_bad_scheme_and_empty():
+    for bad in ({"accepts": []}, {"accepts": [{"scheme": "x", "network": "base"}]}):
+        try:
+            parse_x402_challenge(bad)
+            assert False, "expected HunchX402Error"
+        except HunchX402Error:
+            pass
+
+
+def test_build_typed_data_domain_and_message():
+    req = parse_x402_challenge(_challenge("3000000"))
+    typed, auth = build_transfer_authorization(
+        WALLET, req, now=1000, nonce="0x" + "a" * 64
+    )
+    assert typed["domain"]["chainId"] == BASE_CHAIN_ID
+    assert typed["domain"]["name"] == "USD Coin"
+    assert typed["primaryType"] == "TransferWithAuthorization"
+    assert typed["message"]["value"] == 3000000
+    assert auth["validAfter"] == 940  # now - 60
+    assert auth["validBefore"] == 1600  # now + 600
+
+
+def test_encode_header_round_trips():
+    req = parse_x402_challenge(_challenge("3000000"))
+    _typed, auth = build_transfer_authorization(WALLET, req, now=1000, nonce="0x" + "a" * 64)
+    header = encode_x_payment_header({**auth, "signature": "0x" + "b" * 130})
+    decoded = json.loads(base64.b64decode(header))
+    assert decoded["scheme"] == "exact"
+    assert decoded["network"] == "base"
+    assert decoded["payload"]["authorization"]["value"] == "3000000"
+    assert decoded["payload"]["authorization"]["to"] == SINK
+    assert decoded["payload"]["signature"] == "0x" + "b" * 130
+
+
+def test_random_nonce_is_fresh_32_bytes():
+    a, b = random_nonce(), random_nonce()
+    assert a != b
+    assert len(a) == 66 and a.startswith("0x")