futures.market

async def candles(
  self,
  symbol: str,
  *,
  interval: Literal['Min1', 'Min5', 'Min15', 'Min30', 'Min60', 'Hour4', 'Hour8', 'Day1', 'Week1', 'Month1'] | None = None,
  start: Timestamp | None = None,
  end: Timestamp | None = None,
  validate: bool | None = None
) -> CandlesResponse:
  """Return contract K-line/candlestick series for a symbol and optional time window.

  Args:
    symbol: Contract symbol, for example BTC_USDT.
    interval: K-line interval: Min1, Min5, Min15, Min30, Min60, Hour4, Hour8, Day1, Week1, or Month1.
    start: Start timestamp in seconds.
    end: End timestamp in seconds.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#k-line-data)
  """
  params = {}
  if interval is not None:
    params['interval'] = interval
  if start is not None:
    params['start'] = ts.dump_s(start)
  if end is not None:
    params['end'] = ts.dump_s(end)
  r = await self.request('GET', '/api/v1/contract/kline/{symbol}'.replace('{symbol}', str(symbol)), params=params)
  return self.envelope_output(r.text, adapter, validate)

async def contract_info(
  self,
  *,
  symbol: str | None = None,
  validate: bool | None = None
) -> ContractInfoResponse:
  """Return contract metadata, optionally filtered to one futures contract.

  Args:
    symbol: Optional contract symbol filter, for example BTC_USDT.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-the-contract-information)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  r = await self.request('GET', '/api/v1/contract/detail', params=params)
  return self.envelope_output(r.text, adapter, validate)

async def deals(
  self,
  symbol: str,
  *,
  limit: int | None = None,
  validate: bool | None = None
) -> DealsResponse:
  """Return recent transaction/deal data for a contract.

  Args:
    symbol: Contract symbol, for example BTC_USDT.
    limit: Number of recent deals to return; maximum is 100 and default is 100.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-contract-transaction-data)
  """
  params = {}
  if limit is not None:
    params['limit'] = limit
  r = await self.request('GET', '/api/v1/contract/deals/{symbol}'.replace('{symbol}', str(symbol)), params=params)
  return self.envelope_output(r.text, adapter, validate)

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

  Args:
    symbol: Contract symbol, for example BTC_USDT.
    limit: Depth tier/level count to return.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-the-contract-s-depth-information)
  """
  params = {}
  if limit is not None:
    params['limit'] = limit
  r = await self.request('GET', '/api/v1/contract/depth/{symbol}'.replace('{symbol}', str(symbol)), params=params)
  return self.envelope_output(r.text, adapter, validate)

async def depth_commits(
  self,
  symbol: str,
  limit: int,
  *,
  validate: bool | None = None
) -> DepthCommitsResponse:
  """Return the latest N depth snapshots/commits for a contract.

  Args:
    symbol: Contract symbol, for example BTC_USDT.
    limit: Number of latest depth commits to return.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-a-snapshot-of-the-latest-n-depth-information-of-the-contract)
  """
  params = {}
  r = await self.request('GET', '/api/v1/contract/depth_commits/{symbol}/{limit}'.replace('{symbol}', str(symbol)).replace('{limit}', str(limit)))
  return self.envelope_output(r.text, adapter, validate)

async def fair_price(
  self,
  symbol: str,
  *,
  validate: bool | None = None
) -> FairPriceResponse:
  """Return the current fair price for a contract.

  Args:
    symbol: Contract symbol, for example BTC_USDT.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-contract-fair-price)
  """
  params = {}
  r = await self.request('GET', '/api/v1/contract/fair_price/{symbol}'.replace('{symbol}', str(symbol)))
  return self.envelope_output(r.text, adapter, validate)

async def fair_price_candles(
  self,
  symbol: str,
  *,
  interval: Literal['Min1', 'Min5', 'Min15', 'Min30', 'Min60', 'Hour4', 'Hour8', 'Day1', 'Week1', 'Month1'] | None = None,
  start: Timestamp | None = None,
  end: Timestamp | None = None,
  validate: bool | None = None
) -> FairPriceCandlesResponse:
  """Return fair-price K-line/candlestick series for a symbol and optional time window.

  Args:
    symbol: Contract symbol, for example BTC_USDT.
    interval: K-line interval: Min1, Min5, Min15, Min30, Min60, Hour4, Hour8, Day1, Week1, or Month1.
    start: Start timestamp in seconds.
    end: End timestamp in seconds.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-k-line-data-of-the-fair-price)
  """
  params = {}
  if interval is not None:
    params['interval'] = interval
  if start is not None:
    params['start'] = ts.dump_s(start)
  if end is not None:
    params['end'] = ts.dump_s(end)
  r = await self.request('GET', '/api/v1/contract/kline/fair_price/{symbol}'.replace('{symbol}', str(symbol)), params=params)
  return self.envelope_output(r.text, adapter, validate)

async def funding_rate(
  self,
  symbol: str,
  *,
  validate: bool | None = None
) -> FundingRateResponse:
  """Return the current funding-rate state for a contract.

  Args:
    symbol: Contract symbol, for example BTC_USDT.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-contract-funding-rate)
  """
  params = {}
  r = await self.request('GET', '/api/v1/contract/funding_rate/{symbol}'.replace('{symbol}', str(symbol)))
  return self.envelope_output(r.text, adapter, validate)

