spot.market

async def agg_trades(
  self,
  *,
  symbol: str,
  limit: int | None = None,
  start_time: Timestamp | None = None,
  end_time: Timestamp | None = None,
  validate: bool | None = None
) -> list[AggTradesItem]:
  """Return aggregate public trades for a spot symbol.

  Args:
    symbol: Spot symbol.
    limit: Maximum number of aggregate trades.
    start_time: Start timestamp in milliseconds.
    end_time: End timestamp in milliseconds.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#compressed-aggregate-trades-list)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  if limit is not None:
    params['limit'] = limit
  if start_time is not None:
    params['startTime'] = ts.dump_ms(start_time)
  if end_time is not None:
    params['endTime'] = ts.dump_ms(end_time)
  r = await self.request('GET', '/api/v3/aggTrades', params=params)
  return self.output(r.text, adapter, validate)

async def avg_price(self, *, symbol: str, validate: bool | None = None) -> AvgPriceResponse:
  """Return current average price for a spot symbol.

  Args:
    symbol: Spot symbol.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#current-average-price)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  r = await self.request('GET', '/api/v3/avgPrice', params=params)
  return self.output(r.text, adapter, validate)

async def book_ticker(
  self,
  *,
  symbol: str | None = None,
  validate: bool | None = None
) -> BookTickerResponse | list[BookTickerListItem]:
  """Return best bid and ask for one spot symbol or all symbols.

  Args:
    symbol: Spot symbol. If omitted, returns all symbols.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#symbol-order-book-ticker)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  r = await self.request('GET', '/api/v3/ticker/bookTicker', params=params)
  return self.output(r.text, adapter, validate)

async def candles(
  self,
  *,
  symbol: str,
  interval: Literal['1m', '5m', '15m', '30m', '60m', '4h', '1d', '1W', '1M'],
  start_time: Timestamp | None = None,
  end_time: Timestamp | None = None,
  limit: int | None = None,
  validate: bool | None = None
) -> list[SpotCandle]:
  """Return spot kline/candlestick rows for a symbol.

  Args:
    symbol: Spot symbol.
    interval: Kline interval.
    start_time: Start timestamp in milliseconds.
    end_time: End timestamp in milliseconds.
    limit: Maximum number of candles.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#kline-candlestick-data)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  if interval is not None:
    params['interval'] = interval
  if start_time is not None:
    params['startTime'] = ts.dump_ms(start_time)
  if end_time is not None:
    params['endTime'] = ts.dump_ms(end_time)
  if limit is not None:
    params['limit'] = limit
  r = await self.request('GET', '/api/v3/klines', params=params)
  return self.output(r.text, adapter, validate)

async def default_symbols(
  self,
  *,
  validate: bool | None = None
) -> DefaultSymbolsResponse:
  """Return MEXC spot default symbols.

  Args:
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#api-default-symbol)
  """
  params = {}
  r = await self.request('GET', '/api/v3/defaultSymbols')
  return self.output(r.text, adapter, validate)

async def depth(
  self,
  *,
  symbol: str,
  limit: int | None = None,
  validate: bool | None = None
) -> OrderBook:
  """Return a spot order book snapshot for a symbol.

  Args:
    symbol: Spot symbol.
    limit: Number of bids and asks to return.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#order-book)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  if limit is not None:
    params['limit'] = limit
  r = await self.request('GET', '/api/v3/depth', params=params)
  return self.output(r.text, adapter, validate)

async def etf_info(
  self,
  *,
  symbol: str | None = None,
  validate: bool | None = None
) -> EtfInfoResponse | list[EtfInfoListItem]:
  """Return spot ETF information such as net value, leverage, and fund fee.

  Args:
    symbol: ETF symbol.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#etf-endpoints)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  r = await self.request('GET', '/api/v3/etf/info', params=params)
  return self.output(r.text, adapter, validate)

