IndexerData

async def get_markets(
  self, market: str | None = None, *, limit: int | None = None, validate: bool | None = None,
) -> dict[str, PerpetualMarket]:
  """Retrieves perpetual markets.

  - `market`: The specific market ticker to retrieve (e.g. `'BTC-USD'`). If not provided, all markets are returned.
  - `limit`: 	Maximum number of asset positions to return in the response.
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-perpetual-markets)
  """
  params = {}
  if market is not None:
    params['market'] = market
  if limit is not None:
    params['limit'] = limit
  r = await self.request('GET', '/v4/perpetualMarkets', params=params)
  return parse_response(r, validate=self.validate(validate))['markets']

async def get_market(
  self, market: str, *, validate: bool | None = None,
) -> PerpetualMarket:
  """Retrieves perpetual markets.

  - `market`: The specific market ticker to retrieve (e.g. `'BTC-USD'`). If not provided, all markets are returned.
  - `limit`: 	Maximum number of asset positions to return in the response.
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-perpetual-markets)
  """
  r = await self.get_markets(market, limit=1, validate=validate)
  return r[market]

async def get_order_book(self, market: str, /, *, validate: bool | None = None) -> Book:
  """Retrieves the orderbook for a specific perpetual market.

  - `market`: The market ticker (e.g. `'BTC-USD'`).
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-perpetual-market-orderbook)
  """
  r = await self.request('GET', f'/v4/orderbooks/perpetualMarket/{market}')
  return parse_response(r, validate=self.validate(validate))

async def get_trades(
  self, market: str, *,
  start_height: int | None = None,
  limit: int | None = None,
  validate: bool | None = None,
) -> list[Trade]:
  """Retrieves trades for a specific perpetual market.

  - `market`: The market ticker (e.g. `'BTC-USD'`).
  - `start_height`: The block height to start retrieving trades from.
  - `limit`: The max. number of trades to retrieve (default: 1000, max: 1000).
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-trades)
  """
  params = {}
  if start_height is not None:
    params['startingBeforeOrAtHeight'] = start_height
  if limit is not None:
    params['limit'] = limit
  r = await self.request('GET', f'/v4/trades/perpetualMarket/{market}', params=params)
  return parse_response(r, validate=self.validate(validate))['trades']

async def get_candles(
  self, market: str, resolution: Resolution, *,
  start: datetime | None = None,
  end: datetime | None = None,
  limit: int | None = None,
  validate: bool | None = None,
) -> list[Candle]:
  """Retrieves candle data for a specific perpetual market.

  - `market`: The market ticker (e.g. `'BTC-USD'`).
  - `resolution`: The resolution of the candles.
  - `start`: If given, fetches candles starting from the given timestamp.
  - `end`: If given, fetches candles up to the given timestamp.
  - `limit`: The max. number of candles to retrieve (default: 1000, max: 1000).
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-candles)
  """
  params: dict = {'resolution': resolution}
  if start is not None:
    params['fromISO'] = ts.dump(start)
  if end is not None:
    params['toISO'] = ts.dump(end)
  if limit is not None:
    params['limit'] = limit
  r = await self.request('GET', f'/v4/candles/perpetualMarkets/{market}', params=params)
  return parse_response(r, validate=self.validate(validate))['candles']

async def get_candles_paged(
  self, market: str, resolution: Resolution, *,
  start: datetime | None = None,
  end: datetime | None = None,
  limit: int | None = None,
) -> AsyncIterable[Sequence[Candle]]:
  """Retrieves candle data for a specific perpetual market, paging as needed.

  - `market`: The market ticker (e.g. `'BTC-USD'`).
  - `resolution`: The resolution of the candles.
  - `start`: If given, fetches candles starting from the given timestamp.
  - `end`: If given, fetches candles up to and including the given timestamp.
  - `limit`: The max. number of candles to retrieve per request (default: 1000, max: 1000).
  """
  last_time = end
  while True:
    candles = await self.get_candles(market, resolution, start=start, end=last_time, limit=limit)
    if candles:
      break
    yield candles
    last_time = ts.parse(candles[-1]['startedAt'])

async def get_subaccount(
  self, address: str, *,
  subaccount: int = 0,
  validate: bool | None = None,
) -> Subaccount:
  """Retrieves a specific subaccount associated with a given address and subaccount number.

  - `address`: The address of the subaccount.
  - `subaccount`: The subaccount number.
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-subaccount)
  """
  params = {}
  r = await self.request('GET', f'/v4/addresses/{address}/subaccountNumber/{subaccount}', params=params)
  return parse_response(r, validate=self.validate(validate))['subaccount']

