skinapi-sdk 0.1.0__py3-none-any.whl

skinapi/__init__.py

@@ -0,0 +1,175 @@
+"""
+skinapi - Python client for SkinAPI.
+
+Real-time CS2/Dota2/Rust/TF2 skin prices, float values, inventories,
+profiles and marketplace data.
+
+Docs: https://skinapi.skinvaults.online/docs
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Optional
+
+import requests
+
+__version__ = "0.1.0"
+__all__ = ["SkinAPI", "SkinAPIError"]
+
+DEFAULT_BASE = "https://skinapi.skinvaults.online/api/v1"
+
+
+def _int(v: Optional[str]) -> Optional[int]:
+    try:
+        return int(v) if v not in (None, "") else None
+    except (TypeError, ValueError):
+        return None
+
+
+class SkinAPIError(Exception):
+    """Raised on a non-2xx response or network failure."""
+
+    def __init__(self, status: int, code: Optional[str] = None,
+                 message: Optional[str] = None, retryable: bool = False):
+        super().__init__(message or f"SkinAPI error {status}")
+        self.status = status
+        self.code = code
+        self.retryable = retryable
+
+
+class SkinAPI:
+    """SkinAPI client. Pass your key (sk_live_...), created in the dashboard."""
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE,
+                 timeout: float = 15.0, max_retries: int = 2,
+                 session: Optional[requests.Session] = None):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.session = session or requests.Session()
+        self.session.headers.update({"x-api-key": api_key})
+        #: Rate-limit info from the most recent response, or None.
+        self.rate_limit: Optional[dict] = None
+
+    # -- internals --
+    def _backoff(self, attempt: int) -> float:
+        return (2 ** attempt) * 0.5 * (0.8 + random.random() * 0.4)
+
+    def _retry_after(self, resp: requests.Response) -> Optional[float]:
+        ra = resp.headers.get("retry-after")
+        if ra and ra.isdigit():
+            return float(ra)
+        reset = _int(resp.headers.get("X-RateLimit-Reset"))
+        if reset:
+            ms = (reset - time.time() * 1000) if reset > 1e12 else (reset - time.time())
+            if 0 < ms < 60:
+                return ms
+        return None
+
+    def _request(self, method: str, path: str, *, params: Optional[dict] = None,
+                 json: Optional[dict] = None) -> Any:
+        url = self.base_url + path
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+        attempt = 0
+        while True:
+            try:
+                resp = self.session.request(method, url, params=params, json=json,
+                                            timeout=self.timeout)
+            except requests.RequestException as e:
+                if attempt < self.max_retries:
+                    time.sleep(self._backoff(attempt)); attempt += 1; continue
+                raise SkinAPIError(0, "network_error", str(e), retryable=True)
+
+            self.rate_limit = {
+                "remaining_minute": _int(resp.headers.get("X-RateLimit-Remaining-Minute")),
+                "remaining_day": _int(resp.headers.get("X-RateLimit-Remaining-Day")),
+                "reset": _int(resp.headers.get("X-RateLimit-Reset")),
+            }
+
+            if (resp.status_code == 429 or resp.status_code >= 500) and attempt < self.max_retries:
+                time.sleep(self._retry_after(resp) or self._backoff(attempt))
+                attempt += 1
+                continue
+
+            try:
+                data = resp.json()
+            except ValueError:
+                data = {}
+            if not resp.ok:
+                err = (data or {}).get("error", {}) or {}
+                raise SkinAPIError(resp.status_code, err.get("code"), err.get("message"),
+                                   retryable=resp.status_code == 429 or resp.status_code >= 500)
+            return data.get("data", data)
+
+    def get(self, path: str, **params) -> Any:
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, body: dict) -> Any:
+        return self._request("POST", path, json=body)
+
+    # -- prices --
+    def item_price(self, name: str, *, game: str = "cs2", currency: str = "USD") -> Any:
+        return self.get("/items", name=name, game=game, currency=currency)
+
+    def item_meta(self, name: str) -> Any:
+        return self.get("/items/meta", name=name)
+
+    def search(self, q: str, *, limit: int = 20) -> Any:
+        return self.get("/items/search", q=q, limit=limit)
+
+    def catalog(self, *, game: str = "cs2", limit: Optional[int] = None,
+                offset: Optional[int] = None, q: Optional[str] = None,
+                type: Optional[str] = None, rarity: Optional[str] = None,
+                prices: Optional[bool] = None, sort: Optional[str] = None,
+                currency: str = "USD") -> Any:
+        return self.get("/catalog", game=game, limit=limit, offset=offset, q=q,
+                        type=type, rarity=rarity, prices=prices, sort=sort, currency=currency)
+
+    def history(self, name: str, *, game: str = "cs2", days: int = 30, currency: str = "USD") -> Any:
+        return self.get("/history", name=name, game=game, days=days, currency=currency)
+
+    # -- marketplaces --
+    def markets(self, name: str, *, game: str = "cs2", currency: str = "USD") -> Any:
+        return self.get("/markets", name=name, game=game, currency=currency)
+
+    def markets_batch(self, names: list[str], *, game: str = "cs2", currency: str = "USD") -> Any:
+        return self.post("/markets/batch", {"names": names, "game": game, "currency": currency})
+
+    def deals(self, *, game: str = "cs2", min_discount: Optional[int] = None, currency: str = "USD") -> Any:
+        return self.get("/deals", game=game, min_discount=min_discount, currency=currency)
+
+    # -- floats --
+    def float(self, inspect_url: str) -> Any:
+        return self.get("/float", url=inspect_url)
+
+    def float_leaderboard(self, name: str, *, order: str = "asc", limit: int = 10) -> Any:
+        return self.get("/float/leaderboard", name=name, order=order, limit=limit)
+
+    # -- steam --
+    def profile(self, id_or_vanity: str) -> Any:
+        return self.get("/profile", id=id_or_vanity)
+
+    def friendlist(self, steam_id: str) -> Any:
+        return self.get("/friendlist", steam_id=steam_id)
+
+    def inventory(self, steam_id: str, *, game: str = "cs2", prices: bool = True, currency: str = "USD") -> Any:
+        return self.get("/inventory", steam_id=steam_id, game=game, prices=prices, currency=currency)
+
+    def inventory_history(self, steam_id: str, *, game: str = "cs2", days: int = 30, currency: str = "USD") -> Any:
+        return self.get("/inventory/history", steam_id=steam_id, game=game, days=days, currency=currency)
+
+    def inventory_batch(self, steam_ids: list[str], *, game: str = "cs2") -> Any:
+        return self.post("/inventory/batch", {"steam_ids": steam_ids, "game": game})
+
+    # -- tools --
+    def tradeup(self, items: list[dict]) -> Any:
+        return self.post("/tradeup", {"items": items})
+
+    def status(self) -> Any:
+        return self.get("/status")

skinapi_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: skinapi-sdk
+Version: 0.1.0
+Summary: Python client for SkinAPI - CS2/Steam skin prices, float values, inventories and marketplace data.
+Project-URL: Homepage, https://skinapi.skinvaults.online
+Project-URL: Documentation, https://skinapi.skinvaults.online/docs
+Project-URL: Repository, https://github.com/soccervortex/skinapi-py
+Author: SkinVaults
+License: MIT
+License-File: LICENSE
+Keywords: api,cs2,csgo,float,inventory,marketplace,skin-prices,skinapi,skins,steam
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.20
+Description-Content-Type: text/markdown
+
+# skinapi (Python)
+
+Python client for [SkinAPI](https://skinapi.skinvaults.online) - real-time **CS2 / Dota 2 / Rust / TF2** skin prices, **float values**, Steam **inventories & profiles**, and multi-marketplace data through one REST API.
+
+- Real-time prices aggregated across marketplaces
+- CS2 float values, paint seed and wear
+- Steam inventories, profiles and price history
+- Automatic retries, timeouts and rate-limit tracking
+- Free tier - get a key in ~2 minutes
+
+## Install
+
+```bash
+pip install skinapi
+```
+
+## Get a key
+
+1. Sign in with Steam: https://skinapi.skinvaults.online/api/auth/steam
+2. Create a key in your [dashboard](https://skinapi.skinvaults.online/dashboard)
+
+## Usage
+
+```python
+from skinapi import SkinAPI
+
+api = SkinAPI("sk_live_your_key")
+
+# Aggregated price for one item
+price = api.item_price("AK-47 | Redline (Field-Tested)", game="cs2", currency="USD")
+
+# Compare across marketplaces
+markets = api.markets("AK-47 | Redline (Field-Tested)", game="cs2")
+
+# Float value, paint seed and wear from a Steam inspect link
+fl = api.float("STEAM_INSPECT_LINK")
+
+# Steam profile and bans
+profile = api.profile("STEAM_ID_OR_VANITY")
+
+# Priced Steam inventory
+inv = api.inventory("STEAM_ID", game="cs2", prices=True)
+
+# Many items at once
+batch = api.markets_batch(["AK-47 | Redline (Field-Tested)", "AWP | Asiimov (Field-Tested)"])
+
+# Remaining quota after any call
+print(api.rate_limit)  # {'remaining_minute': ..., 'remaining_day': ..., 'reset': ...}
+```
+
+Errors raise `SkinAPIError` with `.status` and `.code`:
+
+```python
+from skinapi import SkinAPIError
+
+try:
+    api.item_price("Nonexistent Item")
+except SkinAPIError as e:
+    print(e.status, e.code, e)
+```
+
+## Methods
+
+`item_price`, `item_meta`, `search`, `catalog`, `history`, `markets`, `markets_batch`,
+`deals`, `float`, `float_leaderboard`, `profile`, `friendlist`, `inventory`,
+`inventory_history`, `inventory_batch`, `tradeup`, `status`.
+
+Authentication uses the `x-api-key` header. Games: `cs2`, `dota2`, `rust`, `tf2`.
+
+## Links
+
+- Docs: https://skinapi.skinvaults.online/docs
+- OpenAPI spec: https://skinapi.skinvaults.online/api/v1/openapi.json
+- JavaScript client: https://www.npmjs.com/package/skinapi-js
+- Discord: https://discord.gg/CqVnGdGc4Q
+
+## License
+
+MIT

skinapi_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+skinapi/__init__.py,sha256=rJC__NWcYA5O756hDqGYfp_SkYGxm396srBdZiK4vKA,7166
+skinapi_sdk-0.1.0.dist-info/METADATA,sha256=R5IGzJDCbXqj16hpbY4PGvkWU7UQbAMyWxOgNRSl6qA,3102
+skinapi_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+skinapi_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=gZaEVahRmqEN8df_8eQ4AAf5AQCqhF_aqCNPX5OL4-w,1067
+skinapi_sdk-0.1.0.dist-info/RECORD,,

skinapi_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

skinapi_sdk-0.1.0.dist-info/licenses/LICENSE

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