nft

async def compute_rarity(
  self,
  *,
  contract_address: str,
  token_id: str,
  validate: bool | None = None
) -> ComputeRarityResponse:
  """Computes the rarity of each trait attribute for a specific NFT token within its collection.

  Args:
    contract_address: NFT contract address (ERC721 or ERC1155).
    token_id: Token ID in hex or decimal format.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-metadata-endpoints/compute-rarity-v-3)
    """
  params: dict = {
    'contractAddress': contract_address,
    'tokenId': token_id,
  }
  r = await self.request('GET', '/computeRarity', params=params)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

async def get_collection_metadata(
  self,
  *,
  collection_slug: str,
  validate: bool | None = None
) -> CollectionMetadataResponse:
  """Retrieves high-level collection metadata for an NFT collection by OpenSea slug.

  Args:
    collection_slug: OpenSea collection slug.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-metadata-endpoints/get-collection-metadata-v-3)
    """
  params: dict = {
    'collectionSlug': collection_slug,
  }
  r = await self.request('GET', '/getCollectionMetadata', params=params)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

async def get_collections_for_owner(
  self,
  *,
  owner: str,
  page_key: str | None = None,
  page_size: int | None = None,
  with_metadata: bool | None = None,
  include_filters: list[Literal['SPAM', 'AIRDROPS']] | None = None,
  exclude_filters: list[Literal['SPAM', 'AIRDROPS']] | None = None,
  validate: bool | None = None
) -> OwnerCollectionsResponse:
  """Returns all NFT collections held by a given wallet address, with collection-level metadata and floor prices.

  Args:
    owner: Wallet address. Supports ENS format on Eth Mainnet.
    page_key: Pagination cursor from previous response.
    page_size: Collections per page. Maximum 100. Defaults to 100.
    with_metadata: Include NFT metadata. Defaults to true.
    include_filters: Include only tokens matching SPAM or AIRDROPS.
    exclude_filters: Exclude tokens matching SPAM or AIRDROPS.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-ownership-endpoints/get-collections-for-owner-v-3)
    """
  params: dict = {
    'owner': owner,
  }
  if page_key is not None:
    params['pageKey'] = page_key
  if page_size is not None:
    params['pageSize'] = page_size
  if with_metadata is not None:
    params['withMetadata'] = with_metadata
  if include_filters is not None:
    params['includeFilters[]'] = include_filters
  if exclude_filters is not None:
    params['excludeFilters[]'] = exclude_filters
  r = await self.request('GET', '/getCollectionsForOwner', params=params)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

def get_collections_for_owner_paged(
  self,
  *,
  owner: str,
  page_size: int | None = None,
  with_metadata: bool | None = None,
  include_filters: list[Literal['SPAM', 'AIRDROPS']] | None = None,
  exclude_filters: list[Literal['SPAM', 'AIRDROPS']] | None = None,
  validate: bool | None = None,
) -> PaginatedResponse[OwnerCollection, str]:
  """Paged version of get_collections_for_owner.

  Args:
    owner: Wallet address. Supports ENS format on Eth Mainnet.
    page_size: Collections per page. Maximum 100. Defaults to 100.
    with_metadata: Include NFT metadata. Defaults to true.
    include_filters: Include only tokens matching SPAM or AIRDROPS.
    exclude_filters: Exclude tokens matching SPAM or AIRDROPS.
    validate: Validation override for each request.

  Returns:
    An async iterable and awaitable paginated response over owner collections.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-ownership-endpoints/get-collections-for-owner-v-3)
    """
  async def next(state: str):
    response = await self.get_collections_for_owner(
      owner=owner, page_key=state or None, page_size=page_size,
      with_metadata=with_metadata, include_filters=include_filters,
      exclude_filters=exclude_filters, validate=validate,
    )
    return response.get('collections', []), response.get('pageKey')

  return PaginatedResponse('', next)

async def get_contract_metadata(
  self,
  *,
  contract_address: str,
  validate: bool | None = None
) -> ContractMetadataResponse:
  """Retrieves collection-level metadata for a given NFT contract address.

  Args:
    contract_address: NFT contract address (ERC721 or ERC1155).
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-metadata-endpoints/get-contract-metadata-v-3)
    """
  params: dict = {
    'contractAddress': contract_address,
  }
  r = await self.request('GET', '/getContractMetadata', params=params)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

