maicoin.v3

REST v3 client for the MaiCoin MAX API.

Client

Client

Client(
    api_key=None,
    api_secret=None,
    *,
    base_url=BASE_URL,
    timeout=DEFAULT_TIMEOUT,
    session=None,
    nonce_factory=generate_nonce,
    retry_policy=None,
)

Async-first REST v3 client for the MaiCoin MAX exchange.

Construct without credentials for public endpoints, or pass api_key and api_secret to call authenticated (signed) endpoints.

Examples:

Public-only client:

>>> from maicoin.v3 import Client
>>> async with Client() as client:
...     await client.ticker("btctwd")

Authenticated client:

>>> async with Client(api_key="...", api_secret="...") as client:
...     await client.accounts()

Build a REST v3 client.

Parameters:

Name	Type	Description	Default
api_key	str | None	MAX API access key. Required for authenticated endpoints.	None
api_secret	str | None	MAX API secret used to sign authenticated requests.	None
base_url	str	API base URL. Override for staging or test environments.	BASE_URL
timeout	float	Per-request timeout in seconds.	DEFAULT_TIMEOUT
session	RequestSession | None	Custom HTTP session implementing RequestSession. Defaults to a fresh httpx.AsyncClient.	None
nonce_factory	Callable[[], int]	Callable returning a strictly increasing integer nonce in milliseconds. Override in tests.	generate_nonce
retry_policy	RetryPolicy | None	Retry/backoff policy for transient failures. Pass RetryPolicy(enabled=False) to disable retries.	None

Source code in src/maicoin/v3/client.py

def __init__(
    self,
    api_key: str | None = None,
    api_secret: str | None = None,
    *,
    base_url: str = BASE_URL,
    timeout: float = DEFAULT_TIMEOUT,
    session: RequestSession | None = None,
    nonce_factory: Callable[[], int] = generate_nonce,
    retry_policy: RetryPolicy | None = None,
) -> None:
    """Build a REST v3 client.

    Args:
        api_key: MAX API access key. Required for authenticated endpoints.
        api_secret: MAX API secret used to sign authenticated requests.
        base_url: API base URL. Override for staging or test environments.
        timeout: Per-request timeout in seconds.
        session: Custom HTTP session implementing [`RequestSession`][maicoin.v3.client.RequestSession].
            Defaults to a fresh `httpx.AsyncClient`.
        nonce_factory: Callable returning a strictly increasing integer
            nonce in milliseconds. Override in tests.
        retry_policy: Retry/backoff policy for transient failures. Pass
            `RetryPolicy(enabled=False)` to disable retries.
    """
    self.api_key = api_key
    self.api_secret = api_secret
    self.base_url = base_url
    self.timeout = timeout
    self._owns_session = session is None
    self._session: RequestSession | None = session
    self.nonce_factory = nonce_factory
    self.retry_policy = retry_policy or RetryPolicy()
    self._market_data = PublicMarketDataEndpoints(self)
    self._orders = OrderIntakeHistoryEndpoints(self)
    self._funds = FundsEndpoints(self)
    self._convert = ConvertEndpoints(self)
    self._m_wallet = MWalletEndpoints(self)

api_key instance-attribute

api_key = api_key

api_secret instance-attribute

api_secret = api_secret

base_url instance-attribute

base_url = base_url

timeout instance-attribute

timeout = timeout

nonce_factory instance-attribute

nonce_factory = nonce_factory

retry_policy instance-attribute

retry_policy = retry_policy or RetryPolicy()

session property writable

session

Underlying async HTTP session, created lazily for default clients.

aclose async

aclose()

Close the underlying async HTTP session when it supports closing.

Source code in src/maicoin/v3/client.py

async def aclose(self) -> None:
    """Close the underlying async HTTP session when it supports closing."""
    if self._session is None:
        return
    aclose = getattr(self._session, "aclose", None)
    if aclose is not None:
        await aclose()
    if self._owns_session:
        self._session = None

request_sync

request_sync(method, path, params=None, *, auth=False)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def request_sync(
    self, method: str, path: str, params: Mapping[str, object] | None = None, *, auth: bool = False
) -> object:
    """Synchronous convenience wrapper."""
    return self._run_sync("request", method, path, params, auth=auth)

markets_sync

markets_sync()

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def markets_sync(self) -> list[Market]:
    """Synchronous convenience wrapper."""
    return self._run_sync("markets")

currencies_sync

currencies_sync()

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def currencies_sync(self) -> list[Currency]:
    """Synchronous convenience wrapper."""
    return self._run_sync("currencies")

timestamp_sync

timestamp_sync()

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def timestamp_sync(self) -> Timestamp:
    """Synchronous convenience wrapper."""
    return self._run_sync("timestamp")

kline_sync

kline_sync(market, *, limit=30, period=1, timestamp=None)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def kline_sync(self, market: str, *, limit: int = 30, period: int = 1, timestamp: int | None = None) -> list[KLine]:
    """Synchronous convenience wrapper."""
    return self._run_sync("kline", market, limit=limit, period=period, timestamp=timestamp)

depth_sync

depth_sync(market, *, limit=None, sort_by_price=None)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def depth_sync(self, market: str, *, limit: int | None = None, sort_by_price: bool | None = None) -> Depth:
    """Synchronous convenience wrapper."""
    return self._run_sync("depth", market, limit=limit, sort_by_price=sort_by_price)

trades_sync

trades_sync(market, *, timestamp=None, limit=None)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def trades_sync(self, market: str, *, timestamp: int | None = None, limit: int | None = None) -> list[PublicTrade]:
    """Synchronous convenience wrapper."""
    return self._run_sync("trades", market, timestamp=timestamp, limit=limit)

tickers_sync

tickers_sync(markets)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def tickers_sync(self, markets: Sequence[str]) -> list[Ticker]:
    """Synchronous convenience wrapper."""
    return self._run_sync("tickers", markets)

ticker_sync

ticker_sync(market)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def ticker_sync(self, market: str) -> Ticker:
    """Synchronous convenience wrapper."""
    return self._run_sync("ticker", market)

info_sync

info_sync()

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def info_sync(self) -> UserInfo:
    """Synchronous convenience wrapper."""
    return self._run_sync("info")

accounts_sync

accounts_sync(*, wallet_type='spot', currency=None)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def accounts_sync(self, *, wallet_type: str = "spot", currency: str | None = None) -> list[Account]:
    """Synchronous convenience wrapper."""
    return self._run_sync("accounts", wallet_type=wallet_type, currency=currency)

wallet_trades_sync