async def get_subaccounts(
  self, address: str, *,
  limit: int | None = None,
  validate: bool | None = None,
) -> list[Subaccount]:
  """Retrieves a list of subaccounts associated with a given address. Subaccounts are related addresses that fall under the authority or ownership of the primary address.

  - `address`: The address of the subaccount.
  - `limit`: The max. number of subaccounts to retrieve.
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-subaccounts)
  """
  params = {}
  if limit is not None:
    params['limit'] = limit
  r = await self.request('GET', f'/v4/addresses/{address}', params=params)
  return parse_response(r, validate=self.validate(validate))['subaccounts']

async def get_fills(
  self, address: str, *,
  subaccount: int = 0,
  market: str | None = None,
  market_type: MarketType | None = None,
  end_height: int | None = None,
  end: datetime | None = None,
  limit: int | None = None,
  page: int | None = None,
  validate: bool | None = None,
) -> list[Fill]:
  """Retrieves fill records for a specific subaccount on the exchange. A fill represents a trade that has been executed.

  - `address`: The wallet address that owns the account.
  - `subaccount`: The identifier for the specific subaccount within the wallet address.
  - `market`: The market name (e.g. `'BTC-USD'`).
  - `market_type`: The market type (`'PERPETUAL'` or `'SPOT'`). Must be provided if `market` is provided.
  - `end_height`: If given, fetches fills up to and including the given block height.
  - `end`: If given, fetches fills up to and including the given timestamp.
  - `limit`: The max. number of fills to retrieve (default: 1000, max: 1000).
  - `page`: 	The page number for paginated results (default: 1).
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-fills)
  """
  params = {'address': address, 'subaccountNumber': subaccount}
  if market is not None:
    params['market'] = market
  if market_type is not None:
    params['marketType'] = market_type
  if end_height is not None:
    params['createdBeforeOrAtHeight'] = end_height
  if end is not None:
    params['createdBeforeOrAt'] = ts.dump(end)
  if limit is not None:
    params['limit'] = limit
  if page is not None:
    params['page'] = page
  r = await self.request('GET', '/v4/fills', params=params)
  return parse_response(r, validate=self.validate(validate))['fills']

async def get_fills_paged(
  self, address: str, *,
  subaccount: int = 0,
  market: str | None = None,
  market_type: MarketType | None = None,
  end_height: int | None = None,
  end: datetime | None = None,
  limit: int | None = None,
  validate: bool | None = None,
) -> AsyncIterable[list[Fill]]:
  """Retrieves fill records for a specific subaccount on the exchange. A fill represents a trade that has been executed.

  - `address`: The wallet address that owns the account.
  - `subaccount`: The identifier for the specific subaccount within the wallet address.
  - `market`: The market name (e.g. `'BTC-USD'`).
  - `market_type`: The market type (`'PERPETUAL'` or `'SPOT'`). Must be provided if `market` is provided.
  - `end_height`: If given, fetches fills up to and including the given block height.
  - `end`: If given, fetches fills up to and including the given timestamp.
  - `limit`: The max. number of fills to retrieve (default: 1000, max: 1000).
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-fills)
  """
  page = 1
  while True:
    fills = await self.get_fills(address, subaccount=subaccount, market=market, market_type=market_type, end_height=end_height, end=end, limit=limit, page=page, validate=validate)
    if not fills:
      break
    yield fills
    page += 1

async def get_funding_payments(
  self, address: str, *,
  subaccount: int = 0,
  ticker: str | None = None,
  start: datetime | None = None,
  limit: int | None = None,
  page: int | None = None,
  validate: bool | None = None,
) -> list[FundingPayment]:
  """Retrieves funding payment history for a specific subaccount. Funding payments are periodic settlements that occur between long and short positions based on the funding rate.

  - `address`: The wallet address that owns the account.
  - `subaccount`: The identifier for the specific subaccount within the wallet address.
  - `ticker`: The market ticker (e.g. `'BTC-USD'`).
  - `start`: If given, fetches funding payments starting from the given timestamp.
  - `limit`: The max. number of funding payments to retrieve.
  - `page`: 	The page number for paginated results (default: 1).
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-funding-payments)
  """
  params = {'address': address, 'subaccountNumber': subaccount}
  if ticker is not None:
    params['ticker'] = ticker
  if start is not None:
    params['afterOrAt'] = ts.dump(start)
  if limit is not None:
    params['limit'] = limit
  if page is not None:
    params['page'] = page
  r = await self.request('GET', '/v4/fundingPayments', params=params)
  return parse_response(r, validate=self.validate(validate))['fundingPayments']

