RPC Client Documentation¶

Here you will find all the methods that allow you to interact with Qubic's RPC.

qubipy.rpc.rpc_client.QubiPy_RPC ¶

broadcast_transaction ¶

broadcast_transaction(tx: bytes) -> Dict[str, Any]

Broadcasts a transaction to the Qubic network.

Args: tx (bytes): The transaction data to broadcast as bytes.

Returns: Dict[str, Any]: The response from the API after broadcasting the transaction.

Raises: QubiPy_Exceptions: If there is an issue broadcasting the transaction.

get_approved_transaction_for_tick ¶

get_approved_transaction_for_tick(tick: int | None = None) -> Dict[str, Any]

Retrieves the approved transactions for a specific tick (block height) from the API.

Args: tick (Optional[int]): The tick number for which to retrieve approved transactions. If not provided, an exception is raised.

Returns: Dict[str, Any]: A dictionary containing the approved transactions for the given tick. If no approved transactions are found, the key 'approvedTransactions' may be None or an empty dictionary.

Raises: QubiPy_Exceptions: If the tick number is not provided or invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error or invalid response).

get_assets_issuances ¶

get_assets_issuances(
    issuer_identity: str | None = None, asset_name: str | None = None
) -> Dict[str, Any]

Retrieves asset issuances from the RPC server.

This method fetches asset issuances and can filter the results based on an optional issuer identity and/or an optional asset name.

Args: issuer_identity (Optional[str], optional): The identity (wallet ID) of the issuer to filter the issuances by. Defaults to None, meaning no filtering by issuer. If provided (not None), the format of the wallet ID is validated using is_wallet_id_invalid. asset_name (Optional[str], optional): The name of the asset to filter the issuances by. Defaults to None, meaning no filtering by asset name.

Returns: Dict[str, Any]: A dictionary containing the asset issuances data from the API response. Returns an empty dictionary ({}) if the key 'assets' is missing in the successful API response body.

Raises: QubiPy_Exceptions: If the provided issuer_identity is not None and its format is determined to be invalid by is_wallet_id_invalid, or if there is any issue during the API request execution (e.g., network error, non-2xx HTTP status code response, or timeout).

get_assets_issuances_by_index ¶

get_assets_issuances_by_index(index: int | None = None) -> Dict[str, Any]

Retrieves a specific asset issuance by its index from the RPC server.

This method fetches the details of a single asset issuance based on its unique index. A valid index is required.

Args: index (int | None): The index of the asset issuance to retrieve. Although the type hint includes None and the default is None, the function's validation (check_index) requires a value that converts to a non-empty string of digits (representing a non-negative integer). Passing None or an invalid format will cause a validation error.

Returns: Dict[str, Any]: A dictionary containing the data for the specified asset issuance. Returns an empty dictionary ({}) if the key 'data' is missing in the successful API response body.