wallet_trades_sync(
    *,
    wallet_type="spot",
    market=None,
    timestamp=None,
    from_id=None,
    order=None,
    limit=None,
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def wallet_trades_sync(
    self,
    *,
    wallet_type: str = "spot",
    market: str | None = None,
    timestamp: int | None = None,
    from_id: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[PrivateTrade]:
    """Synchronous convenience wrapper."""
    return self._run_sync(
        "wallet_trades",
        wallet_type=wallet_type,
        market=market,
        timestamp=timestamp,
        from_id=from_id,
        order=order,
        limit=limit,
    )

open_orders_sync

open_orders_sync(
    *,
    wallet_type="spot",
    market=None,
    timestamp=None,
    order_by=None,
    limit=None,
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def open_orders_sync(
    self,
    *,
    wallet_type: str = "spot",
    market: str | None = None,
    timestamp: int | None = None,
    order_by: str | None = None,
    limit: int | None = None,
) -> list[Order]:
    """Synchronous convenience wrapper."""
    return self._run_sync(
        "open_orders", wallet_type=wallet_type, market=market, timestamp=timestamp, order_by=order_by, limit=limit
    )

closed_orders_sync

closed_orders_sync(
    *,
    wallet_type="spot",
    market=None,
    timestamp=None,
    order_by=None,
    limit=None,
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def closed_orders_sync(
    self,
    *,
    wallet_type: str = "spot",
    market: str | None = None,
    timestamp: int | None = None,
    order_by: str | None = None,
    limit: int | None = None,
) -> list[Order]:
    """Synchronous convenience wrapper."""
    return self._run_sync(
        "closed_orders", wallet_type=wallet_type, market=market, timestamp=timestamp, order_by=order_by, limit=limit
    )

order_history_sync

order_history_sync(
    market, *, wallet_type="spot", from_id=None, limit=None
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def order_history_sync(
    self, market: str, *, wallet_type: str = "spot", from_id: int | None = None, limit: int | None = None
) -> list[Order]:
    """Synchronous convenience wrapper."""
    return self._run_sync("order_history", market, wallet_type=wallet_type, from_id=from_id, limit=limit)

order_sync

order_sync(*, order_id=None, client_oid=None)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def order_sync(self, *, order_id: int | None = None, client_oid: str | None = None) -> Order:
    """Synchronous convenience wrapper."""
    return self._run_sync("order", order_id=order_id, client_oid=client_oid)

create_order_sync

create_order_sync(
    market,
    side,
    volume,
    *,
    wallet_type="spot",
    price=None,
    client_oid=None,
    stop_price=None,
    ord_type=None,
    group_id=None,
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def create_order_sync(
    self,
    market: str,
    side: OrderSide | str,
    volume: str,
    *,
    wallet_type: str = "spot",
    price: str | None = None,
    client_oid: str | None = None,
    stop_price: str | None = None,
    ord_type: OrderType | str | None = None,
    group_id: int | None = None,
) -> Order:
    """Synchronous convenience wrapper."""
    return self._run_sync(
        "create_order",
        market,
        side,
        volume,
        wallet_type=wallet_type,
        price=price,
        client_oid=client_oid,
        stop_price=stop_price,
        ord_type=ord_type,
        group_id=group_id,
    )

cancel_order_sync

cancel_order_sync(*, order_id=None, client_oid=None)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def cancel_order_sync(self, *, order_id: int | None = None, client_oid: str | None = None) -> Order:
    """Synchronous convenience wrapper."""
    return self._run_sync("cancel_order", order_id=order_id, client_oid=client_oid)

cancel_orders_sync

cancel_orders_sync(
    *,
    wallet_type="spot",
    market=None,
    side=None,
    group_id=None,
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def cancel_orders_sync(
    self,
    *,
    wallet_type: str = "spot",
    market: str | None = None,
    side: OrderSide | str | None = None,
    group_id: int | None = None,
) -> list[Order]:
    """Synchronous convenience wrapper."""
    return self._run_sync("cancel_orders", wallet_type=wallet_type, market=market, side=side, group_id=group_id)

order_trades_sync

order_trades_sync(*, order_id=None, client_oid=None)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def order_trades_sync(self, *, order_id: int | None = None, client_oid: str | None = None) -> list[PrivateTrade]:
    """Synchronous convenience wrapper."""
    return self._run_sync("order_trades", order_id=order_id, client_oid=client_oid)

withdrawal_sync

withdrawal_sync(uuid)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def withdrawal_sync(self, uuid: str) -> Withdrawal:
    """Synchronous convenience wrapper."""
    return self._run_sync("withdrawal", uuid)

create_withdrawal_sync

create_withdrawal_sync(*, withdraw_address_uuid, amount)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def create_withdrawal_sync(self, *, withdraw_address_uuid: str, amount: str) -> Withdrawal:
    """Synchronous convenience wrapper."""
    return self._run_sync("create_withdrawal", withdraw_address_uuid=withdraw_address_uuid, amount=amount)

create_twd_withdrawal_sync

create_twd_withdrawal_sync(amount)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def create_twd_withdrawal_sync(self, amount: str) -> Withdrawal:
    """Synchronous convenience wrapper."""
    return self._run_sync("create_twd_withdrawal", amount)

withdrawals_sync

withdrawals_sync(
    *,
    currency=None,
    state=None,
    timestamp=None,
    order=None,
    limit=None,
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def withdrawals_sync(
    self,
    *,
    currency: str | None = None,
    state: str | None = None,
    timestamp: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[Withdrawal]:
    """Synchronous convenience wrapper."""
    return self._run_sync(
        "withdrawals", currency=currency, state=state, timestamp=timestamp, order=order, limit=limit
    )

withdraw_addresses_sync

withdraw_addresses_sync(
    currency, *, limit=None, offset=None
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def withdraw_addresses_sync(
    self, currency: str, *, limit: int | None = None, offset: int | None = None
) -> list[WithdrawAddress]:
    """Synchronous convenience wrapper."""
    return self._run_sync("withdraw_addresses", currency, limit=limit, offset=offset)

deposit_sync

deposit_sync(*, txid=None, uuid=None)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def deposit_sync(self, *, txid: str | None = None, uuid: str | None = None) -> Deposit:
    """Synchronous convenience wrapper."""
    return self._run_sync("deposit", txid=txid, uuid=uuid)

deposits_sync

deposits_sync(
    *, currency=None, timestamp=None, order=None, limit=None
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def deposits_sync(
    self,
    *,
    currency: str | None = None,
    timestamp: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[Deposit]:
    """Synchronous convenience wrapper."""
    return self._run_sync("deposits", currency=currency, timestamp=timestamp, order=order, limit=limit)

deposit_address_sync

deposit_address_sync(currency_version)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def deposit_address_sync(self, currency_version: str) -> DepositAddress:
    """Synchronous convenience wrapper."""
    return self._run_sync("deposit_address", currency_version)

internal_transfers_sync

internal_transfers_sync(
    side,
    *,
    currency=None,
    timestamp=None,
    order=None,
    limit=None,
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def internal_transfers_sync(
    self,
    side: str,
    *,
    currency: str | None = None,
    timestamp: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[InternalTransfer]:
    """Synchronous convenience wrapper."""
    return self._run_sync(
        "internal_transfers", side, currency=currency, timestamp=timestamp, order=order, limit=limit
    )

rewards_sync

rewards_sync(
    *,
    reward_type=None,
    currency=None,
    timestamp=None,
    order=None,
    limit=None,
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def rewards_sync(
    self,
    *,
    reward_type: str | None = None,
    currency: str | None = None,
    timestamp: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[Reward]:
    """Synchronous convenience wrapper."""
    return self._run_sync(
        "rewards", reward_type=reward_type, currency=currency, timestamp=timestamp, order=order, limit=limit
    )

fund_transaction_deposits_sync

fund_transaction_deposits_sync(
    *, timestamp=None, order=None, limit=None
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def fund_transaction_deposits_sync(
    self, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[FundTransactionDeposit]:
    """Synchronous convenience wrapper."""
    return self._run_sync("fund_transaction_deposits", timestamp=timestamp, order=order, limit=limit)

fund_transaction_deposit_sync

fund_transaction_deposit_sync(sn)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def fund_transaction_deposit_sync(self, sn: str) -> FundTransactionDeposit:
    """Synchronous convenience wrapper."""
    return self._run_sync("fund_transaction_deposit", sn)

fund_transaction_withdrawals_sync

fund_transaction_withdrawals_sync(
    *, timestamp=None, order=None, limit=None
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def fund_transaction_withdrawals_sync(
    self, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[FundTransactionWithdrawal]:
    """Synchronous convenience wrapper."""
    return self._run_sync("fund_transaction_withdrawals", timestamp=timestamp, order=order, limit=limit)

fund_transaction_withdrawal_sync

fund_transaction_withdrawal_sync(sn)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def fund_transaction_withdrawal_sync(self, sn: str) -> FundTransactionWithdrawal:
    """Synchronous convenience wrapper."""
    return self._run_sync("fund_transaction_withdrawal", sn)

fund_transaction_transfers_sync

fund_transaction_transfers_sync(
    *, timestamp=None, order=None, limit=None
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def fund_transaction_transfers_sync(
    self, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[FundTransactionTransfer]:
    """Synchronous convenience wrapper."""
    return self._run_sync("fund_transaction_transfers", timestamp=timestamp, order=order, limit=limit)

fund_transaction_transfer_sync

fund_transaction_transfer_sync(sn)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def fund_transaction_transfer_sync(self, sn: str) -> FundTransactionTransfer:
    """Synchronous convenience wrapper."""
    return self._run_sync("fund_transaction_transfer", sn)

create_convert_sync

create_convert_sync(
    *,
    from_currency,
    to_currency,
    from_amount=None,
    to_amount=None,
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def create_convert_sync(
    self, *, from_currency: str, to_currency: str, from_amount: str | None = None, to_amount: str | None = None
) -> ConvertOrder:
    """Synchronous convenience wrapper."""
    return self._run_sync(
        "create_convert",
        from_currency=from_currency,
        to_currency=to_currency,
        from_amount=from_amount,
        to_amount=to_amount,
    )

convert_sync

convert_sync(sn)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def convert_sync(self, sn: str) -> ConvertOrder:
    """Synchronous convenience wrapper."""
    return self._run_sync("convert", sn)

converts_sync

converts_sync(*, timestamp=None, order=None, limit=None)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def converts_sync(
    self, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[ConvertOrder]:
    """Synchronous convenience wrapper."""
    return self._run_sync("converts", timestamp=timestamp, order=order, limit=limit)

m_wallet_index_prices_sync

m_wallet_index_prices_sync()

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def m_wallet_index_prices_sync(self) -> dict[str, str]:
    """Synchronous convenience wrapper."""
    return self._run_sync("m_wallet_index_prices")

m_wallet_historical_index_prices_sync

m_wallet_historical_index_prices_sync(
    market, *, start_time, end_time
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def m_wallet_historical_index_prices_sync(
    self, market: str, *, start_time: int, end_time: int
) -> list[HistoricalIndexPrice]:
    """Synchronous convenience wrapper."""
    return self._run_sync("m_wallet_historical_index_prices", market, start_time=start_time, end_time=end_time)

m_wallet_limits_sync

m_wallet_limits_sync()

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def m_wallet_limits_sync(self) -> dict[str, str]:
    """Synchronous convenience wrapper."""
    return self._run_sync("m_wallet_limits")

m_wallet_interest_rates_sync

m_wallet_interest_rates_sync()

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def m_wallet_interest_rates_sync(self) -> dict[str, InterestRate]:
    """Synchronous convenience wrapper."""
    return self._run_sync("m_wallet_interest_rates")

create_m_wallet_loan_sync

create_m_wallet_loan_sync(*, currency, amount)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def create_m_wallet_loan_sync(self, *, currency: str, amount: str) -> MWalletLoan:
    """Synchronous convenience wrapper."""
    return self._run_sync("create_m_wallet_loan", currency=currency, amount=amount)

m_wallet_loans_sync

m_wallet_loans_sync(
    currency, *, timestamp=None, order=None, limit=None
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def m_wallet_loans_sync(
    self, currency: str, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[MWalletLoan]:
    """Synchronous convenience wrapper."""
    return self._run_sync("m_wallet_loans", currency, timestamp=timestamp, order=order, limit=limit)

create_m_wallet_transfer_sync

create_m_wallet_transfer_sync(*, currency, amount, side)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def create_m_wallet_transfer_sync(self, *, currency: str, amount: str, side: str) -> MWalletTransfer:
    """Synchronous convenience wrapper."""
    return self._run_sync("create_m_wallet_transfer", currency=currency, amount=amount, side=side)

m_wallet_transfers_sync

m_wallet_transfers_sync(
    *,
    currency,
    side,
    timestamp=None,
    order=None,
    limit=None,
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def m_wallet_transfers_sync(
    self,
    *,
    currency: str,
    side: str,
    timestamp: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[MWalletTransfer]:
    """Synchronous convenience wrapper."""
    return self._run_sync(
        "m_wallet_transfers", currency=currency, side=side, timestamp=timestamp, order=order, limit=limit
    )

create_m_wallet_repayment_sync

create_m_wallet_repayment_sync(*, currency, amount)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def create_m_wallet_repayment_sync(self, *, currency: str, amount: str) -> MWalletRepayment:
    """Synchronous convenience wrapper."""
    return self._run_sync("create_m_wallet_repayment", currency=currency, amount=amount)

m_wallet_repayments_sync

m_wallet_repayments_sync(
    currency, *, timestamp=None, order=None, limit=None
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def m_wallet_repayments_sync(
    self, currency: str, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[MWalletRepayment]:
    """Synchronous convenience wrapper."""
    return self._run_sync("m_wallet_repayments", currency, timestamp=timestamp, order=order, limit=limit)

m_wallet_liquidations_sync

m_wallet_liquidations_sync(
    *, timestamp=None, order=None, limit=None
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def m_wallet_liquidations_sync(
    self, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[MWalletLiquidation]:
    """Synchronous convenience wrapper."""
    return self._run_sync("m_wallet_liquidations", timestamp=timestamp, order=order, limit=limit)

m_wallet_liquidation_sync

m_wallet_liquidation_sync(sn)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def m_wallet_liquidation_sync(self, sn: str) -> MWalletLiquidationDetail:
    """Synchronous convenience wrapper."""
    return self._run_sync("m_wallet_liquidation", sn)

m_wallet_interests_sync

m_wallet_interests_sync(
    *, currency=None, timestamp=None, order=None, limit=None
)

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def m_wallet_interests_sync(
    self,
    *,
    currency: str | None = None,
    timestamp: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[MWalletInterest]:
    """Synchronous convenience wrapper."""
    return self._run_sync("m_wallet_interests", currency=currency, timestamp=timestamp, order=order, limit=limit)

m_wallet_ad_ratio_sync

m_wallet_ad_ratio_sync()

Synchronous convenience wrapper.

Source code in src/maicoin/v3/client.py

def m_wallet_ad_ratio_sync(self) -> MWalletADRatio:
    """Synchronous convenience wrapper."""
    return self._run_sync("m_wallet_ad_ratio")

request async

request(method, path, params=None, *, auth=False)

Send a raw REST v3 request and return the parsed JSON payload.

Use this escape hatch when you need an endpoint that the typed wrappers below don't cover. Auth headers, nonce injection, and error handling work the same way as for the typed methods.

Parameters:

Name	Type	Description	Default
method	str	HTTP method, case-insensitive (e.g. "GET", "POST").	required
path	str	Request path. Leading / is added automatically.	required
params	Mapping[str, object] | None	Query parameters (GET) or JSON body (other methods). Use None values to omit a key — they are dropped before sending.	None
auth	bool	When True, sign the request with the configured credentials.	False

Returns:

Type	Description
object	The parsed JSON response, or None for empty bodies.

Raises:

Type	Description
ValueError	auth=True but the client has no credentials.
MaxHTTPError	Non-2xx HTTP response.
MaxAPIError	MAX-shaped error payload ({"error": {...}}).

Source code in src/maicoin/v3/client.py

async def request(
    self,
    method: str,
    path: str,
    params: Mapping[str, object] | None = None,
    *,
    auth: bool = False,
) -> object:
    """Send a raw REST v3 request and return the parsed JSON payload.

    Use this escape hatch when you need an endpoint that the typed
    wrappers below don't cover. Auth headers, nonce injection, and error
    handling work the same way as for the typed methods.

    Args:
        method: HTTP method, case-insensitive (e.g. `"GET"`, `"POST"`).
        path: Request path. Leading `/` is added automatically.
        params: Query parameters (GET) or JSON body (other methods).
            Use `None` values to omit a key — they are dropped before sending.
        auth: When `True`, sign the request with the configured credentials.

    Returns:
        The parsed JSON response, or `None` for empty bodies.

    Raises:
        ValueError: `auth=True` but the client has no credentials.
        MaxHTTPError: Non-2xx HTTP response.
        MaxAPIError: MAX-shaped error payload (`{"error": {...}}`).
    """
    normalized_method = method.upper()
    normalized_path = path if path.startswith("/") else f"/{path}"
    url = urljoin(self.base_url, normalized_path)
    request_params = dict(params or {})
    headers: dict[str, str] = {}

    if auth:
        if self.api_key is None or self.api_secret is None:
            msg = "api_key and api_secret are required for authenticated requests"
            raise ValueError(msg)
        nonce = self.nonce_factory()
        request_params = {"nonce": nonce, **request_params}
        headers.update(
            build_auth_headers(
                api_key=self.api_key,
                api_secret=self.api_secret,
                path=normalized_path,
                params=request_params,
                nonce=nonce,
            )
        )

    kwargs: dict[str, object] = {
        "headers": headers,
        "timeout": self.timeout,
    }
    if normalized_method == "GET":
        kwargs["params"] = request_params
    else:
        kwargs["json"] = request_params

    response = await self._request_with_retries(normalized_method, url, kwargs)
    raise_for_response_status(response)
    if not response.content:
        return None

    payload = response.json()
    raise_for_api_error(payload)
    return payload

markets async

markets()

List all available markets (GET /api/v3/markets).

Source code in src/maicoin/v3/client.py

async def markets(self) -> list[Market]:
    """List all available markets (`GET /api/v3/markets`)."""
    return await self._market_data.markets()

currencies async

currencies()

List all supported currencies, including network info (GET /api/v3/currencies).

Source code in src/maicoin/v3/client.py

async def currencies(self) -> list[Currency]:
    """List all supported currencies, including network info (`GET /api/v3/currencies`)."""
    return await self._market_data.currencies()

timestamp async

timestamp()

Return the server-side timestamp (GET /api/v3/timestamp).

Source code in src/maicoin/v3/client.py

async def timestamp(self) -> Timestamp:
    """Return the server-side timestamp (`GET /api/v3/timestamp`)."""
    return await self._market_data.timestamp()

kline async

kline(market, *, limit=30, period=1, timestamp=None)

Fetch OHLCV candles for market (GET /api/v3/k).

Source code in src/maicoin/v3/client.py

async def kline(
    self,
    market: str,
    *,
    limit: int = 30,
    period: int = 1,
    timestamp: int | None = None,
) -> list[KLine]:
    """Fetch OHLCV candles for `market` (`GET /api/v3/k`)."""
    return await self._market_data.kline(market, limit=limit, period=period, timestamp=timestamp)

depth async

depth(market, *, limit=None, sort_by_price=None)

Fetch the order book depth for market (GET /api/v3/depth).

Source code in src/maicoin/v3/client.py

async def depth(self, market: str, *, limit: int | None = None, sort_by_price: bool | None = None) -> Depth:
    """Fetch the order book depth for `market` (`GET /api/v3/depth`)."""
    return await self._market_data.depth(market, limit=limit, sort_by_price=sort_by_price)

trades async

trades(market, *, timestamp=None, limit=None)

Fetch recent public trades for market (GET /api/v3/trades).

Source code in src/maicoin/v3/client.py

async def trades(self, market: str, *, timestamp: int | None = None, limit: int | None = None) -> list[PublicTrade]:
    """Fetch recent public trades for `market` (`GET /api/v3/trades`)."""
    return await self._market_data.trades(market, timestamp=timestamp, limit=limit)

tickers async

tickers(markets)

Fetch tickers for several markets in one request (GET /api/v3/tickers).

Source code in src/maicoin/v3/client.py

async def tickers(self, markets: Sequence[str]) -> list[Ticker]:
    """Fetch tickers for several markets in one request (`GET /api/v3/tickers`)."""
    return await self._market_data.tickers(markets)

ticker async

ticker(market)

Fetch the ticker for a single market (GET /api/v3/ticker).

Source code in src/maicoin/v3/client.py

async def ticker(self, market: str) -> Ticker:
    """Fetch the ticker for a single market (`GET /api/v3/ticker`)."""
    return await self._market_data.ticker(market)

info async

info()

Return the authenticated user profile and VIP info (GET /api/v3/info).

Source code in src/maicoin/v3/client.py

async def info(self) -> UserInfo:
    """Return the authenticated user profile and VIP info (`GET /api/v3/info`)."""
    return await self._orders.info()

accounts async

accounts(*, wallet_type='spot', currency=None)

List wallet account balances.

Source code in src/maicoin/v3/client.py

async def accounts(self, *, wallet_type: str = "spot", currency: str | None = None) -> list[Account]:
    """List wallet account balances."""
    return await self._orders.accounts(wallet_type=wallet_type, currency=currency)

wallet_trades async

wallet_trades(
    *,
    wallet_type="spot",
    market=None,
    timestamp=None,
    from_id=None,
    order=None,
    limit=None,
)

List the authenticated user's trades for a wallet.

Source code in src/maicoin/v3/client.py

async def wallet_trades(
    self,
    *,
    wallet_type: str = "spot",
    market: str | None = None,
    timestamp: int | None = None,
    from_id: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[PrivateTrade]:
    """List the authenticated user's trades for a wallet."""
    return await self._orders.wallet_trades(
        wallet_type=wallet_type,
        market=market,
        timestamp=timestamp,
        from_id=from_id,
        order=order,
        limit=limit,
    )

open_orders async

open_orders(
    *,
    wallet_type="spot",
    market=None,
    timestamp=None,
    order_by=None,
    limit=None,
)

List the user's open orders.

Source code in src/maicoin/v3/client.py

async def open_orders(
    self,
    *,
    wallet_type: str = "spot",
    market: str | None = None,
    timestamp: int | None = None,
    order_by: str | None = None,
    limit: int | None = None,
) -> list[Order]:
    """List the user's open orders."""
    return await self._orders.open_orders(
        wallet_type=wallet_type, market=market, timestamp=timestamp, order_by=order_by, limit=limit
    )

closed_orders async

closed_orders(
    *,
    wallet_type="spot",
    market=None,
    timestamp=None,
    order_by=None,
    limit=None,
)

List the user's closed (filled or cancelled) orders.

Source code in src/maicoin/v3/client.py

async def closed_orders(
    self,
    *,
    wallet_type: str = "spot",
    market: str | None = None,
    timestamp: int | None = None,
    order_by: str | None = None,
    limit: int | None = None,
) -> list[Order]:
    """List the user's closed (filled or cancelled) orders."""
    return await self._orders.closed_orders(
        wallet_type=wallet_type, market=market, timestamp=timestamp, order_by=order_by, limit=limit
    )

order_history async

order_history(
    market, *, wallet_type="spot", from_id=None, limit=None
)

Page through the full order history for a market.

Source code in src/maicoin/v3/client.py

async def order_history(
    self,
    market: str,
    *,
    wallet_type: str = "spot",
    from_id: int | None = None,
    limit: int | None = None,
) -> list[Order]:
    """Page through the full order history for a market."""
    return await self._orders.order_history(market, wallet_type=wallet_type, from_id=from_id, limit=limit)

iter_wallet_trades async

iter_wallet_trades(
    *,
    wallet_type="spot",
    market=None,
    timestamp=None,
    from_id=None,
    order="asc",
    page_limit=100,
    max_items=None,
    max_pages=None,
)

Iterate wallet trades using the from_id cursor.

Source code in src/maicoin/v3/client.py

async def iter_wallet_trades(
    self,
    *,
    wallet_type: str = "spot",
    market: str | None = None,
    timestamp: int | None = None,
    from_id: int | None = None,
    order: str = "asc",
    page_limit: int = 100,
    max_items: int | None = None,
    max_pages: int | None = None,
) -> AsyncIterator[PrivateTrade]:
    """Iterate wallet trades using the `from_id` cursor."""
    async for trade in self._orders.iter_wallet_trades(
        wallet_type=wallet_type,
        market=market,
        timestamp=timestamp,
        from_id=from_id,
        order=order,
        page_limit=page_limit,
        max_items=max_items,
        max_pages=max_pages,
    ):
        yield trade

iter_order_history async

iter_order_history(
    market,
    *,
    wallet_type="spot",
    from_id=None,
    page_limit=100,
    max_items=None,
    max_pages=None,
)

Iterate order history using the from_id cursor.

Source code in src/maicoin/v3/client.py

async def iter_order_history(
    self,
    market: str,
    *,
    wallet_type: str = "spot",
    from_id: int | None = None,
    page_limit: int = 100,
    max_items: int | None = None,
    max_pages: int | None = None,
) -> AsyncIterator[Order]:
    """Iterate order history using the `from_id` cursor."""
    async for order_item in self._orders.iter_order_history(
        market,
        wallet_type=wallet_type,
        from_id=from_id,
        page_limit=page_limit,
        max_items=max_items,
        max_pages=max_pages,
    ):
        yield order_item

order async

order(*, order_id=None, client_oid=None)

Fetch a single order by order_id or client_oid.

Source code in src/maicoin/v3/client.py

async def order(self, *, order_id: int | None = None, client_oid: str | None = None) -> Order:
    """Fetch a single order by `order_id` or `client_oid`."""
    return await self._orders.order(order_id=order_id, client_oid=client_oid)

create_order async

create_order(
    market,
    side,
    volume,
    *,
    wallet_type="spot",
    price=None,
    client_oid=None,
    stop_price=None,
    ord_type=None,
    group_id=None,
)

Place a new order.

Source code in src/maicoin/v3/client.py

async def create_order(
    self,
    market: str,
    side: OrderSide | str,
    volume: str,
    *,
    wallet_type: str = "spot",
    price: str | None = None,
    client_oid: str | None = None,
    stop_price: str | None = None,
    ord_type: OrderType | str | None = None,
    group_id: int | None = None,
) -> Order:
    """Place a new order."""
    return await self._orders.create_order(
        market,
        side,
        volume,
        wallet_type=wallet_type,
        price=price,
        client_oid=client_oid,
        stop_price=stop_price,
        ord_type=ord_type,
        group_id=group_id,
    )

cancel_order async

cancel_order(*, order_id=None, client_oid=None)

Cancel an order by order_id or client_oid.

Source code in src/maicoin/v3/client.py

async def cancel_order(self, *, order_id: int | None = None, client_oid: str | None = None) -> Order:
    """Cancel an order by `order_id` or `client_oid`."""
    return await self._orders.cancel_order(order_id=order_id, client_oid=client_oid)

cancel_orders async

cancel_orders(
    *,
    wallet_type="spot",
    market=None,
    side=None,
    group_id=None,
)

Bulk-cancel orders. Filters compose: omit them all to cancel everything in the wallet.

Source code in src/maicoin/v3/client.py

async def cancel_orders(
    self,
    *,
    wallet_type: str = "spot",
    market: str | None = None,
    side: OrderSide | str | None = None,
    group_id: int | None = None,
) -> list[Order]:
    """Bulk-cancel orders. Filters compose: omit them all to cancel everything in the wallet."""
    return await self._orders.cancel_orders(wallet_type=wallet_type, market=market, side=side, group_id=group_id)

order_trades async

order_trades(*, order_id=None, client_oid=None)

List the executed trades for one order.

Source code in src/maicoin/v3/client.py

async def order_trades(self, *, order_id: int | None = None, client_oid: str | None = None) -> list[PrivateTrade]:
    """List the executed trades for one order."""
    return await self._orders.order_trades(order_id=order_id, client_oid=client_oid)

withdrawal async

withdrawal(uuid)

Look up a withdrawal by its uuid.

Source code in src/maicoin/v3/client.py

async def withdrawal(self, uuid: str) -> Withdrawal:
    """Look up a withdrawal by its `uuid`."""
    return await self._funds.withdrawal(uuid)

create_withdrawal async

create_withdrawal(*, withdraw_address_uuid, amount)

Submit a crypto withdrawal to a pre-approved address.

Source code in src/maicoin/v3/client.py

async def create_withdrawal(self, *, withdraw_address_uuid: str, amount: str) -> Withdrawal:
    """Submit a crypto withdrawal to a pre-approved address."""
    return await self._funds.create_withdrawal(withdraw_address_uuid=withdraw_address_uuid, amount=amount)

create_twd_withdrawal async

create_twd_withdrawal(amount)

Submit a TWD bank withdrawal.

Source code in src/maicoin/v3/client.py

async def create_twd_withdrawal(self, amount: str) -> Withdrawal:
    """Submit a TWD bank withdrawal."""
    return await self._funds.create_twd_withdrawal(amount)

withdrawals async

withdrawals(
    *,
    currency=None,
    state=None,
    timestamp=None,
    order=None,
    limit=None,
)

List withdrawal history.

Source code in src/maicoin/v3/client.py

async def withdrawals(
    self,
    *,
    currency: str | None = None,
    state: str | None = None,
    timestamp: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[Withdrawal]:
    """List withdrawal history."""
    return await self._funds.withdrawals(
        currency=currency, state=state, timestamp=timestamp, order=order, limit=limit
    )

withdraw_addresses async

withdraw_addresses(currency, *, limit=None, offset=None)

List the user's whitelisted withdrawal addresses for currency.

Source code in src/maicoin/v3/client.py

async def withdraw_addresses(
    self,
    currency: str,
    *,
    limit: int | None = None,
    offset: int | None = None,
) -> list[WithdrawAddress]:
    """List the user's whitelisted withdrawal addresses for `currency`."""
    return await self._funds.withdraw_addresses(currency, limit=limit, offset=offset)

deposit async

deposit(*, txid=None, uuid=None)

Look up a deposit by txid or uuid.

Source code in src/maicoin/v3/client.py

async def deposit(self, *, txid: str | None = None, uuid: str | None = None) -> Deposit:
    """Look up a deposit by `txid` or `uuid`."""
    return await self._funds.deposit(txid=txid, uuid=uuid)

deposits async

deposits(
    *, currency=None, timestamp=None, order=None, limit=None
)

List deposit history.

Source code in src/maicoin/v3/client.py

async def deposits(
    self,
    *,
    currency: str | None = None,
    timestamp: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[Deposit]:
    """List deposit history."""
    return await self._funds.deposits(currency=currency, timestamp=timestamp, order=order, limit=limit)

deposit_address async

deposit_address(currency_version)

Get the deposit address for a specific currency/network version.

Source code in src/maicoin/v3/client.py

async def deposit_address(self, currency_version: str) -> DepositAddress:
    """Get the deposit address for a specific currency/network version."""
    return await self._funds.deposit_address(currency_version)

internal_transfers async

internal_transfers(
    side,
    *,
    currency=None,
    timestamp=None,
    order=None,
    limit=None,
)

List internal transfers between MAX users.

Source code in src/maicoin/v3/client.py

async def internal_transfers(
    self,
    side: str,
    *,
    currency: str | None = None,
    timestamp: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[InternalTransfer]:
    """List internal transfers between MAX users."""
    return await self._funds.internal_transfers(
        side, currency=currency, timestamp=timestamp, order=order, limit=limit
    )

rewards async

rewards(
    *,
    reward_type=None,
    currency=None,
    timestamp=None,
    order=None,
    limit=None,
)

List reward history (referrals, mining, staking, etc.).

Source code in src/maicoin/v3/client.py

async def rewards(
    self,
    *,
    reward_type: str | None = None,
    currency: str | None = None,
    timestamp: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[Reward]:
    """List reward history (referrals, mining, staking, etc.)."""
    return await self._funds.rewards(
        reward_type=reward_type, currency=currency, timestamp=timestamp, order=order, limit=limit
    )

fund_transaction_deposits async

fund_transaction_deposits(
    *, timestamp=None, order=None, limit=None
)

List fund-transaction deposits (off-exchange settlement).

Source code in src/maicoin/v3/client.py

async def fund_transaction_deposits(
    self, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[FundTransactionDeposit]:
    """List fund-transaction deposits (off-exchange settlement)."""
    return await self._funds.fund_transaction_deposits(timestamp=timestamp, order=order, limit=limit)

fund_transaction_deposit async

fund_transaction_deposit(sn)

Look up a fund-transaction deposit by sn.

Source code in src/maicoin/v3/client.py

async def fund_transaction_deposit(self, sn: str) -> FundTransactionDeposit:
    """Look up a fund-transaction deposit by `sn`."""
    return await self._funds.fund_transaction_deposit(sn)

fund_transaction_withdrawals async

fund_transaction_withdrawals(
    *, timestamp=None, order=None, limit=None
)

List fund-transaction withdrawals.

Source code in src/maicoin/v3/client.py

async def fund_transaction_withdrawals(
    self, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[FundTransactionWithdrawal]:
    """List fund-transaction withdrawals."""
    return await self._funds.fund_transaction_withdrawals(timestamp=timestamp, order=order, limit=limit)

fund_transaction_withdrawal async

fund_transaction_withdrawal(sn)

Look up a fund-transaction withdrawal by sn.

Source code in src/maicoin/v3/client.py

async def fund_transaction_withdrawal(self, sn: str) -> FundTransactionWithdrawal:
    """Look up a fund-transaction withdrawal by `sn`."""
    return await self._funds.fund_transaction_withdrawal(sn)

fund_transaction_transfers async

fund_transaction_transfers(
    *, timestamp=None, order=None, limit=None
)

List fund-transaction transfers.

Source code in src/maicoin/v3/client.py

async def fund_transaction_transfers(
    self, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[FundTransactionTransfer]:
    """List fund-transaction transfers."""
    return await self._funds.fund_transaction_transfers(timestamp=timestamp, order=order, limit=limit)

fund_transaction_transfer async

fund_transaction_transfer(sn)

Look up a fund-transaction transfer by sn.

Source code in src/maicoin/v3/client.py

async def fund_transaction_transfer(self, sn: str) -> FundTransactionTransfer:
    """Look up a fund-transaction transfer by `sn`."""
    return await self._funds.fund_transaction_transfer(sn)

create_convert async

create_convert(
    *,
    from_currency,
    to_currency,
    from_amount=None,
    to_amount=None,
)

Submit a convert order between two currencies.

Source code in src/maicoin/v3/client.py

async def create_convert(
    self,
    *,
    from_currency: str,
    to_currency: str,
    from_amount: str | None = None,
    to_amount: str | None = None,
) -> ConvertOrder:
    """Submit a convert order between two currencies."""
    return await self._convert.create_convert(
        from_currency=from_currency, to_currency=to_currency, from_amount=from_amount, to_amount=to_amount
    )

convert async

convert(sn)

Look up a convert order by sn.

Source code in src/maicoin/v3/client.py

async def convert(self, sn: str) -> ConvertOrder:
    """Look up a convert order by `sn`."""
    return await self._convert.convert(sn)

converts async

converts(*, timestamp=None, order=None, limit=None)

List convert order history.

Source code in src/maicoin/v3/client.py

async def converts(
    self, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[ConvertOrder]:
    """List convert order history."""
    return await self._convert.converts(timestamp=timestamp, order=order, limit=limit)

m_wallet_index_prices async

m_wallet_index_prices()

Return current M-Wallet index prices keyed by market id.

Source code in src/maicoin/v3/client.py

async def m_wallet_index_prices(self) -> dict[str, str]:
    """Return current M-Wallet index prices keyed by market id."""
    return await self._m_wallet.m_wallet_index_prices()

m_wallet_historical_index_prices async

m_wallet_historical_index_prices(
    market, *, start_time, end_time
)

Fetch historical M-Wallet index prices for market.

Source code in src/maicoin/v3/client.py

async def m_wallet_historical_index_prices(
    self,
    market: str,
    *,
    start_time: int,
    end_time: int,
) -> list[HistoricalIndexPrice]:
    """Fetch historical M-Wallet index prices for `market`."""
    return await self._m_wallet.m_wallet_historical_index_prices(market, start_time=start_time, end_time=end_time)

m_wallet_limits async

m_wallet_limits()

Return per-currency M-Wallet borrow limits.

Source code in src/maicoin/v3/client.py

async def m_wallet_limits(self) -> dict[str, str]:
    """Return per-currency M-Wallet borrow limits."""
    return await self._m_wallet.m_wallet_limits()

m_wallet_interest_rates async

m_wallet_interest_rates()

Return current M-Wallet interest rates per currency.

Source code in src/maicoin/v3/client.py

async def m_wallet_interest_rates(self) -> dict[str, InterestRate]:
    """Return current M-Wallet interest rates per currency."""
    return await self._m_wallet.m_wallet_interest_rates()

create_m_wallet_loan async

create_m_wallet_loan(*, currency, amount)

Borrow amount of currency into the M-Wallet.

Source code in src/maicoin/v3/client.py

async def create_m_wallet_loan(self, *, currency: str, amount: str) -> MWalletLoan:
    """Borrow `amount` of `currency` into the M-Wallet."""
    return await self._m_wallet.create_m_wallet_loan(currency=currency, amount=amount)

m_wallet_loans async

m_wallet_loans(
    currency, *, timestamp=None, order=None, limit=None
)

List M-Wallet loans for currency.

Source code in src/maicoin/v3/client.py

async def m_wallet_loans(
    self, currency: str, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[MWalletLoan]:
    """List M-Wallet loans for `currency`."""
    return await self._m_wallet.m_wallet_loans(currency, timestamp=timestamp, order=order, limit=limit)

create_m_wallet_transfer async

create_m_wallet_transfer(*, currency, amount, side)

Transfer between spot and M-Wallet.

Source code in src/maicoin/v3/client.py

async def create_m_wallet_transfer(self, *, currency: str, amount: str, side: str) -> MWalletTransfer:
    """Transfer between spot and M-Wallet."""
    return await self._m_wallet.create_m_wallet_transfer(currency=currency, amount=amount, side=side)

m_wallet_transfers async

m_wallet_transfers(
    *,
    currency,
    side,
    timestamp=None,
    order=None,
    limit=None,
)

List M-Wallet transfer history.

Source code in src/maicoin/v3/client.py

async def m_wallet_transfers(
    self,
    *,
    currency: str,
    side: str,
    timestamp: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[MWalletTransfer]:
    """List M-Wallet transfer history."""
    return await self._m_wallet.m_wallet_transfers(
        currency=currency, side=side, timestamp=timestamp, order=order, limit=limit
    )

create_m_wallet_repayment async

create_m_wallet_repayment(*, currency, amount)

Repay an M-Wallet loan.

Source code in src/maicoin/v3/client.py

async def create_m_wallet_repayment(self, *, currency: str, amount: str) -> MWalletRepayment:
    """Repay an M-Wallet loan."""
    return await self._m_wallet.create_m_wallet_repayment(currency=currency, amount=amount)

m_wallet_repayments async

m_wallet_repayments(
    currency, *, timestamp=None, order=None, limit=None
)

List M-Wallet repayment history for currency.

Source code in src/maicoin/v3/client.py

async def m_wallet_repayments(
    self, currency: str, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[MWalletRepayment]:
    """List M-Wallet repayment history for `currency`."""
    return await self._m_wallet.m_wallet_repayments(currency, timestamp=timestamp, order=order, limit=limit)

m_wallet_liquidations async

m_wallet_liquidations(
    *, timestamp=None, order=None, limit=None
)

List M-Wallet liquidation events.

Source code in src/maicoin/v3/client.py

async def m_wallet_liquidations(
    self, *, timestamp: int | None = None, order: str | None = None, limit: int | None = None
) -> list[MWalletLiquidation]:
    """List M-Wallet liquidation events."""
    return await self._m_wallet.m_wallet_liquidations(timestamp=timestamp, order=order, limit=limit)

m_wallet_liquidation async

m_wallet_liquidation(sn)

Look up a single M-Wallet liquidation, including order/repayment details.

Source code in src/maicoin/v3/client.py

async def m_wallet_liquidation(self, sn: str) -> MWalletLiquidationDetail:
    """Look up a single M-Wallet liquidation, including order/repayment details."""
    return await self._m_wallet.m_wallet_liquidation(sn)

m_wallet_interests async

m_wallet_interests(
    *, currency=None, timestamp=None, order=None, limit=None
)

List M-Wallet interest accruals.

Source code in src/maicoin/v3/client.py

async def m_wallet_interests(
    self,
    *,
    currency: str | None = None,
    timestamp: int | None = None,
    order: str | None = None,
    limit: int | None = None,
) -> list[MWalletInterest]:
    """List M-Wallet interest accruals."""
    return await self._m_wallet.m_wallet_interests(currency=currency, timestamp=timestamp, order=order, limit=limit)

m_wallet_ad_ratio async

m_wallet_ad_ratio()

Return the M-Wallet account debt ratio (asset-to-debt and margin level).

Source code in src/maicoin/v3/client.py

async def m_wallet_ad_ratio(self) -> MWalletADRatio:
    """Return the M-Wallet account debt ratio (asset-to-debt and margin level)."""
    return await self._m_wallet.m_wallet_ad_ratio()

RequestSession

Bases: Protocol

Minimal HTTP session protocol used by Client.

Anything with a request(method, url, **kwargs) -> Response shape works, so you can swap in httpx.AsyncClient, a mocked session for tests, or a custom async transport.

request async

request(method, url, **kwargs)

Source code in src/maicoin/v3/client.py

async def request(self, method: str, url: str, **kwargs: object) -> Response: ...

Constants

BASE_URL module-attribute

BASE_URL = 'https://max-api.maicoin.com'

Default MAX REST v3 base URL.

DEFAULT_TIMEOUT module-attribute

DEFAULT_TIMEOUT = 10

Default per-request timeout in seconds.

Errors

MaxAPIError

MaxAPIError(message, *, status_code=None, payload=None)

Bases: Exception

Raised when MAX returns a structured {"error": ...} payload.

Attributes:

Name	Type	Description
status_code		HTTP status code, when known.
payload		Raw response body that triggered the error, useful for inspecting MAX's error.code / error.message fields.

Source code in src/maicoin/v3/errors.py

def __init__(self, message: str, *, status_code: int | None = None, payload: object = None) -> None:
    super().__init__(message)
    self.status_code = status_code
    self.payload = payload

status_code instance-attribute

status_code = status_code

payload instance-attribute

payload = payload

MaxHTTPError

MaxHTTPError(message, *, status_code=None, payload=None)

Bases: MaxAPIError

Raised for non-2xx HTTP responses without a recognized MAX error body.

Behaves like MaxAPIError — catch it as a subclass when you want to distinguish HTTP-level failures (network, rate-limit, gateway) from API-level failures.

Source code in src/maicoin/v3/errors.py

def __init__(self, message: str, *, status_code: int | None = None, payload: object = None) -> None:
    super().__init__(message)
    self.status_code = status_code
    self.payload = payload

Auth helpers

build_auth_headers

build_auth_headers(
    api_key, api_secret, path, params=None, nonce=None
)

Build the full set of MAX authentication headers for a request.

Parameters:

Name	Type	Description	Default
api_key	str	MAX API access key.	required
api_secret	str	MAX API secret.	required
path	str	Request path beginning with /.	required
params	Mapping[str, object] | None	Request parameters that will be sent (must match the payload actually transmitted, otherwise the signature is rejected).	None
nonce	int | None	Optional millisecond nonce. Generated when omitted.	None

Returns:

Type	Description
dict[str, str]	A dict containing X-MAX-ACCESSKEY, X-MAX-PAYLOAD,
dict[str, str]	X-MAX-SIGNATURE, and Content-Type: application/json.

Source code in src/maicoin/v3/auth.py

def build_auth_headers(
    api_key: str,
    api_secret: str,
    path: str,
    params: Mapping[str, object] | None = None,
    nonce: int | None = None,
) -> dict[str, str]:
    """Build the full set of MAX authentication headers for a request.

    Args:
        api_key: MAX API access key.
        api_secret: MAX API secret.
        path: Request path beginning with `/`.
        params: Request parameters that will be sent (must match the payload
            actually transmitted, otherwise the signature is rejected).
        nonce: Optional millisecond nonce. Generated when omitted.

    Returns:
        A dict containing `X-MAX-ACCESSKEY`, `X-MAX-PAYLOAD`,
        `X-MAX-SIGNATURE`, and `Content-Type: application/json`.
    """
    payload = encode_payload(path=path, params=params, nonce=nonce)
    return {
        "X-MAX-ACCESSKEY": api_key,
        "X-MAX-PAYLOAD": payload,
        "X-MAX-SIGNATURE": sign_payload(api_secret=api_secret, payload=payload),
        "Content-Type": "application/json",
    }

encode_payload

encode_payload(path, params=None, nonce=None)

Build the base64-encoded payload that goes in the X-MAX-PAYLOAD header.

Parameters:

Name	Type	Description	Default
path	str	Request path beginning with /, e.g. "/api/v3/info".	required
params	Mapping[str, object] | None	Request parameters merged into the payload (typically the query string for GET requests, or the JSON body for POST/DELETE).	None
nonce	int | None	Millisecond nonce. Generated via generate_nonce when omitted.	None

Returns:

Type	Description
str	Base64-encoded JSON ready to assign to X-MAX-PAYLOAD.

Source code in src/maicoin/v3/auth.py

def encode_payload(path: str, params: Mapping[str, object] | None = None, nonce: int | None = None) -> str:
    """Build the base64-encoded payload that goes in the `X-MAX-PAYLOAD` header.

    Args:
        path: Request path beginning with `/`, e.g. `"/api/v3/info"`.
        params: Request parameters merged into the payload (typically the
            query string for GET requests, or the JSON body for POST/DELETE).
        nonce: Millisecond nonce. Generated via [`generate_nonce`][maicoin.v3.generate_nonce]
            when omitted.

    Returns:
        Base64-encoded JSON ready to assign to `X-MAX-PAYLOAD`.
    """
    payload: dict[str, object] = {"nonce": generate_nonce() if nonce is None else nonce}
    if params is not None:
        payload.update(params)
    payload["path"] = path

    json_payload = orjson.dumps(payload)
    return base64.b64encode(json_payload).decode()

generate_nonce

generate_nonce()

Return the current UTC time as a millisecond UNIX nonce.

MAX rejects any nonce that is not strictly greater than the previous one used by the key, so reusing this helper across processes that share an API key can race. Pass a custom nonce_factory to Client if you need monotonic generation.

Source code in src/maicoin/v3/auth.py

def generate_nonce() -> int:
    """Return the current UTC time as a millisecond UNIX nonce.

    MAX rejects any nonce that is not strictly greater than the previous one
    used by the key, so reusing this helper across processes that share an API
    key can race. Pass a custom `nonce_factory` to [`Client`][maicoin.v3.Client]
    if you need monotonic generation.
    """
    return int(datetime.now(tz=UTC).timestamp() * 1000)

sign_payload

sign_payload(api_secret, payload)

Return the HMAC-SHA256 hex digest of payload keyed with api_secret.

The result is what MAX expects in the X-MAX-SIGNATURE header.

Source code in src/maicoin/v3/auth.py

def sign_payload(api_secret: str, payload: str) -> str:
    """Return the HMAC-SHA256 hex digest of `payload` keyed with `api_secret`.

    The result is what MAX expects in the `X-MAX-SIGNATURE` header.
    """
    return hmac.new(api_secret.encode(), payload.encode(), digestmod="sha256").hexdigest()

Models

Account

Bases: MaxBaseModel

balance instance-attribute

balance

currency instance-attribute

currency

interest class-attribute instance-attribute

interest = None

locked instance-attribute

locked

principal class-attribute instance-attribute

principal = None

staked class-attribute instance-attribute

staked = None

ConvertOrder

Bases: MaxBaseModel

created_at instance-attribute

created_at

fee instance-attribute

fee

fee_currency instance-attribute

fee_currency

fee_in_twd instance-attribute

fee_in_twd

from_amount instance-attribute

from_amount

from_currency instance-attribute

from_currency

sn instance-attribute

sn

to_amount instance-attribute

to_amount

to_currency instance-attribute

to_currency

Currency

Bases: MaxBaseModel

currency instance-attribute

currency

m_wallet_borrowable instance-attribute

m_wallet_borrowable

m_wallet_mortgageable instance-attribute

m_wallet_mortgageable

m_wallet_supported instance-attribute

m_wallet_supported

min_borrow_amount instance-attribute

min_borrow_amount

networks instance-attribute

networks

precision instance-attribute

precision

staking instance-attribute

staking

type instance-attribute

type

CurrencyNetwork

Bases: MaxBaseModel

deposit_confirmations instance-attribute

deposit_confirmations

deposit_enabled instance-attribute

deposit_enabled

id instance-attribute

id

min_withdrawal_amount instance-attribute

min_withdrawal_amount

need_memo instance-attribute

need_memo

network_congested instance-attribute

network_congested

network_protocol instance-attribute

network_protocol

precision instance-attribute

precision

token_contract_address instance-attribute

token_contract_address

withdrawal_enabled instance-attribute

withdrawal_enabled

withdrawal_fee instance-attribute

withdrawal_fee

Deposit

Bases: MaxBaseModel

amount instance-attribute

amount

confirmations instance-attribute

confirmations

created_at instance-attribute

created_at

currency instance-attribute

currency

network_protocol instance-attribute

network_protocol

state instance-attribute

state

state_reason instance-attribute

state_reason

to_address instance-attribute

to_address

txid instance-attribute

txid

uuid instance-attribute

uuid

DepositAddress

Bases: MaxBaseModel

address instance-attribute

address

currency instance-attribute

currency

currency_version instance-attribute

currency_version

network_protocol instance-attribute

network_protocol

Depth

Bases: MaxBaseModel

asks instance-attribute

asks

bids instance-attribute

bids

last_update_id class-attribute instance-attribute

last_update_id = None

last_update_version class-attribute instance-attribute

last_update_version = None

timestamp instance-attribute

timestamp

FundTransactionDeposit

Bases: MaxBaseModel

amount instance-attribute

amount

created_at instance-attribute

created_at

currency instance-attribute

currency

from_ class-attribute instance-attribute

from_ = Field(
    validation_alias="from", serialization_alias="from"
)

is_internal instance-attribute

is_internal

network_protocol instance-attribute

network_protocol

sn instance-attribute

sn

state instance-attribute

state

to_address instance-attribute

to_address

txid instance-attribute

txid

FundTransactionSource

Bases: MaxBaseModel

platform instance-attribute

platform

sn instance-attribute

sn

wallet_type instance-attribute

wallet_type

FundTransactionTransfer

Bases: MaxBaseModel

amount instance-attribute

amount

created_at instance-attribute

created_at

currency instance-attribute

currency

from_ class-attribute instance-attribute

from_ = Field(
    validation_alias="from", serialization_alias="from"
)

sn instance-attribute

sn

state instance-attribute

state

to instance-attribute

to

FundTransactionWithdrawal

Bases: MaxBaseModel

amount instance-attribute

amount

created_at instance-attribute

created_at

currency instance-attribute

currency

fee instance-attribute

fee

fee_currency instance-attribute

fee_currency

is_internal instance-attribute

is_internal

label instance-attribute

label

network_protocol instance-attribute

network_protocol

sn instance-attribute

sn

state instance-attribute

state

to instance-attribute

to

to_address instance-attribute

to_address

txid instance-attribute

txid

HistoricalIndexPrice

Bases: MaxBaseModel

price instance-attribute

price

timestamp instance-attribute

timestamp

InterestRate

Bases: MaxBaseModel

hourly_interest_rate instance-attribute

hourly_interest_rate

next_hourly_interest_rate instance-attribute

next_hourly_interest_rate

InternalTransfer

Bases: MaxBaseModel

amount instance-attribute

amount

created_at instance-attribute

created_at

currency instance-attribute

currency

from_ class-attribute instance-attribute

from_ = Field(
    validation_alias="from", serialization_alias="from"
)

state instance-attribute

state

to instance-attribute

to

uuid instance-attribute

uuid

KLine

Bases: MaxBaseModel

close instance-attribute

close

high instance-attribute

high

low instance-attribute

low

open instance-attribute

open

timestamp instance-attribute

timestamp

volume instance-attribute

volume

MWalletADRatio

Bases: MaxBaseModel

ad_ratio instance-attribute

ad_ratio

asset_in_usdt instance-attribute

asset_in_usdt

debt_in_usdt instance-attribute

debt_in_usdt

MWalletForcedLiquidation

Bases: MaxBaseModel

fee instance-attribute

fee

fee_currency instance-attribute

fee_currency

market instance-attribute

market

price instance-attribute

price

repayment instance-attribute

repayment

type instance-attribute

type

volume instance-attribute

volume

MWalletInterest

Bases: MaxBaseModel

amount instance-attribute

amount

created_at instance-attribute

created_at

currency instance-attribute

currency

interest_rate instance-attribute

interest_rate

principal instance-attribute

principal

MWalletLiquidation

Bases: MaxBaseModel

ad_ratio instance-attribute

ad_ratio

created_at instance-attribute

created_at

expected_ad_ratio instance-attribute

expected_ad_ratio

sn instance-attribute

sn

state instance-attribute

state

MWalletLiquidationDetail

Bases: MWalletLiquidation

liquidations instance-attribute

liquidations

repayments instance-attribute

repayments

MWalletLiquidationRepayment

Bases: MaxBaseModel

amount instance-attribute

amount

currency instance-attribute

currency

interest instance-attribute

interest

principal instance-attribute

principal

state instance-attribute

state

MWalletLoan

Bases: MaxBaseModel

amount instance-attribute

amount

created_at instance-attribute

created_at

currency instance-attribute

currency

interest_rate instance-attribute

interest_rate

sn instance-attribute

sn

state instance-attribute

state

MWalletRepayment

Bases: MaxBaseModel

amount instance-attribute

amount

created_at instance-attribute

created_at

currency instance-attribute

currency

interest instance-attribute

interest

principal instance-attribute

principal

sn instance-attribute

sn

state instance-attribute

state

MWalletTransfer

Bases: MaxBaseModel

amount instance-attribute

amount

created_at instance-attribute

created_at

currency instance-attribute

currency

side instance-attribute

side

sn instance-attribute

sn

state instance-attribute

state

Market

Bases: MaxBaseModel

base_unit instance-attribute

base_unit

base_unit_precision instance-attribute

base_unit_precision

id instance-attribute

id

m_wallet_supported instance-attribute

m_wallet_supported

min_base_amount instance-attribute

min_base_amount

min_quote_amount instance-attribute

min_quote_amount

quote_unit instance-attribute

quote_unit

quote_unit_precision instance-attribute

quote_unit_precision

status instance-attribute

status

MaxBaseModel

Bases: BaseModel

model_config class-attribute instance-attribute

model_config = ConfigDict(
    extra="allow", populate_by_name=True
)

Order

Bases: MaxBaseModel

avg_price instance-attribute

avg_price

client_oid class-attribute instance-attribute

client_oid = None

created_at instance-attribute

created_at

executed_volume instance-attribute

executed_volume

group_id class-attribute instance-attribute

group_id = None

id instance-attribute

id

market instance-attribute

market

ord_type instance-attribute

ord_type

price class-attribute instance-attribute

price = None

remaining_volume instance-attribute

remaining_volume

side instance-attribute

side

state instance-attribute

state

stop_price class-attribute instance-attribute

stop_price = None

trades_count instance-attribute

trades_count

updated_at instance-attribute

updated_at

volume instance-attribute

volume

wallet_type instance-attribute

wallet_type

OrderSide

Bases: StrEnum

BUY class-attribute instance-attribute

BUY = 'buy'

SELL class-attribute instance-attribute

SELL = 'sell'

OrderState

Bases: StrEnum

CANCEL class-attribute instance-attribute

CANCEL = 'cancel'

CONVERT class-attribute instance-attribute

CONVERT = 'convert'

DONE class-attribute instance-attribute

DONE = 'done'

WAIT class-attribute instance-attribute

WAIT = 'wait'

OrderType

Bases: StrEnum

IOC_LIMIT class-attribute instance-attribute

IOC_LIMIT = 'ioc_limit'

LIMIT class-attribute instance-attribute

LIMIT = 'limit'

MARKET class-attribute instance-attribute

MARKET = 'market'

POST_ONLY class-attribute instance-attribute

POST_ONLY = 'post_only'

STOP_LIMIT class-attribute instance-attribute

STOP_LIMIT = 'stop_limit'

STOP_MARKET class-attribute instance-attribute

STOP_MARKET = 'stop_market'

PrivateTrade

Bases: MaxBaseModel

created_at instance-attribute

created_at

fee class-attribute instance-attribute

fee = None

fee_currency class-attribute instance-attribute

fee_currency = None

fee_discounted class-attribute instance-attribute

fee_discounted = None

funds instance-attribute

funds

id instance-attribute

id

liquidity instance-attribute

liquidity

market instance-attribute

market

market_name instance-attribute

market_name

order_id instance-attribute

order_id

price instance-attribute

price

self_trade_bid_fee class-attribute instance-attribute

self_trade_bid_fee = None

self_trade_bid_fee_currency class-attribute instance-attribute

self_trade_bid_fee_currency = None

self_trade_bid_fee_discounted class-attribute instance-attribute

self_trade_bid_fee_discounted = None

self_trade_bid_order_id class-attribute instance-attribute

self_trade_bid_order_id = None

side instance-attribute

side

volume instance-attribute

volume

wallet_type instance-attribute

wallet_type

PublicTrade

Bases: MaxBaseModel

created_at instance-attribute

created_at

funds instance-attribute

funds

id instance-attribute

id

market instance-attribute

market

price instance-attribute

price

side instance-attribute

side

volume instance-attribute

volume

Reward

Bases: MaxBaseModel

amount instance-attribute

amount

created_at instance-attribute

created_at

currency instance-attribute

currency

note instance-attribute

note

type instance-attribute

type

uuid instance-attribute

uuid

Staking

Bases: MaxBaseModel

stake_flag instance-attribute

stake_flag

unstake_flag instance-attribute

unstake_flag

Ticker

Bases: MaxBaseModel

at instance-attribute

at

buy instance-attribute

buy

buy_vol instance-attribute

buy_vol

high instance-attribute

high

last instance-attribute

last

low instance-attribute

low

market instance-attribute

market

open instance-attribute

open

sell instance-attribute

sell

sell_vol instance-attribute

sell_vol

vol instance-attribute

vol

vol_in_btc instance-attribute

vol_in_btc

vol_in_quote instance-attribute

vol_in_quote

Timestamp

Bases: MaxBaseModel

timestamp instance-attribute

timestamp

UserInfo

Bases: MaxBaseModel

current_vip_level instance-attribute

current_vip_level

email instance-attribute

email

level instance-attribute

level

m_wallet_enabled class-attribute instance-attribute

m_wallet_enabled = None

next_vip_level instance-attribute

next_vip_level

VipLevel

Bases: MaxBaseModel

level instance-attribute

level

maker_fee instance-attribute

maker_fee

minimum_staking_volume instance-attribute

minimum_staking_volume

minimum_trading_volume instance-attribute

minimum_trading_volume

taker_fee instance-attribute

taker_fee

WithdrawAddress

Bases: MaxBaseModel

activated_at instance-attribute

activated_at

address instance-attribute

address

created_at instance-attribute

created_at

currency instance-attribute

currency

extra_label instance-attribute

extra_label

is_internal instance-attribute

is_internal

network_congested instance-attribute

network_congested

network_protocol instance-attribute

network_protocol

uuid instance-attribute

uuid

Withdrawal

Bases: MaxBaseModel

amount instance-attribute

amount

created_at instance-attribute

created_at

currency instance-attribute

currency

fee instance-attribute

fee

fee_currency instance-attribute

fee_currency

label instance-attribute

label

network_protocol instance-attribute

network_protocol

state instance-attribute

state

to_address instance-attribute

to_address

transaction_type instance-attribute

transaction_type

txid instance-attribute

txid

uuid instance-attribute

uuid