phemex-py 0.1.0__tar.gz

phemex_py-0.1.0/.claude/settings.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(just:*)",
+      "Bash(pytest:*)",
+      "Bash(PYTHONPATH=src pytest:*)",
+      "Bash(python:*)",
+      "Bash(PYTHONPATH=src python -m pytest:*)",
+      "Bash(PYTHONPATH=src python:*)",
+      "Bash(find:*)",
+      "Bash(PYTHONPATH=src python3:*)",
+      "Bash(test:*)",
+      "Bash(source .venv/bin/activate)",
+      "Bash(PYTHONPATH=src .venv/bin/python -m pytest:*)",
+      "Bash(PYTHONPATH=src .venv/bin/python:*)"
+    ]
+  }
+}

phemex_py-0.1.0/.env.example

@@ -0,0 +1,3 @@
+PHEMEX_URL=https://testnet-api.phemex.com
+PHEMEX_KEY=
+PHEMEX_SECRET=

phemex_py-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# IDE files
+.idea/
+
+# Environment variables
+.env
+*.env

phemex_py-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

phemex_py-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.0 (2026-02-22)
+
+Initial release.
+
+### Features
+
+- Sync and async clients for the Phemex API (`PhemexClient`, `AsyncPhemexClient`)
+- HMAC-SHA256 request signing with configurable expiry
+- USD-M Perpetual REST API coverage:
+  - Market data: product information, order book, klines, trades, tickers
+  - Orders: place, amend, cancel, bulk cancel, cancel all
+  - Positions: query, query with PnL, switch mode, set leverage, assign balance
+  - Account: risk units
+  - History: open/closed orders, closed positions, user trades, order history, trade history
+  - Funding: fee history, funding rates
+- Fully typed request/response models via Pydantic v2
+- Structured error handling with `PhemexError`
+- PEP 561 typed package support (`py.typed`)

phemex_py-0.1.0/JUSTFILE

@@ -0,0 +1,27 @@
+# Default recipe - list all available recipes
+list:
+    @just --list
+
+# Run all tests with coverage reporting
+test:
+    PYTHONPATH=src pytest -v --cov
+
+# Run unit tests (excluding integration tests) with verbose output and fail-fast
+test-unit:
+    pytest -m "not integration" -v --ff
+
+# Run integration tests with verbose output and fail-fast
+test-integration:
+    pytest -m "integration" -v --ff
+
+# Run all tests in debug mode, stopping after the first failure and showing the full traceback
+test-debug:
+    pytest -x --ff -v -m "not integration" && pytest -x --ff -v -m "integration"
+
+# Run only the tests that failed in the previous test run, with verbose output and fail-fast
+test-failed:
+    pytest --lf -x -v
+
+# Analyze the codebase using cloc, excluding certain directories
+cloc:
+    @cloc . --vcs=git --exclude-dir=products,tests

phemex_py-0.1.0/LICENSE.txt

@@ -0,0 +1,14 @@
+Copyright 2026 Connor Stone
+
+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.

