Metadata-Version: 2.4
Name: tradezero-python
Version: 0.1.0
Summary: Python client for the TradeZero Trading API
Author-email: Sean Michael Suntoso <sean@suntoso.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ssuntoso/tradezero-python
Project-URL: Documentation, https://github.com/ssuntoso/tradezero-python#readme
Project-URL: Repository, https://github.com/ssuntoso/tradezero-python
Project-URL: Issues, https://github.com/ssuntoso/tradezero-python/issues
Keywords: tradezero,trading,api,sdk,client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv>=1.0.1
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Dynamic: license-file

# TradeZero Python SDK

[![PyPI](https://img.shields.io/pypi/v/tradezero-python.svg)](https://pypi.org/project/tradezero-python/)
[![Python](https://img.shields.io/pypi/pyversions/tradezero-python.svg)](https://pypi.org/project/tradezero-python/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Python client for the [TradeZero Trading API](https://tradezero.co/). This SDK wraps the TradeZero REST endpoints with typed models, organized services, and a high-level short-locate workflow helper.

## What it provides

- **`TradeZeroClient`** — the main entry point for all API calls.
- **Service categories** exposed via `TradeZeroClient`:
  - `client.accounts` — list accounts, account details, account PnL.
  - `client.cash` — cash transaction history (paginated).
  - `client.positions` — open and closed positions.
  - `client.orders` — create/read/cancel orders, routes, easy-to-borrow checks, historical paging.
  - `client.locates` — quote/accept/cancel/sell locates, inventory, history.
- **Typed models** split by category under `tradezero/models/`.
- **Extension helpers** under `tradezero.ext/`:
  - `ShortLocateWorkflow` automates the async ETB check → quote → poll → accept → inventory workflow for short selling.

## Installation

Install from PyPI:

```bash
python -m pip install tradezero-python
```

Or install the latest development version directly from GitHub:

```bash
python -m pip install git+https://github.com/ssuntoso/tradezero-python.git
```

If you are working from a local checkout, install in editable mode:

```bash
git clone https://github.com/ssuntoso/tradezero-python.git
cd tradezero-python
python -m pip install -e .
```

## Configuration

Set the required environment variables:

```bash
export TZ_API_KEY_ID="your-api-key-id"
export TZ_API_SECRET_KEY="your-api-secret-key"
```

Optional values:

```bash
export TZ_ACCOUNT="your-account-id"
export TZ_BASE_URL="https://webapi.tradezero.com"
export TZ_TIMEOUT="30"
```

You can also create a `.env` file in the working directory; the bundled examples load it automatically via `python-dotenv`.

## Quick start

```python
from tradezero import TradeZeroClient

client = TradeZeroClient.from_env()

accounts = client.accounts.list_accounts()
print(accounts)

account_id = accounts[0].account
details = client.accounts.get_account(account_id)
print(details)
```

See the [`examples/`](examples/) directory and [`docs/USAGE.md`](docs/USAGE.md) for more detailed usage, including the short-locate workflow.

## Examples

Run the bundled examples after setting your environment variables:

```bash
python examples/account_services_example.py
python examples/short_locate_example.py
```

## Testing

Run the unit tests with the standard library test runner:

```bash
python -m unittest discover -s test -p "test_*.py"
```

Or with `pytest`:

```bash
python -m pytest
```

## Documentation

- [Usage guide](docs/USAGE.md) — detailed examples for accounts, orders, positions, cash, locates, and the short-locate workflow.
- [API reference](https://github.com/ssuntoso/tradezero-python/blob/main/tradezero/) — browse the source code for service and model definitions.

## Development

Install the package with development and test dependencies:

```bash
python -m pip install -e ".[dev,test]"
```

Build the distribution artifacts:

```bash
python -m build
```

This produces `dist/tradezero_python-*.whl` and `dist/tradezero_python-*.tar.gz`.

## Publishing

See [`docs/PUBLISHING.md`](docs/PUBLISHING.md) for step-by-step instructions on uploading a new release to PyPI and publishing a GitHub release.

## License

This project is licensed under the [MIT License](LICENSE).
