typed-mexc 0.2.0

A fully typed, validated async client for the MEXC API.

Typed MEXC

A fully typed, validated async client for the MEXC API

Use autocomplete instead of documentation.

from mexc import MEXC

async with MEXC.new() as client:
    account = await client.spot.account()
    for balance in account['balances']:
        if float(balance['free']) > 0:
            print(f"{balance['asset']}: {balance['free']}")

Why Typed MEXC?

• 🎯 Precise Types: Literal types, not strings. Your IDE knows exactly what's valid.
• ✅ Automatic Validation: Pydantic-powered response validation catches API changes instantly.
• ⚡ Async First: Built on httpx for high-performance async operations.
• 🔒 Type Safety: Full type hints throughout. Catch errors before runtime.
• 🎨 Beautiful DX: No unnecessary imports, sensible defaults, optional complexity.
• 📦 Batteries Included: Pagination helpers, WebSocket streams for real-time data.

Installation

pip install typed-mexc

Quick Start

1. Set up API credentials

export MEXC_ACCESS_KEY="your_access_key"
export MEXC_SECRET_KEY="your_secret_key"

2. Start trading

from mexc import MEXC

async with MEXC.new() as client:
    # Get spot account info
    account = await client.spot.account()
    
    # Get futures positions
    positions = await client.futures.positions()
    
    # Get funding rate
    rate = await client.futures.funding_rate(symbol='BTC_USDT')

Features

No Unnecessary Imports

Notice something? You never imported Literal types. Just use strings:

# ❌ Other libraries
from some_sdk import Interval
candles = await client.get_candles(symbol='BTCUSDT', interval=Interval.M1)

# ✅ Typed MEXC
candles = await client.spot.candles(
    'BTCUSDT', interval='1m'  # Your IDE autocompletes this!
)

Precise Type Annotations

Every field is precisely typed. Prices are strings (for precision), timestamps are datetime where applicable:

from datetime import datetime

account = await client.spot.account()
for balance in account['balances']:
    asset: str = balance['asset']
    free: str = balance['free']  # String for decimal precision

Automatic Validation

Response validation is on by default but can be disabled:

# Validated (default) - throws ValidationError if API response changes
account = await client.spot.account()

# Skip validation for maximum performance
account = await client.spot.account(validate=False)

Built-in Pagination

# Manual pagination
candles = await client.spot.candles(
    'BTCUSDT', interval='1m', limit=500
)

# Automatic pagination - yields chunks as they arrive
async for chunk in client.spot.candles_paged(
    'BTCUSDT', interval='1m', start=start, end=end
):
    for candle in chunk:
        print(f"Candle: {candle['open']} -> {candle['close']}")

WebSocket Streams

Real-time market and user data via WebSockets:

async with MEXC.new() as client:
    # Spot: subscribe to candles (public stream)
    async for candle in client.spot.streams.candles('BTCUSDT', interval='Min1'):
        print(candle)
    
    # Futures: subscribe to tickers
    async for tickers in client.futures.streams.tickers():
        print(tickers)

API Coverage

This library covers Spot and Futures with market data, trading, user data, and WebSocket streams.

• Spot: Account, candles, depth, trades, orders (place/cancel), wallet (deposits, withdrawals)
• Futures: Positions, assets, funding rates, contracts, candles, depth, user streams

📋 See API Overview for complete coverage details.

Documentation

• Quickstart Guide - Get up and running in 5 minutes
• Authentication - API credentials setup
• API Overview - Available endpoints and modules
• Examples - Common use cases and patterns
• Design Philosophy - Why we built it this way

Design Philosophy

Typed MEXC follows the principles outlined in this blog post:

1. Inputs shouldn't require custom imports - Use string literals, not enums
2. Annotate types precisely - TypedDict, strings for prices, Literal for enums
3. Avoid unnecessary complication - Sensible defaults, optional complexity
4. Provide extra behavior optionally - Pagination and validation are opt-in

Details matter. Developer experience matters.

Examples

Portfolio Tracking

async with MEXC.new() as client:
    account = await client.spot.account()
    
    total_held = sum(
        float(b['free']) + float(b['locked'])
        for b in account['balances']
        if float(b['free']) > 0 or float(b['locked']) > 0
    )
    print(f"Spot Balance: {total_held}")

Trading Bot

async with MEXC.new() as client:
    # Get open orders
    orders = await client.spot.open_orders(symbol='BTCUSDT')
    
    # Place limit order
    result = await client.spot.place_order(
        'BTCUSDT',
        {'side': 'BUY', 'type': 'LIMIT', 'price': '50000', 'quantity': '0.001'}
    )

Funding Rate Monitor

async with MEXC.new() as client:
    rate = await client.futures.funding_rate(symbol='BTC_USDT')
    print(f"Funding rate: {rate['fundingRate']}")

Error Handling

from mexc import MEXC
from mexc.core import ApiError, ValidationError, NetworkError

async with MEXC.new() as client:
    try:
        account = await client.spot.account()
    except ValidationError:
        # API response doesn't match expected schema
        pass
    except ApiError as e:
        # MEXC API returned an error
        print(f"API Error: {e}")
    except NetworkError:
        # Network/connection issue
        pass

Contributing

This is a work in progress! Contributions are welcome. The codebase is designed to be:

• Consistent: All endpoints follow the same patterns
• Type-safe: Everything is fully typed
• Validated: Pydantic models for all responses

---

Inspired by this blog post on building better API clients.

Built with ❤️ by Tribulnation