nexode-sdk 0.1.0__py3-none-any.whl

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/_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/_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/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/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/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/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/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/models/_base.py

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

nexode/models/activity.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Optional
+
+from ._base import Model
+
+
+class Mint(Model):
+    """Collateral paid in to create a YES+NO pair."""
+
+    id: str
+    market_id: str
+    party_id: str
+    amount: Decimal
+    created_at: datetime
+    transaction_id: str
+
+
+class Redeem(Model):
+    """Payout claimed on a resolved market."""
+
+    id: str
+    market_id: str
+    party_id: str
+    status: str
+    amount: Optional[Decimal] = None
+    reason: Optional[str] = None
+    created_at: datetime
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    transaction_id: Optional[str] = None
+
+
+class Burn(Model):
+    """A YES+NO pair burned back to collateral."""
+
+    id: str
+    market_id: str
+    party_id: str
+    status: str
+    amount: Decimal
+    reason: Optional[str] = None
+    created_at: datetime
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    transaction_id: Optional[str] = None

nexode/models/api_key.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from ._base import Model
+
+
+class ApiKey(Model):
+    """Masked metadata for an API key — the plaintext is never re-shown."""
+
+    id: str
+    last_four: str
+    name: Optional[str] = None
+    created_at: datetime

nexode/models/market.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+from typing import List, Optional
+
+from ._base import Model
+
+
+class Ticker(Model):
+    best_bid: Optional[Decimal] = None
+    best_ask: Optional[Decimal] = None
+    last_trade_price: Optional[Decimal] = None
+    captured_at: datetime
+
+
+class PriceLevel(Model):
+    price: Decimal
+    quantity: Decimal
+
+
+class BookSnapshot(Model):
+    bids: List[PriceLevel]
+    asks: List[PriceLevel]
+    captured_at: datetime

