futures.trade

async def batch_query(
  self,
  *,
  order_ids: str,
  validate: bool | None = None
) -> BatchQueryResponse:
  """Returns multiple futures orders for a comma-separated list of order ids.

  Args:
    order_ids: Comma-separated order ids; maximum 50 ids.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#query-the-order-in-bulk-based-on-the-order-number)
  """
  headers = {}
  params = {}
  if order_ids is not None:
    params['order_ids'] = order_ids
  r = await self.signed_request('GET', '/api/v1/private/order/batch_query', params=params or None, headers=headers)
  return self.envelope_output(r.text, adapter, validate)

async def cancel_all_orders(
  self,
  body: CancelAllOrdersRequest,
  *,
  validate: bool | None = None
) -> CancelAllOrdersResponse:
  """Cancels all uncompleted futures orders, optionally scoped to one contract symbol.

  Args:
    body: Request body.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#cancel-all-orders-under-a-contract-under-maintenance)
  """
  params = {}
  r = await self.signed_post('/api/v1/private/order/cancel_all', json=body)
  return self.envelope_output(r.text, adapter, validate)

async def cancel_all_plan(
  self,
  body: CancelAllPlanRequest,
  *,
  validate: bool | None = None
) -> CancelAllPlanResponse:
  """Cancels all uncompleted trigger orders, optionally scoped to a contract symbol.

  Args:
    body: Request body.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#cancel-all-trigger-orders-under-maintenance)
  """
  params = {}
  r = await self.signed_post('/api/v1/private/planorder/cancel_all', json=body)
  return self.envelope_output(r.text, adapter, validate)

async def cancel_all_stop(
  self,
  body: CancelAllStopRequest,
  *,
  validate: bool | None = None
) -> CancelAllStopResponse:
  """Cancels stop-limit trigger orders by position, by symbol, or across all symbols when no scope is provided.

  Args:
    body: Request body.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#cancel-all-stop-limit-price-trigger-orders-under-maintenance)
  """
  params = {}
  r = await self.signed_post('/api/v1/private/stoporder/cancel_all', json=body)
  return self.envelope_output(r.text, adapter, validate)

async def cancel_external_order(
  self,
  body: CancelExternalOrderRequest,
  *,
  validate: bool | None = None
) -> CancelExternalOrderResponse:
  """Cancels one uncompleted order under a contract by client-supplied external order id.

  Args:
    body: Request body.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#cancel-the-order-according-to-the-external-order-id-under-maintenance)
  """
  params = {}
  r = await self.signed_post('/api/v1/private/order/cancel_with_external', json=body)
  return self.envelope_output(r.text, adapter, validate)

async def cancel_order(
  self,
  listint_str: list[int | str],
  *,
  validate: bool | None = None
) -> CancelOrderResponse:
  """Cancels up to 50 pending futures orders by order id.

  Args:
    listint_str: Request parameter.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#cancel-the-order-under-maintenance)
  """
  params = {}
  r = await self.signed_post('/api/v1/private/order/cancel', json=listint_str)
  return self.envelope_output(r.text, adapter, validate)

async def cancel_plan(
  self,
  list_item: list[CancelPlanItem],
  *,
  validate: bool | None = None
) -> CancelPlanResponse:
  """Cancels up to 50 futures trigger orders.

  Args:
    list_item: Request parameter.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#cancel-the-trigger-order-under-maintenance)
  """
  params = {}
  r = await self.signed_post('/api/v1/private/planorder/cancel', json=list_item)
  return self.envelope_output(r.text, adapter, validate)

async def cancel_stop(
  self,
  list_item: list[CancelStopItem],
  *,
  validate: bool | None = None
) -> CancelStopResponse:
  """Cancels up to 50 futures stop-limit trigger orders by stop-plan order id.

  Args:
    list_item: Request parameter.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#cancel-the-stop-limit-trigger-order-under-maintenance)
  """
  params = {}
  r = await self.signed_post('/api/v1/private/stoporder/cancel', json=list_item)
  return self.envelope_output(r.text, adapter, validate)

