initial client for the Pkmn Prices API

Sync and async clients over httpx covering sets, cards, sealed, and
health. Typed dataclass responses, typed errors per status code, and
auto-paginating iterators for page and cursor endpoints. Retries rate
limits and transient failures with backoff, but not credit limits.

Python 3.10+, deps are just httpx.

Author: preaverage

.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: mypy src/pkmnprices
+      - run: pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

LICENSE

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

README.md

@@ -0,0 +1,109 @@
+# pkmnprices
+
+Python client for the [Pkmn Prices API](https://pkmnprices.com). Pokemon TCG card pricing from TCGPlayer, Cardmarket, and eBay.
+
+Sync and async clients, both built on httpx. Typed responses, typed errors, and iterators that page through results for you. Python 3.10+.
+
+## Install
+
+```bash
+pip install pkmnprices
+```
+
+## Usage
+
+```python
+from pkmnprices import PkmnPrices
+
+client = PkmnPrices("pk_your_key_here")
+
+page = client.cards.list(name="charizard", per_page=10)
+
+card = client.cards.get(page.data[0].id)
+for price in card.prices:
+    symbol = "€" if price.currency == "EUR" else "$"
+    print(f"{price.source}: {symbol}{price.market_price}")
+
+client.close()
+```
+
+The client is also a context manager:
+
+```python
+with PkmnPrices("pk_...") as client:
+    health = client.health()
+```
+
+### Async
+
+```python
+import asyncio
+from pkmnprices import AsyncPkmnPrices
+
+async def main():
+    async with AsyncPkmnPrices("pk_...") as client:
+        page = await client.cards.list(name="charizard")
+        async for card in client.cards.iterate(name="charizard"):
+            print(card.name)
+
+asyncio.run(main())
+```
+
+Get an API key from <https://pkmnprices.com/dashboard>.
+
+## Options
+
+```python
+PkmnPrices(
+    "pk_...",         # API key, sent as the x-api-key header
+    max_retries=2,    # retries on 429 rate limits and 5xx/network errors
+    timeout=30.0,     # per-request timeout in seconds
+)
+```
+
+Rate-limit `429`s are retried with backoff. Credit-limit `429`s (`credit_limit_exceeded`) are not, since they don't reset until the next day.
+
+## Pagination
+
+List endpoints return a `Page` (`.data`, `.pagination`). Listing endpoints (eBay/Cardmarket) return a `CursorPage`. Both resources expose iterators so you don't track pages or cursors:
+
+```python
+for card in client.cards.iterate(name="charizard"):
+    print(card.name)
+
+all_sets = client.sets.list_all(language="english")
+
+for sale in client.cards.listings.iterate_ebay(789, grader="PSA", grade="10"):
+    print(sale.title, sale.price)
+```
+
+## Currency
+
+Every price has a `currency` field. Pass `currency="usd"` or `currency="eur"` to filter, or leave it off to get everything your plan allows. EUR (Cardmarket) prices need a Pro plan; a free key asking for `eur` raises `ForbiddenError`.
+
+```python
+card = client.cards.get(789, currency="usd")
+```
+
+## Errors
+
+Everything raised subclasses `PkmnPricesError`, which carries `status`, `code`, `rate_limit`, and `retry_after`.
+
+```python
+from pkmnprices import ForbiddenError, NotFoundError, RateLimitError
+
+try:
+    client.cards.get(789, currency="eur")
+except ForbiddenError:
+    ...  # needs a higher plan
+except NotFoundError:
+    ...  # no such card
+except RateLimitError:
+    ...  # ran out of retries
+```
+
+Subclasses: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `CreditLimitError` and `RateLimitError` (429), `InternalServerError` (5xx), `APIConnectionError` (network/timeout).
+
+## License
+
+MIT

pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pkmnprices"
+version = "1.0.0"
+description = "Python client for the Pkmn Prices API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Pkmn Prices" }]
+keywords = ["pokemon", "tcg", "pricing", "tcgplayer", "cardmarket", "ebay", "sdk", "api-client"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://pkmnprices.com"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "mypy>=1.10", "ruff>=0.5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pkmnprices"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

src/pkmnprices/__init__.py

@@ -0,0 +1,66 @@
+from .client import AsyncPkmnPrices, PkmnPrices
+from .errors import (
+    APIConnectionError,
+    BadRequestError,
+    ConflictError,
+    CreditLimitError,
+    ForbiddenError,
+    InternalServerError,
+    NotFoundError,
+    PkmnPricesError,
+    RateLimitError,
+    RateLimitInfo,
+    UnauthorizedError,
+)
+from .models import (
+    Card,
+    CardmarketListing,
+    CardSummary,
+    CursorInfo,
+    CursorPage,
+    EbayListing,
+    Health,
+    Page,
+    PageInfo,
+    Price,
+    PriceHistoryPoint,
+    Sealed,
+    SealedEbayListing,
+    SealedSummary,
+    Set,
+    SetRef,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "PkmnPrices",
+    "AsyncPkmnPrices",
+    "PkmnPricesError",
+    "BadRequestError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "CreditLimitError",
+    "RateLimitError",
+    "InternalServerError",
+    "APIConnectionError",
+    "RateLimitInfo",
+    "Card",
+    "CardSummary",
+    "CardmarketListing",
+    "CursorInfo",
+    "CursorPage",
+    "EbayListing",
+    "Health",
+    "Page",
+    "PageInfo",
+    "Price",
+    "PriceHistoryPoint",
+    "Sealed",
+    "SealedEbayListing",
+    "SealedSummary",
+    "Set",
+    "SetRef",
+]

src/pkmnprices/_endpoints.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .models import CursorInfo, CursorPage, Model, Page, PageInfo
+
+
+@dataclass
+class Request:
+    method: str
+    path: str
+    query: dict[str, Any] = field(default_factory=dict)
+    auth: bool = True
+
+
+def _clean(query: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in query.items() if value is not None}
+
+
+def health() -> Request:
+    return Request("GET", "/health", auth=False)
+
+
+def sets_list(**query: Any) -> Request:
+    return Request("GET", "/v1/sets", _clean(query))
+
+
+def sets_get(set_id: int) -> Request:
+    return Request("GET", f"/v1/sets/{set_id}")
+
+
+def cards_list(**query: Any) -> Request:
+    return Request("GET", "/v1/cards", _clean(query))
+
+
+def cards_get(card_id: int, **query: Any) -> Request:
+    return Request("GET", f"/v1/cards/{card_id}", _clean(query))
+
+
+def cards_history(card_id: int, **query: Any) -> Request:
+    return Request("GET", f"/v1/cards/{card_id}/prices/history", _clean(query))
+
+
+def cards_listings_ebay(card_id: int, **query: Any) -> Request:
+    return Request("GET", f"/v1/cards/{card_id}/listings/ebay", _clean(query))
+
+
+def cards_listings_cardmarket(card_id: int, **query: Any) -> Request:
+    return Request("GET", f"/v1/cards/{card_id}/listings/cardmarket", _clean(query))
+
+
+def sealed_list(**query: Any) -> Request:
+    return Request("GET", "/v1/sealed", _clean(query))
+
+
+def sealed_get(sealed_id: int) -> Request:
+    return Request("GET", f"/v1/sealed/{sealed_id}")
+
+
+def sealed_history(sealed_id: int, **query: Any) -> Request:
+    return Request("GET", f"/v1/sealed/{sealed_id}/prices/history", _clean(query))
+
+
+def sealed_listings(sealed_id: int, **query: Any) -> Request:
+    return Request("GET", f"/v1/sealed/{sealed_id}/listings", _clean(query))
+
+
+def build_page(raw: dict[str, Any], model: type[Model]) -> Page[Any]:
+    items = [model.from_dict(item) for item in raw["data"]]
+    return Page(items, PageInfo.from_dict(raw["pagination"]))
+
+
+def build_cursor_page(raw: dict[str, Any], model: type[Model]) -> CursorPage[Any]:
+    items = [model.from_dict(item) for item in raw["data"]]
+    return CursorPage(items, CursorInfo.from_dict(raw["pagination"]))