phemex_py-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: phemex-py
+Version: 0.1.0
+Summary: Typed, production-grade Python SDK for the Phemex crypto exchange API
+Project-URL: Homepage, https://github.com/cstone/phemex-py
+Project-URL: Repository, https://github.com/cstone/phemex-py
+Project-URL: Issues, https://github.com/cstone/phemex-py/issues
+Project-URL: Changelog, https://github.com/cstone/phemex-py/blob/main/CHANGELOG.md
+Author: Connor Stone
+License: MIT
+License-File: LICENSE.txt
+Keywords: api,crypto,exchange,futures,phemex,sdk,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Description-Content-Type: text/markdown
+
+# phemex-py
+
+[![PyPI version](https://img.shields.io/pypi/v/phemex-py)](https://pypi.org/project/phemex-py/)
+[![Python](https://img.shields.io/pypi/pyversions/phemex-py)](https://pypi.org/project/phemex-py/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Typed, production-grade Python SDK for the [Phemex](https://phemex.com) crypto exchange API.
+
+- Sync and async clients (built on [httpx](https://www.python-httpx.org/))
+- Fully typed request/response models (built on [Pydantic](https://docs.pydantic.dev/))
+- USD-M perpetual futures: orders, positions, market data, funding rates, and more
+
+## Installation
+
+```bash
+pip install phemex-py
+```
+
+## Quick Start
+
+### Authentication
+
+You need a Phemex API key and secret. Create one from your [Phemex account settings](https://phemex.com/account/apiKeys).
+
+Set them as environment variables or pass them directly:
+
+```bash
+export PHEMEX_API_KEY="your-api-key"
+export PHEMEX_API_SECRET="your-api-secret"
+```
+
+### Sync Client
+
+```python
+from phemex_py import PhemexClient
+
+with PhemexClient(
+    base_url="https://api.phemex.com",
+    api_key="your-api-key",
+    api_secret="your-api-secret",
+) as client:
+    # Get server time
+    server_time = client.server_time()
+
+    # Get product info
+    products = client.usdm_rest.product_information()
+
+    # Get ticker
+    ticker = client.usdm_rest.ticker(symbol="BTCUSDT")
+
+    # Get open orders
+    orders = client.usdm_rest.open_orders(symbol="BTCUSDT")
+
+    # Get account positions
+    positions = client.usdm_rest.positions()
+```
+
+### Async Client
+
+```python
+import asyncio
+from phemex_py import AsyncPhemexClient
+
+async def main():
+    async with AsyncPhemexClient(
+        base_url="https://api.phemex.com",
+        api_key="your-api-key",
+        api_secret="your-api-secret",
+    ) as client:
+        ticker = await client.usdm_rest.ticker(symbol="BTCUSDT")
+        positions = await client.usdm_rest.positions()
+
+asyncio.run(main())
+```
+
+### Testnet
+
+Use the testnet base URL for paper trading:
+
+```python
+client = PhemexClient(
+    base_url="https://testnet-api.phemex.com",
+    api_key="your-testnet-key",
+    api_secret="your-testnet-secret",
+)
+```
+
+## API Coverage
+
+### USD-M Perpetual REST API
+
+| Category | Endpoints |
+|----------|-----------|
+| Market Data | `product_information`, `order_book`, `klines`, `trades`, `ticker`, `tickers` |
+| Orders | `place_order`, `amend_order`, `cancel_order`, `bulk_cancel`, `cancel_all` |
+| Positions | `positions`, `positions_with_pnl`, `switch_position_mode`, `set_leverage`, `assign_position_balance` |
+| Account | `risk_units` |
+| History | `open_orders`, `closed_orders`, `closed_positions`, `user_trades`, `order_history`, `lookup_order`, `trade_history` |
+| Funding | `funding_fee_history`, `funding_rates` |
+
+## Links
+
+- [Phemex API Documentation](https://phemex-docs.github.io/)
+- [GitHub Repository](https://github.com/cstone/phemex-py)
+- [PyPI Package](https://pypi.org/project/phemex-py/)
+
+## License
+
+[MIT](LICENSE.txt)

phemex_py-0.1.0/README.md

@@ -0,0 +1,109 @@
+# phemex-py
+
+[![PyPI version](https://img.shields.io/pypi/v/phemex-py)](https://pypi.org/project/phemex-py/)
+[![Python](https://img.shields.io/pypi/pyversions/phemex-py)](https://pypi.org/project/phemex-py/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Typed, production-grade Python SDK for the [Phemex](https://phemex.com) crypto exchange API.
+
+- Sync and async clients (built on [httpx](https://www.python-httpx.org/))
+- Fully typed request/response models (built on [Pydantic](https://docs.pydantic.dev/))
+- USD-M perpetual futures: orders, positions, market data, funding rates, and more
+
+## Installation
+
+```bash
+pip install phemex-py
+```
+
+## Quick Start
+
+### Authentication
+
+You need a Phemex API key and secret. Create one from your [Phemex account settings](https://phemex.com/account/apiKeys).
+
+Set them as environment variables or pass them directly:
+
+```bash
+export PHEMEX_API_KEY="your-api-key"
+export PHEMEX_API_SECRET="your-api-secret"
+```
+
+### Sync Client
+
+```python
+from phemex_py import PhemexClient
+
+with PhemexClient(
+    base_url="https://api.phemex.com",
+    api_key="your-api-key",
+    api_secret="your-api-secret",
+) as client:
+    # Get server time
+    server_time = client.server_time()
+
+    # Get product info
+    products = client.usdm_rest.product_information()
+
+    # Get ticker
+    ticker = client.usdm_rest.ticker(symbol="BTCUSDT")
+
+    # Get open orders
+    orders = client.usdm_rest.open_orders(symbol="BTCUSDT")
+
+    # Get account positions
+    positions = client.usdm_rest.positions()
+```
+
+### Async Client
+
+```python
+import asyncio
+from phemex_py import AsyncPhemexClient
+
+async def main():
+    async with AsyncPhemexClient(
+        base_url="https://api.phemex.com",
+        api_key="your-api-key",
+        api_secret="your-api-secret",
+    ) as client:
+        ticker = await client.usdm_rest.ticker(symbol="BTCUSDT")
+        positions = await client.usdm_rest.positions()
+
+asyncio.run(main())
+```
+
+### Testnet
+
+Use the testnet base URL for paper trading:
+
+```python
+client = PhemexClient(
+    base_url="https://testnet-api.phemex.com",
+    api_key="your-testnet-key",
+    api_secret="your-testnet-secret",
+)
+```
+
+## API Coverage
+
+### USD-M Perpetual REST API
+
+| Category | Endpoints |
+|----------|-----------|
+| Market Data | `product_information`, `order_book`, `klines`, `trades`, `ticker`, `tickers` |
+| Orders | `place_order`, `amend_order`, `cancel_order`, `bulk_cancel`, `cancel_all` |
+| Positions | `positions`, `positions_with_pnl`, `switch_position_mode`, `set_leverage`, `assign_position_balance` |
+| Account | `risk_units` |
+| History | `open_orders`, `closed_orders`, `closed_positions`, `user_trades`, `order_history`, `lookup_order`, `trade_history` |
+| Funding | `funding_fee_history`, `funding_rates` |
+
+## Links
+
+- [Phemex API Documentation](https://phemex-docs.github.io/)
+- [GitHub Repository](https://github.com/cstone/phemex-py)
+- [PyPI Package](https://pypi.org/project/phemex-py/)
+
+## License
+
+[MIT](LICENSE.txt)

phemex_py-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "phemex-py"
+version = "0.1.0"
+description = "Typed, production-grade Python SDK for the Phemex crypto exchange API"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Connor Stone" }
+]
+requires-python = ">=3.12"
+keywords = ["phemex", "crypto", "exchange", "api", "sdk", "trading", "futures"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.12.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/cstone/phemex-py"
+Repository = "https://github.com/cstone/phemex-py"
+Issues = "https://github.com/cstone/phemex-py/issues"
+Changelog = "https://github.com/cstone/phemex-py/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/phemex_py"]
+
+[tool.uv]
+package = true
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = []
+markers = ["integration: marks tests as hitting external APIs (run with -m integration)"]
+asyncio_mode = "strict"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=7.0.0",
+    "python-dotenv>=1.2.1",
+]

phemex_py-0.1.0/src/phemex_py/__init__.py

@@ -0,0 +1,10 @@
+import logging
+
+from .client import PhemexClient, AsyncPhemexClient
+from .exceptions import PhemexError
+
+logging.getLogger("phemex_py").addHandler(logging.NullHandler())
+logging.getLogger("phemex_py").setLevel(logging.WARNING)
+
+__version__ = "0.1.0"
+__all__ = ["PhemexClient", "AsyncPhemexClient", "PhemexError"]

phemex_py-0.1.0/src/phemex_py/client.py

@@ -0,0 +1,196 @@
+import hmac
+import hashlib
+import logging
+import time
+
+import httpx
+
+from .core.requests import Request, Extractor
+from .exceptions import PhemexError
+
+from .usdm_rest import USDMRest, AsyncUSDMRest
+
+logger = logging.getLogger(__name__)
+
+_SENSITIVE_HEADERS = {"x-phemex-access-token", "x-phemex-request-signature"}
+_EXPIRY = 60  # default expiry time in seconds for request signatures
+
+
+class BasePhemexClient:
+    """
+    Shared state and request preparation for sync and async Phemex clients.
+    """
+
+    def __init__(self, base_url: str, api_key: str, api_secret: str, expiry: int = _EXPIRY):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.api_secret = api_secret.encode()
+        self.expiry = expiry
+
+    def _prepare(self, req: Request) -> tuple[str, dict, bytes | None]:
+        """
+        Build the URL, signed headers, and encoded body for a request.
+
+        :return: (url, headers, content)
+        """
+        query = req.build_query_string()
+        body_json = req.build_body_json()
+
+        expires = int(time.time()) + self.expiry
+        parts = [req.path]
+        if query:
+            parts.append(query)
+        parts.append(str(expires))
+        if body_json:
+            parts.append(body_json)
+
+        payload = "".join(parts)
+        signature = hmac.new(
+            self.api_secret,
+            payload.encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+
+        headers = {
+            "x-phemex-access-token": self.api_key,
+            "x-phemex-request-expiry": str(expires),
+            "x-phemex-request-signature": signature,
+        }
+
+        url = f"{self.base_url}{req.path}"
+        if query:
+            url = f"{url}?{query}"
+
+        if body_json:
+            headers["Content-Type"] = "application/json"
+
+        safe_headers = {k: v for k, v in headers.items() if k not in _SENSITIVE_HEADERS}
+        logger.debug("REQUEST")
+        logger.debug(f"Request: {req.method} {url}")
+        logger.debug(f"Headers: {safe_headers}")
+        logger.debug(f"Body: {body_json or None}")
+
+        content = body_json.encode("utf-8") if body_json else None
+        return url, headers, content
+
+    @staticmethod
+    def _handle_response(resp: httpx.Response, req: Request, url: str, body_json: str | None):
+        """
+        Raise PhemexError on HTTP errors and return parsed JSON on success.
+        """
+        logger.debug("RESPONSE")
+        logger.debug(f"Status Code: {resp.status_code}")
+        logger.debug(f"Response Text: {resp.text}")
+
+        try:
+            resp.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            raise PhemexError(
+                message="Phemex API request failed",
+                cause=e,
+                context={
+                    "request": {
+                        "method": req.method,
+                        "url": url,
+                        "body": body_json or None,
+                    },
+                    "response": {
+                        "status_code": resp.status_code,
+                        "text": resp.text,
+                    },
+                }
+            )
+
+        return resp.json()
+
+
+class PhemexClient(BasePhemexClient):
+    """
+    Sync client for Phemex API (https://phemex-docs.github.io/). Built using httpx.Client.
+    """
+
+    def __init__(self, base_url: str, api_key: str, api_secret: str, expiry: int = 60):
+        super().__init__(base_url, api_key, api_secret, expiry)
+        self.session = httpx.Client()
+        self.usdm_rest = USDMRest(self)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def close(self):
+        """Close the underlying HTTP session."""
+        self.session.close()
+
+    def request(self, req: Request):
+        """
+        Make an authenticated request to Phemex API.
+
+        :param req: Request object
+        :return: Parsed JSON response.
+        """
+        url, headers, content = self._prepare(req)
+        resp = self.session.request(method=req.method, url=url, headers=headers, content=content)
+        return self._handle_response(resp, req, url, req.build_body_json())
+
+    # ----------------------------------------
+    # Common endpoints shared across APIs
+    # ----------------------------------------
+
+    def server_time(self, ms: bool = True) -> int:
+        """
+        Fetch current Phemex server time (ms by default). For details, see:
+        https://phemex-docs.github.io/#query-server-time-2
+        """
+        req = Request.get("/public/time")
+        resp = self.request(req)
+        timestamp = Extractor(resp).key("data", "serverTime").extract()
+        return timestamp if ms else timestamp // 1000
+
+
+class AsyncPhemexClient(BasePhemexClient):
+    """
+    Async client for Phemex API (https://phemex-docs.github.io/). Built using httpx.AsyncClient.
+    """
+
+    def __init__(self, base_url: str, api_key: str, api_secret: str, expiry: int = 60):
+        super().__init__(base_url, api_key, api_secret, expiry)
+        self.session = httpx.AsyncClient()
+        self.usdm_rest = AsyncUSDMRest(self)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    async def close(self):
+        """Close the underlying async HTTP session."""
+        await self.session.aclose()
+
+    async def request(self, req: Request):
+        """
+        Make an authenticated request to Phemex API.
+
+        :param req: Request object
+        :return: Parsed JSON response.
+        """
+        url, headers, content = self._prepare(req)
+        resp = await self.session.request(method=req.method, url=url, headers=headers, content=content)
+        return self._handle_response(resp, req, url, req.build_body_json())
+
+    # ----------------------------------------
+    # Common endpoints shared across APIs
+    # ----------------------------------------
+
+    async def server_time(self, ms: bool = True) -> int:
+        """
+        Fetch current Phemex server time (ms by default). For details, see:
+        https://phemex-docs.github.io/#query-server-time-2
+        """
+        req = Request.get("/public/time")
+        resp = await self.request(req)
+        timestamp = Extractor(resp).key("data", "serverTime").extract()
+        return timestamp if ms else timestamp // 1000