Metadata-Version: 2.4
Name: immix_sdk
Version: 0.4.0
Summary: The Python SDK for the Immix API — REST, market data and trading
License: MIT
License-File: LICENSE
Keywords: immix,trading,market data,crypto,api
Requires-Python: >=3.10,<4.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Provides-Extra: aiohttp
Requires-Dist: aiohttp (>=3.14.1,<4) ; (python_version >= "3.10") and (extra == "aiohttp")
Requires-Dist: httpx (>=0.21.2)
Requires-Dist: httpx-aiohttp (>=0.1.8,<0.2.0) ; (python_version >= "3.10") and (extra == "aiohttp")
Requires-Dist: pydantic (>=1.9.2)
Requires-Dist: pydantic-core (>=2.18.2,<3.0.0)
Requires-Dist: typing_extensions (>=4.0.0)
Requires-Dist: websockets (>=12.0)
Project-URL: Documentation, https://docs.immix.xyz
Project-URL: Homepage, https://immix.xyz
Project-URL: Repository, https://github.com/coinstrats/immix-python-sdk-v3
Description-Content-Type: text/markdown

# Immix Python SDK

The Python SDK for the Immix API: REST, the market-data stream and the trading socket.

```bash
pip install immix_sdk
```

The package installs as `immix_sdk` and imports as `immix`. It needs Python 3.10 or newer. The API
reference and guides are at [docs.immix.xyz](https://docs.immix.xyz).

## Use

```python
from immix import Immix, MarketData
from immix.dataframe import to_frame  # needs pandas, which you install yourself
from immix.market_data import TradeEvent

# REST: there is no public REST environment yet, so the base URL is the one your onboarding gave you.
client = Immix(base_url="https://…", token=token)
me = client.users.get_me()

# A write mints its own Idempotency-Key when you name none, and an order is named by order_id.
client.orders.cancel(order_id="7185994167554")

# A list response as a DataFrame: money exact, timestamps UTC datetimes, enums by name.
orders = to_frame(client.orders.list())

# Market data: the public socket by default. The token goes in an `auth` message after
# connecting, never in the handshake. The stream reconnects and resubscribes by itself, and
# yields `Reconnected` where the gap is.
async def stream() -> None:
    async with MarketData(token=token) as md:
        await md.subscribe("trade.OKX@BTC/USDT")
        async for frame in md:
            ...
```

- Money is a decimal string. `immix.to_decimal` and `immix.format_decimal` cross to and from
  `Decimal` exactly, and never through a float. A REST write's money parameters (`qty`, `price`, a
  policy's `…_amount`) take a `Decimal` or an int too, sent in plain notation
  (`Decimal("1E-7")` as `"0.0000001"`); a float is refused before anything is sent.
- **A write mints its own key.** Every write takes an `Idempotency-Key`, and one is minted per call
  when you name none. The SDK's own retries resend it, so they cannot act twice. Name your own
  (`immix.new_idempotency_key()` mints one) when you may retry the write yourself, or retry under
  the key a failed write went out under: its exception carries it, as `idempotency_key`. An asyncio
  timeout is asyncio's exception, not the write's, so name the key when you bound a write's time. On
  `orders.submit` the key is the order's `clientOrderId`, so name either one.
- **An order is named by `order_id`**, the platform's id on every order row:
  `orders.get(order_id=…)`, `orders.cancel(order_id=…)`. REST cannot cancel by `client_order_id`;
  the trading socket's `cancel_order` takes either.
- **Rows as DataFrames.** `immix.dataframe.to_frame` takes a list response, one row, or rows. Money
  columns are exact `Decimal`s (`money="float"` reads floats, for a plot), epoch-nanosecond columns
  are UTC datetimes, and enums are their names. pandas is not a dependency: `pip install pandas`.

## Development

How this repository changes and how a version ships: `DEVELOPING.md`.

## License

MIT. See `LICENSE`.

