Metadata-Version: 2.4
Name: agavadex
Version: 0.1.1
Summary: Python SDK for the AgavaDEX exchange API (REST + WebSocket)
Project-URL: Homepage, https://agavadex.com
Project-URL: Documentation, https://docs.agavadex.com
Project-URL: Source, https://gitlab.com/agavadex-group/agavadex-python
Project-URL: Issues, https://gitlab.com/agavadex-group/agavadex-python/-/issues
Author: AgavaDEX
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agavadex,api,crypto,exchange,sdk,trading,websocket
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: websockets>=12
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# AgavaDEX Python SDK

Python client for the [AgavaDEX](https://agavadex.com) exchange
API — a thin, typed wrapper over the public REST + WebSocket interface.

## Install

```sh
pip install agavadex
```

Requires Python 3.9+.

## Quick start

### Public market data — no key needed

```python
from agavadex import Client

with Client() as client:
    for sym in client.get_symbols():
        print(sym.symbol, sym.tick_size)

    book = client.get_order_book("AGAVAUSDT")
    print(book.bids[0].price, book.asks[0].price)
```

### Private account & trading

API keys are created in the AgavaDEX web app (Account → API keys). Pass
them to the client — never hard-code them; read them from the
environment.

```python
import os
from agavadex import Client

with Client(api_key=os.environ["AGAVADEX_API_KEY"],
            api_secret=os.environ["AGAVADEX_API_SECRET"]) as client:
    for balance in client.get_balances():
        print(balance.asset, balance.available)

    result = client.place_order(
        "AGAVAUSDT", side="buy", type="limit", price="100.00", qty="1",
    )
    print(result.order.id, result.order.status)
```

### WebSocket streams

```python
import asyncio
from agavadex import MarketDataStream

async def main():
    async with MarketDataStream(channels=["trades@AGAVAUSDT"]) as stream:
        async for msg in stream:
            print(msg.channel, msg.type, msg.data)

asyncio.run(main())
```

The public `MarketDataStream` needs no auth; the private `UserStream`
takes `api_key` / `api_secret` and authenticates in-band. Both
auto-reconnect and re-subscribe on a dropped socket.

## The decimal contract

Every monetary value — `price`, `qty`, `volume`, fee amounts — is a
`decimal.Decimal`, never a `float`. The API sends and receives these as
JSON *strings*; this SDK parses them losslessly. When placing orders,
`price` / `qty` accept a `Decimal`, `str` or `int`.

## Errors

Non-2xx responses raise a typed exception — `BadRequestError`,
`AuthenticationError`, `PermissionDeniedError`, `NotFoundError`,
`RateLimitError`, `ServerError` — all subclasses of `APIError`. Each
carries `status_code` and the API's `request_id`; `RateLimitError` adds
`retry_after`. Pass `max_retries=` to `Client` to auto-retry `429`s.

## What this SDK does not do

Withdrawals are not part of the AgavaDEX API and not in this SDK — they
require a wallet signature and happen only in the web app.

## Development

```sh
pip install -e ".[dev]"
pytest            # offline tests run with no credentials
ruff check .
```

Integration tests run only when `AGAVADEX_API_KEY` / `AGAVADEX_API_SECRET`
are set, and are read-only — they never place orders.

## Links

- Docs: <https://docs.agavadex.com>
- API reference: <https://docs.agavadex.com/api/reference/>
- Security policy: [SECURITY.md](SECURITY.md)

## License

[Apache-2.0](LICENSE)