async def get_funding_payments_paged(
  self, address: str, *,
  subaccount: int = 0,
  ticker: str | None = None,
  start: datetime | None = None,
  limit: int | None = None,
  validate: bool | None = None,
) -> AsyncIterable[list[FundingPayment]]:
  """Retrieves funding payment history for a specific subaccount. Funding payments are periodic settlements that occur between long and short positions based on the funding rate.

  - `address`: The wallet address that owns the account.
  - `subaccount`: The identifier for the specific subaccount within the wallet address.
  - `ticker`: The market ticker (e.g. `'BTC-USD'`).
  - `start`: If given, fetches funding payments starting from the given timestamp.
  - `limit`: The max. number of funding payments to retrieve.
  - `page`: 	The page number for paginated results (default: 1).
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-funding-payments)
  """
  page = 1
  while True:
    funding_payments = await self.get_funding_payments(address, subaccount=subaccount, ticker=ticker, start=start, limit=limit, page=page, validate=validate)
    if not funding_payments:
      break
    yield funding_payments
    page += 1

async def get_transfers(
  self, address: str, *,
  subaccount: int = 0,
  end_height: int | None = None,
  end: datetime | None = None,
  limit: int | None = None,
  page: int | None = None,
  validate: bool | None = None,
) -> list[Transfer]:
  """Retrieves the transfer history for a specific subaccount.

  - `address`: The wallet address that owns the account.
  - `subaccount`: The identifier for the specific subaccount within the wallet address.
  - `end_height`: If given, fetches transfers up to and including the given block height.
  - `end`: If given, fetches transfers up to and including the given timestamp.
  - `limit`: The max. number of transfers to retrieve (default: 1000, max: 1000).
  - `page`: 	The page number for paginated results (default: 1).
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-transfers)
  """
  params = {'address': address, 'subaccountNumber': subaccount}
  if end_height is not None:
    params['createdBeforeOrAtHeight'] = end_height
  if end is not None:
    params['createdBeforeOrAt'] = ts.dump(end)
  if limit is not None:
    params['limit'] = limit
  if page is not None:
    params['page'] = page
  r = await self.request('GET', '/v4/transfers', params=params)
  return parse_response(r, validate=self.validate(validate))['transfers']

async def get_transfers_paged(
  self, address: str, *,
  subaccount: int = 0,
  end_height: int | None = None,
  end: datetime | None = None,
  limit: int | None = None,
  validate: bool | None = None,
) -> AsyncIterable[list[Transfer]]:
  """Retrieves the transfer history for a specific subaccount.

  - `address`: The wallet address that owns the account.
  - `subaccount`: The identifier for the specific subaccount within the wallet address.
  - `end_height`: If given, fetches transfers up to and including the given block height.
  - `end`: If given, fetches transfers up to and including the given timestamp.
  - `limit`: The max. number of transfers to retrieve (default: 1000, max: 1000).
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-transfers)
  """
  page = 1
  while True:
    transfers = await self.get_transfers(address, subaccount=subaccount, end_height=end_height, end=end, limit=limit, page=page, validate=validate)
    if not transfers:
      break
    yield transfers
    page += 1

async def list_orders(
  self, address: str, *,
  subaccount: int = 0,
  limit: int | None = None,
  ticker: str | None = None,
  side: OrderSide | None = None,
  status: OrderStatus | None = None,
  type: OrderType | None = None,
  good_til_block_end: int | None = None,
  good_til_block_time_end: datetime | None = None,
  latest_only: bool | None = None,
  validate: bool | None = None,
) -> list[OrderState]:
  """Retrieves orders for a specific subaccount, with various filtering options to narrow down the results based on order characteristics.

  - `address`: The wallet address that owns the account.
  - `subaccount`: The identifier for the specific subaccount within the wallet address.
  - `limit`: Maximum number of asset positions to return in the response.
  - `ticker`: The ticker filter.
  - `side`: The order side filter (LONG or SHORT).
  - `status`: The order status filter (Open, Filled, Canceled, etc).
  - `type`: The order type filter (LIMIT, MARKET, STOP_LIMIT, etc).
  - `good_til_block_end`: The block number filter for orders good until before or at.
  - `good_til_block_time_end`: The timestamp filter for orders good until before or at (UTC).
  - `latest_only`: Whether to return only the latest orders.
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#list-orders)
  """
  params = {'address': address, 'subaccountNumber': subaccount}
  if limit is not None:
    params['limit'] = limit
  if ticker is not None:
    params['ticker'] = ticker
  if side is not None:
    params['side'] = side
  if status is not None:
    params['status'] = status
  if type is not None:
    params['type'] = type
  if good_til_block_end is not None:
    params['goodTilBlockBeforeOrAt'] = good_til_block_end
  if good_til_block_time_end is not None:
    params['goodTilBlockTimeBeforeOrAt'] = good_til_block_time_end
  if latest_only is not None:
    params['returnLatestOrders'] = latest_only
  r = await self.request('GET', '/v4/orders', params=params)
  return parse_response(r, validate=self.validate(validate))

