nexode-sdk 0.1.0__tar.gz

nexode_sdk-0.1.0/.gitignore

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

nexode_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: nexode-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the Nexode prediction-market API
+Project-URL: Homepage, https://nexode.io
+Project-URL: Documentation, https://docs.nexode.io
+Project-URL: Source, https://github.com/k2flabs/nexode
+Author: Nexode
+License-Expression: MIT
+Keywords: nexode,prediction-markets,sdk,trading
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nexode-sdk
+
+Official Python SDK for the [Nexode](https://nexode.io) prediction-market API.
+
+```bash
+pip install nexode-sdk
+```
+
+```python
+from nexode import Nexode, Outcome, OrderSide
+
+nx = Nexode(api_key="nxd_...")          # or set NEXODE_API_KEY
+
+market = nx.markets.list()[0]
+print(nx.markets.ticker(market.id, Outcome.YES).best_bid)
+
+order = nx.orders.create(
+    market_id=market.id, outcome=Outcome.YES,
+    side=OrderSide.BUY, price="0.55", quantity=100,
+)
+nx.orders.cancel(order.id)
+```
+
+Create an API key in **Settings → Developer**. The SDK exchanges it for
+short-lived access tokens and refreshes them automatically.
+
+You work in terms of a **market** and an **outcome** (`yes`/`no`); the SDK
+handles the routing. `nx.markets` and `nx.events` browse markets,
+`nx.orders`/`nx.trades` trade and report fills, and `nx.mints`/`nx.redeems`/
+`nx.burns` cover account activity.
+
+Browsing is filtered and sorted server-side:
+
+```python
+from nexode import EventSort
+
+events = nx.events.list(
+    category="sports",
+    sort=EventSort.TRENDING,   # ending / trending / new / markets / name
+    hide_stale_settled=True,
+    limit=20,
+)
+
+event = nx.events.by_slug("nba-finals")     # markets too: nx.markets.by_slug(...)
+```
+
+Outcomes carry display labels — on a game market `yes`/`no` might read
+"Lakers"/"Celtics". The SDK maps both ways:
+
+```python
+market.labels                       # {Outcome.YES: "Lakers", Outcome.NO: "Celtics"}
+market.outcome_label(Outcome.YES)   # "Lakers" (falls back to "Yes"/"No")
+market.outcome_for_label("Celtics") # Outcome.NO — trade by team name
+market.winning_label                # label of the resolved outcome, or None
+```
+
+`nx.api_keys` lists and revokes keys on your account; create them in
+**Settings → Developer**.
+
+`nx.portfolio.snapshot()` returns the raw inputs for PnL in one call — trades,
+open orders, mints, redeems, burns, the markets involved, and current tickers:
+
+```python
+s = nx.portfolio.snapshot()
+# s.trades[i].market_id / .outcome / .price / .quantity
+# s.markets[market_id].collateral_price        # cost basis / resolution
+# s.tickers[f"{market_id}:{outcome}"].best_bid # mark open positions
+```
+
+See the full reference at [docs.nexode.io](https://docs.nexode.io).
+
+## Development
+
+```bash
+cd nexode-sdk
+pip install -e '.[dev]'
+pytest
+```

nexode_sdk-0.1.0/README.md

@@ -0,0 +1,78 @@
+# nexode-sdk
+
+Official Python SDK for the [Nexode](https://nexode.io) prediction-market API.
+
+```bash
+pip install nexode-sdk
+```
+
+```python
+from nexode import Nexode, Outcome, OrderSide
+
+nx = Nexode(api_key="nxd_...")          # or set NEXODE_API_KEY
+
+market = nx.markets.list()[0]
+print(nx.markets.ticker(market.id, Outcome.YES).best_bid)
+
+order = nx.orders.create(
+    market_id=market.id, outcome=Outcome.YES,
+    side=OrderSide.BUY, price="0.55", quantity=100,
+)
+nx.orders.cancel(order.id)
+```
+
+Create an API key in **Settings → Developer**. The SDK exchanges it for
+short-lived access tokens and refreshes them automatically.
+
+You work in terms of a **market** and an **outcome** (`yes`/`no`); the SDK
+handles the routing. `nx.markets` and `nx.events` browse markets,
+`nx.orders`/`nx.trades` trade and report fills, and `nx.mints`/`nx.redeems`/
+`nx.burns` cover account activity.
+
+Browsing is filtered and sorted server-side:
+
+```python
+from nexode import EventSort
+
+events = nx.events.list(
+    category="sports",
+    sort=EventSort.TRENDING,   # ending / trending / new / markets / name
+    hide_stale_settled=True,
+    limit=20,
+)
+
+event = nx.events.by_slug("nba-finals")     # markets too: nx.markets.by_slug(...)
+```
+
+Outcomes carry display labels — on a game market `yes`/`no` might read
+"Lakers"/"Celtics". The SDK maps both ways:
+
+```python
+market.labels                       # {Outcome.YES: "Lakers", Outcome.NO: "Celtics"}
+market.outcome_label(Outcome.YES)   # "Lakers" (falls back to "Yes"/"No")
+market.outcome_for_label("Celtics") # Outcome.NO — trade by team name
+market.winning_label                # label of the resolved outcome, or None
+```
+
+`nx.api_keys` lists and revokes keys on your account; create them in
+**Settings → Developer**.
+
+`nx.portfolio.snapshot()` returns the raw inputs for PnL in one call — trades,
+open orders, mints, redeems, burns, the markets involved, and current tickers:
+
+```python
+s = nx.portfolio.snapshot()
+# s.trades[i].market_id / .outcome / .price / .quantity
+# s.markets[market_id].collateral_price        # cost basis / resolution
+# s.tickers[f"{market_id}:{outcome}"].best_bid # mark open positions
+```
+
+See the full reference at [docs.nexode.io](https://docs.nexode.io).
+
+## Development
+
+```bash
+cd nexode-sdk
+pip install -e '.[dev]'
+pytest
+```

nexode_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nexode-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the Nexode prediction-market API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Nexode" }]
+keywords = ["nexode", "prediction-markets", "trading", "sdk"]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+]
+
+[project.urls]
+Homepage = "https://nexode.io"
+Documentation = "https://docs.nexode.io"
+Source = "https://github.com/k2flabs/nexode"
+
+# Import package is `nexode` (PyPI distribution is `nexode-sdk`):
+#   pip install nexode-sdk  ->  from nexode import Nexode
+[tool.hatch.build.targets.wheel]
+packages = ["src/nexode"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

nexode_sdk-0.1.0/src/nexode/__init__.py

@@ -0,0 +1,67 @@
+from .client import Nexode
+from .enums import EventSort, MarketStatus, OrderSide, OrderStatus, Outcome, TimeInForce
+from .errors import (
+    AuthError,
+    NexodeError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    UnprocessableError,
+    ValidationError,
+)
+from .models import (
+    ApiKey,
+    BookSnapshot,
+    Burn,
+    Event,
+    Instrument,
+    Market,
+    MarketEvent,
+    MarketTrade,
+    Mint,
+    Order,
+    PortfolioSnapshot,
+    PriceLevel,
+    Redeem,
+    Ticker,
+    Token,
+    Trade,
+)
+
+__all__ = [
+    "Nexode",
+    # enums
+    "Outcome",
+    "OrderSide",
+    "OrderStatus",
+    "MarketStatus",
+    "EventSort",
+    "TimeInForce",
+    # models
+    "Market",
+    "Event",
+    "MarketEvent",
+    "Instrument",
+    "Order",
+    "Trade",
+    "MarketTrade",
+    "Ticker",
+    "PriceLevel",
+    "BookSnapshot",
+    "Token",
+    "Mint",
+    "Redeem",
+    "Burn",
+    "PortfolioSnapshot",
+    "ApiKey",
+    # errors
+    "NexodeError",
+    "AuthError",
+    "ValidationError",
+    "UnprocessableError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+]
+
+__version__ = "0.1.0"

nexode_sdk-0.1.0/src/nexode/_resolver.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Dict, Iterable, Optional, Tuple
+
+from ._transport import Transport
+from .enums import Outcome
+
+_OUTCOME_KEYS = (
+    (Outcome.YES, "atomix_yes_market_id"),
+    (Outcome.NO, "atomix_no_market_id"),
+)
+
+
+class Resolver:
+    """Translates between a (market, outcome) and its order book, both ways.
+
+    The platform runs a separate order book per outcome; the SDK hides that by
+    routing on (market, outcome). Lookups are cached, so a market resolves once.
+    """
+
+    def __init__(self, nexode: Transport) -> None:
+        self._n = nexode
+        self._to_book: Dict[Tuple[str, Outcome], str] = {}
+        self._from_book: Dict[str, Tuple[str, Outcome]] = {}
+
+    def order_book_id(self, market_id: str, outcome) -> str:
+        outcome = Outcome(outcome)
+        if (market_id, outcome) not in self._to_book:
+            self._load_market(market_id)
+        try:
+            return self._to_book[(market_id, outcome)]
+        except KeyError:
+            raise ValueError(f"market {market_id!r} has no {outcome.value} order book")
+
+    def resolve(self, order_book_ids: Iterable[str]) -> Dict[str, Tuple[str, Outcome]]:
+        ids = list(order_book_ids)
+        unknown = sorted({i for i in ids if i not in self._from_book})
+        if unknown:
+            body = self._n.get(
+                "/v0/markets/by-atomix-id", params={"ids": ",".join(unknown)}
+            )
+            for m in body["mappings"]:
+                self._index(m["atomix_market_id"], m["market"]["id"], Outcome(m["outcome"]))
+        return {i: self._from_book[i] for i in ids if i in self._from_book}
+
+    def market_outcome(self, order_book_id: str) -> Optional[Tuple[str, Outcome]]:
+        return self.resolve([order_book_id]).get(order_book_id)
+
+    def _load_market(self, market_id: str) -> None:
+        metadata = self._n.get(f"/v0/markets/{market_id}")["market"].get("metadata") or {}
+        for outcome, key in _OUTCOME_KEYS:
+            if metadata.get(key):
+                self._index(metadata[key], market_id, outcome)
+
+    def _index(self, order_book_id: str, market_id: str, outcome: Outcome) -> None:
+        self._to_book[(market_id, outcome)] = order_book_id
+        self._from_book[order_book_id] = (market_id, outcome)

nexode_sdk-0.1.0/src/nexode/_transport.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .errors import error_from_response
+
+
+class Transport:
+    """Issues requests against a fixed base URL and returns the flattened body.
+
+    Builds absolute URLs (base + path) rather than relying on httpx base_url
+    merging, so a base that includes a path prefix (e.g. ``.../atomix``) is
+    preserved even though request paths start with ``/``.
+    """
+
+    def __init__(self, client: httpx.Client, base_url: str) -> None:
+        self._client = client
+        self._base = base_url.rstrip("/")
+
+    def request(self, method: str, path: str, **kwargs: Any) -> dict:
+        response = self._client.request(method, self._base + path, **kwargs)
+        body = response.json() if response.content else {}
+        if response.status_code >= 400:
+            raise error_from_response(response.status_code, body)
+        return body
+
+    def get(self, path: str, **kwargs: Any) -> dict:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> dict:
+        return self.request("POST", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> dict:
+        return self.request("DELETE", path, **kwargs)

nexode_sdk-0.1.0/src/nexode/auth.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import time
+from typing import Generator
+
+import httpx
+
+from .errors import AuthError
+
+# Re-exchange this many seconds before the token's stated expiry.
+_EXPIRY_SKEW_SECONDS = 30
+
+
+class ApiKeyAuth(httpx.Auth):
+    """Exchanges a long-lived API key for short-lived access tokens, caches
+    them, and re-exchanges transparently on expiry or 401."""
+
+    def __init__(self, api_key: str, *, exchange_url: str) -> None:
+        self._api_key = api_key
+        self._exchange_url = exchange_url
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+
+    def sync_auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        if not self._fresh():
+            response = yield self._exchange()
+            response.read()
+            self._store(response)
+        self._apply(request)
+        response = yield request
+        if response.status_code == 401:
+            response = yield self._exchange()
+            response.read()
+            self._store(response)
+            self._apply(request)
+            yield request
+
+    async def async_auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        if not self._fresh():
+            response = yield self._exchange()
+            await response.aread()
+            self._store(response)
+        self._apply(request)
+        response = yield request
+        if response.status_code == 401:
+            response = yield self._exchange()
+            await response.aread()
+            self._store(response)
+            self._apply(request)
+            yield request
+
+    def _fresh(self) -> bool:
+        return self._token is not None and time.time() < self._expires_at - _EXPIRY_SKEW_SECONDS
+
+    def _exchange(self) -> httpx.Request:
+        # Absolute URL so the exchange always targets the auth endpoint.
+        return httpx.Request("POST", self._exchange_url, json={"api_key": self._api_key})
+
+    def _apply(self, request: httpx.Request) -> None:
+        request.headers["Authorization"] = f"Bearer {self._token}"
+
+    def _store(self, response: httpx.Response) -> None:
+        if response.status_code != 200:
+            raise AuthError("API key exchange failed.", status=response.status_code)
+        data = response.json()
+        self._token = data["access_token"]
+        self._expires_at = float(data["access_expires_at"])

nexode_sdk-0.1.0/src/nexode/client.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import httpx
+
+from ._resolver import Resolver
+from ._transport import Transport
+from .auth import ApiKeyAuth
+from .resources import (
+    ApiKeys,
+    Burns,
+    Events,
+    Markets,
+    Mints,
+    Orders,
+    Portfolio,
+    Redeems,
+    Tokens,
+    Trades,
+)
+
+DEFAULT_API_BASE = "https://api.nexode.io"
+DEFAULT_ATOMIX_BASE = "https://api.nexode.io/atomix"
+
+
+class Nexode:
+    """Synchronous Nexode client.
+
+    A single API key authenticates the whole platform — prediction markets,
+    the order book, and your account activity.
+
+    Args:
+        api_key: A ``nxd_...`` key. Falls back to ``$NEXODE_API_KEY``.
+        api_base: Override the Nexode API base URL.
+        atomix_base: Override the order-book (Atomix) base URL.
+        timeout: Per-request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        api_base: str = DEFAULT_API_BASE,
+        atomix_base: str = DEFAULT_ATOMIX_BASE,
+        timeout: float = 30.0,
+    ) -> None:
+        api_key = api_key or os.environ.get("NEXODE_API_KEY")
+        if not api_key:
+            raise ValueError("api_key is required — pass api_key=... or set NEXODE_API_KEY.")
+
+        auth = ApiKeyAuth(api_key, exchange_url=f"{api_base.rstrip('/')}/v0/api-keys/exchange")
+        self._http = httpx.Client(auth=auth, timeout=timeout)
+        nexode = Transport(self._http, api_base)
+        atomix = Transport(self._http, atomix_base)
+        resolver = Resolver(nexode)
+
+        self.markets = Markets(nexode, atomix, resolver)
+        self.events = Events(nexode)
+        self.orders = Orders(atomix, resolver)
+        self.trades = Trades(atomix, resolver)
+        self.tokens = Tokens(atomix)
+        self.mints = Mints(nexode)
+        self.redeems = Redeems(nexode)
+        self.burns = Burns(nexode)
+        self.portfolio = Portfolio(atomix=atomix, nexode=nexode, resolver=resolver)
+        self.api_keys = ApiKeys(nexode)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Nexode":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()

nexode_sdk-0.1.0/src/nexode/enums.py

@@ -0,0 +1,43 @@
+from enum import Enum
+
+
+class Outcome(str, Enum):
+    YES = "yes"
+    NO = "no"
+
+
+class OrderSide(str, Enum):
+    BUY = "buy"
+    SELL = "sell"
+
+
+class OrderStatus(str, Enum):
+    OPEN = "open"
+    PARTIALLY_FILLED = "partially_filled"
+    FILLED = "filled"
+    CANCELLED = "cancelled"
+
+
+class MarketStatus(str, Enum):
+    ACTIVE = "active"
+    RESOLVED = "resolved"
+    VOIDED = "voided"
+
+
+class EventSort(str, Enum):
+    """Sort order for the events list. Every mode keeps active events ahead
+    of overdue and settled ones; the mode picks the tiebreaker."""
+
+    ENDING = "ending"
+    TRENDING = "trending"
+    NEW = "new"
+    MARKETS = "markets"
+    NAME = "name"
+
+
+class TimeInForce(str, Enum):
+    GTC = "gtc"
+    IOC = "ioc"
+    FOK = "fok"
+    GTD = "gtd"
+    DAY = "day"

nexode_sdk-0.1.0/src/nexode/errors.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Type
+
+
+class NexodeError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        trace_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.trace_id = trace_id
+
+
+class AuthError(NexodeError):
+    """Invalid or expired credentials (401/403)."""
+
+
+class ValidationError(NexodeError):
+    """The request was malformed (400)."""
+
+
+class UnprocessableError(NexodeError):
+    """A well-formed request rejected by a business rule — insufficient funds,
+    missing trade delegation, market halted, etc. (422)."""
+
+
+class NotFoundError(NexodeError):
+    """The resource does not exist (404)."""
+
+
+class RateLimitError(NexodeError):
+    """Too many requests (429)."""
+
+
+class ServerError(NexodeError):
+    """The server failed to handle the request (5xx)."""
+
+
+def error_from_response(status: int, body: Mapping[str, Any]) -> NexodeError:
+    match status:
+        case 400:
+            cls: Type[NexodeError] = ValidationError
+        case 401 | 403:
+            cls = AuthError
+        case 404:
+            cls = NotFoundError
+        case 422:
+            cls = UnprocessableError
+        case 429:
+            cls = RateLimitError
+        case s if s >= 500:
+            cls = ServerError
+        case _:
+            cls = NexodeError
+    return cls(
+        body.get("message") or f"HTTP {status}",
+        status=status,
+        trace_id=body.get("trace_id"),
+    )

nexode_sdk-0.1.0/src/nexode/models/__init__.py

@@ -0,0 +1,27 @@
+from .activity import Burn, Mint, Redeem
+from .api_key import ApiKey
+from .market import BookSnapshot, PriceLevel, Ticker
+from .nexode import Event, Instrument, Market, MarketEvent
+from .order import Order
+from .portfolio import PortfolioSnapshot
+from .token import Token
+from .trade import MarketTrade, Trade
+
+__all__ = [
+    "Market",
+    "Event",
+    "MarketEvent",
+    "Instrument",
+    "Order",
+    "Trade",
+    "MarketTrade",
+    "Ticker",
+    "PriceLevel",
+    "BookSnapshot",
+    "Token",
+    "Mint",
+    "Redeem",
+    "Burn",
+    "PortfolioSnapshot",
+    "ApiKey",
+]

nexode_sdk-0.1.0/src/nexode/models/_base.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class Model(BaseModel):
+    model_config = ConfigDict(extra="ignore", frozen=True)