Metadata-Version: 2.4
Name: merx-sdk
Version: 2.0.0
Summary: Official Python SDK for the Merx TRON resource exchange
License: MIT
Project-URL: Homepage, https://merx.exchange
Project-URL: Repository, https://github.com/Hovsteder/merx-sdk-python
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# merx-sdk

Python SDK for the Merx TRON energy exchange.

## Installation

```bash
pip install merx-sdk
```

Requires Python 3.11+. No external dependencies (uses stdlib `urllib` and `json`).

## Quickstart

```python
from merx import MerxClient

client = MerxClient(api_key="sk_live_...")

# Check prices
prices = client.prices.list()
best = client.prices.best("ENERGY")

# Preview cost
preview = client.prices.preview(
    resource="ENERGY",
    amount=65000,
    duration=3600,
)

# Create order
order = client.orders.create(
    resource_type="ENERGY",
    amount=65000,
    duration_sec=3600,
    target_address="TYourAddress...",
)
```

## API Reference

### Constructor

```python
client = MerxClient(
    api_key: str,                              # Required
    base_url: str = "https://merx.exchange",   # Optional
)
```

### client.prices

| Method | Returns | Description |
|--------|---------|-------------|
| `list()` | `list[ProviderPrice]` | All current prices from all providers |
| `best(resource, amount=None)` | `PriceHistoryEntry` | Cheapest available provider (server-side) |
| `history(provider=None, resource=None, period="24h")` | `list[PriceHistoryEntry]` | Historical price snapshots |
| `stats()` | `PriceStats` | Market statistics |
| `preview(resource, amount, duration, max_price_sun=None)` | `OrderPreview` | Preview order cost |

### client.orders

| Method | Returns | Description |
|--------|---------|-------------|
| `create(resource_type, amount, duration_sec, target_address, ...)` | `Order` | Place a new order |
| `list(limit=30, offset=0, status=None)` | `tuple[list[Order], int]` | Orders with total count |
| `get(order_id)` | `OrderWithFills` | Order details with fills |

`create` parameters:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource_type` | `str` | Yes | `"ENERGY"` or `"BANDWIDTH"` |
| `amount` | `int` | Yes | Min 65000 for ENERGY, 300 for BANDWIDTH |
| `duration_sec` | `int` | Yes | Duration in seconds (3600 = 1h, 86400 = 1d) |
| `target_address` | `str` | Yes | TRON address to receive resources |
| `order_type` | `str` | No | `"MARKET"` (default), `"LIMIT"`, `"PERIODIC"`, `"BROADCAST"` |
| `max_price_sun` | `int` | No | Maximum price per unit in SUN |
| `idempotency_key` | `str` | No | Prevent duplicate orders |

### client.balance

| Method | Returns | Description |
|--------|---------|-------------|
| `get()` | `Balance` | TRX, USDT, locked amounts |
| `deposit_info()` | `DepositInfo` | Deposit address and memo |
| `withdraw(address, amount, currency="TRX", idempotency_key=None)` | `Withdrawal` | Withdraw TRX or USDT |
| `history(period="30D")` | `list[HistoryEntry]` | Transaction history |
| `summary()` | `HistorySummary` | Aggregated stats |

### client.webhooks

| Method | Returns | Description |
|--------|---------|-------------|
| `create(url, events)` | `Webhook` | Register webhook (secret shown once) |
| `list()` | `list[Webhook]` | List all webhooks |
| `delete(webhook_id)` | `bool` | Delete a webhook |

## Error Handling

All API errors raise `MerxError`:

```python
from merx import MerxClient, MerxError

try:
    order = client.orders.create(...)
except MerxError as e:
    print(e.code, str(e))
```

## Types

All responses are dataclasses: `ProviderPrice`, `PricePoint`, `PriceHistoryEntry`, `PriceStats`, `OrderPreview`, `PreviewMatch`, `Balance`, `DepositInfo`, `Order`, `OrderWithFills`, `Fill`, `HistoryEntry`, `HistorySummary`, `Withdrawal`, `Webhook`.

## License

MIT