async def get_contract_metadata_batch(
  self,
  body: ContractMetadataBatchRequest,
  *,
  validate: bool | None = None
) -> ContractMetadataBatchResponse:
  """Fetches collection-level metadata for multiple NFT contracts in a single request.

  Args:
    body: List of contract addresses to fetch metadata for.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-metadata-endpoints/get-contract-metadata-batch-v-3)
    """
  r = await self.request('POST', '/getContractMetadataBatch', json=body)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

async def get_contracts_for_owner(
  self,
  *,
  owner: str,
  page_key: str | None = None,
  page_size: int | None = None,
  with_metadata: bool | None = None,
  include_filters: list[Literal['SPAM', 'AIRDROPS']] | None = None,
  exclude_filters: list[Literal['SPAM', 'AIRDROPS']] | None = None,
  order_by: Literal['transferTime'] | None = None,
  spam_confidence_level: Literal['VERY_HIGH', 'HIGH', 'MEDIUM', 'LOW'] | None = None,
  validate: bool | None = None
) -> OwnerContractsResponse:
  """Lists all NFT contracts (collections) for which a given wallet holds at least one token.

  Args:
    owner: Wallet address. Supports ENS format on Eth Mainnet.
    page_key: Pagination cursor from previous response.
    page_size: Contracts per page. Maximum 100. Defaults to 100.
    with_metadata: Include contract metadata. Defaults to true.
    include_filters: Include only tokens matching SPAM or AIRDROPS filters.
    exclude_filters: Exclude tokens matching SPAM or AIRDROPS filters.
    order_by: Sort order. 'transferTime' sorts by most recent transfer first.
    spam_confidence_level: Spam threshold (paid tier). One of: VERY_HIGH, HIGH, MEDIUM, LOW.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-ownership-endpoints/get-contracts-for-owner-v-3)
    """
  params: dict = {
    'owner': owner,
  }
  if page_key is not None:
    params['pageKey'] = page_key
  if page_size is not None:
    params['pageSize'] = page_size
  if with_metadata is not None:
    params['withMetadata'] = with_metadata
  if include_filters is not None:
    params['includeFilters[]'] = include_filters
  if exclude_filters is not None:
    params['excludeFilters[]'] = exclude_filters
  if order_by is not None:
    params['orderBy'] = order_by
  if spam_confidence_level is not None:
    params['spamConfidenceLevel'] = spam_confidence_level
  r = await self.request('GET', '/getContractsForOwner', params=params)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

def get_contracts_for_owner_paged(
  self,
  *,
  owner: str,
  page_size: int | None = None,
  with_metadata: bool | None = None,
  include_filters: list[Literal['SPAM', 'AIRDROPS']] | None = None,
  exclude_filters: list[Literal['SPAM', 'AIRDROPS']] | None = None,
  order_by: Literal['transferTime'] | None = None,
  spam_confidence_level: Literal['VERY_HIGH', 'HIGH', 'MEDIUM', 'LOW'] | None = None,
  validate: bool | None = None,
) -> PaginatedResponse[OwnerContract, str]:
  """Paged version of get_contracts_for_owner.

  Args:
    owner: Wallet address. Supports ENS format on Eth Mainnet.
    page_size: Contracts per page. Maximum 100. Defaults to 100.
    with_metadata: Include contract metadata. Defaults to true.
    include_filters: Include only tokens matching SPAM or AIRDROPS filters.
    exclude_filters: Exclude tokens matching SPAM or AIRDROPS filters.
    order_by: Sort order. 'transferTime' sorts by most recent transfer first.
    spam_confidence_level: Spam threshold (paid tier). One of: VERY_HIGH, HIGH, MEDIUM, LOW.
    validate: Validation override for each request.

  Returns:
    An async iterable and awaitable paginated response over owner contracts.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-ownership-endpoints/get-contracts-for-owner-v-3)
    """
  async def next(state: str):
    response = await self.get_contracts_for_owner(
      owner=owner, page_key=state or None, page_size=page_size,
      with_metadata=with_metadata, include_filters=include_filters,
      exclude_filters=exclude_filters, order_by=order_by,
      spam_confidence_level=spam_confidence_level, validate=validate,
    )
    return response.get('contracts', []), response.get('pageKey')

  return PaginatedResponse('', next)

