0xinsider 0.1.0__tar.gz

0xinsider-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+# Publishes a GitHub release to https://pypi.org/project/0xinsider/ through
+# PyPI trusted publishing: no API token is stored anywhere. The PyPI project
+# lists this repository and this workflow file as its trusted publisher, and
+# the `pypi` environment scopes the OIDC grant to this job.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Check the tag matches the package version
+        if: github.event_name == 'release'
+        run: |
+          version=$(python3 -c "import re;print(re.search(r'\"(.+)\"', open('src/oxinsider/_version.py').read()).group(1))")
+          test "v${version}" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} does not match version ${version}"; exit 1; }
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # A version already on PyPI is skipped, not failed: a release event
+          # after a manual dispatch of the same version is then a no-op.
+          skip-existing: true

0xinsider-0.1.0/.github/workflows/regenerate.yml

@@ -0,0 +1,32 @@
+name: Regenerate from OpenAPI
+
+on:
+  schedule:
+    - cron: "23 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  regenerate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python scripts/generate.py
+      - name: Open a pull request when the contract changed
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if git diff --quiet; then echo "no change"; exit 0; fi
+          branch="regenerate/$(date -u +%Y%m%d)"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$branch"
+          git commit -am "chore: regenerate operations from the OpenAPI document"
+          git push origin "$branch"
+          gh pr create --title "Regenerate operations from the OpenAPI document" --body "The published OpenAPI document changed. Review the generated diff before releasing."

0xinsider-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+dist/
+__pycache__/
+*.pyc
+.venv/

0xinsider-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 0xinsider
+
+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.

