:doc:`ManagedBlockchainQuery <../../managedblockchain-query>` / Client / list_token_balances

*******************
list_token_balances
*******************



.. py:method:: ManagedBlockchainQuery.Client.list_token_balances(**kwargs)

  

  This action returns the following for a given blockchain network:

   

  
  * Lists all token balances owned by an address (either a contract address or a wallet address).
   
  * Lists all token balances for all tokens created by a contract.
   
  * Lists all token balances for a given token.
  

   

  .. note::

    

    You must always specify the network property of the ``tokenFilter`` when using this operation.

    

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/managedblockchain-query-2023-05-04/ListTokenBalances>`_  


  **Request Syntax**
  ::

    response = client.list_token_balances(
        ownerFilter={
            'address': 'string'
        },
        tokenFilter={
            'network': 'ETHEREUM_MAINNET'|'ETHEREUM_SEPOLIA_TESTNET'|'BITCOIN_MAINNET'|'BITCOIN_TESTNET',
            'contractAddress': 'string',
            'tokenId': 'string'
        },
        nextToken='string',
        maxResults=123
    )
    
  :type ownerFilter: dict
  :param ownerFilter: 

    The contract or wallet address on the blockchain network by which to filter the request. You must specify the ``address`` property of the ``ownerFilter`` when listing balances of tokens owned by the address.

    

  
    - **address** *(string) --* **[REQUIRED]** 

      The contract or wallet address.

      

    
  
  :type tokenFilter: dict
  :param tokenFilter: **[REQUIRED]** 

    The contract address or a token identifier on the blockchain network by which to filter the request. You must specify the ``contractAddress`` property of this container when listing tokens minted by a contract.

     

    .. note::

      

      You must always specify the network property of this container when using this operation.

      

    

  
    - **network** *(string) --* **[REQUIRED]** 

      The blockchain network of the token.

      

    
    - **contractAddress** *(string) --* 

      This is the address of the contract.

      

    
    - **tokenId** *(string) --* 

      The unique identifier of the token.

      

    
  
  :type nextToken: string
  :param nextToken: 

    The pagination token that indicates the next set of results to retrieve.

    

  
  :type maxResults: integer
  :param maxResults: 

    The maximum number of token balances to return.

     

    Default: ``100``

     

    .. note::

      

      Even if additional results can be retrieved, the request can return less results than ``maxResults`` or an empty array of results.

       

      To retrieve the next set of results, make another request with the returned ``nextToken`` value. The value of ``nextToken`` is ``null`` when there are no more results to return

      

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'tokenBalances': [
              {
                  'ownerIdentifier': {
                      'address': 'string'
                  },
                  'tokenIdentifier': {
                      'network': 'ETHEREUM_MAINNET'|'ETHEREUM_SEPOLIA_TESTNET'|'BITCOIN_MAINNET'|'BITCOIN_TESTNET',
                      'contractAddress': 'string',
                      'tokenId': 'string'
                  },
                  'balance': 'string',
                  'atBlockchainInstant': {
                      'time': datetime(2015, 1, 1)
                  },
                  'lastUpdatedTime': {
                      'time': datetime(2015, 1, 1)
                  }
              },
          ],
          'nextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **tokenBalances** *(list) --* 

        An array of ``TokenBalance`` objects. Each object contains details about the token balance.

        
        

        - *(dict) --* 

          The balance of the token.

          
          

          - **ownerIdentifier** *(dict) --* 

            The container for the identifier of the owner.

            
            

            - **address** *(string) --* 

              The contract or wallet address for the owner.

              
        
          

          - **tokenIdentifier** *(dict) --* 

            The identifier for the token, including the unique token ID and its blockchain network.

            
            

            - **network** *(string) --* 

              The blockchain network of the token.

              
            

            - **contractAddress** *(string) --* 

              This is the token's contract address.

              
            

            - **tokenId** *(string) --* 

              The unique identifier of the token.

               

              .. note::

                

                For native tokens, use the 3 character abbreviation that best matches your token. For example, btc for Bitcoin, eth for Ether, etc. For all other token types you must specify the ``tokenId`` in the 64 character hexadecimal ``tokenid`` format.

                

              
        
          

          - **balance** *(string) --* 

            The container of the token balance.

            
          

          - **atBlockchainInstant** *(dict) --* 

            The time for when the TokenBalance is requested or the current time if a time is not provided in the request.

             

            .. note::

              

              This time will only be recorded up to the second.

              

            
            

            - **time** *(datetime) --* 

              The container of the ``Timestamp`` of the blockchain instant.

               

              .. note::

                

                This ``timestamp`` will only be recorded up to the second.

                

              
        
          

          - **lastUpdatedTime** *(dict) --* 

            The ``Timestamp`` of the last transaction at which the balance for the token in the wallet was updated.

            
            

            - **time** *(datetime) --* 

              The container of the ``Timestamp`` of the blockchain instant.

               

              .. note::

                

                This ``timestamp`` will only be recorded up to the second.

                

              
        
      
    
      

      - **nextToken** *(string) --* 

        The pagination token that indicates the next set of results to retrieve.

        
  
  **Exceptions**
  
  *   :py:class:`ManagedBlockchainQuery.Client.exceptions.ThrottlingException`

  
  *   :py:class:`ManagedBlockchainQuery.Client.exceptions.ValidationException`

  
  *   :py:class:`ManagedBlockchainQuery.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`ManagedBlockchainQuery.Client.exceptions.InternalServerException`

  
  *   :py:class:`ManagedBlockchainQuery.Client.exceptions.ServiceQuotaExceededException`

  