docs: document async client (AsyncDatamaxi) in README and docs

README.md

@@ -19,6 +19,7 @@ This package is compatible with Python v3.10+.
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Quickstart](#quickstart)
+- [Async Client](#async-client)
 - [API Reference](#api-reference)
   - [CEX Candle Data](#cex-candle-data)
   - [CEX Ticker Data](#cex-ticker-data)
@@ -83,37 +84,113 @@ the key stays out of source code):
 export DATAMAXI_API_KEY="your_api_key"
 ```
 
+=== "Sync"
+
+    ```python
+    from datamaxi import Datamaxi, Telegram, Naver
+
+    # Clients read DATAMAXI_API_KEY from the environment automatically.
+    # Alternatively, pass api_key="your_api_key" explicitly to each client.
+    maxi = Datamaxi()
+    telegram = Telegram()
+    naver = Naver()
+
+    # Fetch CEX candle data (returns pandas DataFrame)
+    df = maxi.cex.candle(
+        exchange="binance",
+        symbol="BTC-USDT",
+        interval="1d",
+        market="spot"
+    )
+    print(df.head())
+
+    # Fetch ticker data
+    ticker = maxi.cex.ticker.get(
+        exchange="binance",
+        symbol="BTC-USDT",
+        market="spot"
+    )
+    print(ticker)
+
+    # Fetch premium data
+    premium = maxi.premium(asset="BTC")
+    print(premium.head())
+    ```
+
+=== "Async"
+
+    ```python
+    import asyncio
+    from datamaxi.aio import AsyncDatamaxi
+
+
+    async def main():
+        # Reads DATAMAXI_API_KEY from the environment automatically.
+        # Alternatively, pass api_key="your_api_key" explicitly.
+        async with AsyncDatamaxi() as client:
+            # Fetch CEX candle data (returns pandas DataFrame)
+            df = await client.cex.candle(
+                exchange="binance",
+                symbol="BTC-USDT",
+                interval="1d",
+                market="spot",
+            )
+            print(df.head())
+
+            # Fetch ticker data
+            ticker = await client.cex.ticker.get(
+                exchange="binance",
+                symbol="BTC-USDT",
+                market="spot",
+            )
+            print(ticker)
+
+            # Fetch premium data
+            premium = await client.premium(asset="BTC")
+            print(premium.head())
+
+
+    asyncio.run(main())
+    ```
+
+## Async Client
+
+The SDK also ships an async client, `AsyncDatamaxi` (built on
+[httpx](https://www.python-httpx.org/)). It mirrors the same resource tree and
+arguments as `Datamaxi`, with one rule: every method is a coroutine and must be
+`await`ed. Install the async extra:
+
+```shell
+pip install "datamaxi[async]"
+```
+
 ```python
-from datamaxi import Datamaxi, Telegram, Naver
+import asyncio
+from datamaxi.aio import AsyncDatamaxi
 
-# Clients read DATAMAXI_API_KEY from the environment automatically.
-# Alternatively, pass api_key="your_api_key" explicitly to each client.
-maxi = Datamaxi()
-telegram = Telegram()
-naver = Naver()
 
-# Fetch CEX candle data (returns pandas DataFrame)
-df = maxi.cex.candle(
-    exchange="binance",
-    symbol="BTC-USDT",
-    interval="1d",
-    market="spot"
-)
-print(df.head())
+async def main():
+    # Reads DATAMAXI_API_KEY from the environment, or pass api_key=... explicitly.
+    async with AsyncDatamaxi() as client:
+        df = await client.cex.candle(
+            exchange="binance", symbol="BTC-USDT", interval="1d", market="spot"
+        )
+        print(df.head())
 
-# Fetch ticker data
-ticker = maxi.cex.ticker.get(
-    exchange="binance",
-    symbol="BTC-USDT",
-    market="spot"
-)
-print(ticker)
 
-# Fetch premium data
-premium = maxi.premium(asset="BTC")
-print(premium.head())
+asyncio.run(main())
 ```
 
+Use `AsyncDatamaxi` as an async context manager (shown above) or call
+`await client.aclose()` yourself. Paginated endpoints return an async
+`next_request` — `await` it too
+(`data, next_request = await client.cex.announcement(...)`). Telegram and Naver
+have standalone `AsyncTelegram` / `AsyncNaver` clients.
+
+Every endpoint in the [API Reference](#api-reference) works the same under the
+async client — see the [docs](https://datamaxi.readthedocs.io/) where each
+example has a Sync/Async tab.
+
 ## API Reference
 
 > **Discovery helpers.** Most endpoints expose helpers to list valid argument
@@ -236,7 +313,6 @@ data, next_request = maxi.cex.token.updates(
     page=1,                  # Optional: page number
     limit=1000,              # Optional: items per page
     type=None,               # Optional: "listed" or "delisted"
-    sort="desc"              # Optional: "asc" or "desc"
 )
 ```
 

docs/async.md

@@ -0,0 +1,77 @@
+# Async client
+
+The SDK ships an async client, `AsyncDatamaxi`, built on
+[httpx](https://www.python-httpx.org/). It mirrors the sync
+[`Datamaxi`](api.md) resource tree — the same endpoints and arguments — with one
+rule: every method is a coroutine and must be `await`ed.
+
+Every endpoint page in this documentation carries a **Sync** / **Async** tab —
+switch to the *Async* tab to see the awaited twin of that page's example.
+
+## Installation
+
+The async client requires the `async` extra, which pulls in `httpx`:
+
+```shell
+pip install "datamaxi[async]"
+```
+
+## Lifecycle
+
+Use `AsyncDatamaxi` as an async context manager so the underlying `httpx` client
+is closed cleanly, or call `await client.aclose()` yourself. It reads the same
+`DATAMAXI_API_KEY` environment variable as the sync client.
+
+```python
+import asyncio
+from datamaxi.aio import AsyncDatamaxi
+
+
+async def main():
+    # Reads DATAMAXI_API_KEY from the environment, or pass api_key=... explicitly.
+    async with AsyncDatamaxi() as client:
+        df = await client.cex.candle(
+            exchange="binance", symbol="BTC-USDT", interval="1d", market="spot"
+        )
+        print(df.head())
+
+
+asyncio.run(main())
+```
+
+Without a context manager, close the client explicitly:
+
+```python
+client = AsyncDatamaxi()
+try:
+    df = await client.cex.candle(
+        exchange="binance", symbol="BTC-USDT", interval="1d", market="spot"
+    )
+finally:
+    await client.aclose()
+```
+
+## Notes
+
+- Every data and discovery method is a coroutine — `await` it (e.g.
+  `await client.cex.candle.exchanges(market="spot")`).
+- Telegram and Naver have standalone async clients, `AsyncTelegram` and
+  `AsyncNaver`, also imported from `datamaxi.aio` and used the same way (async
+  context managers, awaited methods). See the [Telegram](telegram.md) and
+  [Naver Trend](naver-trend.md) pages for tabbed examples.
+
+## Pagination
+
+Paginated endpoints return an **async** `next_request` callable — `await` it too:
+
+```python
+data, next_request = await client.cex.announcement(page=1, limit=100)
+data2, _ = await next_request()
+```
+
+## Reference
+
+::: datamaxi.aio.AsyncDatamaxi
+    options:
+      show_submodules: false
+      show_source: false

docs/cex-announcement.md

@@ -4,21 +4,46 @@ Exchange announcements such as listings and delistings.
 
 ## Usage
 
-```python
-from datamaxi import Datamaxi
+=== "Sync"
 
-maxi = Datamaxi(api_key="YOUR_API_KEY")
+    ```python
+    from datamaxi import Datamaxi
 
-data, next_request = maxi.cex.announcement(
-    exchange="binance",
-    category="listing",
-    page=1,
-    limit=50,
-    sort="desc",
-)
+    maxi = Datamaxi(api_key="YOUR_API_KEY")
 
-more_data, _ = next_request()
-```
+    data, next_request = maxi.cex.announcement(
+        exchange="binance",
+        category="listing",
+        page=1,
+        limit=50,
+        sort="desc",
+    )
+
+    more_data, _ = next_request()
+    ```
+
+=== "Async"
+
+    ```python
+    import asyncio
+    from datamaxi.aio import AsyncDatamaxi
+
+
+    async def main():
+        async with AsyncDatamaxi(api_key="YOUR_API_KEY") as client:
+            data, next_request = await client.cex.announcement(
+                exchange="binance",
+                category="listing",
+                page=1,
+                limit=50,
+                sort="desc",
+            )
+
+            more_data, _ = await next_request()
+
+
+    asyncio.run(main())
+    ```
 
 ## Notes
 

docs/cex-candle.md

@@ -4,24 +4,52 @@ Historical OHLCV candle data for centralized exchanges.
 
 ## Usage
 
-```python
-from datamaxi import Datamaxi
-
-maxi = Datamaxi(api_key="YOUR_API_KEY")
-
-exchanges = maxi.cex.candle.exchanges(market="spot")
-symbols = maxi.cex.candle.symbols(exchange="binance", market="spot")
-intervals = maxi.cex.candle.intervals()
-
-df = maxi.cex.candle(
-    exchange="binance",
-    symbol="BTC-USDT",
-    interval="1d",
-    market="spot",
-    from_unix=1704067200,
-    to_unix=1706745600,
-)
-```
+=== "Sync"
+
+    ```python
+    from datamaxi import Datamaxi
+
+    maxi = Datamaxi(api_key="YOUR_API_KEY")
+
+    exchanges = maxi.cex.candle.exchanges(market="spot")
+    symbols = maxi.cex.candle.symbols(exchange="binance", market="spot")
+    intervals = maxi.cex.candle.intervals()
+
+    df = maxi.cex.candle(
+        exchange="binance",
+        symbol="BTC-USDT",
+        interval="1d",
+        market="spot",
+        from_unix=1704067200,
+        to_unix=1706745600,
+    )
+    ```
+
+=== "Async"
+
+    ```python
+    import asyncio
+    from datamaxi.aio import AsyncDatamaxi
+
+
+    async def main():
+        async with AsyncDatamaxi(api_key="YOUR_API_KEY") as client:
+            exchanges = await client.cex.candle.exchanges(market="spot")
+            symbols = await client.cex.candle.symbols(exchange="binance", market="spot")
+            intervals = await client.cex.candle.intervals()
+
+            df = await client.cex.candle(
+                exchange="binance",
+                symbol="BTC-USDT",
+                interval="1d",
+                market="spot",
+                from_unix=1704067200,
+                to_unix=1706745600,
+            )
+
+
+    asyncio.run(main())
+    ```
 
 ## Notes