maicoin 🪙

Python client for the MaiCoin MAX exchange. Provides a typed REST v3 client and a WebSocket stream client built on httpx, websockets, and pydantic.

📦 Installation

uv add maicoin
# or
pip install maicoin

Requires Python 3.12+.

🚀 Quick start

Set credentials in your environment (or a .env file):

MAX_API_KEY=your_key
MAX_API_SECRET=your_secret

🌐 REST

from maicoin.v3 import Client

async with Client() as client:  # public endpoints
    ticker = await client.ticker("btctwd")

async with Client(api_key=..., api_secret=...) as client:  # private endpoints (signed)
    accounts = await client.accounts()
    raw = await client.request("GET", "/api/v3/...", auth=True)  # raw escape hatch

Client owns an underlying httpx.AsyncClient by default. Prefer async with Client(...) so the HTTP session is closed automatically, or call await client.aclose() when managing the lifecycle manually.

For small synchronous scripts, use the explicit _sync wrappers:

from maicoin.v3 import Client

ticker = Client().ticker_sync("btctwd")

Do not call _sync wrappers from code that already runs inside an event loop, such as FastAPI handlers, Jupyter notebooks, or async trading bots. Await the async methods there instead:

from collections.abc import AsyncIterator

from maicoin.v3 import Client


async def max_client() -> AsyncIterator[Client]:
    async with Client(api_key="...", api_secret="...") as client:
        yield client


async def handler(client: Client) -> dict[str, str]:
    ticker = await client.ticker("btctwd")
    return {"last": ticker.last}

Use async iterators for cursor-paginated history endpoints:

async with Client(api_key=..., api_secret=...) as client:
    async for order in client.iter_order_history("btctwd", page_limit=100):
        print(order.id, order.state)

[!WARNING] ⚠️ Private methods can place orders, transfer funds, take loans, and trigger withdrawals. Double-check arguments before calling state-changing methods against a live account.

📡 WebSocket

from maicoin.ws import Channel, Stream, Subscription

stream = Stream()                  # or Stream.from_env() for private channels
stream.subscribe([Subscription(channel=Channel.TICKER, market="btcusdt")])
stream.add_handler(lambda r: print(r.model_dump(exclude_none=True)))
stream.run()

Full runnable scripts: examples/rest.py, examples/websocket.py.

🛠️ Development

This repo uses uv and just:

uv sync
just         # format, lint, type-check, test
just test    # pytest with coverage

Live integration tests

Live tests call the real MAX API and are skipped unless explicitly enabled:

RUN_LIVE_TESTS=1 uv run pytest -v -s -m live tests/live
# or
just live-test

Private read-only live tests also require MAX_API_KEY and MAX_API_SECRET; just loads these from .env automatically. Set MAX_LIVE_MARKET to override the default public test market (btctwd). Destructive live tests are intentionally not implemented yet.

📚 References

• HTTP API v3: https://max-api.maicoin.com/doc/v3.html
• WebSocket API: https://maicoin.github.io/max-websocket-docs/

📄 License

MIT