async def get_order(self, id: str, *, validate: bool | None = None) -> OrderState:
  """Retrieves detailed information about a specific order based on its unique identifier (the order ID).

  - `id`: The ID of the order to retrieve.
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-order)
  """
  r = await self.request('GET', f'/v4/orders/{id}')
  return parse_response(r, validate=self.validate(validate))

async def list_positions(
  self, address: str, *,
  subaccount: int = 0,
  status: PerpetualPositionStatus | None = None,
  limit: int | None = None,
  end_height: int | None = None,
  end: datetime | None = None,
  validate: bool | None = None,
) -> list[PerpetualPosition]:
  """Retrieves perpetual positions for a specific subaccount. Both open and closed/historical positions can be queried.

  - `address`: The wallet address that owns the account.
  - `subaccount`: The identifier for the specific subaccount within the wallet address.
  - `status`: Status filter.
  - `limit`: Maximum number of perpetual positions to return in the response.
  - `end_height`: Restricts results to positions created at or before a specific blockchain height.
  - `end`: 	Restricts results to positions created at or before a specific timestamp.
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#list-positions)
  """
  params = {'address': address, 'subaccountNumber': subaccount}
  if status is not None:
    params['status'] = status
  if limit is not None:
    params['limit'] = limit
  if end_height is not None:
    params['createdBeforeOrAtHeight'] = end_height
  if end is not None:
    params['createdBeforeOrAt'] = ts.dump(end)
  r = await self.request('GET', '/v4/perpetualPositions', params=params)
  return parse_response(r, validate=self.validate(validate))['positions']

async def get_open_position(
  self, market: str, *,
  address: str,
  subaccount: int = 0,
  validate: bool | None = None,
) -> PerpetualPosition | None:
  """Retrieves the open perpetual position for a specific subaccount."""
  positions = await self.list_positions(address, subaccount=subaccount, status='OPEN', validate=validate)
  for p in positions:
    if p['market'] == market:
      return p

async def get_historical_funding(
  self, market: str, *,
  end: datetime | None = None,
  end_block: int | None = None,
  limit: int | None = None,
  validate: bool | None = None,
) -> list[Funding]:
  """Retrieves historical funding rates for a specific perpetual market..

  - `market`: The market ticker (e.g. `'BTC-USD'`).
  - `end`: If given, fetches funding rates up to and including the given timestamp.
  - `end_block`: If given, fetches funding rates up to and including the given block height.
  - `limit`: The max. number of candles to retrieve (default: 1000, max: 1000).
  - `validate`: Whether to validate the response against the expected schema.

  > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-historical-funding)
  """
  params = {}
  if end is not None:
    params['effectiveBeforeOrAt'] = ts.dump(end)
  if end_block is not None:
    params['effectiveBeforeOrAtHeight'] = end_block
  if limit is not None:
    params['limit'] = limit
  r = await self.request('GET', f'/v4/historicalFunding/{market}', params=params)
  return parse_response(r, validate=self.validate(validate))['historicalFunding']

async def get_historical_funding_paged(
  self, market: str, *,
  end: datetime | None = None,
  end_block: int | None = None,
  limit: int | None = None,
) -> AsyncIterable[Sequence[Funding]]:
  """Retrieves historical funding rates for a specific perpetual market, automatically paginating.

    - `market`: The market ticker (e.g. `'BTC-USD'`).
    - `end`: If given, fetches funding rates up to and including the given timestamp.
    - `end_block`: If given, fetches funding rates up to and including the given block height.
    - `limit`: The max. number of candles to retrieve (default: 1000, max: 1000).
    - `validate`: Whether to validate the response against the expected schema.

    > [dYdX API docs](https://docs.dydx.xyz/indexer-client/http#get-historical-funding)
    """
  last_block = end_block
  while True:
    fs = await self.get_historical_funding(market, end=end, end_block=last_block, limit=limit)
    if not fs:
      break
    new_last_block = int(fs[-1]['effectiveAtHeight'])
    if new_last_block == last_block:
      break
    last_block = new_last_block
    yield fs