0xinsider-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: 0xinsider
+Version: 0.1.0
+Summary: Official Python client for the 0xinsider Developer API: Polymarket sports and esports analytics, trader grades, large trades and sharp-money flow.
+Project-URL: Homepage, https://0xinsider.com/developers
+Project-URL: Documentation, https://docs.0xinsider.com
+Project-URL: Repository, https://github.com/0xinsider/0xinsider-python
+Project-URL: Issues, https://github.com/0xinsider/0xinsider-python/issues
+Project-URL: OpenAPI, https://0xinsider.com/api/v1/openapi.json
+Author-email: 0xinsider <support@0xinsider.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 0xinsider,api,polymarket,prediction markets,sdk,sports analytics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# 0xinsider Python SDK
+
+Official Python client for the [0xinsider Developer API](https://0xinsider.com/developers): Polymarket sports and esports analytics, wallet grades, large trades, positions, reports and sharp-money flow.
+
+```sh
+pip install 0xinsider
+```
+
+The distribution is `0xinsider`; the import is `oxinsider`, because a Python module name cannot start with a digit.
+
+## Try it without a key
+
+The [sandbox](https://0xinsider.com/sandbox/api/v1) answers every documented operation with example data. It needs no credential and never touches production data.
+
+```python
+import oxinsider
+
+with oxinsider.Client.sandbox() as client:
+    page = client.list_leaderboard(limit=5)
+    print(page["data"][0]["username"])
+
+    # Any error the operation documents, on demand:
+    try:
+        client.request("GET", "/api/v1/leaderboard", query={"sandbox_status": 429})
+    except oxinsider.RateLimitedError as error:
+        print(error.code, error.retry_after)
+```
+
+## Live data
+
+Data operations need an API key from [0xinsider.com/developers](https://0xinsider.com/developers) or an OAuth 2.1 access token ([auth.md](https://0xinsider.com/auth.md)), plus an active Pro subscription. Discovery, health and platforms are public.
+
+```python
+import oxinsider
+
+client = oxinsider.Client()  # reads OXINSIDER_API_KEY
+trader = client.get_trader("swisstony", expand=["strategy", "categories"])
+print(trader["data"]["grade"])
+
+for trade in client.paginate("list_whale_trades", min_grade="A", limit=100):
+    print(trade["size_usd"], trade["market"]["title"])
+```
+
+- Every documented operation is a method named after its operationId in snake_case (`listLeaderboard` becomes `list_leaderboard`). Each returns the decoded JSON body.
+- `if_none_match="<etag>"` returns `{"object": "not_modified", "data": None, "etag": ...}` when nothing changed.
+- `idempotency_key=` is accepted on the webhook mutations that document it.
+- The SSE stream is read with `client.request("GET", "/api/v1/stream", stream=True)`, which returns the open `httpx.Response`.
+
+## Errors
+
+Every non-2xx response raises `oxinsider.OxinsiderApiError` or a subclass: `BadRequestError`, `AuthenticationError`, `SubscriptionRequiredError`, `PermissionDeniedError`, `NotFoundError`, `RateLimitedError` or `ServerError`. Each carries `status`, `code`, `reason`, `param`, `retry_at`, `retry_after` and `request_id`. Branch on `reason` when it is present. For `RateLimitedError`, wait `retry_after` seconds. A request that gets no response raises `OxinsiderConnectionError`.
+
+## How it is built
+
+`src/oxinsider/_operations.py` is generated from the published [OpenAPI document](https://0xinsider.com/api/v1/openapi.json) by `scripts/generate.py`, and a weekly workflow opens a pull request when the contract changes. Releases publish to PyPI from GitHub Actions through trusted publishing.
+
+## Other official tools
+
+- CLI and MCP server: `npm install --global @0xinsider/mcp` or `brew install 0xinsider/tap/oxinsider`
+- Go SDK: `go get github.com/0xinsider/0xinsider-go`
+- Remote MCP server: `https://api.0xinsider.com/api/v1/mcp`
+
+## License
+
+MIT

0xinsider-0.1.0/README.md

@@ -0,0 +1,65 @@
+# 0xinsider Python SDK
+
+Official Python client for the [0xinsider Developer API](https://0xinsider.com/developers): Polymarket sports and esports analytics, wallet grades, large trades, positions, reports and sharp-money flow.
+
+```sh
+pip install 0xinsider
+```
+
+The distribution is `0xinsider`; the import is `oxinsider`, because a Python module name cannot start with a digit.
+
+## Try it without a key
+
+The [sandbox](https://0xinsider.com/sandbox/api/v1) answers every documented operation with example data. It needs no credential and never touches production data.
+
+```python
+import oxinsider
+
+with oxinsider.Client.sandbox() as client:
+    page = client.list_leaderboard(limit=5)
+    print(page["data"][0]["username"])
+
+    # Any error the operation documents, on demand:
+    try:
+        client.request("GET", "/api/v1/leaderboard", query={"sandbox_status": 429})
+    except oxinsider.RateLimitedError as error:
+        print(error.code, error.retry_after)
+```
+
+## Live data
+
+Data operations need an API key from [0xinsider.com/developers](https://0xinsider.com/developers) or an OAuth 2.1 access token ([auth.md](https://0xinsider.com/auth.md)), plus an active Pro subscription. Discovery, health and platforms are public.
+
+```python
+import oxinsider
+
+client = oxinsider.Client()  # reads OXINSIDER_API_KEY
+trader = client.get_trader("swisstony", expand=["strategy", "categories"])
+print(trader["data"]["grade"])
+
+for trade in client.paginate("list_whale_trades", min_grade="A", limit=100):
+    print(trade["size_usd"], trade["market"]["title"])
+```
+
+- Every documented operation is a method named after its operationId in snake_case (`listLeaderboard` becomes `list_leaderboard`). Each returns the decoded JSON body.
+- `if_none_match="<etag>"` returns `{"object": "not_modified", "data": None, "etag": ...}` when nothing changed.
+- `idempotency_key=` is accepted on the webhook mutations that document it.
+- The SSE stream is read with `client.request("GET", "/api/v1/stream", stream=True)`, which returns the open `httpx.Response`.
+
+## Errors
+
+Every non-2xx response raises `oxinsider.OxinsiderApiError` or a subclass: `BadRequestError`, `AuthenticationError`, `SubscriptionRequiredError`, `PermissionDeniedError`, `NotFoundError`, `RateLimitedError` or `ServerError`. Each carries `status`, `code`, `reason`, `param`, `retry_at`, `retry_after` and `request_id`. Branch on `reason` when it is present. For `RateLimitedError`, wait `retry_after` seconds. A request that gets no response raises `OxinsiderConnectionError`.
+
+## How it is built
+
+`src/oxinsider/_operations.py` is generated from the published [OpenAPI document](https://0xinsider.com/api/v1/openapi.json) by `scripts/generate.py`, and a weekly workflow opens a pull request when the contract changes. Releases publish to PyPI from GitHub Actions through trusted publishing.
+
+## Other official tools
+
+- CLI and MCP server: `npm install --global @0xinsider/mcp` or `brew install 0xinsider/tap/oxinsider`
+- Go SDK: `go get github.com/0xinsider/0xinsider-go`
+- Remote MCP server: `https://api.0xinsider.com/api/v1/mcp`
+
+## License
+
+MIT

0xinsider-0.1.0/examples/discovery.py

@@ -0,0 +1,9 @@
+"""Read the public discovery document and health from the live API. No key needed."""
+
+import oxinsider
+
+with oxinsider.Client(api_key="") as client:
+    discovery = client.get_api_discovery()
+    print("api base:", discovery["data"]["api_base_url"])
+    health = client.get_health()
+    print("health:", health.get("data", {}).get("status", health))

0xinsider-0.1.0/examples/sandbox.py

@@ -0,0 +1,15 @@
+"""Call the 0xinsider sandbox: no key, example data, simulated errors."""
+
+import oxinsider
+
+with oxinsider.Client.sandbox() as client:
+    leaderboard = client.list_leaderboard(limit=3)
+    print("leaderboard object:", leaderboard["object"], "rows:", len(leaderboard["data"]))
+
+    trader = client.get_trader("0x0000000000000000000000000000000000000001")
+    print("trader grade:", trader["data"]["grade"])
+
+    try:
+        client.request("GET", "/api/v1/leaderboard", query={"sandbox_status": 429})
+    except oxinsider.RateLimitedError as error:
+        print("simulated rate limit:", error.code, "retry after", error.retry_after, "s")

0xinsider-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "0xinsider"
+dynamic = ["version"]
+description = "Official Python client for the 0xinsider Developer API: Polymarket sports and esports analytics, trader grades, large trades and sharp-money flow."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "0xinsider", email = "support@0xinsider.com" }]
+keywords = ["0xinsider", "polymarket", "prediction markets", "sports analytics", "api", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.urls]
+Homepage = "https://0xinsider.com/developers"
+Documentation = "https://docs.0xinsider.com"
+Repository = "https://github.com/0xinsider/0xinsider-python"
+Issues = "https://github.com/0xinsider/0xinsider-python/issues"
+"OpenAPI" = "https://0xinsider.com/api/v1/openapi.json"
+
+[tool.hatch.version]
+path = "src/oxinsider/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oxinsider"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "B", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+# Generated: docstrings quote the OpenAPI descriptions verbatim.
+"src/oxinsider/_operations.py" = ["E501"]
+"scripts/generate.py" = ["E501"]

0xinsider-0.1.0/scripts/generate.py

@@ -0,0 +1,177 @@
+"""Generate src/oxinsider/_operations.py from the published 0xinsider OpenAPI document.
+
+Usage: python scripts/generate.py [path-or-url]
+Default source: https://0xinsider.com/api/v1/openapi.json
+"""
+
+from __future__ import annotations
+
+import json
+import keyword
+import re
+import sys
+import textwrap
+import urllib.request
+from pathlib import Path
+
+DEFAULT_SOURCE = "https://0xinsider.com/api/v1/openapi.json"
+OUTPUT = Path(__file__).resolve().parent.parent / "src" / "oxinsider" / "_operations.py"
+METHODS = ("get", "post", "put", "patch", "delete")
+# Operations whose success response is a Server-Sent Events stream. They are
+# reachable through Client.request(..., stream=True), not a generated method.
+STREAMING_CONTENT = "text/event-stream"
+
+
+def load(source: str) -> dict:
+    if source.startswith("http://") or source.startswith("https://"):
+        request = urllib.request.Request(source, headers={"User-Agent": "0xinsider-python-generator"})
+        with urllib.request.urlopen(request, timeout=60) as response:  # noqa: S310 - fixed https source
+            return json.load(response)
+    return json.loads(Path(source).read_text())
+
+
+def snake(name: str) -> str:
+    name = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", name)
+    name = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)
+    return name.lower()
+
+
+def python_name(name: str) -> str:
+    candidate = re.sub(r"[^0-9a-zA-Z_]", "_", name.replace("[]", ""))
+    if keyword.iskeyword(candidate) or candidate in {"self", "body", "headers"}:
+        candidate += "_"
+    return candidate
+
+
+def first_sentence(text: str, limit: int = 300) -> str:
+    text = " ".join((text or "").split())
+    if len(text) <= limit:
+        return text
+    cut = text[:limit]
+    return cut[: cut.rfind(" ")] + " ..."
+
+
+def success_content_types(operation: dict) -> list[str]:
+    for code in ("200", "201", "202"):
+        response = operation.get("responses", {}).get(code)
+        if isinstance(response, dict):
+            return list((response.get("content") or {}).keys())
+    return []
+
+
+def generate(doc: dict) -> str:
+    entries = []
+    methods = []
+    for path, item in doc.get("paths", {}).items():
+        shared_params = item.get("parameters", [])
+        for method in METHODS:
+            operation = item.get(method)
+            if not isinstance(operation, dict):
+                continue
+            operation_id = operation.get("operationId")
+            if not operation_id:
+                continue
+            params = [*shared_params, *operation.get("parameters", [])]
+            seen = set()
+            unique = []
+            for param in params:
+                if "$ref" in param or param.get("name", "").endswith("[]"):
+                    continue
+                key = (param.get("in"), param.get("name"))
+                if key in seen:
+                    continue
+                seen.add(key)
+                unique.append(param)
+            path_params = [p for p in unique if p.get("in") == "path"]
+            query_params = [p for p in unique if p.get("in") == "query"]
+            header_params = [p for p in unique if p.get("in") == "header"]
+            has_body = "requestBody" in operation
+            content_types = success_content_types(operation)
+            streaming = content_types == [STREAMING_CONTENT]
+            entries.append(
+                {
+                    "operation_id": operation_id,
+                    "method": method.upper(),
+                    "path": path,
+                    "streaming": streaming,
+                }
+            )
+            if streaming:
+                continue
+            name = snake(operation_id)
+            args = ["self"]
+            args += [f"{python_name(p['name'])}: str" for p in path_params]
+            if has_body:
+                required = operation["requestBody"].get("required", False)
+                args.append("body: Any" if required else "body: Any = None")
+            kw = [f"{python_name(p['name'])}: Any = None" for p in query_params]
+            for header in header_params:
+                hname = header["name"].lower()
+                if hname == "if-none-match":
+                    kw.append("if_none_match: str | None = None")
+                elif hname == "idempotency-key":
+                    kw.append("idempotency_key: str | None = None")
+            if kw:
+                args.append("*")
+                args += kw
+            summary = first_sentence(operation.get("summary") or operation_id, 200)
+            description = first_sentence(operation.get("description") or "")
+            doc_lines = [f"{summary}.".replace("..", "."), "", f"``{method.upper()} {path}`` (operationId ``{operation_id}``)."]
+            if description:
+                doc_lines += ["", *textwrap.wrap(description, 88)]
+            if query_params:
+                doc_lines += ["", "Query parameters:"]
+                for p in query_params:
+                    pdesc = first_sentence(p.get("description") or "", 160)
+                    doc_lines.append(f"    {python_name(p['name'])}: {pdesc}".rstrip())
+            docstring = "\n        ".join(line.replace('"""', "'''") for line in doc_lines)
+            path_map = ", ".join(f'"{p["name"]}": {python_name(p["name"])}' for p in path_params)
+            query_map = ", ".join(f'"{p["name"]}": {python_name(p["name"])}' for p in query_params)
+            header_args = []
+            if any(h["name"].lower() == "if-none-match" for h in header_params):
+                header_args.append("if_none_match=if_none_match")
+            if any(h["name"].lower() == "idempotency-key" for h in header_params):
+                header_args.append("idempotency_key=idempotency_key")
+            call = [f'"{operation_id}"', f"path_params={{{path_map}}}", f"query={{{query_map}}}"]
+            if has_body:
+                call.append("body=body")
+            call += header_args
+            signature = ",\n        ".join(args)
+            methods.append(
+                f"    def {name}(\n        {signature},\n    ) -> Any:\n"
+                f'        """{docstring}\n        """\n'
+                f"        return self._call({', '.join(call)})\n"
+            )
+    table = ",\n".join(
+        f'    "{e["operation_id"]}": Operation("{e["method"]}", "{e["path"]}", streaming={e["streaming"]})'
+        for e in entries
+    )
+    version = doc.get("info", {}).get("version", "unknown")
+    header = (
+        '"""Generated from the 0xinsider OpenAPI document by scripts/generate.py. Do not edit."""\n\n'
+        "from __future__ import annotations\n\n"
+        "from typing import Any, NamedTuple\n\n\n"
+        f'OPENAPI_VERSION = "{version}"\n\n\n'
+        "class Operation(NamedTuple):\n"
+        "    method: str\n"
+        "    path: str\n"
+        "    streaming: bool = False\n\n\n"
+        f"OPERATIONS: dict[str, Operation] = {{\n{table},\n}}\n\n\n"
+        "class OperationsMixin:\n"
+        '    """One method per documented operation. Each returns the decoded JSON body."""\n\n'
+        "    def _call(self, operation_id: str, **kwargs: Any) -> Any:  # pragma: no cover - provided by Client\n"
+        "        raise NotImplementedError\n\n"
+    )
+    source = header + "\n".join(methods)
+    # Blank docstring lines must not carry the indentation.
+    return re.sub(r"[ \t]+\n", "\n", source)
+
+
+def main() -> None:
+    source = sys.argv[1] if len(sys.argv) > 1 else DEFAULT_SOURCE
+    OUTPUT.write_text(generate(load(source)))
+    print(f"wrote {OUTPUT}")
+
+
+if __name__ == "__main__":
+    main()

0xinsider-0.1.0/src/oxinsider/__init__.py

@@ -0,0 +1,41 @@
+"""Official Python client for the 0xinsider Developer API.
+
+https://0xinsider.com/developers
+"""
+
+from ._client import API_KEY_ENV, NOT_MODIFIED, PRODUCTION_BASE_URL, SANDBOX_BASE_URL, Client
+from ._errors import (
+    AuthenticationError,
+    BadRequestError,
+    NotFoundError,
+    OxinsiderApiError,
+    OxinsiderConnectionError,
+    OxinsiderError,
+    PermissionDeniedError,
+    RateLimitedError,
+    ServerError,
+    SubscriptionRequiredError,
+)
+from ._operations import OPENAPI_VERSION, OPERATIONS
+from ._version import __version__
+
+__all__ = [
+    "API_KEY_ENV",
+    "NOT_MODIFIED",
+    "OPENAPI_VERSION",
+    "OPERATIONS",
+    "PRODUCTION_BASE_URL",
+    "SANDBOX_BASE_URL",
+    "AuthenticationError",
+    "BadRequestError",
+    "Client",
+    "NotFoundError",
+    "OxinsiderApiError",
+    "OxinsiderConnectionError",
+    "OxinsiderError",
+    "PermissionDeniedError",
+    "RateLimitedError",
+    "ServerError",
+    "SubscriptionRequiredError",
+    "__version__",
+]