Metadata-Version: 2.4
Name: tronsave
Version: 2.0.0
Summary: Fully-typed Python SDK for the Tronsave v2 API (TRON Energy & Bandwidth).
Project-URL: Homepage, https://github.com/tronsave/tronsave-sdk
Project-URL: Repository, https://github.com/tronsave/tronsave-sdk
Project-URL: Issues, https://github.com/tronsave/tronsave-sdk/issues
Author: Tronsave
License: MIT
License-File: LICENSE
Keywords: bandwidth,energy,sdk,tron,tronsave
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == 'dev'
Description-Content-Type: text/markdown

# tronsave (Python)

Fully-typed Python SDK for the [Tronsave](https://tronsave.io) v2 API (TRON Energy & Bandwidth).
Python 3.9+, built on `httpx`.

## Install

```bash
pip install tronsave
```

## Quick start

```python
import os
from tronsave import TronsaveClient, Network

sdk = TronsaveClient(api_key=os.environ["TRONSAVE_API_KEY"], network=Network.MAINNET)

me = sdk.get_user_info()
print(me.balance, "SUN")

est = sdk.estimate_buy_resource({
    "receiver": "TFwUFWr3QV376677Z8VWXxGUAMFSrq1MbM",
    "resourceType": "ENERGY",
    "resourceAmount": 65000,   # ENERGY must be > 64000
    "durationSec": 3600,
})

order = sdk.buy_resource(
    {"receiver": "TFwUFWr3QV376677Z8VWXxGUAMFSrq1MbM", "resourceAmount": 65000, "durationSec": 3600},
    {"allowPartialFill": True, "maxPriceAccepted": 100},
)

status = sdk.get_order(order.order_id)
print(status.fulfilled_percent)  # 100 = fully delegated
```

## Errors

All exceptions subclass `tronsave.TronsaveError` (`.code`, `.status`, `.raw`):
`TronsaveAuthError` (401), `TronsaveValidationError` / `TronsaveBusinessError` (400),
`TronsaveRateLimitError` (429, `.retry_after_ms`), `TronsaveNetworkError` (transport).

```python
from tronsave import TronsaveBusinessError, TronsaveRateLimitError

try:
    sdk.buy_resource({"receiver": "T...", "resourceAmount": 65000})
except TronsaveRateLimitError as e:
    print("retry after", e.retry_after_ms, "ms")
except TronsaveBusinessError as e:
    print(e.code, e.status)
```

## Notes

- Defaults: `ENERGY`, `MEDIUM`, `durationSec=259200`.
- ENERGY `resourceAmount` must be **> 64000** (rejected client-side).
- `extendTo` is a **Unix timestamp in seconds**.
- Rate limits enforced client-side (15/s; 1/s for `get_extendable_delegates`).

## Develop

```bash
pip install -e ".[dev]"
pytest   # runs the shared conformance suite (needs Node.js for the mock server)
```

See [`../../spec/PARITY.md`](../../spec/PARITY.md) for cross-language parity.