async def change_stop_plan_price(
  self,
  body: ChangeStopPlanPriceRequest,
  *,
  validate: bool | None = None
) -> ChangeStopPlanPriceResponse:
  """Updates stop-loss and/or take-profit prices for a futures stop-limit trigger order.

  Args:
    body: Request body.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#switch-the-stop-limit-price-of-trigger-orders)
  """
  params = {}
  r = await self.signed_post('/api/v1/private/stoporder/change_plan_price', json=body)
  return self.envelope_output(r.text, adapter, validate)

async def change_stop_price(
  self,
  body: ChangeStopPriceRequest,
  *,
  validate: bool | None = None
) -> ChangeStopPriceResponse:
  """Updates or clears stop-loss and take-profit prices attached to a futures limit order.

  Args:
    body: Request body.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#switch-stop-limit-limited-order-price)
  """
  params = {}
  r = await self.signed_post('/api/v1/private/stoporder/change_price', json=body)
  return self.envelope_output(r.text, adapter, validate)

async def deal_details(
  self,
  order_id: str,
  *,
  validate: bool | None = None
) -> DealDetailsResponse:
  """Returns fills/deals for a futures order id.

  Args:
    order_id: Exchange order id.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#get-order-transaction-details-based-on-the-order-id)
  """
  headers = {}
  params = {}
  r = await self.signed_request('GET', '/api/v1/private/order/deal_details/{order_id}'.replace('{order_id}', str(order_id)), params=params or None, headers=headers)
  return self.envelope_output(r.text, adapter, validate)

async def external_order(
  self,
  symbol: str,
  external_oid: str,
  *,
  validate: bool | None = None
) -> ExternalOrderResponse:
  """Returns a futures order by contract symbol and client-provided external order id.

  Args:
    symbol: Contract symbol.
    external_oid: External order id.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#query-the-order-based-on-the-external-number)
  """
  headers = {}
  params = {}
  r = await self.signed_request('GET', '/api/v1/private/order/external/{symbol}/{external_oid}'.replace('{symbol}', str(symbol)).replace('{external_oid}', str(external_oid)), params=params or None, headers=headers)
  return self.envelope_output(r.text, adapter, validate)

async def history_orders(
  self,
  *,
  symbol: str | None = None,
  states: str | None = None,
  category: int | None = None,
  start_time: Timestamp | None = None,
  end_time: Timestamp | None = None,
  side: int | None = None,
  page_num: int,
  page_size: int,
  validate: bool | None = None
) -> HistoryOrdersResponse:
  """Returns paginated historical futures orders for the signed account.

  Args:
    symbol: Optional contract symbol filter.
    states: Comma-separated order states.
    category: Order category filter.
    start_time: Start time in milliseconds; maximum 90-day span with end_time.
    end_time: End time in milliseconds; maximum 90-day span with start_time.
    side: Order side filter.
    page_num: Page number; default is 1.
    page_size: Page size; default 20, maximum 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-all-of-the-user-39-s-historical-orders)
  """
  headers = {}
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  if states is not None:
    params['states'] = states
  if category is not None:
    params['category'] = category
  if start_time is not None:
    params['start_time'] = ts.dump_ms(start_time)
  if end_time is not None:
    params['end_time'] = ts.dump_ms(end_time)
  if side is not None:
    params['side'] = side
  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.signed_request('GET', '/api/v1/private/order/list/history_orders', params=params or None, headers=headers)
  return self.envelope_output(r.text, adapter, validate)

