pax-api 2.0.0__py3-none-any.whl

pax_api/__init__.py

@@ -0,0 +1,60 @@
+"""PredictAsiaX (PAX) Python SDK.
+
+Web3-native prediction market REST + WebSocket API client.
+Homepage: https://predictasiax.com/developer
+Docs: https://docs.predictasiax.com
+
+Quick start (anonymous sandbox mint in 30 sec):
+    >>> from pax_api import PaxClient
+    >>> boot = PaxClient(api_key="anonymous")
+    >>> key = boot.mint_sandbox_key(org_name="my-app")
+    >>> print(key["api_key"])   # sk_live_..., shown ONCE — save it
+    >>> client = PaxClient(api_key=key["api_key"])
+    >>> client.list_markets(category="crypto", limit=10)
+
+For HMAC signing (production trading bots):
+    >>> client = PaxClient(
+    ...     api_key="sk_live_...",
+    ...     secret="<hex-secret>",
+    ...     passphrase="<passphrase>",
+    ... )
+    >>> client.place_order(market_id="m_...", outcome_id="yes",
+    ...                    side="buy", order_type="market", size="100")
+
+Environment model: sandbox is a *tier* on the key (tier=self_serve, $10/$100
+caps), not a separate host. Same prefix, same URL — promote to production by
+upgrading the key's tier.
+"""
+
+__version__ = "2.0.0"
+
+from pax_api.client import PaxClient  # noqa: E402
+from pax_api.ws_client import PaxWSClient  # noqa: E402
+from pax_api.errors import (  # noqa: E402
+    PaxError,
+    PaxAuthError,
+    PaxRateLimitError,
+    PaxValidationError,
+    PaxNotFoundError,
+    PaxConflictError,
+    PaxServerError,
+    PaxReadOnlyModeError,
+    PaxSandboxOnlyError,
+    PaxWrongEnvKeyError,
+)
+
+__all__ = [
+    "PaxClient",
+    "PaxWSClient",
+    "PaxError",
+    "PaxAuthError",
+    "PaxRateLimitError",
+    "PaxValidationError",
+    "PaxNotFoundError",
+    "PaxConflictError",
+    "PaxServerError",
+    "PaxReadOnlyModeError",
+    "PaxSandboxOnlyError",
+    "PaxWrongEnvKeyError",
+    "__version__",
+]

pax_api/auth.py