Raises: QubiPy_Exceptions: If the provided index is invalid (i.e., fails the validation performed by check_index, which includes if it's None), or if there is any issue during the API request execution (e.g., network error, non-2xx HTTP status code response from the server, or timeout). Specifically raises QubiPy_Exceptions.INVALID_INDEX if the index validation fails.

get_assets_owners_per_asset ¶

get_assets_owners_per_asset(
    issuer_identity: int | None = None,
    asset_name: str | None = None,
    page_1: int | None = None,
    page_size: int | None = None,
) -> Dict[str, Any]

Retrieves the list of owners for a specific asset from the RPC server.

This method fetches asset owners, requiring the asset to be identified by its issuer identity and asset name. Pagination parameters (page number and page size) are optional and sent as query parameters.

Args: issuer_identity (int | None): The identity (integer ID) of the asset's issuer. Defaults to None. This parameter is required by this function's validation and must not be falsy (i.e., must not be None and must not be the integer 0). Note: Based on the usage in the endpoint path, this parameter is expected by the API. asset_name (str | None): The name of the asset. Defaults to None. This parameter is required by this function's validation and must not be falsy (i.e., must not be None and must not be the empty string ""). Note: This parameter is used in the endpoint path. page_1 (int | None, optional): The page number for pagination. Defaults to None. Validation of this parameter's value or format is not performed within this function. If not None, it's sent as a query parameter 'page'. page_size (int | None, optional): The number of entries per page for pagination. Defaults to None. Validation of this parameter's value or format is not performed within this function. If not None, it's sent as a query parameter 'pageSize'.

Returns: Dict[str, Any]: A dictionary containing the entire JSON response body received from the API, typically including the list of owners for the specified asset and potentially pagination metadata.

Raises: QubiPy_Exceptions: If issuer_identity or asset_name are falsy (i.e., fails the if not issuer_identity or not asset_name: check), raising QubiPy_Exceptions.INVALID_IDENTITY_ASSET. Also, if there is any issue during the API request execution (e.g., network error, non-2xx HTTP status code response, or timeout).

get_assets_possessions ¶

get_assets_possessions(
    issuer_identity: int | None = None,
    asset_name: int | None = None,
    owner_identity: int | None = None,
    possessor_identity: int | None = None,
    ownership_managing_contract: int | None = None,
    possession_managing_contrct: int | None = None,
) -> Dict[str, Any]

Retrieves asset possessions from the RPC server based on optional criteria.

This method fetches asset possessions and can filter the results based on optional issuer identity, asset name, owner identity, possessor identity, and managing contracts for ownership and possession.

Args: issuer_identity (int | None, optional): The identity (integer ID) of the issuer to filter by. Defaults to None, meaning no filtering by issuer. Note: Based on the name and common API patterns, this parameter likely represents a string identifier expected by the API. asset_name (int | None, optional): The name (integer ID) of the asset to filter by. Defaults to None. This parameter is required by this function's validation and must not be falsy (i.e., must not be None and must not be the integer 0). Note: Based on the name and common API patterns, this parameter likely represents a string name expected by the API. owner_identity (int | None, optional): The identity (integer ID) of the owner to filter by. Defaults to None, meaning no filtering by owner. Note: Based on the name and common API patterns, this parameter likely represents a string identifier expected by the API. possessor_identity (int | None, optional): The identity (integer ID) of the possessor to filter by. Defaults to None, meaning no filtering by possessor. Note: Based on the name and common API patterns, this parameter likely represents a string identifier expected by the API. ownership_managing_contract (int | None, optional): The identity (integer ID) of the ownership managing contract to filter by. Defaults to None, meaning no filtering by ownership managing contract. Note: Based on the name and common API patterns, this parameter likely represents a string identifier expected by the API. possession_managing_contrct (int | None, optional): The identity (integer ID) of the possession managing contract to filter by. Defaults to None, meaning no filtering by possession managing contract. Note: Based on the name and common API patterns, this parameter likely represents a string identifier expected by the API.

Returns: Dict[str, Any]: A dictionary containing the asset possessions data from the API response. Returns an empty dictionary ({}) if the key 'assets' is missing in the successful API response body.

Raises: QubiPy_Exceptions: If the asset_name provided is falsy (i.e., is None or the integer 0), raising QubiPy_Exceptions.INVALID_ASSET_NAME. Also, if there is any issue during the API request execution (e.g., network error, non-2xx HTTP status code response from the server, or timeout).

get_assets_possessions_by_index ¶

get_assets_possessions_by_index(index: int | None = None) -> Dict[str, Any]

Retrieves specific asset possessions by their index from the RPC server.

This method fetches the details of asset possessions based on their unique index. A valid index is required for the request.

Args: index (int | None): The index of the asset possessions to retrieve. Although the type hint includes None and the default value is None, the function's internal validation (check_index) requires a value that converts to a non-empty string consisting only of decimal digits (representing a non-negative integer). Providing None or any other invalid format will raise a validation error.

Returns: Dict[str, Any]: A dictionary containing the entire JSON response body received from the API for the specified asset possessions.

Raises: QubiPy_Exceptions: If the provided index is invalid (fails the validation performed by check_index, including if the input is None), or if there is any issue during the API request execution (e.g., a network error, a non-2xx HTTP status code response from the server, or a timeout). Specifically raises QubiPy_Exceptions.INVALID_INDEX if the index validation fails.

get_balance ¶

get_balance(wallet_id: str | None = None) -> Dict[str, Any]

Retrieves the balance of a specific wallet from the API.

Args: wallet_id (str, optional): The ID of the wallet for which to retrieve the balance. If not provided, an exception is raised.

Returns: Dict[str, Any]: A dictionary containing the wallet balance. If no balance is found, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If the wallet ID is not provided or is invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_block_height ¶

get_block_height() -> Dict[str, Any]

Retrieves the current block height from the API.

..deprecated:: 0.4.0 The get_block_height() function is deprecated and will be removed in a future version of QubiPy. Please use get_tick_info() instead for future compatibility.

Returns: Dict[str, Any]: A dictionary containing the current block height. If the block height is not found, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_chain_hash ¶

get_chain_hash(tick_number: int | None = None) -> Dict[str, Any]

Retrieves the chain hash (hexadecimal digest) for a specific tick number from the API.

Args: tick_number (Optional[int]): The tick number for which to retrieve the chain hash. If not provided, an exception is raised.

Returns: Dict[str, Any]: A dictionary containing the chain hash. If no chain hash is found, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If the tick number is not provided or is invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_computors ¶

get_computors(epoch: int | None = None) -> Dict[str, Any]

Retrieves computors associated with a specific epoch from the API.

Args: epoch (Optional[int]): The epoch for which to retrieve computors. If not provided, an exception is raised.

Returns: Dict[str, Any]: A dictionary containing the computors associated with the specified epoch. If no computors are found, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If the epoch is not provided or is invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_health_check ¶

get_health_check() -> Dict[str, Any]

Performs a health check on the API to verify its availability and status.

Returns: Dict[str, Any]: A dictionary containing the health check status and related information from the API.

Raises: QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_issued_assets ¶

get_issued_assets(identity: str | None = None) -> Dict[str, Any]

Retrieves the list of assets issued by a specific identity from the API.

Args: identity (Optional[int]): The identity for which to retrieve the issued assets. Raises an exception if not provided.

Returns: Dict[str, Any]: A dictionary containing the issued assets for the specified identity. If no issued assets are found, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If the identity is not provided or invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_latest_stats ¶

get_latest_stats() -> Dict[str, Any]

Retrieves the latest statistics from the RPC server.

Returns: Dict[str, Any]: A dictionary containing the latest statistics. If no statistics are found, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_latest_tick ¶

get_latest_tick() -> Dict[str, Any]

Retrieves the latest tick (block height) from the API.

Returns: Dict[str, Any]: A dictionary containing the latest tick information or an error message if no tick is found.

Raises: QubiPy_Exceptions: If there is an issue retrieving the tick from the API.

get_owned_assets ¶

get_owned_assets(identity: str | None = None) -> Dict[str, Any]

Retrieves the list of assets owned by a specific identity from the API.

Args: identity (Optional[int]): The identity for which to retrieve the owned assets. Raises an exception if not provided.

Returns: Dict[str, Any]: A dictionary containing the owned assets for the specified identity. If no owned assets are found, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If the identity is not provided or invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_ownerships_assets ¶

get_ownerships_assets(
    issuer_identity: int | None = None,
    asset_name: int | None = None,
    owner_identity: int | None = None,
    ownership_managing_contract: int | None = None,
) -> Dict[str, Any]

Retrieves asset ownerships from the RPC server based on optional criteria.

This method can filter ownerships by issuer identity, asset name, owner identity, and/or ownership managing contract.

Args: issuer_identity (int | None, optional): The identity (integer ID) of the issuer to filter by. Defaults to None, meaning no filtering by issuer. Note: Based on the name, this might conceptually represent a string identifier expected by the API. asset_name (int | None, optional): The name (integer ID) of the asset to filter by. Defaults to None. This parameter is required by this function's validation and must not be falsy (i.e., must not be None and must not be the integer 0). Note: Based on the name, this might conceptually represent a string name expected by the API. owner_identity (int | None, optional): The identity (integer ID) of the owner to filter by. Defaults to None, meaning no filtering by owner. Note: Based on the name, this might conceptually represent a string identifier expected by the API. ownership_managing_contract (int | None, optional): The identity (integer ID) of the ownership managing contract to filter by. Defaults to None, meaning no filtering by contract. Note: Based on the name, this might conceptually represent a string identifier expected by the API.

Returns: Dict[str, Any]: A dictionary containing the asset ownerships data from the API response. Returns an empty dictionary ({}) if the key 'assets' is missing in the successful API response body.

Raises: QubiPy_Exceptions: If the asset_name provided is falsy (i.e., is None or the integer 0), raising QubiPy_Exceptions.INVALID_ASSET_NAME. Also, if there is any issue during the API request execution (e.g., network error, non-2xx HTTP status code response from the server, or timeout).

get_ownerships_assets_by_index ¶

get_ownerships_assets_by_index(index: int | None = None) -> Dict[str, Any]

Retrieves a specific asset ownership by its index from the RPC server.

This method fetches the details of a single asset ownership based on its unique index. A valid index is required.

Args: index (int | None): The index of the asset ownership to retrieve. Although the type hint includes None and the default is None, the function's validation (check_index) requires a value that converts to a non-empty string of digits (representing a non-negative integer). Passing None or an invalid format will cause a validation error.

Returns: Dict[str, Any]: A dictionary containing the data for the specified asset ownership. Returns an empty dictionary ({}) if the key 'data' is missing in the successful API response body.

Raises: QubiPy_Exceptions: If the provided index is invalid (fails check_index validation, including if it's None), or if there is an issue during the API request (e.g., network error, non-2xx HTTP status code, or timeout). Specifically raises QubiPy_Exceptions.INVALID_INDEX for index validation failures.

get_possessed_assets ¶

get_possessed_assets(identity: str | None = None) -> Dict[str, Any]

Retrieves the list of assets possessed by a specific identity from the API.

Args: identity (Optional[int]): The identity for which to retrieve the possessed assets. Raises an exception if not provided.

Returns: Dict[str, Any]: A dictionary containing the possessed assets for the specified identity. If no possessed assets are found, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If the identity is not provided or invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_quorum_tick_data ¶

get_quorum_tick_data(tick_number: int | None = None) -> Dict[str, Any]

Retrieves quorum data for a specific tick (block height) from the API.

Args: tick_number (Optional[int]): The tick number for which to retrieve the quorum data. If not provided, an exception is raised.

Returns: Dict[str, Any]: A dictionary containing the quorum data for the specified tick number. If no data is found, the dictionary may be empty.

Raises: QubiPy_Exceptions: If the tick number is not provided or is invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_rich_list ¶

get_rich_list(
    page_1: int | None = None, page_size: int | None = None
) -> Dict[str, Any]

Retrieves the rich list from the RPC server based on the provided page and page size.

Args: page_1 (Optional[int], optional): The page number to retrieve. Must be a positive integer. page_size (Optional[int], optional): The number of entries per page. Must be a positive integer.

Returns: Dict[str, Any]: A dictionary containing the rich list data. If no data is available, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If page_1 or page_size are not provided or are invalid, or if there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_rpc_status ¶

get_rpc_status() -> Dict[str, Any]

Retrieves the current RPC status from the API.

Returns: Dict[str, Any]: A dictionary containing the RPC status information. This typically includes server health, version, and other metadata.

Raises: QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_store_hash ¶

get_store_hash(tick_number: int | None = None) -> Dict[str, Any]

Retrieves the store hash for a specific tick (block height) from the API.

Args: tick_number (Optional[int]): The tick number for which to retrieve the store hash. If not provided, an exception is raised.

Returns: Dict[str, Any]: A dictionary containing the store hash data for the specified tick number. The structure of the dictionary is determined by the API response.

Raises: QubiPy_Exceptions: If the tick number is not provided or is invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_tick_data ¶

get_tick_data(tick: int | None = None) -> Dict[str, Any]

Retrieves the data associated with a specific tick number from the API.

Args: tick (Optional[int]): The tick number for which to retrieve the data. If not provided, an exception is raised.

Returns: Dict[str, Any]: A dictionary containing the data associated with the specified tick number. If no data is found, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If the tick number is not provided or is invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_tick_info ¶

get_tick_info() -> Dict[str, Any]

Retrieves information about the current tick from the API.

Returns: Dict[str, Any]: A dictionary containing the tick information. If no tick information is found, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_transaction ¶

get_transaction(tx_id: str | None = None) -> Dict[str, Any]

Retrieves transaction data for a specific transaction ID from the API.

Args: tx_id (Optional[str]): The transaction ID for which to retrieve data. If not provided, an exception is raised.

Returns: Dict[str, Any]: A dictionary containing the transaction data associated with the specified transaction ID. If no transaction is found, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If the transaction ID is not provided or is invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_transaction_status ¶

get_transaction_status(tx_id: str | None = None) -> Dict[str, Any]

Retrieves the status of a specific transaction using its transaction ID from the API.

Args: tx_id (Optional[str]): The transaction ID for which to retrieve the status. If not provided, an exception is raised.

Returns: Dict[str, Any]: A dictionary containing the status of the transaction associated with the specified transaction ID. If no status is found, an empty dictionary is returned.

Raises: QubiPy_Exceptions: If the transaction ID is not provided or is invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

get_transfer_transactions_per_tick ¶

get_transfer_transactions_per_tick(
    identity: str | None = None,
    start_tick: int | None = None,
    end_tick: int | None = None,
) -> Dict[str, Any]

Retrieves transfer transactions for a specific identity within a specified range of ticks from the API.

Args: identity (Optional[str]): The identity for which to retrieve transfer transactions. If not provided, an exception is raised. startTick (Optional[str]): The starting tick for the range of transactions. If not provided, an exception is raised. endTick (Optional[str]): The ending tick for the range of transactions. If not provided, an exception is raised.

Returns: Dict[str, Any]: A dictionary containing the transfer transactions within the specified range of ticks for the given identity.

Raises: QubiPy_Exceptions: If the identity is not provided or is invalid. QubiPy_Exceptions: If either the startTick or endTick is not provided or is invalid. QubiPy_Exceptions: If there is an issue with the API request (e.g., network error, invalid response, or timeout).

query_smart_contract ¶

query_smart_contract(
    contract_index: str | None = None,
    input_type: str | None = None,
    input_size: str | None = None,
    request_data: str | None = "",
) -> Dict[str, Any]

Query a smart contract to the Qubic network

Args: contractIndex (Optional[str], optional): Contract Index to query inputType (Optional[str], optional): Input type to query inputSize (Optional[str], optional): The input size to query requestData (Optional[str], optional): The request data to query the smart contract

Returns: Dict[str, Any]: The response from the API after querying the smart contract.

Raises: QubiPy_Exceptions: If the request data is invalid base64 encoded string. QubiPy_Exceptions: If there is an issue querying the smart contract (e.g., network error, invalid response, or timeout).