hunch-agent 0.1.0__py3-none-any.whl

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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+hunch_agent/__init__.py,sha256=swLQsA7_3y8Ijhd1K4Xpnu1RXEK3kC6kbjRoiEn51uo,1169
+hunch_agent/client.py,sha256=OeGS6isWj_k8q9yFHLXefBB7MTrRt2U__w_4u771JZI,7573
+hunch_agent/errors.py,sha256=_w1O5jJ8G6-NFh_AUOhwzmAvAmCc9JXrgAwt9u792io,1308
+hunch_agent/webhooks.py,sha256=PTxK7agC4llU7xHRKJmkehmJv7oF-lr092MIqrZjriI,2472
+hunch_agent/x402.py,sha256=R-ZiNLO5ZAqsm0rm1C-lxfvAosU1_dax6SEFJTO_z5U,4485
+hunch_agent-0.1.0.dist-info/METADATA,sha256=y21e66lBtu4ujiAcrGs4VLOm4h_sp9fCucPY3CqI-M0,2525
+hunch_agent-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+hunch_agent-0.1.0.dist-info/RECORD,,

hunch_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any