async def get_floor_price(
  self,
  *,
  contract_address: str,
  collection_slug: str | None = None,
  validate: bool | None = None
) -> FloorPriceResponse:
  """Retrieves the floor price of an NFT collection on OpenSeaFloorPrice and LooksRareFloorPrice marketplaces. Ethereum Mainnet only.

  Args:
    contract_address: NFT contract address (ERC721 or ERC1155).
    collection_slug: OpenSeaFloorPrice collection slug for the collection.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-sales-endpoints/get-floor-price-v-3)
    """
  params: dict = {
    'contractAddress': contract_address,
  }
  if collection_slug is not None:
    params['collectionSlug'] = collection_slug
  r = await self.request('GET', '/getFloorPrice', params=params)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

async def get_nft_metadata(
  self,
  *,
  contract_address: str,
  token_id: str,
  token_type: NftTokenType | None = None,
  token_uri_timeout_in_ms: int | None = None,
  refresh_cache: bool | None = None,
  validate: bool | None = None
) -> NftMetadataResponse:
  """Fetches metadata for a specific NFT identified by contract address and token ID.

  Args:
    contract_address: NFT contract address (ERC721 or ERC1155).
    token_id: Token ID as a decimal integer string or hex string.
    token_type: Token standard hint to improve response time. One of 'ERC721' or 'ERC1155'.
    token_uri_timeout_in_ms: Timeout in milliseconds for fetching the token URI. Set to 0 for cache-only access.
    refresh_cache: If true, forces a cache refresh and re-fetches metadata from the original source. Defaults to false.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/data/nft-api/api-reference/nft-metadata-endpoints/get-nft-metadata-v-3)
    """
  params: dict = {
    'contractAddress': contract_address,
    'tokenId': token_id,
  }
  if token_type is not None:
    params['tokenType'] = token_type
  if token_uri_timeout_in_ms is not None:
    params['tokenUriTimeoutInMs'] = token_uri_timeout_in_ms
  if refresh_cache is not None:
    params['refreshCache'] = refresh_cache
  r = await self.request('GET', '/getNFTMetadata', params=params)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

async def get_nft_metadata_batch(
  self,
  body: NftMetadataBatchRequest,
  *,
  validate: bool | None = None
) -> NftMetadataBatchResponse:
  """Fetches metadata for up to 100 NFTs in a single request. Returns an array of NFT objects.

  Args:
    body: Batch request payload specifying the tokens to fetch metadata for.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-metadata-endpoints/get-nft-metadata-batch-v-3)
    """
  r = await self.request('POST', '/getNFTMetadataBatch', json=body)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

async def get_nft_sales(
  self,
  *,
  from_block: str | None = None,
  to_block: str | None = None,
  order: Literal['asc', 'desc'] | None = None,
  marketplace: Literal['seaport', 'wyvern', 'looksrare', 'x2y2', 'blur', 'cryptopunks'] | None = None,
  contract_address: str | None = None,
  token_id: str | None = None,
  buyer_address: str | None = None,
  seller_address: str | None = None,
  taker: Literal['BUYER', 'SELLER'] | None = None,
  limit: int | None = None,
  page_key: str | None = None,
  validate: bool | None = None
) -> NftSalesResponse:
  """Retrieves NFT sales data from on-chain marketplaces with rich filtering options.

  Args:
    from_block: Start block number (decimal, hex, or 'latest'). Defaults to '0'.
    to_block: End block number (decimal, hex, or 'latest'). Defaults to 'latest'.
    order: Sort direction from fromBlock: 'asc' or 'desc'. Defaults to 'desc'.
    marketplace: Filter by marketplace. One of: seaport, wyvern, looksrare, x2y2, blur, cryptopunks.
    contract_address: Filter by NFT contract address.
    token_id: Filter by token ID within the contractAddress collection.
    buyer_address: Filter by buyer wallet address.
    seller_address: Filter by seller wallet address.
    taker: Filter by price taker role: BUYER or SELLER.
    limit: Max results to return. Maximum 1000. Defaults to 1000.
    page_key: Pagination cursor from a previous response.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-sales-endpoints/get-nft-sales-v-3)
    """
  params = {}
  if from_block is not None:
    params['fromBlock'] = from_block
  if to_block is not None:
    params['toBlock'] = to_block
  if order is not None:
    params['order'] = order
  if marketplace is not None:
    params['marketplace'] = marketplace
  if contract_address is not None:
    params['contractAddress'] = contract_address
  if token_id is not None:
    params['tokenId'] = token_id
  if buyer_address is not None:
    params['buyerAddress'] = buyer_address
  if seller_address is not None:
    params['sellerAddress'] = seller_address
  if taker is not None:
    params['taker'] = taker
  if limit is not None:
    params['limit'] = limit
  if page_key is not None:
    params['pageKey'] = page_key
  r = await self.request('GET', '/getNFTSales', params=params)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