async def funding_rate_history(
  self,
  *,
  symbol: str,
  page_num: int,
  page_size: int,
  validate: bool | None = None
) -> FundingRateHistoryResponse:
  """Return paginated funding-rate history for a contract.

  Args:
    symbol: Contract symbol, for example BTC_USDT.
    page_num: Current page number; default is 1.
    page_size: Page size; default is 20 and maximum is 1000.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-contract-funding-rate-history)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  if page_num is not None:
    params['page_num'] = page_num
  if page_size is not None:
    params['page_size'] = page_size
  r = await self.request('GET', '/api/v1/contract/funding_rate/history', params=params)
  return self.envelope_output(r.text, adapter, validate)

async def funding_rate_history_paged(self, *, symbol: str, page_size: int, max_pages: int | None = None, validate: bool | None = None) -> AsyncIterator[FundingRateHistoryResponse]:
  """Yield pages from `funding_rate_history` until the response reports the final page."""
  page = 1
  while True:
    response = await self.funding_rate_history(symbol=symbol, page_size=page_size, page_num=page, validate=validate)
    yield response
    if max_pages is not None and page >= max_pages:
      break
    data = response.get('data') if isinstance(response, dict) else None
    total = None
    if isinstance(data, dict):
      total = data.get('totalPage') or data.get('totalPageNum')
    if total is None and isinstance(response, dict):
      total = response.get('totalPage') or response.get('totalPageNum')
    if total is None:
      if data == [] or response == []:
        break
      if max_pages is None:
        break
      page += 1
      continue
    if total is None or page >= total:
      break
    page += 1

async def index_price(
  self,
  symbol: str,
  *,
  validate: bool | None = None
) -> IndexPriceResponse:
  """Return the current index price for a contract.

  Args:
    symbol: Contract symbol, for example BTC_USDT.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-contract-index-price)
  """
  params = {}
  r = await self.request('GET', '/api/v1/contract/index_price/{symbol}'.replace('{symbol}', str(symbol)))
  return self.envelope_output(r.text, adapter, validate)

async def index_price_candles(
  self,
  symbol: str,
  *,
  interval: Literal['Min1', 'Min5', 'Min15', 'Min30', 'Min60', 'Hour4', 'Hour8', 'Day1', 'Week1', 'Month1'] | None = None,
  start: Timestamp | None = None,
  end: Timestamp | None = None,
  validate: bool | None = None
) -> IndexPriceCandlesResponse:
  """Return index-price K-line/candlestick series for a symbol and optional time window.

  Args:
    symbol: Contract symbol, for example BTC_USDT.
    interval: K-line interval: Min1, Min5, Min15, Min30, Min60, Hour4, Hour8, Day1, Week1, or Month1.
    start: Start timestamp in seconds.
    end: End timestamp in seconds.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-k-line-data-of-the-index-price)
  """
  params = {}
  if interval is not None:
    params['interval'] = interval
  if start is not None:
    params['start'] = ts.dump_s(start)
  if end is not None:
    params['end'] = ts.dump_s(end)
  r = await self.request('GET', '/api/v1/contract/kline/index_price/{symbol}'.replace('{symbol}', str(symbol)), params=params)
  return self.envelope_output(r.text, adapter, validate)

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

  Args:
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-the-server-time)
  """
  params = {}
  r = await self.request('GET', '/api/v1/contract/ping')
  return self.envelope_output(r.text, adapter, validate)

async def risk_reverse(self, *, validate: bool | None = None) -> RiskReverseResponse:
  """Return all contract risk fund balances.

  Args:
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-all-contract-risk-fund-balance)
  """
  params = {}
  r = await self.request('GET', '/api/v1/contract/risk_reverse')
  return self.envelope_output(r.text, adapter, validate)

async def risk_reverse_history(
  self,
  *,
  symbol: str,
  page_num: int,
  page_size: int,
  validate: bool | None = None
) -> RiskReverseHistoryResponse:
  """Return paginated risk fund balance history for a contract.

  Args:
    symbol: Contract symbol, for example BTC_USDT.
    page_num: Current page number; default is 1.
    page_size: Page size; default is 20 and maximum is 100.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-contract-risk-fund-balance-history)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  if page_num is not None:
    params['page_num'] = page_num
  if page_size is not None:
    params['page_size'] = page_size
  r = await self.request('GET', '/api/v1/contract/risk_reverse/history', params=params)
  return self.envelope_output(r.text, adapter, validate)

async def risk_reverse_history_paged(self, *, symbol: str, page_size: int, max_pages: int | None = None, validate: bool | None = None) -> AsyncIterator[RiskReverseHistoryResponse]:
  """Yield pages from `risk_reverse_history` until the response reports the final page."""
  page = 1
  while True:
    response = await self.risk_reverse_history(symbol=symbol, page_size=page_size, page_num=page, validate=validate)
    yield response
    if max_pages is not None and page >= max_pages:
      break
    data = response.get('data') if isinstance(response, dict) else None
    total = None
    if isinstance(data, dict):
      total = data.get('totalPage') or data.get('totalPageNum')
    if total is None and isinstance(response, dict):
      total = response.get('totalPage') or response.get('totalPageNum')
    if total is None:
      if data == [] or response == []:
        break
      if max_pages is None:
        break
      page += 1
      continue
    if total is None or page >= total:
      break
    page += 1

async def support_currencies(
  self,
  *,
  validate: bool | None = None
) -> SupportCurrenciesResponse:
  """Return currencies supported for futures transfers.

  Args:
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-the-transferable-currencies)
  """
  params = {}
  r = await self.request('GET', '/api/v1/contract/support_currencies')
  return self.envelope_output(r.text, adapter, validate)

async def ticker(
  self,
  *,
  symbol: str | None = None,
  validate: bool | None = None
) -> TickerResponse:
  """Return ticker/trend data, optionally filtered to one futures contract.

  Args:
    symbol: Optional contract symbol filter, for example BTC_USDT.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-contract-trend-data)
  """
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  r = await self.request('GET', '/api/v1/contract/ticker', params=params)
  return self.envelope_output(r.text, adapter, validate)