nexode/models/nexode.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import model_validator
+
+from ..enums import MarketStatus, Outcome
+from ._base import Model
+
+_DEFAULT_LABELS = {Outcome.YES: "Yes", Outcome.NO: "No"}
+
+
+class Instrument(Model):
+    id: str
+    admin_id: str
+
+
+class MarketEvent(Model):
+    id: str
+    slug: str
+    title: str
+    image_url: Optional[str] = None
+    market_count: int
+
+
+class Market(Model):
+    """A prediction market (the question), with both outcomes' order books."""
+
+    id: str
+    slug: str
+    name: str
+    status: str
+    category: Optional[str] = None
+    title: Optional[str] = None
+    yes_label: Optional[str] = None
+    no_label: Optional[str] = None
+    collateral_price: Decimal
+    redeem_fee_rate: Decimal
+    collateral_instrument: Instrument
+    yes_instrument: Instrument
+    no_instrument: Instrument
+    yes_order_book_id: Optional[str] = None
+    no_order_book_id: Optional[str] = None
+    liquidity: Optional[Decimal] = None
+    resolved_outcome: Optional[Outcome] = None
+    resolved_at: Optional[datetime] = None
+    voided_at: Optional[datetime] = None
+    event: Optional[MarketEvent] = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _lift_metadata(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            meta = data.get("metadata") or {}
+            data = {
+                **data,
+                "category": meta.get("category"),
+                "title": meta.get("title"),
+                "yes_label": meta.get("yes_label"),
+                "no_label": meta.get("no_label"),
+                "yes_order_book_id": meta.get("atomix_yes_market_id"),
+                "no_order_book_id": meta.get("atomix_no_market_id"),
+            }
+        return data
+
+    @property
+    def is_active(self) -> bool:
+        return self.status == MarketStatus.ACTIVE
+
+    @property
+    def is_resolved(self) -> bool:
+        return self.status == MarketStatus.RESOLVED
+
+    @property
+    def is_voided(self) -> bool:
+        return self.status == MarketStatus.VOIDED
+
+    def outcome_label(self, outcome: Union[Outcome, str]) -> str:
+        """Display label for an outcome — e.g. ``"Lakers"``/``"Celtics"`` on a
+        game market. Falls back to ``"Yes"``/``"No"`` when unset."""
+        outcome = Outcome(outcome)
+        raw = self.yes_label if outcome is Outcome.YES else self.no_label
+        return (raw or "").strip() or _DEFAULT_LABELS[outcome]
+
+    @property
+    def labels(self) -> Dict[Outcome, str]:
+        """Both outcomes' display labels, keyed by :class:`Outcome`."""
+        return {o: self.outcome_label(o) for o in Outcome}
+
+    def outcome_for_label(self, label: str) -> Outcome:
+        """Map a display label (or a literal ``"yes"``/``"no"``) back to its
+        outcome side. Matching is case-insensitive."""
+        needle = label.strip().casefold()
+        for outcome in Outcome:
+            if needle in (self.outcome_label(outcome).casefold(), outcome.value):
+                return outcome
+        raise ValueError(
+            f"label {label!r} does not match either outcome of market {self.slug!r} "
+            f"({self.outcome_label(Outcome.YES)!r} / {self.outcome_label(Outcome.NO)!r})"
+        )
+
+    @property
+    def winning_outcome(self) -> Optional[Outcome]:
+        """The resolved outcome, or ``None`` while unresolved/voided."""
+        return self.resolved_outcome
+
+    @property
+    def winning_label(self) -> Optional[str]:
+        """Display label of the winning outcome, or ``None`` while unresolved."""
+        return None if self.resolved_outcome is None else self.outcome_label(self.resolved_outcome)
+
+
+class Event(Model):
+    id: str
+    slug: str
+    admin_party: str
+    title: Optional[str] = None
+    category: Optional[str] = None
+    description: Optional[str] = None
+    image_url: Optional[str] = None
+    created_at: Optional[datetime] = None
+    market_ids: List[str]
+    markets: List[Market]
+
+    @model_validator(mode="before")
+    @classmethod
+    def _lift_metadata(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            meta = data.get("metadata") or {}
+            data = {
+                **data,
+                "title": meta.get("title"),
+                "category": meta.get("category"),
+                "description": meta.get("description"),
+                "image_url": meta.get("image_url"),
+                "created_at": meta.get("created_at"),
+            }
+        return data

nexode/models/order.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Optional
+
+from ..enums import Outcome, OrderSide, OrderStatus
+from ._base import Model
+
+
+class Order(Model):
+    id: str
+    market_id: str
+    outcome: Outcome
+    party_id: str
+    side: OrderSide
+    status: OrderStatus
+    quantity: Decimal
+    filled_quantity: Decimal
+    remaining_quantity: Decimal
+    price: Optional[Decimal] = None
+    cancel_reason: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime

nexode/models/portfolio.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Dict, List
+
+from .activity import Burn, Mint, Redeem
+from .market import Ticker
+from .nexode import Market
+from .order import Order
+from .trade import Trade
+from ._base import Model
+
+
+class PortfolioSnapshot(Model):
+    """Everything needed to compute PnL — raw data, no math.
+
+    A position is reconstructed from `mints` (+ buys − sells) and `trades`; use
+    `markets` for cost-basis/resolution and `tickers` to mark open positions.
+    `markets` is keyed by market id; `tickers` by ``"{market_id}:{outcome}"``.
+    """
+
+    trades: List[Trade]
+    open_orders: List[Order]
+    mints: List[Mint]
+    redeems: List[Redeem]
+    burns: List[Burn]
+    markets: Dict[str, Market]
+    tickers: Dict[str, Ticker]

nexode/models/token.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Optional
+
+from ._base import Model
+
+
+class Token(Model):
+    instrument_id: str
+    instrument_admin_id: str
+    symbol: str
+    name: str
+    decimals: int
+    total_supply: Optional[Decimal] = None

nexode/models/trade.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+
+from ..enums import Outcome, OrderSide
+from ._base import Model
+
+
+class Trade(Model):
+    id: str
+    market_id: str
+    outcome: Outcome
+    price: Decimal
+    quantity: Decimal
+    taker_side: OrderSide
+    maker_order_id: str
+    taker_order_id: str
+    maker_party_id: str
+    taker_party_id: str
+    maker_fee: Decimal
+    taker_fee: Decimal
+    executed_at: datetime
+
+
+class MarketTrade(Model):
+    trade_id: str
+    price: Decimal
+    quantity: Decimal
+    taker_side: OrderSide
+    executed_at: datetime

nexode/resources/__init__.py

@@ -0,0 +1,21 @@
+from .activity import Burns, Mints, Redeems
+from .api_keys import ApiKeys
+from .events import Events
+from .markets import Markets
+from .orders import Orders
+from .portfolio import Portfolio
+from .tokens import Tokens
+from .trades import Trades
+
+__all__ = [
+    "ApiKeys",
+    "Markets",
+    "Events",
+    "Orders",
+    "Trades",
+    "Tokens",
+    "Mints",
+    "Redeems",
+    "Burns",
+    "Portfolio",
+]

nexode/resources/_base.py

@@ -0,0 +1,6 @@
+from .._transport import Transport
+
+
+class Resource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport

nexode/resources/activity.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import List
+
+from ..models import Burn, Mint, Redeem
+from ._base import Resource
+
+
+class Mints(Resource):
+    def list(self) -> List[Mint]:
+        body = self._t.get("/v0/mints")
+        return [Mint.model_validate(m) for m in body["mints"]]
+
+
+class Redeems(Resource):
+    def list(self) -> List[Redeem]:
+        body = self._t.get("/v0/redeems")
+        return [Redeem.model_validate(r) for r in body["redeems"]]
+
+    def get(self, redeem_id: str) -> Redeem:
+        return Redeem.model_validate(self._t.get(f"/v0/redeems/{redeem_id}"))
+
+
+class Burns(Resource):
+    def list(self) -> List[Burn]:
+        body = self._t.get("/v0/burns")
+        return [Burn.model_validate(b) for b in body["burns"]]
+
+    def get(self, burn_id: str) -> Burn:
+        return Burn.model_validate(self._t.get(f"/v0/burns/{burn_id}"))

nexode/resources/api_keys.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import List
+
+from ..models import ApiKey
+from ._base import Resource
+
+
+class ApiKeys(Resource):
+    """Inspect and revoke the API keys on your account. New keys are created
+    in the web app (Settings → Developer), never through the SDK."""
+
+    def list(self) -> List[ApiKey]:
+        body = self._t.get("/v0/api-keys/me")
+        return [ApiKey.model_validate(k) for k in body["api_keys"]]
+
+    def revoke(self, api_key_id: str) -> None:
+        self._t.delete(f"/v0/api-keys/me/{api_key_id}")

nexode/resources/events.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import List, Optional, Sequence, Union
+
+from ..enums import EventSort
+from ..models import Event
+from ._base import Resource
+
+
+class Events(Resource):
+    def list(
+        self,
+        *,
+        q: Optional[str] = None,
+        category: Optional[str] = None,
+        sort: Optional[Union[EventSort, str]] = None,
+        market_ids: Optional[Sequence[str]] = None,
+        hide_stale_settled: Optional[bool] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> List[Event]:
+        """List events, filtered and sorted server-side.
+
+        Args:
+            q: Full-text search over event titles.
+            category: Only events in this category.
+            sort: ``ending``/``trending``/``new``/``markets``/``name``;
+                defaults to ``new``. Active events always sort ahead of
+                overdue and settled ones.
+            market_ids: Only events containing at least one of these markets.
+            hide_stale_settled: Drop fully-settled events whose dispute
+                windows have elapsed.
+            limit: Maximum events to return (server default 100, max 1000).
+            offset: Number of sorted events to skip before the returned
+                window — pair with ``limit`` to page through the feed.
+        """
+        params: dict = {}
+        if q is not None:
+            params["q"] = q
+        if category is not None:
+            params["category"] = category
+        if sort is not None:
+            params["sort"] = EventSort(sort).value
+        if market_ids:
+            params["market_ids"] = ",".join(market_ids)
+        if hide_stale_settled is not None:
+            params["hide_stale_settled"] = hide_stale_settled
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+        body = self._t.get("/v0/events", params=params)
+        return [Event.model_validate(e) for e in body["events"]]
+
+    def get(self, event_id: str) -> Event:
+        body = self._t.get(f"/v0/events/{event_id}")
+        return Event.model_validate(body["event"])
+
+    def by_slug(self, slug: str) -> Event:
+        body = self._t.get(f"/v0/events/by-slug/{slug}")
+        return Event.model_validate(body["event"])

nexode/resources/markets.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import List, Optional, Union
+
+from .._resolver import Resolver
+from .._transport import Transport
+from ..enums import MarketStatus, Outcome
+from ..models import BookSnapshot, Market, MarketTrade, Ticker
+
+
+class Markets:
+    """Prediction markets: browse them, and read live data per outcome."""
+
+    def __init__(self, nexode: Transport, atomix: Transport, resolver: Resolver) -> None:
+        self._n = nexode
+        self._a = atomix
+        self._r = resolver
+
+    def list(
+        self,
+        *,
+        category: Optional[str] = None,
+        status: Optional[Union[MarketStatus, str]] = None,
+        q: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> List[Market]:
+        """List prediction markets, filtered server-side.
+
+        Args:
+            category: Only markets in this category.
+            status: Only markets in this lifecycle state
+                (``active``/``resolved``/``voided``).
+            q: Full-text search over market questions.
+            limit: Maximum markets to return (max 1000).
+        """
+        params: dict = {}
+        if category is not None:
+            params["category"] = category
+        if status is not None:
+            params["status"] = MarketStatus(status).value
+        if q is not None:
+            params["q"] = q
+        if limit is not None:
+            params["limit"] = limit
+        body = self._n.get("/v0/markets", params=params)
+        return [Market.model_validate(m) for m in body["markets"]]
+
+    def get(self, market_id: str) -> Market:
+        return Market.model_validate(self._n.get(f"/v0/markets/{market_id}")["market"])
+
+    def by_slug(self, slug: str) -> Market:
+        return Market.model_validate(self._n.get(f"/v0/markets/by-slug/{slug}")["market"])
+
+    def ticker(self, market_id: str, outcome: Union[Outcome, str]) -> Ticker:
+        book = self._r.order_book_id(market_id, outcome)
+        return Ticker.model_validate(self._a.get(f"/v0/markets/{book}/ticker")["ticker"])
+
+    def book(self, market_id: str, outcome: Union[Outcome, str]) -> BookSnapshot:
+        book = self._r.order_book_id(market_id, outcome)
+        return BookSnapshot.model_validate(self._a.get(f"/v0/markets/{book}/book")["snapshot"])
+
+    def recent_trades(self, market_id: str, outcome: Union[Outcome, str]) -> List[MarketTrade]:
+        book = self._r.order_book_id(market_id, outcome)
+        body = self._a.get(f"/v0/markets/{book}/trades")
+        return [MarketTrade.model_validate(t) for t in body["trades"]]

nexode/resources/orders.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+from typing import List, Optional, Tuple, Union
+
+from .._resolver import Resolver
+from .._transport import Transport
+from ..enums import Outcome, OrderSide, TimeInForce
+from ..models import Order
+
+Number = Union[str, int, float, Decimal]
+
+
+class Orders:
+    def __init__(self, atomix: Transport, resolver: Resolver) -> None:
+        self._a = atomix
+        self._r = resolver
+
+    def create(
+        self,
+        *,
+        market_id: str,
+        outcome: Union[Outcome, str],
+        side: Union[OrderSide, str],
+        price: Number,
+        quantity: Number,
+        time_in_force: Union[TimeInForce, str] = TimeInForce.GTC,
+        expires_at: Optional[datetime] = None,
+    ) -> Order:
+        book = self._r.order_book_id(market_id, outcome)
+        body = self._a.post(
+            "/v0/orders",
+            json={
+                "market_id": book,
+                "side": OrderSide(side).value,
+                "quantity": str(quantity),
+                "order_type": {
+                    "type": "limit",
+                    "price": str(price),
+                    "time_in_force": _time_in_force(time_in_force, expires_at),
+                },
+            },
+        )
+        return self._order(body["order"])
+
+    def list(self) -> List[Order]:
+        raw = self._a.get("/v0/orders")["orders"]
+        resolved = self._r.resolve(r["market_id"] for r in raw)
+        return [_build(r, resolved.get(r["market_id"])) for r in raw]
+
+    def get(self, order_id: str) -> Order:
+        return self._order(self._a.get(f"/v0/orders/{order_id}")["order"])
+
+    def cancel(self, order_id: str) -> None:
+        self._a.post(f"/v0/orders/{order_id}/cancel")
+
+    def _order(self, raw: dict) -> Order:
+        return _build(raw, self._r.market_outcome(raw["market_id"]))
+
+
+def _build(raw: dict, mapped: Optional[Tuple[str, Outcome]]) -> Order:
+    market_id, outcome = mapped if mapped else (raw["market_id"], None)
+    return Order.model_validate({**raw, "market_id": market_id, "outcome": outcome})
+
+
+def _time_in_force(value: Union[TimeInForce, str], expires_at: Optional[datetime]) -> dict:
+    tif = TimeInForce(value)
+    if tif is TimeInForce.GTD:
+        if expires_at is None:
+            raise ValueError("time_in_force=gtd requires expires_at")
+        return {"type": "gtd", "expires_at": expires_at.isoformat()}
+    return {"type": tif.value}

nexode/resources/portfolio.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from .._resolver import Resolver
+from .._transport import Transport
+from ..enums import OrderStatus
+from ..errors import NotFoundError
+from ..models import PortfolioSnapshot
+from .activity import Burns, Mints, Redeems
+from .markets import Markets
+from .orders import Orders
+from .trades import Trades
+
+_OPEN = (OrderStatus.OPEN, OrderStatus.PARTIALLY_FILLED)
+
+
+class Portfolio:
+    """Fetches everything needed to compute PnL in one call."""
+
+    def __init__(self, *, atomix: Transport, nexode: Transport, resolver: Resolver) -> None:
+        self._markets = Markets(nexode, atomix, resolver)
+        self._orders = Orders(atomix, resolver)
+        self._trades = Trades(atomix, resolver)
+        self._mints = Mints(nexode)
+        self._redeems = Redeems(nexode)
+        self._burns = Burns(nexode)
+
+    def snapshot(self) -> PortfolioSnapshot:
+        trades = self._trades.list()
+        open_orders = [o for o in self._orders.list() if o.status in _OPEN]
+        mints = self._mints.list()
+        redeems = self._redeems.list()
+        burns = self._burns.list()
+
+        market_ids = sorted(
+            {t.market_id for t in trades}
+            | {o.market_id for o in open_orders}
+            | {m.market_id for m in mints}
+            | {r.market_id for r in redeems}
+        )
+        markets = {}
+        for market_id in market_ids:
+            try:
+                markets[market_id] = self._markets.get(market_id)
+            except NotFoundError:
+                pass
+
+        # Tickers exist only for markets that are currently open.
+        tickers = {}
+        for trade in trades:
+            key = f"{trade.market_id}:{trade.outcome.value}"
+            if key in tickers:
+                continue
+            try:
+                tickers[key] = self._markets.ticker(trade.market_id, trade.outcome)
+            except NotFoundError:
+                pass
+
+        return PortfolioSnapshot(
+            trades=trades,
+            open_orders=open_orders,
+            mints=mints,
+            redeems=redeems,
+            burns=burns,
+            markets=markets,
+            tickers=tickers,
+        )

nexode/resources/tokens.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import List
+
+from ..models import Token
+from ._base import Resource
+
+
+class Tokens(Resource):
+    def list(self) -> List[Token]:
+        body = self._t.get("/v0/tokens")
+        return [Token.model_validate(t) for t in body["tokens"]]

nexode/resources/trades.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+from .._resolver import Resolver
+from .._transport import Transport
+from ..enums import Outcome
+from ..models import Trade
+
+
+class Trades:
+    def __init__(self, atomix: Transport, resolver: Resolver) -> None:
+        self._a = atomix
+        self._r = resolver
+
+    def list(self) -> List[Trade]:
+        raw = self._a.get("/v0/trades")["trades"]
+        resolved = self._r.resolve(r["market_id"] for r in raw)
+        return [_build(r, resolved.get(r["market_id"])) for r in raw]
+
+    def get(self, trade_id: str) -> Trade:
+        raw = self._a.get(f"/v0/trades/{trade_id}")["trade"]
+        return _build(raw, self._r.market_outcome(raw["market_id"]))
+
+
+def _build(raw: dict, mapped: Optional[Tuple[str, Outcome]]) -> Trade:
+    market_id, outcome = mapped if mapped else (raw["market_id"], None)
+    return Trade.model_validate({**raw, "market_id": market_id, "outcome": outcome})

nexode_sdk-0.1.0.dist-info/METADATA

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

@@ -0,0 +1,30 @@
+nexode/__init__.py,sha256=j-0T0RNRhX23cNM2aeOP1Ux-NdS46FABHlz9484OByM,1111
+nexode/_resolver.py,sha256=89l09yZbqIL_PMEea8wviF5_-17OfUupsuoZ0gi3Og8,2274
+nexode/_transport.py,sha256=_X9L1fNOv1n1LrWsuFoH9Jb8n3D3QaAhPTPvN3mSLnU,1231
+nexode/auth.py,sha256=nLRAjkJH0C8A9viVi1nsKQtgSlNz177xqLye5XooXsU,2450
+nexode/client.py,sha256=oNNae4PQd8idUpvKZALS2sGgeVpWj4OAw1k7ZYKxoP4,2203
+nexode/enums.py,sha256=YKW3HxJt_3zzGlZqHqPMtpeTJAzvwKwESpaFGCkY5Pg,781
+nexode/errors.py,sha256=hRHJ6sdDxF-_GY9jleI2HkiHR6J260Ld_2LHRxGDgdM,1606
+nexode/models/__init__.py,sha256=hKdJFojiUHOl93M523kY22NkhRpADf7aKK_TvCYVkZY,576
+nexode/models/_base.py,sha256=9ZAttGlYJ2lMgBeAl9XIHPpx2xGuexbzTKfr_-Zf0DI,128
+nexode/models/activity.py,sha256=anaQroT3ctos2p0Ltr7nc1GxrXiatyYTT0avB29YPnQ,1043
+nexode/models/api_key.py,sha256=PSnxTOIBuS80AT1Ek_2fO-ERQ0aXWMmV81V690MSmuA,309
+nexode/models/market.py,sha256=nWklrxT0-0BwF0CzZMV20oasjKs-PpcijCyBpdKUU6I,505
+nexode/models/nexode.py,sha256=3dWnDMfVki5LVAoVU6uCbsaLWSx16fy0N2XUuZ6WFks,4550
+nexode/models/order.py,sha256=eq5gPtghW4sw51kfYomTgLYWgf38P4njNydwvTD43GY,545
+nexode/models/portfolio.py,sha256=ym_8obQLc16M5xuZ8BXEdGqmLv8MXOFDx6VGFJJQb-Q,768
+nexode/models/token.py,sha256=GzjIgQ7Ek4gN1yCHG1_OlFdh34cLOnae6EDLHWuQ4qo,283
+nexode/models/trade.py,sha256=cKoEmJSo5jxIcSsZtaL3KqLBJpk5NOnGVE7dJNiXMO4,607
+nexode/resources/__init__.py,sha256=UhSxegO8PN4npROk5NiK-0OFhFBbPpv4FBaMJ-P-VTs,403
+nexode/resources/_base.py,sha256=x1Q-XCzsuzA5ZhJG7mrRXac27Ems_IFpj0wOifVClT4,135
+nexode/resources/activity.py,sha256=A56J-kM2af5HU5alIwS35h_XfnF_rbTEdSzQSVBM5JI,863
+nexode/resources/api_keys.py,sha256=vSGd4w_qrQ91sQXyYlBPj1_GG9ScChTSpptDmxnn_x0,547
+nexode/resources/events.py,sha256=s1DQ5ya6afaD-2ZUsmfMroMGscy783fcNLNEvV2C6r8,2322
+nexode/resources/markets.py,sha256=CWnzt4_tta12yaGS0q6yE32IVT8_ceP1hFccU2-IsSk,2552
+nexode/resources/orders.py,sha256=v_FqDPOOKtxIfYJ0L_oz8VaP19wP30QumBZm82wZV6A,2458
+nexode/resources/portfolio.py,sha256=stI2iQB2aN7ZBqnjcQQzYPeju2_3QWGwooqprmjuOPM,2157
+nexode/resources/tokens.py,sha256=nTXiqT1xTD9yZvdRarjSpTAcQIp2dGt9R0dIjwB89jI,283
+nexode/resources/trades.py,sha256=7upx8TgKdcBdYMvR9GfwnLJfWK7mjAfEGFVJVQ-Ma1Y,964
+nexode_sdk-0.1.0.dist-info/METADATA,sha256=eazWZBw1HBzOG1-N09FD20K7AkLQVShmN1Tq-o6zM9c,2901
+nexode_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+nexode_sdk-0.1.0.dist-info/RECORD,,

nexode_sdk-0.1.0.dist-info/WHEEL

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