def get_nft_sales_paged(
  self, *, from_block: str | None = None, to_block: str | None = None,
  order: Literal['asc', 'desc'] | None = None,
  marketplace: Literal['seaport', 'wyvern', 'looksrare', 'x2y2', 'blur', 'cryptopunks'] | None = None,
  contract_address: str | None = None,
  token_id: str | None = None,
  buyer_address: str | None = None,
  seller_address: str | None = None,
  taker: Literal['BUYER', 'SELLER'] | None = None,
  limit: int | None = None,
  validate: bool | None = None,
) -> PaginatedResponse[NftSale, str]:
  """Paged version of get_nft_sales.

  Args:
    from_block: Start block number.
    to_block: End block number.
    order: Sort direction from fromBlock.
    marketplace: Filter by marketplace.
    contract_address: Filter by NFT contract address.
    token_id: Filter by token ID.
    buyer_address: Filter by buyer wallet address.
    seller_address: Filter by seller wallet address.
    taker: Filter by price taker role.
    limit: Max results to return per page.
    validate: Validation override for each request.

  Returns:
    An async iterable and awaitable paginated response over NFT sales.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-sales-endpoints/get-nft-sales-v-3)
  """
  async def next(state: str):
    response = await self.get_nft_sales(
      from_block=from_block, to_block=to_block, order=order,
      marketplace=marketplace, contract_address=contract_address,
      token_id=token_id, buyer_address=buyer_address,
      seller_address=seller_address, taker=taker, limit=limit,
      page_key=state or None, validate=validate,
    )
    return response.get('nftSales', []), response.get('pageKey')

  return PaginatedResponse('', next)

async def get_nfts_for_collection(
  self,
  *,
  contract_address: str | None = None,
  collection_slug: str | None = None,
  with_metadata: bool | None = None,
  start_token: str | None = None,
  limit: int | None = None,
  token_uri_timeout_in_ms: int | None = None,
  validate: bool | None = None
) -> CollectionNftsResponse:
  """Retrieves NFTs associated with a specific NFT collection.

  Args:
    contract_address: NFT contract address (ERC721 or ERC1155).
    collection_slug: OpenSea collection slug.
    with_metadata: Include NFT metadata. Defaults to true.
    start_token: Token ID offset for pagination (hex or decimal).
    limit: Number of NFTs to return. Defaults to 100.
    token_uri_timeout_in_ms: Timeout for metadata fetching in milliseconds. Set to 0 for cache-only.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-metadata-endpoints/get-nf-ts-for-collection-v-3)
    """
  params = {}
  if contract_address is not None:
    params['contractAddress'] = contract_address
  if collection_slug is not None:
    params['collectionSlug'] = collection_slug
  if with_metadata is not None:
    params['withMetadata'] = with_metadata
  if start_token is not None:
    params['startToken'] = start_token
  if limit is not None:
    params['limit'] = limit
  if token_uri_timeout_in_ms is not None:
    params['tokenUriTimeoutInMs'] = token_uri_timeout_in_ms
  r = await self.request('GET', '/getNFTsForCollection', params=params)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

def get_nfts_for_collection_paged(
  self, *, contract_address: str | None = None,
  collection_slug: str | None = None, with_metadata: bool | None = None,
  limit: int | None = None, token_uri_timeout_in_ms: int | None = None,
  validate: bool | None = None,
) -> PaginatedResponse[NftMetadataResponse, str]:
  """Paged version of get_nfts_for_collection.

  Args:
    contract_address: NFT contract address (ERC721 or ERC1155).
    collection_slug: OpenSea collection slug.
    with_metadata: Include NFT metadata. Defaults to true.
    limit: Number of NFTs to return per page. Defaults to 100.
    token_uri_timeout_in_ms: Timeout for metadata fetching in milliseconds. Set to 0 for cache-only.
    validate: Validation override for each request.

  Returns:
    An async iterable and awaitable paginated response over NFT metadata.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-metadata-endpoints/get-nf-ts-for-collection-v-3)
  """
  async def next(state: str):
    response = await self.get_nfts_for_collection(
      contract_address=contract_address, collection_slug=collection_slug,
      with_metadata=with_metadata, start_token=state or None,
      limit=limit, token_uri_timeout_in_ms=token_uri_timeout_in_ms,
      validate=validate,
    )
    return response.get('nfts', []), response.get('pageKey') or response.get('nextToken')

  return PaginatedResponse('', next)