async def exchange_info(
  self,
  *,
  symbol: str | None = None,
  symbols: str | None = None,
  validate: bool | None = None
) -> ExchangeInfoResponse:
  """Return spot exchange metadata and symbol trading rules.

  Args:
    symbol: Single spot symbol to query.
    symbols: Comma-separated spot symbols to query.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#exchange-information)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  if symbols is not None:
    params['symbols'] = symbols
  r = await self.request('GET', '/api/v3/exchangeInfo', params=params)
  return self.output(r.text, adapter, validate)

async def historical_trades(
  self,
  *,
  symbol: str,
  limit: int | None = None,
  from_id: str | None = None,
  validate: bool | None = None
) -> list[HistoricalTradesItem]:
  """Return older public spot trades for a symbol.

  Args:
    symbol: Spot symbol.
    limit: Maximum number of trades to return.
    from_id: Trade id to fetch from.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#old-trade-lookup)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  if limit is not None:
    params['limit'] = limit
  if from_id is not None:
    params['fromId'] = from_id
  r = await self.request('GET', '/api/v3/historicalTrades', params=params)
  return self.output(r.text, adapter, validate)

async def historical_trades_paged(
  self, *,
  symbol: str,
  limit: int | None = None,
  from_id: str | None = None,
  max_pages: int | None = None,
  validate: bool | None = None,
) -> AsyncIterator[list[HistoricalTradesItem]]:
  """Yield historical trade pages by advancing the `fromId` cursor."""
  page = 0
  cursor = from_id
  while True:
    response = await self.historical_trades(symbol=symbol, limit=limit, from_id=cursor, validate=validate)
    yield response
    page += 1
    if max_pages is not None and page >= max_pages:
      break
    if not response or (limit is not None and len(response) < limit):
      break
    ids = [trade.get('id') for trade in response if trade.get('id') is not None]
    if not ids:
      break
    next_cursor = str(ids[-1])
    if next_cursor == cursor:
      break
    cursor = next_cursor

async def ping(self, *, validate: bool | None = None) -> PingResponse:
  """Test connectivity to the MEXC spot REST API.

  Args:
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#test-connectivity)
  """
  params = {}
  r = await self.request('GET', '/api/v3/ping')
  return self.output(r.text, adapter, validate)

async def ticker_24hr(
  self,
  *,
  symbol: str | None = None,
  validate: bool | None = None
) -> Ticker24hrStats | list[Ticker24hrStatsListItem]:
  """Return 24-hour ticker statistics for one spot symbol or all symbols.

  Args:
    symbol: Spot symbol. If omitted, returns all symbols.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#24hr-ticker-price-change-statistics)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  r = await self.request('GET', '/api/v3/ticker/24hr', params=params)
  return self.output(r.text, adapter, validate)

async def ticker_price(
  self,
  *,
  symbol: str | None = None,
  validate: bool | None = None
) -> TickerPriceResponse | list[TickerPriceListItem]:
  """Return latest price for one spot symbol or all symbols.

  Args:
    symbol: Spot symbol. If omitted, returns all symbols.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#symbol-price-ticker)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  r = await self.request('GET', '/api/v3/ticker/price', params=params)
  return self.output(r.text, adapter, validate)

async def time(self, *, validate: bool | None = None) -> TimeResponse:
  """Return the current MEXC spot server time.

  Args:
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#check-server-time)
  """
  params = {}
  r = await self.request('GET', '/api/v3/time')
  return self.output(r.text, adapter, validate)

async def trades(
  self,
  *,
  symbol: str,
  limit: int | None = None,
  validate: bool | None = None
) -> list[TradesItem]:
  """Return recent public trades for a spot symbol.

  Args:
    symbol: Spot symbol.
    limit: Maximum number of trades to return.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/spot_v3_en/#recent-trades-list)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  if limit is not None:
    params['limit'] = limit
  r = await self.request('GET', '/api/v3/trades', params=params)
  return self.output(r.text, adapter, validate)