@@ -0,0 +1,66 @@
+"""HMAC signing helpers — Polymarket-compatible 5-header pattern.
+
+Signature construction:
+    message = timestamp_ms + method_upper + path + body
+    signature = base64(HMAC-SHA256(secret, message))
+
+Headers sent:
+    POLY_ACCESS_KEY: <key_id>
+    POLY_TIMESTAMP:  <ms epoch>
+    POLY_PASSPHRASE: <passphrase>
+    POLY_SIGNATURE:  <base64 sig>
+
+Server rejects with 401 INVALID_SIGNATURE if timestamp is more than
+±30 seconds from server clock. Sync your machine via NTP.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import time
+from typing import Dict, Optional
+
+
+def sign_request(
+    method: str,
+    path: str,
+    body: str,
+    key_id: str,
+    secret: str,
+    passphrase: str,
+    timestamp_ms: Optional[int] = None,
+) -> Dict[str, str]:
+    """Build the 5 POLY_* headers for an HMAC-signed request.
+
+    Args:
+        method: HTTP method (GET/POST/DELETE/etc.). Case-normalized to upper.
+        path: URL path INCLUDING leading slash and query string, e.g.
+            ``/v1/markets?category=crypto``.
+        body: Raw request body as string (empty string for GET/DELETE
+            without body). Must be the exact bytes sent on the wire.
+        key_id: Your ``sk_live_*`` key ID.
+        secret: HMAC secret (hex string) obtained at key mint time.
+        passphrase: Passphrase obtained at key mint time.
+        timestamp_ms: Override timestamp for testing. Defaults to now.
+
+    Returns:
+        Dict of 5 headers to merge into the request.
+    """
+    ts = str(timestamp_ms if timestamp_ms is not None else int(time.time() * 1000))
+    method_u = method.upper()
+    message = ts + method_u + path + (body or "")
+    digest = hmac.new(secret.encode("utf-8"), message.encode("utf-8"), hashlib.sha256).digest()
+    signature = base64.b64encode(digest).decode("ascii")
+    return {
+        "POLY_ACCESS_KEY": key_id,
+        "POLY_TIMESTAMP": ts,
+        "POLY_PASSPHRASE": passphrase,
+        "POLY_SIGNATURE": signature,
+    }
+
+
+def build_message(method: str, path: str, body: str, timestamp_ms: int) -> str:
+    """Return the canonical signing message (exposed for debugging)."""
+    return f"{timestamp_ms}{method.upper()}{path}{body or ''}"

pax_api/client.py

@@ -0,0 +1,349 @@
+"""Synchronous REST client for the PAX Trader Track API.
+
+Auth modes (auto-detected):
+    1. HMAC — pass ``api_key`` + ``secret`` + ``passphrase``. Every request
+       signed with 5 POLY_* headers. Use for high-security trading bots.
+    2. API Key — pass only ``api_key``. Sent via X-Api-Key header. Simple
+       for read-only or low-risk M2M flows.
+    3. Bearer — pass ``bearer_token``. Session-based. Browser/mobile only.
+
+Environment:
+    All ``env`` values resolve to the same canonical origin —
+    ``https://api.predictasiax.com/v1``. Sandbox is a *tier* on the key
+    (``tier=self_serve``), not a separate host. Pass a full ``base_url``
+    to override.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from typing import Any, Callable, Dict, List, Optional
+
+import requests
+
+from pax_api.auth import sign_request
+from pax_api.errors import PaxError, build_error
+from pax_api.retry import run_with_retry
+
+__version__ = "2.0.0"  # keep in sync with __init__.py + pyproject.toml
+
+
+# v2: sandbox is a tier on the key, not a separate host. All env aliases
+# resolve to the same canonical origin.
+_ENV_URLS = {
+    "production": "https://api.predictasiax.com/v1",
+    "prod":       "https://api.predictasiax.com/v1",
+    "live":       "https://api.predictasiax.com/v1",
+    "sandbox":    "https://api.predictasiax.com/v1",
+    "test":       "https://api.predictasiax.com/v1",
+}
+
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_USER_AGENT = f"pax-api-python/{__version__}"
+
+
+class PaxClient:
+    """Synchronous PAX API client.
+
+    Examples:
+        Simple API-key read (mint an anonymous sandbox key first):
+
+            >>> boot = PaxClient(api_key="anonymous")
+            >>> key = boot.mint_sandbox_key(org_name="my-app")
+            >>> print(key["api_key"])   # sk_live_..., shown ONCE — save it
+            >>> client = PaxClient(api_key=key["api_key"])
+            >>> client.list_markets(category="crypto", limit=10)
+
+        HMAC-signed trade (production tier):
+
+            >>> client = PaxClient(
+            ...     api_key="sk_live_...",
+            ...     secret="<32-bytes hex>",
+            ...     passphrase="<passphrase>",
+            ... )
+            >>> client.place_order(market_id="m_...", outcome_id="yes",
+            ...                    side="buy", order_type="market", size="100")
+
+        Session bearer (rare — browser/mobile):
+
+            >>> client = PaxClient(bearer_token="<session token>")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        secret: Optional[str] = None,
+        passphrase: Optional[str] = None,
+        bearer_token: Optional[str] = None,
+        env: str = "production",
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 5,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        if not (api_key or bearer_token):
+            raise ValueError("Provide api_key or bearer_token")
+        if secret and not passphrase:
+            raise ValueError("Provide passphrase together with secret for HMAC")
+
+        self.api_key = api_key
+        self.secret = secret
+        self.passphrase = passphrase
+        self.bearer_token = bearer_token
+        self.base_url = (base_url or _ENV_URLS.get(env.lower()) or _ENV_URLS["production"]).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.user_agent = user_agent or DEFAULT_USER_AGENT
+        self._session = requests.Session()
+        self._session.headers.update({"User-Agent": self.user_agent, "Accept": "application/json"})
+
+    # ── low-level request plumbing ──────────────────────────────────────────
+    def _headers_for(self, method: str, path_with_query: str, body: str) -> Dict[str, str]:
+        headers: Dict[str, str] = {}
+        if body:
+            headers["Content-Type"] = "application/json"
+        if self.secret and self.passphrase and self.api_key:
+            # HMAC — path must NOT include /api prefix if base_url already includes /api.
+            # Server signs against the URL path AFTER /api. We strip /api if present.
+            sig_path = path_with_query
+            headers.update(sign_request(method, sig_path, body, self.api_key, self.secret, self.passphrase))
+        elif self.api_key:
+            headers["X-Api-Key"] = self.api_key
+        elif self.bearer_token:
+            headers["Authorization"] = f"Bearer {self.bearer_token}"
+        return headers
+
+    def _do_request(self, method: str, path: str, params: Optional[Dict[str, Any]] = None,
+                    json_body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        url = self.base_url + path
+        body = _json.dumps(json_body, separators=(",", ":"), sort_keys=False) if json_body is not None else ""
+        # Reconstruct path+query for signing to match what server sees
+        # (requests will apply params to URL — replicate here for signature)
+        path_for_sig = path
+        if params:
+            from urllib.parse import urlencode
+            qs = urlencode(params, doseq=True)
+            if qs:
+                path_for_sig = f"{path}?{qs}"
+        headers = self._headers_for(method, path_for_sig, body)
+
+        resp = self._session.request(
+            method=method,
+            url=url,
+            params=params,
+            data=body if body else None,
+            headers=headers,
+            timeout=self.timeout,
+            allow_redirects=False,
+        )
+        try:
+            payload = resp.json()
+        except ValueError:
+            payload = {"ok": False, "error": {"code": "MALFORMED_RESPONSE", "message": resp.text[:300]}}
+
+        if resp.status_code >= 400 or (isinstance(payload, dict) and payload.get("ok") is False):
+            retry_after = resp.headers.get("Retry-After")
+            retry_after_i: Optional[int] = None
+            try:
+                retry_after_i = int(retry_after) if retry_after is not None else None
+            except (TypeError, ValueError):
+                retry_after_i = None
+            raise build_error(resp.status_code, payload, retry_after=retry_after_i)
+        return payload
+
+    def _request(self, method: str, path: str, params: Optional[Dict[str, Any]] = None,
+                 json_body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return run_with_retry(
+            lambda: self._do_request(method, path, params=params, json_body=json_body),
+            max_attempts=self.max_retries,
+        )
+
+    # ── Discovery ────────────────────────────────────────────────────────────
+    def list_markets(self, category: Optional[str] = None, market_type: Optional[str] = None,
+                     status: Optional[str] = None, cursor: Optional[str] = None,
+                     limit: int = 50) -> Dict[str, Any]:
+        """List active markets. Public — no auth strictly required.
+
+        Args:
+            category: e.g. "crypto", "sports", "politics".
+            market_type: "fast" | "normal" | "creator".
+            status: "active" | "locked" | "settling".
+            cursor: Opaque pagination cursor from previous ``meta.next_cursor``.
+            limit: 1-500 (default 50).
+        """
+        params: Dict[str, Any] = {"limit": max(1, min(500, limit))}
+        if category:
+            params["category"] = category
+        if market_type:
+            params["market_type"] = market_type
+        if status:
+            params["status"] = status
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/v1/markets", params=params)
+
+    def get_market(self, market_id: str) -> Dict[str, Any]:
+        """Get one market's detail (envelope with ``data`` containing Market)."""
+        return self._request("GET", f"/v1/markets/{market_id}")
+
+    def list_templates(self, category: Optional[str] = None,
+                       market_type: Optional[str] = None) -> Dict[str, Any]:
+        """List active market templates."""
+        params: Dict[str, Any] = {}
+        if category:
+            params["category"] = category
+        if market_type:
+            params["market_type"] = market_type
+        return self._request("GET", "/v1/markets/templates", params=params or None)
+
+    def get_health(self) -> Dict[str, Any]:
+        """API health check."""
+        return self._request("GET", "/v1/health")
+
+    # ── Market Data ──────────────────────────────────────────────────────────
+    def get_candles(self, market_id: str, outcome_id: str, interval: str = "1m",
+                    from_ms: Optional[int] = None, to_ms: Optional[int] = None,
+                    limit: int = 500) -> Dict[str, Any]:
+        """OHLCV candles for a market outcome's price history.
+
+        Args:
+            interval: "1m" | "5m" | "15m" | "30m" | "1h" | "4h" | "1d".
+        """
+        params: Dict[str, Any] = {"outcome_id": outcome_id, "interval": interval,
+                                  "limit": max(1, min(500, limit))}
+        if from_ms is not None:
+            params["from_ms"] = from_ms
+        if to_ms is not None:
+            params["to_ms"] = to_ms
+        return self._request("GET", f"/v1/candles/{market_id}", params=params)
+
+    def get_orderbook(self, market_id: str, outcome_id: str, depth: int = 20) -> Dict[str, Any]:
+        """Top-of-book depth snapshot."""
+        return self._request("GET", f"/v1/orderbook/{market_id}",
+                             params={"outcome_id": outcome_id, "depth": max(1, min(100, depth))})
+
+    def get_trades(self, market_id: str, outcome_id: Optional[str] = None,
+                   cursor: Optional[str] = None, limit: int = 50) -> Dict[str, Any]:
+        """Recent public trades tape for a market."""
+        params: Dict[str, Any] = {"limit": max(1, min(500, limit))}
+        if outcome_id:
+            params["outcome_id"] = outcome_id
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", f"/v1/trades/{market_id}", params=params)
+
+    # ── Account ──────────────────────────────────────────────────────────────
+    def get_account(self) -> Dict[str, Any]:
+        """Get authenticated account snapshot."""
+        return self._request("GET", "/v1/account")
+
+    def get_positions(self) -> Dict[str, Any]:
+        """List open positions for the authenticated account."""
+        return self._request("GET", "/v1/account/positions")
+
+    def get_orders(self, status: Optional[str] = None, cursor: Optional[str] = None,
+                   limit: int = 50) -> Dict[str, Any]:
+        """List orders (active + recent)."""
+        params: Dict[str, Any] = {"limit": max(1, min(500, limit))}
+        if status:
+            params["status"] = status
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/v1/account/orders", params=params)
+
+    def get_own_trades(self, cursor: Optional[str] = None, limit: int = 50) -> Dict[str, Any]:
+        """List own trade fills."""
+        params: Dict[str, Any] = {"limit": max(1, min(500, limit))}
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/v1/account/trades", params=params)
+
+    # ── Trading ──────────────────────────────────────────────────────────────
+    def place_order(self, market_id: str, outcome_id: str, side: str, order_type: str,
+                    size: str, price: Optional[str] = None,
+                    client_order_id: Optional[str] = None) -> Dict[str, Any]:
+        """Place an order. Engine-agnostic (server routes to AMM or CLOB).
+
+        Args:
+            side: "buy" | "sell".
+            order_type: "market" | "limit". ``price`` required if limit.
+            size: Decimal string (e.g. "100" or "0.5").
+            price: Required when order_type=limit. Decimal string.
+            client_order_id: Idempotency key — retry-safe within 24h.
+        """
+        body: Dict[str, Any] = {
+            "market_id": market_id, "outcome_id": outcome_id,
+            "side": side, "order_type": order_type, "size": str(size),
+        }
+        if price is not None:
+            body["price"] = str(price)
+        if client_order_id:
+            body["client_order_id"] = client_order_id
+        return self._request("POST", "/v1/orders", json_body=body)
+
+    def cancel_order(self, order_id: str) -> Dict[str, Any]:
+        """Cancel an open order."""
+        return self._request("DELETE", f"/v1/orders/{order_id}")
+
+    def create_market(self, template_id: str, params: Dict[str, Any],
+                      creator_metadata: Optional[Dict[str, Any]] = None,
+                      idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        """Create a market from a template. Deterministic ID — idempotent."""
+        body: Dict[str, Any] = {"template_id": template_id, "params": params}
+        if creator_metadata:
+            body["creator_metadata"] = creator_metadata
+        if idempotency_key:
+            body["idempotency_key"] = idempotency_key
+        return self._request("POST", "/v1/markets", json_body=body)
+
+    # ── Keys ─────────────────────────────────────────────────────────────────
+    def create_api_key(self, name: str = "default", scopes: Optional[List[str]] = None) -> Dict[str, Any]:
+        """Mint a new API key. Requires session bearer auth."""
+        body = {"name": name, "scopes": scopes or ["read"]}
+        return self._request("POST", "/v1/keys", json_body=body)
+
+    def list_api_keys(self) -> Dict[str, Any]:
+        return self._request("GET", "/v1/keys")
+
+    def revoke_api_key(self, key_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/keys/{key_id}")
+
+    # ── Sandbox mint + Builder applications (anonymous, no auth) ────────────
+    def mint_sandbox_key(self, org_name: str, contact_email: Optional[str] = None) -> Dict[str, Any]:
+        """POST /v1/sandbox-keys — mint an anonymous sk_live_ key tagged
+        tier=self_serve with $10/order + $100/day notional caps. The response
+        contains ``api_key`` shown ONCE — save it immediately."""
+        body: Dict[str, Any] = {"org_name": org_name}
+        if contact_email is not None:
+            body["contact_email"] = contact_email
+        return self._request("POST", "/v1/sandbox-keys", json_body=body)
+
+    def apply(self, track: str, *, org: Optional[str] = None, email: Optional[str] = None,
+              url: Optional[str] = None, description: Optional[str] = None) -> Dict[str, Any]:
+        """POST /v1/apply — apply for a Builder track (``genesis`` / ``self_serve``
+        / ``rfb-japan-app`` / ``rfb-ai-agent`` / ``rfb-telegram-bot`` /
+        ``rfb-news-media`` / ``rfb-sports`` / ``rfb-election`` / ``rfb-terminal``
+        / ``rfb-mm-stack`` / ``data`` / ``app`` / ``agent`` / ``distribution`` /
+        ``market`` / ``liquidity`` / ``oracle`` / ``reviewer`` / ``operator`` /
+        ``institutional``). Auto-approve tracks return ``api_key`` immediately;
+        ``genesis`` and ``institutional`` queue for human review."""
+        body: Dict[str, Any] = {"track": track}
+        if org is not None: body["org"] = org
+        if email is not None: body["email"] = email
+        if url is not None: body["url"] = url
+        if description is not None: body["description"] = description
+        return self._request("POST", "/v1/apply", json_body=body)
+
+    def get_application(self, application_code: str) -> Dict[str, Any]:
+        """GET /v1/apply/{code} — check application review status."""
+        return self._request("GET", f"/v1/apply/{application_code}")
+
+    # ── Helpers ──────────────────────────────────────────────────────────────
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> "PaxClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

pax_api/errors.py

@@ -0,0 +1,146 @@
+"""Exception hierarchy for PAX SDK.
+
+Every PAX error response returns a canonical envelope with an ``error.code``.
+The client maps HTTP status + error.code to the most specific exception.
+Catch ``PaxError`` for a blanket catch, or specific subclasses to react to
+individual failures.
+"""
+
+from typing import Any, Dict, Optional
+
+
+class PaxError(Exception):
+    """Base class for all PAX SDK errors.
+
+    Attributes:
+        code: PAX error code (e.g. "MARKET_NOT_FOUND", "READ_ONLY_MODE").
+        message: Human-readable message from the server.
+        http_status: HTTP status code of the failed response.
+        request_id: Server-assigned request ID — include this in support tickets.
+        details: Optional structured details dict (per-endpoint schema).
+        response_json: Raw response payload for debugging.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        http_status: int,
+        request_id: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        response_json: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.code = code
+        self.message = message
+        self.http_status = http_status
+        self.request_id = request_id
+        self.details = details or {}
+        self.response_json = response_json
+        parts = [f"[{code}]", message]
+        if request_id:
+            parts.append(f"(request_id={request_id})")
+        super().__init__(" ".join(parts))
+
+
+# ── 4xx family ──────────────────────────────────────────────────────────────
+class PaxAuthError(PaxError):
+    """401 — MISSING_AUTH / INVALID_KEY / INVALID_SIGNATURE / SESSION_EXPIRED / KEY_REVOKED."""
+
+
+class PaxWrongEnvKeyError(PaxAuthError):
+    """401 WRONG_ENV_KEY — key's tier flag does not match the requested capability
+    (e.g. a tier=self_serve key attempting an operation that requires a
+    production tier like ``verified`` / ``trade_capped`` / ``trade_full``)."""
+
+
+class PaxValidationError(PaxError):
+    """400 — MISSING_FIELD / INVALID_TYPE / INVALID_ENUM / TEMPLATE_PARAMS_INVALID / INVALID_ORDER_SIZE."""
+
+
+class PaxNotFoundError(PaxError):
+    """404 — MARKET_NOT_FOUND / ORDER_NOT_FOUND / TEMPLATE_NOT_FOUND / SANDBOX_ONLY."""
+
+
+class PaxSandboxOnlyError(PaxNotFoundError):
+    """404 SANDBOX_ONLY — sandbox endpoint called on production."""
+
+
+class PaxConflictError(PaxError):
+    """409 — ORDER_ALREADY_FILLED / MARKET_CLOSED / DUPLICATE_CLIENT_ORDER_ID."""
+
+
+class PaxRateLimitError(PaxError):
+    """429 — RATE_LIMITED. Check ``retry_after`` for wait seconds."""
+
+    def __init__(self, *args: Any, retry_after: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.retry_after = retry_after
+
+
+# ── 5xx family ──────────────────────────────────────────────────────────────
+class PaxServerError(PaxError):
+    """500/502/504 — INTERNAL_ERROR / UPSTREAM_ERROR / UPSTREAM_TIMEOUT."""
+
+
+class PaxReadOnlyModeError(PaxError):
+    """503 READ_ONLY_MODE — writes gated by ops team."""
+
+
+class PaxCircuitBreakerError(PaxError):
+    """503 CIRCUIT_BREAKER_OPEN — trading paused on this market/asset."""
+
+
+# ── Mapping helper ──────────────────────────────────────────────────────────
+_CODE_MAP = {
+    "WRONG_ENV_KEY": PaxWrongEnvKeyError,
+    "SANDBOX_ONLY": PaxSandboxOnlyError,
+    "READ_ONLY_MODE": PaxReadOnlyModeError,
+    "CIRCUIT_BREAKER_OPEN": PaxCircuitBreakerError,
+}
+
+_STATUS_MAP = {
+    400: PaxValidationError,
+    401: PaxAuthError,
+    403: PaxAuthError,
+    404: PaxNotFoundError,
+    409: PaxConflictError,
+    429: PaxRateLimitError,
+    500: PaxServerError,
+    502: PaxServerError,
+    503: PaxServerError,
+    504: PaxServerError,
+}
+
+
+def build_error(http_status: int, response_json: Dict[str, Any], retry_after: Optional[int] = None) -> PaxError:
+    """Construct the most specific PaxError from an HTTP response."""
+    raw_err = response_json.get("error")
+    if isinstance(raw_err, dict):
+        err = raw_err
+        code = str(err.get("code") or "UNKNOWN")
+        message = str(err.get("message") or code)
+    else:
+        # Legacy shape: {"ok": false, "error": "missing-api-key", "message": "..."}
+        err = {}
+        code = str(raw_err or "UNKNOWN")
+        message = str(response_json.get("message") or code)
+
+    meta = response_json.get("meta") if isinstance(response_json.get("meta"), dict) else {}
+    request_id = meta.get("request_id") if isinstance(meta, dict) else None
+    details = err.get("details") if isinstance(err.get("details"), dict) else None
+
+    exc_class = _CODE_MAP.get(code) or _STATUS_MAP.get(http_status) or PaxError
+
+    kwargs: Dict[str, Any] = {}
+    if exc_class is PaxRateLimitError and retry_after is not None:
+        kwargs["retry_after"] = retry_after
+
+    return exc_class(
+        code=code,
+        message=message,
+        http_status=http_status,
+        request_id=request_id,
+        details=details,
+        response_json=response_json,
+        **kwargs,
+    )

pax_api/retry.py

@@ -0,0 +1,97 @@
+"""Retry logic with exponential backoff for transient failures.
+
+Retry policy (matches docs.predictasiax.com/errors#retry-policy):
+    - 4xx errors (except 429): DO NOT retry — fix the request.
+    - 429: respect Retry-After header, otherwise exponential backoff.
+    - 500/502/504: retry once immediately, then exponential backoff.
+    - 503 READ_ONLY_MODE / CIRCUIT_BREAKER_OPEN: do not retry.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import Callable, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+def compute_backoff(attempt: int, base: float = 1.0, cap: float = 60.0, jitter: bool = True) -> float:
+    """Full-jitter exponential backoff.
+
+    ``sleep = random(0, min(cap, base * 2^attempt))``
+
+    Args:
+        attempt: 0-indexed retry attempt (0 = first retry).
+        base: Base wait in seconds (default 1s).
+        cap: Max wait in seconds (default 60s).
+        jitter: If True, use full-jitter randomization.
+
+    Returns:
+        Seconds to sleep.
+    """
+    exp = min(cap, base * (2 ** attempt))
+    return random.uniform(0, exp) if jitter else exp
+
+
+def sleep_with_retry_after(retry_after_header: Optional[str], attempt: int, cap: float = 60.0) -> float:
+    """Compute sleep duration for a 429 response.
+
+    Respects Retry-After header (seconds) if present, else uses backoff.
+    """
+    if retry_after_header:
+        try:
+            return min(cap, float(retry_after_header))
+        except (TypeError, ValueError):
+            pass
+    return compute_backoff(attempt, cap=cap)
+
+
+def run_with_retry(
+    fn: Callable[[], T],
+    max_attempts: int = 5,
+    retryable_statuses: tuple = (429, 500, 502, 504),
+    on_retry: Optional[Callable[[int, Exception], None]] = None,
+) -> T:
+    """Execute ``fn`` with retry on transient errors.
+
+    Args:
+        fn: Callable that returns T or raises PaxError. Should be idempotent
+            (send ``client_order_id`` for order creates to guarantee this).
+        max_attempts: Total attempts including the first (default 5).
+        retryable_statuses: HTTP statuses that trigger retry.
+        on_retry: Optional hook called before each retry with (attempt, exception).
+
+    Returns:
+        Result of successful ``fn`` invocation.
+
+    Raises:
+        The last exception if all attempts fail.
+    """
+    from pax_api.errors import PaxError, PaxRateLimitError, PaxReadOnlyModeError
+
+    last_exc: Optional[Exception] = None
+    for attempt in range(max_attempts):
+        try:
+            return fn()
+        except PaxReadOnlyModeError:
+            # Never retry — ops team decision, will not self-heal
+            raise
+        except PaxRateLimitError as e:
+            last_exc = e
+            if attempt >= max_attempts - 1:
+                raise
+            wait = e.retry_after if e.retry_after is not None else compute_backoff(attempt)
+            if on_retry:
+                on_retry(attempt + 1, e)
+            time.sleep(wait)
+        except PaxError as e:
+            last_exc = e
+            if e.http_status not in retryable_statuses or attempt >= max_attempts - 1:
+                raise
+            wait = compute_backoff(attempt)
+            if on_retry:
+                on_retry(attempt + 1, e)
+            time.sleep(wait)
+    assert last_exc is not None
+    raise last_exc

pax_api/ws_client.py

@@ -0,0 +1,195 @@
+"""WebSocket client for the PAX real-time API.
+
+Wraps ``websocket-client`` with:
+    - Auto-reconnect + exponential backoff
+    - SUBSCRIBE / UNSUBSCRIBE / AUTH / LOCALE helpers
+    - Per-type event dispatch via callbacks
+    - Heartbeat handled by underlying lib
+
+Example:
+    >>> ws = PaxWSClient(api_key="sk_live_...")
+    >>> ws.on("fast_tick", lambda evt: print("tick:", evt))
+    >>> ws.subscribe(["fast_tick", "trade_executed"])
+    >>> ws.run_forever()
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from typing import Any, Callable, Dict, Iterable, List, Optional
+
+try:
+    import websocket  # type: ignore
+except ImportError as e:
+    raise ImportError(
+        "PaxWSClient requires the 'websocket-client' package. Install with: pip install pax-api[ws] "
+        "or pip install websocket-client"
+    ) from e
+
+# Same WSS endpoint for every env — sandbox is a tier on the key, not a host.
+_ENV_URLS = {
+    "production": "wss://predictasiax.com/ws",
+    "prod":       "wss://predictasiax.com/ws",
+    "live":       "wss://predictasiax.com/ws",
+    "sandbox":    "wss://predictasiax.com/ws",
+    "test":       "wss://predictasiax.com/ws",
+}
+
+_log = logging.getLogger("pax_api.ws")
+
+
+class PaxWSClient:
+    """PAX WebSocket client with auto-reconnect + typed event dispatch.
+
+    Args:
+        api_key: Optional sk_live_ key for AUTH after connect (unlocks
+            private channels: account, deposit, security_alert, etc.).
+        env: "production" (default) or "sandbox". Overridden by ``url``.
+        url: Full ``wss://...`` URL (overrides env).
+        locale: BCP-47 tag for i18n rendering (e.g. "zh-CN"). Auto-sent post-connect.
+        reconnect: Auto-reconnect on close/error.
+        backoff_min: Initial reconnect wait (seconds).
+        backoff_max: Max reconnect wait (seconds).
+        subscribe_on_connect: List of channels to auto-subscribe on connect + reconnect.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        env: str = "production",
+        url: Optional[str] = None,
+        locale: Optional[str] = None,
+        reconnect: bool = True,
+        backoff_min: float = 1.0,
+        backoff_max: float = 60.0,
+        subscribe_on_connect: Optional[List[str]] = None,
+    ) -> None:
+        self.api_key = api_key
+        self.locale = locale
+        self.url = url or _ENV_URLS.get(env.lower()) or _ENV_URLS["production"]
+        self.reconnect = reconnect
+        self.backoff_min = backoff_min
+        self.backoff_max = backoff_max
+        self._subscribe_on_connect: List[str] = list(subscribe_on_connect or [])
+        self._handlers: Dict[str, List[Callable[[Dict[str, Any]], None]]] = {}
+        self._catch_all: List[Callable[[Dict[str, Any]], None]] = []
+        self._ws: Optional["websocket.WebSocketApp"] = None
+        self._thread: Optional[threading.Thread] = None
+        self._stop = threading.Event()
+        self._backoff_current = backoff_min
+
+    # ── event handlers ──────────────────────────────────────────────────────
+    def on(self, event_type: str, handler: Callable[[Dict[str, Any]], None]) -> None:
+        """Register a handler for a specific event type (e.g. "fast_tick")."""
+        self._handlers.setdefault(event_type, []).append(handler)
+
+    def on_any(self, handler: Callable[[Dict[str, Any]], None]) -> None:
+        """Register a catch-all handler for every incoming event."""
+        self._catch_all.append(handler)
+
+    # ── client → server commands ────────────────────────────────────────────
+    def subscribe(self, channels: Iterable[str]) -> None:
+        """Batch subscribe (10 msgs/sec client throttle — batch when possible)."""
+        self._send({"method": "SUBSCRIBE", "params": list(channels)})
+
+    def unsubscribe(self, channels: Iterable[str]) -> None:
+        self._send({"method": "UNSUBSCRIBE", "params": list(channels)})
+
+    def auth(self, token: Optional[str] = None) -> None:
+        """Send AUTH command. Uses ``token`` if given, else self.api_key."""
+        tok = token or self.api_key
+        if not tok:
+            raise ValueError("No auth token provided (pass token or set api_key on client)")
+        self._send({"method": "AUTH", "token": tok})
+
+    def set_locale(self, locale: str) -> None:
+        self.locale = locale
+        self._send({"method": "LOCALE", "locale": locale})
+
+    # ── lifecycle ───────────────────────────────────────────────────────────
+    def run_forever(self, ping_interval: float = 25.0, ping_timeout: float = 10.0) -> None:
+        """Blocking event loop with auto-reconnect. Call ``close()`` to stop."""
+        self._stop.clear()
+        while not self._stop.is_set():
+            try:
+                self._connect_and_run(ping_interval=ping_interval, ping_timeout=ping_timeout)
+            except Exception as e:
+                _log.warning("WS loop error: %s", e)
+            if not self.reconnect or self._stop.is_set():
+                break
+            wait = min(self.backoff_max, self._backoff_current)
+            _log.info("Reconnecting in %.1fs", wait)
+            time.sleep(wait)
+            self._backoff_current = min(self.backoff_max, self._backoff_current * 2)
+
+    def start(self, ping_interval: float = 25.0, ping_timeout: float = 10.0) -> None:
+        """Start the WS in a background thread."""
+        if self._thread and self._thread.is_alive():
+            return
+        self._thread = threading.Thread(
+            target=self.run_forever,
+            kwargs={"ping_interval": ping_interval, "ping_timeout": ping_timeout},
+            daemon=True,
+        )
+        self._thread.start()
+
+    def close(self) -> None:
+        """Stop reconnecting and close the connection."""
+        self._stop.set()
+        if self._ws is not None:
+            try:
+                self._ws.close()
+            except Exception:  # noqa: BLE001
+                pass
+
+    # ── internals ───────────────────────────────────────────────────────────
+    def _connect_and_run(self, ping_interval: float, ping_timeout: float) -> None:
+        def on_open(ws: "websocket.WebSocketApp") -> None:
+            self._backoff_current = self.backoff_min
+            _log.info("WS connected: %s", self.url)
+            if self.api_key:
+                self._send({"method": "AUTH", "token": self.api_key})
+            if self.locale:
+                self._send({"method": "LOCALE", "locale": self.locale})
+            if self._subscribe_on_connect:
+                self._send({"method": "SUBSCRIBE", "params": self._subscribe_on_connect})
+
+        def on_message(ws: "websocket.WebSocketApp", raw: str) -> None:
+            try:
+                evt = json.loads(raw)
+            except json.JSONDecodeError:
+                _log.warning("WS non-JSON message: %s", raw[:120])
+                return
+            evt_type = evt.get("type") if isinstance(evt, dict) else None
+            for cb in self._catch_all:
+                try:
+                    cb(evt)
+                except Exception as e:  # noqa: BLE001
+                    _log.exception("catch-all handler raised: %s", e)
+            if isinstance(evt_type, str):
+                for cb in self._handlers.get(evt_type, ()):
+                    try:
+                        cb(evt)
+                    except Exception as e:  # noqa: BLE001
+                        _log.exception("handler for %s raised: %s", evt_type, e)
+
+        def on_error(ws: "websocket.WebSocketApp", err: Any) -> None:
+            _log.warning("WS error: %s", err)
+
+        def on_close(ws: "websocket.WebSocketApp", code: Any, reason: Any) -> None:
+            _log.info("WS closed code=%s reason=%s", code, reason)
+
+        self._ws = websocket.WebSocketApp(
+            self.url, on_open=on_open, on_message=on_message,
+            on_error=on_error, on_close=on_close,
+        )
+        # Blocks until closed
+        self._ws.run_forever(ping_interval=ping_interval, ping_timeout=ping_timeout)
+
+    def _send(self, obj: Dict[str, Any]) -> None:
+        if not self._ws or not getattr(self._ws, "sock", None):
+            raise RuntimeError("WS not connected yet — call after on_open or via subscribe_on_connect")
+        self._ws.send(json.dumps(obj, separators=(",", ":")))

pax_api-2.0.0.dist-info/METADATA

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: pax-api
+Version: 2.0.0
+Summary: Official Python SDK for the PredictAsiaX Trader Track API — Web3-native prediction markets
+Author-email: PredictAsiaX <support@predictasiax.com>
+License: MIT
+Project-URL: Homepage, https://predictasiax.com/developer
+Project-URL: Documentation, https://docs.predictasiax.com
+Project-URL: Repository, https://github.com/predictasiax/pax-python-sdk
+Project-URL: Issues, https://github.com/predictasiax/pax-python-sdk/issues
+Project-URL: Changelog, https://docs.predictasiax.com/changelog
+Keywords: predictasiax,pax,prediction-market,trading-api,web3,hmac,polymarket-compatible
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: websocket-client>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=4; extra == "dev"
+Dynamic: license-file
+
+# pax-api — Official Python SDK for PredictAsiaX
+
+Web3-native prediction market REST + WebSocket API client. Polymarket-compatible HMAC signing pattern.
+
+**Version 1.0.0** · MIT license · Python 3.8+
+
+- **Docs**: https://docs.predictasiax.com
+- **Developer landing**: https://predictasiax.com/developer
+- **Get API key**: https://predictasiax.com/settings/api-keys
+- **Support**: support@predictasiax.com
+
+## Install
+
+```bash
+# Direct install from PredictAsiaX-hosted wheel
+pip install https://docs.predictasiax.com/downloads/sdk/python/pax_api-1.0.0-py3-none-any.whl
+
+# Or download tarball + install locally
+curl -O https://docs.predictasiax.com/downloads/sdk/python/pax_api-1.0.0.tar.gz
+pip install pax_api-1.0.0.tar.gz
+```
+
+(PyPI publish coming soon — install methods above work today.)
+
+## Quickstart (sandbox — no real money)
+
+```python
+from pax_api import PaxClient
+
+with PaxClient(api_key="sk_test_YOUR_KEY", env="sandbox") as pax:
+    faucet = pax.faucet()                          # get 10k test USDT
+    print(faucet["data"]["balance_free"])           # → "10000.000000"
+
+    templates = pax.list_templates()
+    markets   = pax.list_markets(category="crypto", limit=10)
+
+    market = pax.create_market(
+        template_id="crypto_price_binary_60s",
+        params={"asset": "BTC"},
+    )
+    print(market["data"]["market"]["market_id"])    # → "m_..."
+```
+
+## HMAC-signed requests (production)
+
+Machine-to-machine trading bots should use HMAC signing (Polymarket-compatible 5-header pattern).
+
+```python
+from pax_api import PaxClient
+
+pax = PaxClient(
+    api_key="sk_live_YOUR_KEY",
+    secret="<64-hex secret>",
+    passphrase="<passphrase>",
+    env="production",
+)
+
+pax.place_order(
+    market_id="m_...",
+    outcome_id="yes",
+    side="buy",
+    order_type="limit",
+    size="100",
+    price="0.55",
+    client_order_id="unique-per-intent-id",  # retry-safe within 24h
+)
+```
+
+## WebSocket streams
+
+```python
+from pax_api import PaxWSClient
+
+ws = PaxWSClient(
+    api_key="sk_test_...",
+    env="sandbox",
+    subscribe_on_connect=["fast_tick", "trade_executed", "account"],
+)
+ws.on("fast_tick",      lambda e: print("tick:", e))
+ws.on("trade_executed", lambda e: print("trade:", e))
+ws.on("account",        lambda e: print("balance:", e.get("balance_free")))
+ws.run_forever()                                    # blocks; Ctrl+C to exit
+```
+
+Auto-reconnect + exponential backoff built-in. All 4 client methods supported:
+`subscribe`, `unsubscribe`, `auth`, `set_locale`.
+
+## Error handling
+
+Every response error becomes a typed exception. Catch the specific type
+you want to handle:
+
+```python
+from pax_api import (
+    PaxClient,
+    PaxRateLimitError,
+    PaxReadOnlyModeError,
+    PaxValidationError,
+    PaxWrongEnvKeyError,
+    PaxError,           # base class — catch-all
+)
+
+try:
+    pax.place_order(...)
+except PaxRateLimitError as e:
+    time.sleep(e.retry_after or 5)
+    # then retry
+except PaxValidationError as e:
+    print(f"Bad request: {e.details}")             # {'field': 'size', ...}
+except PaxReadOnlyModeError:
+    print("Trading paused by ops")
+except PaxWrongEnvKeyError:
+    print("Wrong environment key")
+except PaxError as e:
+    print(f"[{e.code}] {e.message} (request_id={e.request_id})")
+```
+
+## Automatic retry
+
+Built-in exponential backoff on `429`, `500`, `502`, `504` responses. `Retry-After`
+header respected on rate limits. Non-idempotent creates are safe when you send
+`client_order_id`.
+
+```python
+pax = PaxClient(api_key="sk_test_...", env="sandbox", max_retries=5)
+# max_retries=0 disables retries entirely
+```
+
+## Environments
+
+| Env | Base URL | Keys |
+|---|---|---|
+| `production` | `https://api.predictasiax.com/v1` | `sk_live_*` |
+| `sandbox`    | `https://api.predictasiax.com/v1` | `sk_test_*` |
+
+`sk_test_*` on production returns `401 WRONG_ENV_KEY`. Same the other way. See
+[docs auth guide](https://docs.predictasiax.com/auth#env-separation).
+
+## Custom base URL
+
+```python
+pax = PaxClient(api_key="...", base_url="https://your-mirror/api")
+```
+
+## Development
+
+```bash
+# Get source (tarball)
+curl -O https://docs.predictasiax.com/downloads/sdk/python/pax_api-1.0.0.tar.gz
+tar -xzf pax_api-1.0.0.tar.gz && cd pax_api-1.0.0
+pip install -e ".[dev]"
+pytest                                              # run all tests
+ruff check src tests                                # lint
+mypy src                                            # type-check
+```
+
+## Links
+
+- [OpenAPI spec](https://docs.predictasiax.com/openapi)
+- [AsyncAPI (WebSocket) spec](https://docs.predictasiax.com/asyncapi)
+- [Auth guide](https://docs.predictasiax.com/auth)
+- [Error codes](https://docs.predictasiax.com/errors)
+- [Rate limits](https://docs.predictasiax.com/rate-limits)
+- [FAQ](https://docs.predictasiax.com/faq)
+- [API Terms](https://docs.predictasiax.com/api-terms)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pax_api-2.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pax_api/__init__.py,sha256=vf_ZTe-aY4nrsGzGMxHlSkZ5lvOcdiRoqCQzUlT4bc4,1760
+pax_api/auth.py,sha256=AjpPOmPxykndoY12lZLg99VRpeUwzdVbwSLs-_Gswrg,2200
+pax_api/client.py,sha256=pXGVFXhKvd115u3txWy8-Bh8XevGIn844WFpoJjN90Q,16647
+pax_api/errors.py,sha256=wtgnXiA1DO389f0vMuLb_1aioda5qviEYjdL6JLGHL0,5374
+pax_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pax_api/retry.py,sha256=6GCSKsuV0I754QmeeWdP0Dq9aWRHUMF1MWvf161X60w,3294
+pax_api/ws_client.py,sha256=P9Zd7EIZtKo_Ilt-lgg0JgsCASczHBsLF_s5N4vTiP0,8694
+pax_api-2.0.0.dist-info/licenses/LICENSE,sha256=2xepe-7T7Wrs8WMzu3tfbiB5lZPqNzvKHcdFK4qkfgE,1069
+pax_api-2.0.0.dist-info/METADATA,sha256=19KBL6qTk2URBvv7Vhl9_Fnl73Az27GkdLzzZ3PxYV8,6679
+pax_api-2.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pax_api-2.0.0.dist-info/top_level.txt,sha256=ubONv5nsTA8lcuaqqMXovax0Q10q0RCshzUE7CzUgKY,8
+pax_api-2.0.0.dist-info/RECORD,,

pax_api-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pax_api-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PredictAsiaX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pax_api-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pax_api