async def get_nfts_for_contract(
  self,
  *,
  contract_address: str,
  with_metadata: bool | None = None,
  start_token: str | None = None,
  limit: int | None = None,
  token_uri_timeout_in_ms: int | None = None,
  validate: bool | None = None
) -> ContractNftsResponse:
  """Retrieves all NFTs belonging to a given contract address.

  Args:
    contract_address: NFT contract address (ERC721 or ERC1155).
    with_metadata: Include NFT metadata. Defaults to true.
    start_token: Token ID offset for pagination (hex or decimal).
    limit: Number of NFTs to return. Defaults to 100.
    token_uri_timeout_in_ms: Timeout for metadata fetching in milliseconds. Set to 0 for cache-only.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-metadata-endpoints/get-nf-ts-for-contract-v-3)
    """
  params: dict = {
    'contractAddress': contract_address,
  }
  if with_metadata is not None:
    params['withMetadata'] = with_metadata
  if start_token is not None:
    params['startToken'] = start_token
  if limit is not None:
    params['limit'] = limit
  if token_uri_timeout_in_ms is not None:
    params['tokenUriTimeoutInMs'] = token_uri_timeout_in_ms
  r = await self.request('GET', '/getNFTsForContract', params=params)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

def get_nfts_for_contract_paged(
  self, *, contract_address: str, with_metadata: bool | None = None,
  limit: int | None = None, token_uri_timeout_in_ms: int | None = None,
  validate: bool | None = None,
) -> PaginatedResponse[NftMetadataResponse, str]:
  """Paged version of get_nfts_for_contract.

  Args:
    contract_address: NFT contract address (ERC721 or ERC1155).
    with_metadata: Include NFT metadata. Defaults to true.
    limit: Number of NFTs to return per page. Defaults to 100.
    token_uri_timeout_in_ms: Timeout for metadata fetching in milliseconds. Set to 0 for cache-only.
    validate: Validation override for each request.

  Returns:
    An async iterable and awaitable paginated response over NFT metadata.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-metadata-endpoints/get-nf-ts-for-contract-v-3)
  """
  async def next(state: str):
    response = await self.get_nfts_for_contract(
      contract_address=contract_address, with_metadata=with_metadata,
      start_token=state or None, limit=limit,
      token_uri_timeout_in_ms=token_uri_timeout_in_ms,
      validate=validate,
    )
    return response.get('nfts', []), response.get('pageKey')

  return PaginatedResponse('', next)