async def history_orders_paged(self, *, symbol: str | None = None, states: str | None = None, category: int | None = None, start_time: Timestamp | None = None, end_time: Timestamp | None = None, side: int | None = None, page_size: int, max_pages: int | None = None, validate: bool | None = None) -> AsyncIterator[HistoryOrdersResponse]:
  """Yield pages from `history_orders` until the response reports the final page."""
  page = 1
  while True:
    response = await self.history_orders(symbol=symbol, states=states, category=category, start_time=start_time, end_time=end_time, side=side, 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 open_orders(
  self,
  symbol: str,
  *,
  page_num: int,
  page_size: int,
  validate: bool | None = None
) -> OpenOrdersResponse:
  """Returns current pending futures orders for a contract or, when supported by upstream, all contracts.

  Args:
    symbol: Contract symbol path component; upstream notes all contracts when omitted, but the documented path contains this segment.
    page_num: Page number; default is 1.
    page_size: Page size; default 20, maximum 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-the-user-39-s-current-pending-order)
  """
  headers = {}
  params = {}
  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.signed_request('GET', '/api/v1/private/order/list/open_orders/{symbol}'.replace('{symbol}', str(symbol)), params=params or None, headers=headers)
  return self.envelope_output(r.text, adapter, validate)

async def open_orders_paged(self, symbol: str, *, page_size: int, max_pages: int | None = None, validate: bool | None = None) -> AsyncIterator[OpenOrdersResponse]:
  """Yield pages from `open_orders` until the response reports the final page."""
  page = 1
  while True:
    response = await self.open_orders(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 order(self, order_id: str, *, validate: bool | None = None) -> OrderResponse:
  """Returns a futures order by exchange order id.

  Args:
    order_id: Exchange order id.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#query-the-order-based-on-the-order-number)
  """
  headers = {}
  params = {}
  r = await self.signed_request('GET', '/api/v1/private/order/get/{order_id}'.replace('{order_id}', str(order_id)), params=params or None, headers=headers)
  return self.envelope_output(r.text, adapter, validate)

async def order_deals(
  self,
  *,
  symbol: str,
  start_time: Timestamp | None = None,
  end_time: Timestamp | None = None,
  page_num: int,
  page_size: int,
  validate: bool | None = None
) -> OrderDealsResponse:
  """Returns paginated futures order deal history for the signed account.

  Args:
    symbol: Contract symbol.
    start_time: Start time in milliseconds; default is the last 7 days and maximum span is 90 days.
    end_time: End time in milliseconds; maximum span is 90 days.
    page_num: Page number; default is 1.
    page_size: Page size; default 20, maximum 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-all-transaction-details-of-the-user-s-order)
  """
  headers = {}
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  if start_time is not None:
    params['start_time'] = ts.dump_ms(start_time)
  if end_time is not None:
    params['end_time'] = ts.dump_ms(end_time)
  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.signed_request('GET', '/api/v1/private/order/list/order_deals', params=params or None, headers=headers)
  return self.envelope_output(r.text, adapter, validate)

async def order_deals_paged(self, *, symbol: str, start_time: Timestamp | None = None, end_time: Timestamp | None = None, page_size: int, max_pages: int | None = None, validate: bool | None = None) -> AsyncIterator[OrderDealsResponse]:
  """Yield pages from `order_deals` until the response reports the final page."""
  page = 1
  while True:
    response = await self.order_deals(symbol=symbol, start_time=start_time, end_time=end_time, 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 place_plan(
  self,
  body: PlacePlanRequest,
  *,
  validate: bool | None = None
) -> PlacePlanResponse:
  """Places a futures trigger order with trigger price, trigger direction, execution cycle, and execution order type.

  Args:
    body: Request body.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#trigger-order-under-maintenance)
  """
  params = {}
  r = await self.signed_post('/api/v1/private/planorder/place', json=body)
  return self.envelope_output(r.text, adapter, validate)

async def plan_orders(
  self,
  *,
  symbol: str | None = None,
  states: str | None = None,
  start_time: Timestamp | None = None,
  end_time: Timestamp | None = None,
  page_num: int,
  page_size: int,
  validate: bool | None = None
) -> PlanOrdersResponse:
  """Returns paginated trigger/plan orders for the signed futures account.

  Args:
    symbol: Optional contract symbol filter.
    states: Comma-separated trigger order states.
    start_time: Start time in milliseconds; maximum span is 90 days.
    end_time: End time in milliseconds; maximum span is 90 days.
    page_num: Page number; default is 1.
    page_size: Page size; default 20, maximum 100.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#gets-the-trigger-order-list)
  """
  headers = {}
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  if states is not None:
    params['states'] = states
  if start_time is not None:
    params['start_time'] = ts.dump_ms(start_time)
  if end_time is not None:
    params['end_time'] = ts.dump_ms(end_time)
  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.signed_request('GET', '/api/v1/private/planorder/list/orders', params=params or None, headers=headers)
  return self.envelope_output(r.text, adapter, validate)

async def plan_orders_paged(self, *, symbol: str | None = None, states: str | None = None, start_time: Timestamp | None = None, end_time: Timestamp | None = None, page_size: int, max_pages: int | None = None, validate: bool | None = None) -> AsyncIterator[PlanOrdersResponse]:
  """Yield pages from `plan_orders` until the response reports the final page."""
  page = 1
  while True:
    response = await self.plan_orders(symbol=symbol, states=states, start_time=start_time, end_time=end_time, 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 stop_orders(
  self,
  *,
  symbol: str | None = None,
  is_finished: int | None = None,
  start_time: Timestamp | None = None,
  end_time: Timestamp | None = None,
  page_num: int,
  page_size: int,
  validate: bool | None = None
) -> StopOrdersResponse:
  """Returns paginated stop-limit trigger orders for the signed futures account.

  Args:
    symbol: Optional contract symbol filter.
    is_finished: Final-state filter: 0 unfinished, 1 finished.
    start_time: Start time in milliseconds; maximum span is 90 days.
    end_time: End time in milliseconds; maximum span is 90 days.
    page_num: Page number; default is 1.
    page_size: Page size; default 20, maximum 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-the-stop-limit-order-list)
  """
  headers = {}
  params = {}
  if symbol is not None:
    params['symbol'] = symbol
  if is_finished is not None:
    params['is_finished'] = is_finished
  if start_time is not None:
    params['start_time'] = ts.dump_ms(start_time)
  if end_time is not None:
    params['end_time'] = ts.dump_ms(end_time)
  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.signed_request('GET', '/api/v1/private/stoporder/list/orders', params=params or None, headers=headers)
  return self.envelope_output(r.text, adapter, validate)

async def stop_orders_paged(self, *, symbol: str | None = None, is_finished: int | None = None, start_time: Timestamp | None = None, end_time: Timestamp | None = None, page_size: int, max_pages: int | None = None, validate: bool | None = None) -> AsyncIterator[StopOrdersResponse]:
  """Yield pages from `stop_orders` until the response reports the final page."""
  page = 1
  while True:
    response = await self.stop_orders(symbol=symbol, is_finished=is_finished, start_time=start_time, end_time=end_time, 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 submit_batch(
  self,
  list_body_item: list[SubmitBatchRequestItem],
  *,
  validate: bool | None = None
) -> SubmitBatchResponse:
  """Places up to 50 futures orders in one request when the endpoint and account permission are available.

  Args:
    list_body_item: Request parameter.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#bulk-order-under-maintenance)
  """
  params = {}
  r = await self.signed_post('/api/v1/private/order/submit_batch', json=list_body_item)
  return self.envelope_output(r.text, adapter, validate)

async def submit_order(
  self,
  body: SubmitOrderRequest,
  *,
  validate: bool | None = None
) -> SubmitOrderResponse:
  """Places a futures limit, market, or post-only order when the endpoint is available and the account has sufficient margin.

  Args:
    body: Request body.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [MEXC API docs](https://mexcdevelop.github.io/apidocs/contract_v1_en/#order-under-maintenance)
  """
  params = {}
  r = await self.signed_post('/api/v1/private/order/submit', json=body)
  return self.envelope_output(r.text, adapter, validate)