Metadata-Version: 2.4
Name: pionex_py
Version: 1.2.0
Summary: Connector library for Pionex REST and WS API with enhanced error handling and performance.
License: MIT
License-File: LICENSE
Keywords: pionex,crypto,api,trading,websocket,rest
Author: Alejandro Rodríguez Moreno
Author-email: alejandrorodm@proton.me
Requires-Python: >=3.11,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: requests (>=2.31.0,<3.0.0)
Requires-Dist: websocket-client (>=1.7.0,<2.0.0)
Project-URL: Repository, https://github.com/alejandrorodm/pionex_py
Description-Content-Type: text/markdown

# Pionex to Python

Python connector for the [Pionex API](https://www.pionex.com/docs/api-docs)
— REST, WebSocket, **bots, dual investment** and high-level portfolio helpers
in one package. Tracks the official OpenAPI spec
([pionex-official/pionex-open-api](https://github.com/pionex-official/pionex-open-api)).

## Installation

```sh
pip install pionex_py
```

## What's included

| Module        | Coverage                                                    | Auth |
|---------------|-------------------------------------------------------------|------|
| `Common`      | Symbol metadata (`/api/v1/common/symbols`)                  | no   |
| `Markets`     | Trades, depth, tickers, book tickers, klines (+ paging)     | no   |
| `Account`     | Balances + per-coin / portfolio helpers                     | yes  |
| `Orders`      | Spot orders: new, mass, cancel, lookup, fills, market/limit helpers, `wait_for_order` | yes |
| `Trade`       | High-level façade: portfolio value/weights, **daily rebalancer** with dry-run | yes |
| `Bot`         | **Spot Grid, Futures Grid, Smart Copy, custom signal listener** | yes |
| `EarnDual`    | **Dual Investment** — products, prices, invest/revoke/collect | mixed |
| `PublicStream` / `PrivateStream` | Trade / Depth / Order / Fill / Balance WebSocket | mixed |

Implements every endpoint exposed by the official 1.x OpenAPI spec for the
Trade, Bot, Earn-Dual and WebSocket APIs (Futures and Partner APIs are
invite-only and not included).

## 30-second tour

```python
from pionex_python import Common, Markets, Account, Orders, Trade, Bot, EarnDual

# Public
print(Markets().get_price('BTC_USDT'))
print(Common().list_symbols(market_type='SPOT')[:5])

# Authenticated trading
orders = Orders('KEY', 'SECRET')
orders.market_buy('BTC_USDT', amount=20)             # spend 20 USDT
orders.limit_sell('BTC_USDT', price=80000, size=0.0002)

# Portfolio rebalance — what the daily rebalancer is built on
trade = Trade('KEY', 'SECRET', quote='USDT')
trade.execute_rebalance({'BTC': 0.5, 'ETH': 0.3, 'USDT': 0.2}, dry_run=True)

# Spot-grid bot
bot = Bot('KEY', 'SECRET')
print(bot.get_spot_grid_ai_strategy('BTC', 'USDT'))   # AI suggestion
```

For a full walkthrough of every module — including bot creation, custom
signal pushing, dual-investment subscriptions and a daily rebalancer
skeleton — see **[EXAMPLES.md](./EXAMPLES.md)**.

## Daily portfolio rebalancer

```python
from pionex_python import Trade

trade = Trade(api_key, api_secret, quote='USDT')

# 1. From your TA + sentiment pipeline
target = {'BTC': 0.50, 'ETH': 0.30, 'USDT': 0.20}

# 2. Compute the diff between current and target weights
plan = trade.compute_rebalance_orders(target, threshold=0.01)

# 3. Always preview first
print(trade.execute_rebalance(plan, dry_run=True))

# 4. When ready
# trade.execute_rebalance(plan, dry_run=False)
```

`execute_rebalance` automatically:

- sells overweight positions before buying underweight ones (so quote cash is available)
- rounds sizes/amounts to each symbol's `basePrecision` / `quotePrecision`
- skips orders below `minNotional` / `minTradeSize`
- supports `dry_run=True` so you can iterate safely

## API key

1. Create the key at <https://www.pionex.com/en/apiKey>.
2. For a rebalancer enable **Read** + **Trade** only — never **Withdraw**.
3. Restrict the key to your server's IP.
4. Export it:

   ```sh
   export PIONEX_KEY=...
   export PIONEX_SECRET=...
   ```

## Versioning

Tracks the published Pionex Open API spec. The library is in `pionex_python.__version__`.

## TODO

- [ ] WebSocket auto-reconnect
- [ ] Retry/backoff on REST 5xx
- [ ] CLI for ad-hoc trading
- [ ] Futures REST coverage (gated by Pionex invite-only access)

## Contributing

PRs welcome — issues and feature requests at
<https://github.com/alejandrorodm/pionex_py/issues>.

## License

MIT — see `LICENSE`.

