poh-sdk 0.1.0__tar.gz

poh_sdk-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.*
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store

poh_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: poh-sdk
+Version: 0.1.0
+Summary: Proof of Human SDK — scan wallets, poll async jobs, access signal methods
+License: MIT
+Keywords: identity,proof-of-human,solana,wallet,web3
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# poh-sdk
+
+Python SDK for the [Proof of Human](https://proofofhuman.ge) API.
+
+## Install
+
+```bash
+pip install poh-sdk
+```
+
+## Quick start
+
+```python
+import asyncio
+from poh_sdk import PohClient
+
+async def main():
+    async with PohClient("https://proofofhuman.ge") as poh:
+        result = await poh.scan("0xabc...")
+        print(result.result)   # True = human, False = bot, None = inconclusive
+
+asyncio.run(main())
+```
+
+## Sync usage
+
+```python
+from poh_sdk import PohClient
+
+poh = PohClient.sync("https://proofofhuman.ge")
+result = poh.scan("0xabc...")
+```
+
+## Bulk scanning
+
+```python
+async with PohClient("https://proofofhuman.ge") as poh:
+    job = await poh.scan_bulk(["0xaaa", "0xbbb", "0xccc"])
+
+    async for snap in poh.watch_job(job.job_id):
+        print(f"{snap.percent:.0f}% done")
+```

poh_sdk-0.1.0/README.md

@@ -0,0 +1,42 @@
+# poh-sdk
+
+Python SDK for the [Proof of Human](https://proofofhuman.ge) API.
+
+## Install
+
+```bash
+pip install poh-sdk
+```
+
+## Quick start
+
+```python
+import asyncio
+from poh_sdk import PohClient
+
+async def main():
+    async with PohClient("https://proofofhuman.ge") as poh:
+        result = await poh.scan("0xabc...")
+        print(result.result)   # True = human, False = bot, None = inconclusive
+
+asyncio.run(main())
+```
+
+## Sync usage
+
+```python
+from poh_sdk import PohClient
+
+poh = PohClient.sync("https://proofofhuman.ge")
+result = poh.scan("0xabc...")
+```
+
+## Bulk scanning
+
+```python
+async with PohClient("https://proofofhuman.ge") as poh:
+    job = await poh.scan_bulk(["0xaaa", "0xbbb", "0xccc"])
+
+    async for snap in poh.watch_job(job.job_id):
+        print(f"{snap.percent:.0f}% done")
+```

poh_sdk-0.1.0/poh_sdk/__init__.py

@@ -0,0 +1,28 @@
+from .client import PohClient, PohError
+from .types import (
+    ScanResult,
+    BulkScanResult,
+    JobStatus,
+    ScanResultItem,
+    BrainVerdict,
+    BrainPollOptions,
+    ScanWithVerdict,
+    Method,
+    ScanOptions,
+    PollOptions,
+)
+
+__all__ = [
+    "PohClient",
+    "PohError",
+    "ScanResult",
+    "BulkScanResult",
+    "JobStatus",
+    "ScanResultItem",
+    "BrainVerdict",
+    "BrainPollOptions",
+    "ScanWithVerdict",
+    "Method",
+    "ScanOptions",
+    "PollOptions",
+]

poh_sdk-0.1.0/poh_sdk/client.py

@@ -0,0 +1,403 @@
+"""
+Proof of Human Python SDK — async + sync client.
+
+Async usage (recommended):
+    import asyncio
+    from poh_sdk import PohClient
+
+    async def main():
+        async with PohClient("https://proofofhuman.ge", api_key="...") as poh:
+            res = await poh.scan("0xabc...")
+            print(res.result)
+
+    asyncio.run(main())
+
+Sync usage:
+    from poh_sdk import PohClient
+
+    poh = PohClient.sync("https://proofofhuman.ge", api_key="...")
+    res = poh.scan_sync("0xabc...")
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import AsyncIterator, List, Optional
+from urllib.parse import quote
+
+import httpx
+
+from .types import (
+    BrainPollOptions,
+    BrainVerdict,
+    BulkScanResult,
+    JobStatus,
+    Method,
+    PollOptions,
+    ScanOptions,
+    ScanResult,
+    ScanWithVerdict,
+)
+
+
+class PohError(Exception):
+    """Raised when the POH API returns a non-2xx response."""
+
+    def __init__(self, message: str, status: int) -> None:
+        super().__init__(message)
+        self.status = status
+
+    def __repr__(self) -> str:
+        return f"PohError(status={self.status}, message={str(self)!r})"
+
+
+class PohClient:
+    """
+    Async Proof of Human API client.
+
+    Use as an async context manager or call :meth:`aclose` when done.
+    For one-off synchronous use, see :meth:`sync`.
+
+    Parameters
+    ----------
+    base_url:
+        Base URL of the POH API, e.g. ``"https://proofofhuman.ge"``.
+    api_key:
+        API key for paid tier.
+    wallet_address:
+        Solana wallet address for free-tier request tracking.
+    timeout:
+        Per-request timeout in seconds (default: 30).
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key:        Optional[str] = None,
+        wallet_address: Optional[str] = None,
+        timeout:        float         = 30.0,
+    ) -> None:
+        self._base_url       = base_url.rstrip("/")
+        self._api_key        = api_key
+        self._wallet_address = wallet_address
+        headers: dict = {"Accept": "application/json"}
+        if api_key:
+            headers["x-api-key"] = api_key
+        self._client = httpx.AsyncClient(
+            base_url = self._base_url,
+            headers  = headers,
+            timeout  = timeout,
+        )
+
+    async def __aenter__(self) -> "PohClient":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    # ── Internal ──────────────────────────────────────────────────────────────
+
+    async def _request(self, method: str, path: str, **kwargs: object) -> dict:
+        try:
+            res = await self._client.request(method, path, **kwargs)
+        except httpx.TimeoutException as exc:
+            raise PohError("Request timed out", 408) from exc
+
+        if res.is_error:
+            try:
+                msg = res.json().get("error", res.text)
+            except Exception:
+                msg = res.text or f"HTTP {res.status_code}"
+            raise PohError(str(msg), res.status_code)
+
+        return res.json()
+
+    # ── Scan ──────────────────────────────────────────────────────────────────
+
+    async def scan(
+        self,
+        input: str,
+        options: Optional[ScanOptions] = None,
+    ) -> ScanResult:
+        """Scan a single wallet address.
+
+        Returns ``result=True`` for human, ``False`` for not-human,
+        ``None`` for inconclusive.
+        """
+        body: dict = {"input": input}
+        if self._wallet_address:
+            body["walletAddress"] = self._wallet_address
+        if options:
+            body.update(options.to_dict())
+        return ScanResult.from_dict(await self._request("POST", "/checker", json=body))
+
+    async def scan_bulk(
+        self,
+        inputs: List[str],
+        options: Optional[ScanOptions] = None,
+    ) -> BulkScanResult:
+        """Submit a bulk scan.
+
+        Returns a :class:`BulkScanResult` with a ``job_id``.
+        Use :meth:`poll_job` or :meth:`watch_job` to retrieve results.
+        """
+        if not inputs:
+            raise ValueError("inputs list must not be empty")
+        body: dict = {"input": inputs}
+        if self._wallet_address:
+            body["walletAddress"] = self._wallet_address
+        if options:
+            body.update(options.to_dict())
+        return BulkScanResult.from_dict(await self._request("POST", "/checker", json=body))
+
+    # ── Job polling ───────────────────────────────────────────────────────────
+
+    async def get_job(self, job_id: str) -> JobStatus:
+        """Fetch the current status snapshot of an async scan job."""
+        return JobStatus.from_dict(await self._request("GET", f"/checker/job/{quote(job_id)}"))
+
+    async def poll_job(
+        self,
+        job_id: str,
+        options: Optional[PollOptions] = None,
+    ) -> JobStatus:
+        """Poll a job until it reaches ``done`` or ``error``.
+
+        Raises :class:`asyncio.TimeoutError` if the job does not finish
+        within ``options.timeout`` seconds.
+        """
+        opts     = options or PollOptions()
+        deadline = time.monotonic() + opts.timeout
+
+        while True:
+            job = await self.get_job(job_id)
+            if opts.on_progress:
+                opts.on_progress(job)
+            if job.is_terminal:
+                return job
+            if time.monotonic() + opts.interval > deadline:
+                raise TimeoutError(
+                    f"POH job '{job_id}' did not complete within {opts.timeout}s"
+                )
+            await asyncio.sleep(opts.interval)
+
+    async def watch_job(
+        self,
+        job_id: str,
+        options: Optional[PollOptions] = None,
+    ) -> AsyncIterator[JobStatus]:
+        """Async generator that yields a status snapshot on each poll tick.
+
+        Terminates when the job is ``done`` or ``error``.
+
+        Example::
+
+            async for snap in poh.watch_job(job_id):
+                print(f"{snap.percent:.0f}% ({snap.done}/{snap.total})")
+        """
+        opts     = options or PollOptions()
+        deadline = time.monotonic() + opts.timeout
+
+        while True:
+            job = await self.get_job(job_id)
+            yield job
+            if job.is_terminal:
+                return
+            if time.monotonic() + opts.interval > deadline:
+                raise TimeoutError(
+                    f"POH job '{job_id}' did not complete within {opts.timeout}s"
+                )
+            await asyncio.sleep(opts.interval)
+
+    async def scan_and_wait(
+        self,
+        inputs: List[str],
+        scan_options:  Optional[ScanOptions]  = None,
+        poll_options:  Optional[PollOptions]  = None,
+    ) -> JobStatus:
+        """Convenience: submit a bulk scan and wait for all results."""
+        job = await self.scan_bulk(inputs, scan_options)
+        return await self.poll_job(job.job_id, poll_options)
+
+    # ── Brain verdict ──────────────────────────────────────────────────────────
+
+    async def get_brain_verdict(self, brain_key: str) -> BrainVerdict:
+        """Retrieve the AI brain verdict for a completed scan."""
+        return BrainVerdict.from_dict(
+            await self._request("GET", f"/checker/brain/{quote(brain_key)}")
+        )
+
+    async def poll_brain_verdict(
+        self,
+        brain_key: str,
+        options: Optional[BrainPollOptions] = None,
+    ) -> BrainVerdict:
+        """Poll the brain verdict until the status leaves ``pending``.
+
+        Raises :class:`TimeoutError` if the verdict does not resolve within
+        ``options.timeout`` seconds.
+
+        Example::
+
+            verdict = await poh.poll_brain_verdict(scan.brain_key)
+            print(verdict.verdict, verdict.confidence)
+        """
+        opts     = options or BrainPollOptions()
+        deadline = time.monotonic() + opts.timeout
+
+        while True:
+            v = await self.get_brain_verdict(brain_key)
+            if v.status != "pending":
+                return v
+            if time.monotonic() + opts.interval > deadline:
+                raise TimeoutError(
+                    f"Brain verdict for '{brain_key}' did not resolve within {opts.timeout}s"
+                )
+            await asyncio.sleep(opts.interval)
+
+    async def scan_and_verdict(
+        self,
+        input: str,
+        scan_options:  Optional[ScanOptions]      = None,
+        brain_options: Optional[BrainPollOptions] = None,
+    ) -> ScanWithVerdict:
+        """Convenience: scan a single address and wait for the AI brain verdict.
+
+        Returns a :class:`ScanWithVerdict` with both the raw scan evidence and
+        the resolved AI verdict.
+
+        Example::
+
+            sv = await poh.scan_and_verdict("0xabc...")
+            print(sv.verdict.verdict, sv.verdict.confidence)
+        """
+        scan = await self.scan(input, scan_options)
+        if not scan.brain_key:
+            return ScanWithVerdict(scan=scan, verdict=BrainVerdict(status="not_found"))
+        verdict = await self.poll_brain_verdict(scan.brain_key, brain_options)
+        return ScanWithVerdict(scan=scan, verdict=verdict)
+
+    # ── Methods ───────────────────────────────────────────────────────────────
+
+    async def get_methods(self, wallet_address: Optional[str] = None) -> List[Method]:
+        """List available signal verification methods."""
+        addr = wallet_address or self._wallet_address
+        qs   = f"?address={quote(addr)}" if addr else ""
+        data = await self._request("GET", f"/verifyer{qs}")
+        return [Method.from_dict(m) for m in data]
+
+    async def get_method(self, method_id: str) -> Method:
+        """Fetch a single signal method by ID."""
+        return Method.from_dict(
+            await self._request("GET", f"/verifyer/{quote(method_id)}")
+        )
+
+    # ── Sync convenience ──────────────────────────────────────────────────────
+
+    @classmethod
+    def sync(
+        cls,
+        base_url: str,
+        *,
+        api_key:        Optional[str] = None,
+        wallet_address: Optional[str] = None,
+        timeout:        float         = 30.0,
+    ) -> "_SyncPohClient":
+        """Return a synchronous wrapper around the async client.
+
+        Example::
+
+            poh = PohClient.sync("https://proofofhuman.ge")
+            res = poh.scan_sync("0xabc...")
+        """
+        return _SyncPohClient(
+            base_url        = base_url,
+            api_key         = api_key,
+            wallet_address  = wallet_address,
+            timeout         = timeout,
+        )
+
+
+class _SyncPohClient:
+    """Synchronous wrapper that runs an event loop internally."""
+
+    def __init__(self, **kwargs: object) -> None:
+        self._kwargs = kwargs
+
+    def _run(self, coro):  # type: ignore[no-untyped-def]
+        return asyncio.get_event_loop().run_until_complete(coro)
+
+    def _client(self) -> PohClient:
+        return PohClient(**self._kwargs)  # type: ignore[arg-type]
+
+    def scan(self, input: str, options: Optional[ScanOptions] = None) -> ScanResult:
+        async def _go():
+            async with self._client() as c:
+                return await c.scan(input, options)
+        return self._run(_go())
+
+    def scan_bulk(self, inputs: List[str], options: Optional[ScanOptions] = None) -> BulkScanResult:
+        async def _go():
+            async with self._client() as c:
+                return await c.scan_bulk(inputs, options)
+        return self._run(_go())
+
+    def get_job(self, job_id: str) -> JobStatus:
+        async def _go():
+            async with self._client() as c:
+                return await c.get_job(job_id)
+        return self._run(_go())
+
+    def poll_job(self, job_id: str, options: Optional[PollOptions] = None) -> JobStatus:
+        async def _go():
+            async with self._client() as c:
+                return await c.poll_job(job_id, options)
+        return self._run(_go())
+
+    def scan_and_wait(
+        self,
+        inputs: List[str],
+        scan_options: Optional[ScanOptions] = None,
+        poll_options: Optional[PollOptions] = None,
+    ) -> JobStatus:
+        async def _go():
+            async with self._client() as c:
+                return await c.scan_and_wait(inputs, scan_options, poll_options)
+        return self._run(_go())
+
+    def get_brain_verdict(self, brain_key: str) -> BrainVerdict:
+        async def _go():
+            async with self._client() as c:
+                return await c.get_brain_verdict(brain_key)
+        return self._run(_go())
+
+    def poll_brain_verdict(
+        self,
+        brain_key: str,
+        options: Optional[BrainPollOptions] = None,
+    ) -> BrainVerdict:
+        async def _go():
+            async with self._client() as c:
+                return await c.poll_brain_verdict(brain_key, options)
+        return self._run(_go())
+
+    def scan_and_verdict(
+        self,
+        input: str,
+        scan_options:  Optional[ScanOptions]      = None,
+        brain_options: Optional[BrainPollOptions] = None,
+    ) -> ScanWithVerdict:
+        async def _go():
+            async with self._client() as c:
+                return await c.scan_and_verdict(input, scan_options, brain_options)
+        return self._run(_go())
+
+    def get_methods(self, wallet_address: Optional[str] = None) -> List[Method]:
+        async def _go():
+            async with self._client() as c:
+                return await c.get_methods(wallet_address)
+        return self._run(_go())

poh_sdk-0.1.0/poh_sdk/types.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional
+
+
+# ── Scan ──────────────────────────────────────────────────────────────────────
+
+@dataclass
+class ScanOptions:
+    chain_ids: Optional[List[str]] = None
+    tx_hash:   Optional[str]       = None
+
+    def to_dict(self) -> dict:
+        d = {}
+        if self.chain_ids is not None:
+            d["chainIds"] = self.chain_ids
+        if self.tx_hash is not None:
+            d["txHash"] = self.tx_hash
+        return d
+
+
+@dataclass
+class ScanResult:
+    result:          Optional[bool]
+    brain_key:       Optional[str]  = None
+    free_scans_left: Optional[int]  = None
+    source:          Optional[str]  = None
+    count:           Optional[int]  = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ScanResult":
+        return cls(
+            result          = d.get("result"),
+            brain_key       = d.get("brainKey"),
+            free_scans_left = d.get("freeScansLeft"),
+            source          = d.get("source"),
+            count           = d.get("count"),
+        )
+
+
+@dataclass
+class BulkScanResult:
+    job_id:          str
+    status:          str
+    total:           int
+    poll_url:        str
+    free_scans_left: Optional[int] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "BulkScanResult":
+        return cls(
+            job_id          = d["jobId"],
+            status          = d["status"],
+            total           = d["total"],
+            poll_url        = d["pollUrl"],
+            free_scans_left = d.get("freeScansLeft"),
+        )
+
+
+# ── Jobs ──────────────────────────────────────────────────────────────────────
+
+@dataclass
+class ScanResultItem:
+    input:  str
+    result: Optional[bool]
+    error:  Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ScanResultItem":
+        return cls(input=d["input"], result=d.get("result"), error=d.get("error"))
+
+
+@dataclass
+class JobStatus:
+    job_id:       str
+    status:       str
+    total:        int
+    done:         int
+    percent:      float
+    results:      List[ScanResultItem]
+    errors:       List[str]
+    created_at:   str
+    completed_at: Optional[str] = None
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in ("done", "error")
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "JobStatus":
+        return cls(
+            job_id       = d["jobId"],
+            status       = d["status"],
+            total        = d["total"],
+            done         = d["done"],
+            percent      = d["percent"],
+            results      = [ScanResultItem.from_dict(r) for r in d.get("results", [])],
+            errors       = d.get("errors", []),
+            created_at   = d["createdAt"],
+            completed_at = d.get("completedAt"),
+        )
+
+
+# ── Poll options ──────────────────────────────────────────────────────────────
+
+@dataclass
+class PollOptions:
+    interval:    float                              = 1.5
+    """Seconds between status checks."""
+    timeout:     float                              = 120.0
+    """Maximum total wait time in seconds."""
+    on_progress: Optional[Callable[[JobStatus], None]] = field(default=None, repr=False)
+
+
+# ── Brain poll options ────────────────────────────────────────────────────────
+
+@dataclass
+class BrainPollOptions:
+    interval: float = 1.5
+    """Seconds between brain verdict checks."""
+    timeout: float = 30.0
+    """Maximum total wait time in seconds."""
+
+
+# ── Scan + verdict combined ───────────────────────────────────────────────────
+
+@dataclass
+class ScanWithVerdict:
+    """Combined result of :meth:`PohClient.scan_and_verdict`."""
+    scan: "ScanResult"
+    verdict: "BrainVerdict"
+
+
+# ── Brain verdict ──────────────────────────────────────────────────────────────
+
+@dataclass
+class BrainVerdict:
+    status:     str
+    verdict:    Optional[str]              = None  # "HUMAN" | "AI" | "UNCERTAIN"
+    confidence: Optional[float]            = None
+    signals:    Optional[Dict[str, float]] = None
+    reasoning:  Optional[str]              = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "BrainVerdict":
+        return cls(
+            status     = d["status"],
+            verdict    = d.get("verdict"),
+            confidence = d.get("confidence"),
+            signals    = d.get("signals"),
+            reasoning  = d.get("reasoning"),
+        )
+
+
+# ── Methods ───────────────────────────────────────────────────────────────────
+
+@dataclass
+class Method:
+    id:          str
+    type:        str
+    description: str
+    score:       float
+    address:     Optional[str] = None
+    method:      Optional[str] = None
+    vote_count:  Optional[int] = None
+    chain_id:    Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Method":
+        return cls(
+            id          = d["id"],
+            type        = d["type"],
+            description = d["description"],
+            score       = d["score"],
+            address     = d.get("address"),
+            method      = d.get("method"),
+            vote_count  = d.get("voteCount"),
+            chain_id    = d.get("chainId"),
+        )

poh_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires      = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name            = "poh-sdk"
+version         = "0.1.0"
+description     = "Proof of Human SDK — scan wallets, poll async jobs, access signal methods"
+readme          = "README.md"
+license         = { text = "MIT" }
+requires-python = ">=3.8"
+keywords        = ["proof-of-human", "identity", "solana", "wallet", "web3"]
+dependencies    = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+dev  = ["pytest", "pytest-asyncio", "respx"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

poh_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,130 @@
+"""Unit tests — no live server required (uses respx to mock httpx)."""
+import asyncio
+import json
+import pytest
+import respx
+from httpx import Response
+
+from poh_sdk import PohClient, PohError, PollOptions, ScanResult, JobStatus
+
+
+BASE = "http://mock-poh"
+
+# ── scan ──────────────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_scan_returns_result():
+    with respx.mock:
+        respx.post(f"{BASE}/checker").mock(return_value=Response(200, json={
+            "result": True, "brainKey": "bk1", "freeScansLeft": 9
+        }))
+        async with PohClient(BASE) as poh:
+            res = await poh.scan("0xabc")
+    assert res.result is True
+    assert res.brain_key == "bk1"
+    assert res.free_scans_left == 9
+
+
+@pytest.mark.asyncio
+async def test_scan_raises_poh_error_on_4xx():
+    with respx.mock:
+        respx.post(f"{BASE}/checker").mock(return_value=Response(
+            401, json={"error": "unauthorized"}
+        ))
+        async with PohClient(BASE) as poh:
+            with pytest.raises(PohError) as exc_info:
+                await poh.scan("0xabc")
+    assert exc_info.value.status == 401
+    assert "unauthorized" in str(exc_info.value)
+
+
+# ── bulk + poll ───────────────────────────────────────────────────────────────
+
+SNAPS = [
+    {"jobId":"j1","status":"processing","total":2,"done":1,"percent":50,"results":[],"errors":[],"createdAt":""},
+    {"jobId":"j1","status":"done","total":2,"done":2,"percent":100,"results":[
+        {"input":"0xaaa","result":True},{"input":"0xbbb","result":False}
+    ],"errors":[],"createdAt":"","completedAt":"2024-01-01T00:00:00Z"},
+]
+
+@pytest.mark.asyncio
+async def test_poll_job_resolves_on_done():
+    call = 0
+    def side_effect(_):
+        nonlocal call
+        snap = SNAPS[min(call, len(SNAPS)-1)]
+        call += 1
+        return Response(200, json=snap)
+
+    with respx.mock:
+        respx.post(f"{BASE}/checker").mock(return_value=Response(200, json={
+            "jobId":"j1","status":"queued","total":2,"pollUrl":"/checker/job/j1","freeScansLeft":5
+        }))
+        respx.get(f"{BASE}/checker/job/j1").mock(side_effect=side_effect)
+
+        async with PohClient(BASE) as poh:
+            bulk = await poh.scan_bulk(["0xaaa","0xbbb"])
+            opts = PollOptions(interval=0.01)
+            done = await poh.poll_job(bulk.job_id, opts)
+
+    assert done.status == "done"
+    assert done.percent == 100
+    assert len(done.results) == 2
+
+
+@pytest.mark.asyncio
+async def test_poll_job_raises_on_timeout():
+    with respx.mock:
+        respx.get(f"{BASE}/checker/job/jx").mock(return_value=Response(200, json={
+            "jobId":"jx","status":"processing","total":1,"done":0,"percent":0,
+            "results":[],"errors":[],"createdAt":""
+        }))
+        async with PohClient(BASE) as poh:
+            with pytest.raises(TimeoutError):
+                await poh.poll_job("jx", PollOptions(interval=0.05, timeout=0.06))
+
+
+@pytest.mark.asyncio
+async def test_watch_job_yields_all_snapshots():
+    call = 0
+    snaps = [
+        {"jobId":"jw","status":"processing","total":3,"done":1,"percent":33,"results":[],"errors":[],"createdAt":""},
+        {"jobId":"jw","status":"processing","total":3,"done":2,"percent":66,"results":[],"errors":[],"createdAt":""},
+        {"jobId":"jw","status":"done","total":3,"done":3,"percent":100,"results":[],"errors":[],"createdAt":""},
+    ]
+    def side(_):
+        nonlocal call
+        s = snaps[min(call, len(snaps)-1)]
+        call += 1
+        return Response(200, json=s)
+
+    with respx.mock:
+        respx.get(f"{BASE}/checker/job/jw").mock(side_effect=side)
+        async with PohClient(BASE) as poh:
+            seen = [snap.percent async for snap in poh.watch_job("jw", PollOptions(interval=0.01))]
+
+    assert seen == [33.0, 66.0, 100.0]
+
+
+# ── scan_bulk validation ───────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_scan_bulk_rejects_empty_list():
+    async with PohClient(BASE) as poh:
+        with pytest.raises(ValueError):
+            await poh.scan_bulk([])
+
+
+# ── methods ───────────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_get_methods_returns_list():
+    with respx.mock:
+        respx.get(f"{BASE}/verifyer").mock(return_value=Response(200, json=[
+            {"id":"m1","type":"evm","description":"ETH balance","score":42.0}
+        ]))
+        async with PohClient(BASE) as poh:
+            methods = await poh.get_methods()
+    assert len(methods) == 1
+    assert methods[0].id == "m1"
+    assert methods[0].type == "evm"