portals-api 0.1.0__tar.gz

portals_api-0.1.0/LICENSE

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

portals_api-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: portals-api
+Version: 0.1.0
+Summary: A typed Python client for the Portals Partners API
+Author: Portals API client contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/NicolasKingreen/portals-python
+Project-URL: Source, https://github.com/NicolasKingreen/portals-python
+Project-URL: Issues, https://github.com/NicolasKingreen/portals-python/issues
+Project-URL: Changelog, https://github.com/NicolasKingreen/portals-python/blob/main/CHANGELOG.md
+Project-URL: API documentation, https://docs.portals.tg/developers/api/
+Keywords: portals,telegram,ton,nft,api,asyncio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx2<3,>=2.16
+Requires-Dist: pydantic<3,>=2.8
+Dynamic: license-file
+
+# Portals API Python client
+
+A typed synchronous and asynchronous Python client for the [Portals Partners API](https://docs.portals.tg/developers/api/), the partner-facing programmatic API of the Portals marketplace.
+
+## Features
+
+- All 35 operations from the Portals Partners OpenAPI contract
+- Matching `PortalsClient` and `AsyncPortalsClient` APIs
+- Typed Pydantic v2 models for every schema in the contract (strict requests, forward-compatible responses)
+- httpx2 connection pooling and injectable HTTP clients
+- Exact `Decimal` amounts and parsed `datetime` timestamps
+- Typed API errors and rate-limit metadata
+- Python 3.11+ and a `py.typed` marker
+
+## Installation
+
+```bash
+pip install portals-api
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add portals-api
+```
+
+From a local checkout:
+
+```bash
+pip install .
+```
+
+The distribution is named `portals-api`; the import package is `portals`.
+
+## Quickstart
+
+### Synchronous
+
+```python
+from portals import PortalsClient
+
+with PortalsClient("your-api-key") as client:
+    config = client.market.config()
+    wallet = client.wallet.get()
+    results = client.nfts.search(max_price="20", limit=20)
+
+    print(config.deposit_wallet)
+    print(wallet.balance)
+    print(results.total_count)
+```
+
+### Asynchronous
+
+```python
+import asyncio
+
+from portals import AsyncPortalsClient
+
+
+async def main() -> None:
+    async with AsyncPortalsClient("your-api-key") as client:
+        wallet = await client.wallet.get()
+        state = await client.arena.state()
+
+        print(wallet.balance)
+        print(state.server_time)
+
+
+asyncio.run(main())
+```
+
+Get an API key from the Portals mini app under **Profile → Partner API**. Keep the key on your server and never commit it to source control.
+
+## Resources
+
+| Resource | Operations |
+| --- | --- |
+| `client.arena` | Arena state, inventory, and bets |
+| `client.offers` | Create, update, cancel, inspect, and accept collection offers |
+| `client.collections` | Collection previews, metrics, and attribute floor prices |
+| `client.market` | Market configuration and activity |
+| `client.nfts` | Search, owned NFTs, purchases, listings, transfers, and withdrawals |
+| `client.users` | User existence and authenticated user activity |
+| `client.wallet` | Balance, deposits, TON withdrawals, and withdrawal statuses |
+
+Methods return typed models. For example:
+
+```python
+from decimal import Decimal
+
+from portals import BuyDetail, PortalsClient
+
+with PortalsClient("your-api-key") as client:
+    purchase = client.nfts.buy(
+        [
+            BuyDetail(id="nft-id", price=Decimal("12.50")),
+        ]
+    )
+
+    print(purchase.total_purchased)
+    print(purchase.total_failed)
+    print(purchase.total_spent)
+```
+
+Purchases may partially succeed. Inspect each item in `purchase.purchase_results` rather than assuming the whole request succeeded or failed.
+
+## Amounts and timestamps
+
+Pass amounts as decimal strings or `Decimal` instances. Floats are rejected to avoid binary floating-point errors. Amounts are serialized as strings on the wire and exposed as `Decimal` values by response models.
+
+RFC 3339 timestamps are exposed as `datetime` instances. Arena timestamps remain integers because the API returns Unix milliseconds.
+
+## Errors
+
+```python
+from portals import APIError, PortalsClient, RateLimitError
+
+with PortalsClient("your-api-key") as client:
+    try:
+        client.market.actions()
+    except RateLimitError as exc:
+        if exc.rate_limit is not None:
+            print(exc.rate_limit.reset_seconds)
+    except APIError as exc:
+        print(exc.status_code, exc.code, exc.message)
+```
+
+Specific exceptions cover authentication, access denial, rate limits, an unavailable market feed, and unknown Arena bet outcomes. Transport failures, invalid JSON, and response-validation failures have separate exception types.
+
+Write operations are not automatically retried. In particular, an Arena bet that returns `504 BET_OUTCOME_UNKNOWN` or fails during network transmission may already have been placed; check `client.arena.state()` before trying again.
+
+## Custom HTTP clients
+
+Pass an `httpx2.Client` or `httpx2.AsyncClient` to customize transports, proxies, or test behavior. The library closes only clients it creates itself.
+
+```python
+import httpx2
+
+from portals import PortalsClient
+
+http_client = httpx2.Client(timeout=10)
+client = PortalsClient("your-api-key", client=http_client)
+
+client.close()
+http_client.close()
+```
+
+## Low-level requests
+
+Use `request()` for new endpoints that do not yet have a typed method:
+
+```python
+payload = client.request("GET", "/partners/example", params={"limit": 10})
+```
+
+Pass `response_model=YourModel` to validate the response with Pydantic.
+
+## Development
+
+Install the project and development tools with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync
+```
+
+Run the checks used by CI:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv build
+```
+
+The OpenAPI contract is vendored at `specs/partners.en.json`. Refresh it and regenerate the
+models, then review the resulting changes:
+
+```bash
+uv run python scripts/update_spec.py
+uv run python scripts/generate_models.py
+uv run ruff check --fix src/portals/models.py
+uv run ruff format src/portals/models.py
+```
+
+## License
+
+MIT

portals_api-0.1.0/README.md

@@ -0,0 +1,188 @@
+# Portals API Python client
+
+A typed synchronous and asynchronous Python client for the [Portals Partners API](https://docs.portals.tg/developers/api/), the partner-facing programmatic API of the Portals marketplace.
+
+## Features
+
+- All 35 operations from the Portals Partners OpenAPI contract
+- Matching `PortalsClient` and `AsyncPortalsClient` APIs
+- Typed Pydantic v2 models for every schema in the contract (strict requests, forward-compatible responses)
+- httpx2 connection pooling and injectable HTTP clients
+- Exact `Decimal` amounts and parsed `datetime` timestamps
+- Typed API errors and rate-limit metadata
+- Python 3.11+ and a `py.typed` marker
+
+## Installation
+
+```bash
+pip install portals-api
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add portals-api
+```
+
+From a local checkout:
+
+```bash
+pip install .
+```
+
+The distribution is named `portals-api`; the import package is `portals`.
+
+## Quickstart
+
+### Synchronous
+
+```python
+from portals import PortalsClient
+
+with PortalsClient("your-api-key") as client:
+    config = client.market.config()
+    wallet = client.wallet.get()
+    results = client.nfts.search(max_price="20", limit=20)
+
+    print(config.deposit_wallet)
+    print(wallet.balance)
+    print(results.total_count)
+```
+
+### Asynchronous
+
+```python
+import asyncio
+
+from portals import AsyncPortalsClient
+
+
+async def main() -> None:
+    async with AsyncPortalsClient("your-api-key") as client:
+        wallet = await client.wallet.get()
+        state = await client.arena.state()
+
+        print(wallet.balance)
+        print(state.server_time)
+
+
+asyncio.run(main())
+```
+
+Get an API key from the Portals mini app under **Profile → Partner API**. Keep the key on your server and never commit it to source control.
+
+## Resources
+
+| Resource | Operations |
+| --- | --- |
+| `client.arena` | Arena state, inventory, and bets |
+| `client.offers` | Create, update, cancel, inspect, and accept collection offers |
+| `client.collections` | Collection previews, metrics, and attribute floor prices |
+| `client.market` | Market configuration and activity |
+| `client.nfts` | Search, owned NFTs, purchases, listings, transfers, and withdrawals |
+| `client.users` | User existence and authenticated user activity |
+| `client.wallet` | Balance, deposits, TON withdrawals, and withdrawal statuses |
+
+Methods return typed models. For example:
+
+```python
+from decimal import Decimal
+
+from portals import BuyDetail, PortalsClient
+
+with PortalsClient("your-api-key") as client:
+    purchase = client.nfts.buy(
+        [
+            BuyDetail(id="nft-id", price=Decimal("12.50")),
+        ]
+    )
+
+    print(purchase.total_purchased)
+    print(purchase.total_failed)
+    print(purchase.total_spent)
+```
+
+Purchases may partially succeed. Inspect each item in `purchase.purchase_results` rather than assuming the whole request succeeded or failed.
+
+## Amounts and timestamps
+
+Pass amounts as decimal strings or `Decimal` instances. Floats are rejected to avoid binary floating-point errors. Amounts are serialized as strings on the wire and exposed as `Decimal` values by response models.
+
+RFC 3339 timestamps are exposed as `datetime` instances. Arena timestamps remain integers because the API returns Unix milliseconds.
+
+## Errors
+
+```python
+from portals import APIError, PortalsClient, RateLimitError
+
+with PortalsClient("your-api-key") as client:
+    try:
+        client.market.actions()
+    except RateLimitError as exc:
+        if exc.rate_limit is not None:
+            print(exc.rate_limit.reset_seconds)
+    except APIError as exc:
+        print(exc.status_code, exc.code, exc.message)
+```
+
+Specific exceptions cover authentication, access denial, rate limits, an unavailable market feed, and unknown Arena bet outcomes. Transport failures, invalid JSON, and response-validation failures have separate exception types.
+
+Write operations are not automatically retried. In particular, an Arena bet that returns `504 BET_OUTCOME_UNKNOWN` or fails during network transmission may already have been placed; check `client.arena.state()` before trying again.
+
+## Custom HTTP clients
+
+Pass an `httpx2.Client` or `httpx2.AsyncClient` to customize transports, proxies, or test behavior. The library closes only clients it creates itself.
+
+```python
+import httpx2
+
+from portals import PortalsClient
+
+http_client = httpx2.Client(timeout=10)
+client = PortalsClient("your-api-key", client=http_client)
+
+client.close()
+http_client.close()
+```
+
+## Low-level requests
+
+Use `request()` for new endpoints that do not yet have a typed method:
+
+```python
+payload = client.request("GET", "/partners/example", params={"limit": 10})
+```
+
+Pass `response_model=YourModel` to validate the response with Pydantic.
+
+## Development
+
+Install the project and development tools with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync
+```
+
+Run the checks used by CI:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv build
+```
+
+The OpenAPI contract is vendored at `specs/partners.en.json`. Refresh it and regenerate the
+models, then review the resulting changes:
+
+```bash
+uv run python scripts/update_spec.py
+uv run python scripts/generate_models.py
+uv run ruff check --fix src/portals/models.py
+uv run ruff format src/portals/models.py
+```
+
+## License
+
+MIT

portals_api-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "portals-api"
+version = "0.1.0"
+description = "A typed Python client for the Portals Partners API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Portals API client contributors" }]
+keywords = ["portals", "telegram", "ton", "nft", "api", "asyncio"]
+dependencies = [
+    "httpx2>=2.16,<3",
+    "pydantic>=2.8,<3",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/NicolasKingreen/portals-python"
+Source = "https://github.com/NicolasKingreen/portals-python"
+Issues = "https://github.com/NicolasKingreen/portals-python/issues"
+Changelog = "https://github.com/NicolasKingreen/portals-python/blob/main/CHANGELOG.md"
+"API documentation" = "https://docs.portals.tg/developers/api/"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.8",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "ruff>=0.8",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+portals = ["py.typed"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "RUF"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/portals/models.py" = ["RUF022"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+plugins = ["pydantic.mypy"]
+files = ["src/portals", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = "-ra --strict-markers"

portals_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

portals_api-0.1.0/src/portals/__init__.py

@@ -0,0 +1,40 @@
+"""Typed synchronous and asynchronous Python client for the Portals Partners API."""
+
+from . import models as _models
+from ._contract import __api_version__
+from ._models import Amount, RateLimit
+from ._version import __version__
+from .client import AsyncPortalsClient, PortalsClient
+from .exceptions import (
+    AccessDeniedError,
+    APIError,
+    AuthenticationError,
+    BetOutcomeUnknownError,
+    InvalidResponseError,
+    MarketFeedUnavailableError,
+    PortalsError,
+    RateLimitError,
+    ResponseValidationError,
+    TransportError,
+)
+from .models import *  # noqa: F403
+
+__all__ = [
+    "AccessDeniedError",
+    "APIError",
+    "Amount",
+    "AsyncPortalsClient",
+    "AuthenticationError",
+    "BetOutcomeUnknownError",
+    "InvalidResponseError",
+    "MarketFeedUnavailableError",
+    "PortalsClient",
+    "PortalsError",
+    "RateLimit",
+    "RateLimitError",
+    "ResponseValidationError",
+    "TransportError",
+    "__api_version__",
+    "__version__",
+    *_models.__all__,
+]

portals_api-0.1.0/src/portals/_contract.py

@@ -0,0 +1,2 @@
+# Generated by scripts/generate_models.py from specs/partners.en.json.
+__api_version__ = "1.0.0"

portals_api-0.1.0/src/portals/_models.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation
+from typing import Annotated, Any
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, PlainSerializer
+
+
+def _amount(value: Any) -> Decimal:
+    if not isinstance(value, (str, Decimal)):
+        raise ValueError("Amounts must be decimal strings or Decimal instances")
+    try:
+        result = Decimal(value)
+    except InvalidOperation as exc:
+        raise ValueError(f"Invalid decimal amount: {value!r}") from exc
+    if not result.is_finite():
+        raise ValueError("Amounts must be finite")
+    return result
+
+
+def _serialize_amount(value: Decimal) -> str:
+    return format(value, "f")
+
+
+Amount = Annotated[
+    Decimal,
+    BeforeValidator(_amount),
+    PlainSerializer(_serialize_amount, return_type=str),
+]
+
+
+class PortalsModel(BaseModel):
+    """Common Pydantic base model for Portals API schemas."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class PortalsRequest(PortalsModel):
+    """Base model for API request payloads (`extra="forbid"`)."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+class PortalsResponse(PortalsModel):
+    """Base model for API response payloads (`extra="allow"`)."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+@dataclass(frozen=True, slots=True)
+class RateLimit:
+    """Rate-limit state parsed from `X-RateLimit-*` response headers."""
+
+    limit: int
+    remaining: int
+    reset_seconds: int
+
+    @classmethod
+    def from_headers(cls, headers: Mapping[str, str]) -> RateLimit | None:
+        """Parse rate-limit headers from an HTTP response, or return `None` if absent."""
+        normalized = {key.lower(): value for key, value in headers.items()}
+        try:
+            return cls(
+                limit=int(normalized["x-ratelimit-limit"]),
+                remaining=int(normalized["x-ratelimit-remaining"]),
+                reset_seconds=int(normalized["x-ratelimit-reset"]),
+            )
+        except (KeyError, TypeError, ValueError):
+            return None