async def get_nfts_for_owner(
  self,
  *,
  owner: str,
  contract_addresses: list[str] | None = None,
  with_metadata: bool | None = None,
  order_by: Literal['transferTime'] | None = None,
  exclude_filters: list[Literal['SPAM', 'AIRDROPS']] | None = None,
  include_filters: list[Literal['SPAM', 'AIRDROPS']] | None = None,
  spam_confidence_level: Literal['VERY_HIGH', 'HIGH', 'MEDIUM', 'LOW'] | None = None,
  token_uri_timeout_in_ms: int | None = None,
  page_key: str | None = None,
  page_size: int | None = None,
  validate: bool | None = None
) -> OwnedNftsResponse:
  """Fetches all NFTs owned by a given wallet address on the requested chain. Supports filtering by contract, spam confidence, and metadata inclusion.

  Args:
    owner: Wallet address whose NFTs should be fetched. Supports ENS format on Eth Mainnet.
    contract_addresses: Filter results to specific NFT contract addresses. Maximum 45 contracts.
    with_metadata: Whether to include NFT metadata (name, description, image, attributes). Defaults to true.
    order_by: Sort order. 'transferTime' sorts by most recent transfer first.
    exclude_filters: Exclude NFTs matching these filters. Mutually exclusive with includeFilters. Values: SPAM, AIRDROPS.
    include_filters: Include only NFTs matching these filters. Mutually exclusive with excludeFilters. Values: SPAM, AIRDROPS.
    spam_confidence_level: Spam confidence threshold (paid tier only). One of: VERY_HIGH, HIGH, MEDIUM, LOW.
    token_uri_timeout_in_ms: Timeout in milliseconds for fetching token URIs. Set to 0 for cache-only access.
    page_key: Pagination cursor returned by a previous response.
    page_size: Number of NFTs per page. Maximum 100. Defaults to 100.
    validate: Validation override for this request.

  Returns:
    The validated endpoint response.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-ownership-endpoints/get-nf-ts-for-owner-v-3)
    """
  params: dict = {
    'owner': owner,
  }
  if contract_addresses is not None:
    params['contractAddresses[]'] = contract_addresses
  if with_metadata is not None:
    params['withMetadata'] = with_metadata
  if order_by is not None:
    params['orderBy'] = order_by
  if exclude_filters is not None:
    params['excludeFilters[]'] = exclude_filters
  if include_filters is not None:
    params['includeFilters[]'] = include_filters
  if spam_confidence_level is not None:
    params['spamConfidenceLevel'] = spam_confidence_level
  if token_uri_timeout_in_ms is not None:
    params['tokenUriTimeoutInMs'] = token_uri_timeout_in_ms
  if page_key is not None:
    params['pageKey'] = page_key
  if page_size is not None:
    params['pageSize'] = page_size
  r = await self.request('GET', '/getNFTsForOwner', params=params)

  if r.status_code != 200:
    self.raise_error(r)
  return adapter.json(r.text) if self.should_validate(validate) else r.json()

def get_nfts_for_owner_paged(
  self,
  *,
  owner: str,
  contract_addresses: list[str] | None = None,
  with_metadata: bool | None = None,
  order_by: Literal['transferTime'] | None = None,
  exclude_filters: list[Literal['SPAM', 'AIRDROPS']] | None = None,
  include_filters: list[Literal['SPAM', 'AIRDROPS']] | None = None,
  spam_confidence_level: Literal['VERY_HIGH', 'HIGH', 'MEDIUM', 'LOW'] | None = None,
  token_uri_timeout_in_ms: int | None = None,
  page_size: int | None = None,
  validate: bool | None = None,
) -> PaginatedResponse[OwnedNft, str]:
  """Paged version of get_nfts_for_owner.

  Args:
    owner: Wallet address whose NFTs should be fetched. Supports ENS format on Eth Mainnet.
    contract_addresses: Filter results to specific NFT contract addresses. Maximum 45 contracts.
    with_metadata: Whether to include NFT metadata (name, description, image, attributes). Defaults to true.
    order_by: Sort order. 'transferTime' sorts by most recent transfer first.
    exclude_filters: Exclude NFTs matching these filters. Mutually exclusive with includeFilters. Values: SPAM, AIRDROPS.
    include_filters: Include only NFTs matching these filters. Mutually exclusive with excludeFilters. Values: SPAM, AIRDROPS.
    spam_confidence_level: Spam confidence threshold (paid tier only). One of: VERY_HIGH, HIGH, MEDIUM, LOW.
    token_uri_timeout_in_ms: Timeout in milliseconds for fetching token URIs. Set to 0 for cache-only access.
    page_size: Number of NFTs per page. Maximum 100. Defaults to 100.
    validate: Validation override for each request.

  Returns:
    An async iterable and awaitable paginated response over owned NFTs.

  References:
    - [Alchemy API docs](https://www.alchemy.com/docs/reference/nft-api-endpoints/nft-api-endpoints/nft-ownership-endpoints/get-nf-ts-for-owner-v-3)
    """
  async def next(state: str):
    response = await self.get_nfts_for_owner(
      owner=owner, contract_addresses=contract_addresses,
      with_metadata=with_metadata, order_by=order_by,
      exclude_filters=exclude_filters, include_filters=include_filters,
      spam_confidence_level=spam_confidence_level,
      token_uri_timeout_in_ms=token_uri_timeout_in_ms,
      page_key=state or None, page_size=page_size, validate=validate,
    )
    return response.get('ownedNfts', []), response.get('pageKey')

  return PaginatedResponse('', next)