Rest

Account

class supra_sdk.clients.rest.account.AccountRestClient(api_client)

Bases: RestClient

A class that provides methods to invoke Account REST endpoints from a Supra RPC node.

api_client

Inherited from RestClient. Used to send HTTP requests to the Supra RPC node.

Type:: supra_sdk.clients.api_client.ApiClient

async account(account_address)

Provides the authentication key and the sequence number of the given account.

Parameters:: account_address (AccountAddress) – Address of the account.
Returns:: The authentication key and sequence number of the given account.
Return type:: dict[str, str]

async account_automated_transactions(account_address, pagination=None)

Retrieves details of finalized automated transactions based on the automation tasks registered by a given: account.

Parameters:

account_address (AccountAddress) – Address of the account.
pagination (AutomatedTransactionsPagination | None) – Pagination options. Default to None.

Returns:

A tuple containing,

list[dict[str, Any]]: Details of finalized automated transactions details based on the automation
tasks registered by a given account.
str: Cursor to retrieve the next page.

Return type:

tuple[list[dict[str, Any]], str]

async account_coin_transactions(account_address, pagination=None)

Retrieves details of finalized coin deposit/withdraw type transactions associated with a given account.

Parameters:

account_address (AccountAddress) – Address of the account.
pagination (PaginationWithOrder | None) – Pagination options. Default to None.

Returns:

A tuple containing,

list[dict[str, Any]]: Details of finalized coin deposit/withdraw type transactions associated with a
given account.
str: Cursor to retrieve the next page.

Return type:

tuple[list[dict[str, Any]], str]

async account_module(account_address, module_name)

Retrieves an individual module from a given account.

Parameters:

account_address (AccountAddress) – Address of the account.
module_name (str) – Name of the module to retrieve e.g. ‘account’

Returns:

An individual module from a given account.

Return type:

dict[str, Any]

async account_modules(account_address, pagination=None)

Retrieves all account modules from a given account.

Parameters:

account_address (AccountAddress) – Address of the account.
pagination (Pagination | None) – Pagination options. Default to None.

Returns:

A tuple containing,

list[dict[str, Any]]: All account modules from a given account.
str: Cursor to retrieve the next page.

Return type:

tuple[list[dict[str, Any]], str]

async account_resource(account_address, resource_type)

Retrieves an individual resource from a given account.

Parameters:

account_address (AccountAddress) – Address of the account.
resource_type (str) – Type of the resource e.g. ‘0x1::account::Account’.

Returns:

An individual resource from a given account.

Return type:

dict[str, Any]

async account_resources(account_address, pagination=None)

Retrieves all account resources for a given account.

Parameters:

account_address (AccountAddress) – Address of the account.
pagination (Pagination | None) – Pagination options. Default to None.

Returns:

A tuple containing,

list[dict[str, Any]]: All account resources for a given account.
str: Cursor to retrieve the next page.

Return type:

tuple[list[dict[str, Any]], str]

async account_transactions(account_address, pagination=None)

Retrieves details of finalized transactions sent by a given account.

Parameters:

account_address (AccountAddress) – Address of the account.
pagination (PaginationWithOrder | None) – Pagination options. Default to None. Note: Sequence number would be used as start in pagination option.

Returns:

Details of finalized transactions sent by a given account.

Return type:

list[dict[str, Any]]

Block

class supra_sdk.clients.rest.block.BlockRestClient(api_client)

Bases: RestClient

A class that provides methods to invoke Block REST endpoints from a Supra RPC node.

api_client

Inherited from RestClient. Used to send HTTP requests to the Supra RPC node.

Type:: supra_sdk.clients.api_client.ApiClient

async block_by_hash(block_hash)

Retrieves the header and execution output statistics of the block with the given hash.

Parameters:: block_hash (str) – The hash of the block.
Returns:: Header and execution output statistics of the block with the given hash.
Return type:: dict[str, Any]

async block_by_height(height, transaction_type=None, with_finalized_transaction=False)

Retrieves information about the block that has been finalized at the given height.

Parameters:

height (int) – The height of the block.
transaction_type (TransactionType | None) – Transaction type to query. If missing any/all type of transactions will be looked for. Default to None.
with_finalized_transaction (bool) – Whether to include finalized transactions or not. Default to False.

Returns:

Information about the block that has been finalized at the given height.

Return type:

dict[str, Any]

async latest_block()

Retrieves the metadata information of the most recently finalized and executed block.

Returns:: Metadata information of the most recently finalized and executed block.
Return type:: dict[str, Any]

async txs_by_block(block_hash, transaction_type=None)

Retrieves a list containing the hashes of the transactions that were finalized in the block with the given: hash in the order that they were executed.

Parameters:

block_hash (str) – The hash of the block.
transaction_type (TransactionType | None) – Transaction type to query. If missing any/all type of transactions will be looked for. Default tp None

Returns:

List transaction’s hash that were finalized in the given block.

Return type:

list[str]

Consensus

class supra_sdk.clients.rest.consensus.ConsensusRestClient(api_client)

Bases: RestClient

A class that provides methods to invoke Consensus REST endpoints from a Supra RPC node.

api_client

Inherited from RestClient. Used to send HTTP requests to the Supra RPC node.

Type:: supra_sdk.clients.api_client.ApiClient

async committee_authorization(epoch)

Retrieves the BCS bytes of the Committee Authorization for the given epoch.

Parameters:: epoch (int) – The epoch number.
Returns:: BCS bytes of the Committee Authorization for the requested epoch.
Return type:: bytes

async consensus_block_by_height(height, with_batches=False)

Retrieves the BCS bytes of the consensus block at the requested height.

Parameters:

height (int) – The height of the consensus block to retrieve.
with_batches (bool) – If true, returns all batches of transactions with certificates contained in this block. Default to False.

Returns:

BCS bytes of the consensus block at the requested height.

Return type:

bytes

async latest_consensus_block()

Retrieves the BCS bytes of the latest consensus block.

Returns:: BCS bytes of the latest consensus block.
Return type:: bytes

Faucet

class supra_sdk.clients.rest.faucet.FaucetRestClient(api_client)

Bases: RestClient

A class that provides methods to invoke Faucet REST endpoints from a Supra RPC node.

api_client

Inherited from RestClient. Used to send HTTP requests to the Supra RPC node.

Type:: supra_sdk.clients.api_client.ApiClient

async faucet(address)

Requests faucet funds to be sent to the given account address.

Parameters:: address (AccountAddress) – The target account address to receive funds.
Returns:: Faucet transaction hash if faucet request is accepted else None.
Return type:: str | None

async faucet_transaction_by_hash(tx_hash)

Retrieves details of a faucet transaction by its hash.

Parameters:: tx_hash (str) – The hash of the faucet transaction.
Returns:: Faucet transaction details.
Return type:: dict[str, Any]

General

class supra_sdk.clients.rest.general.GeneralRestClient(api_client)

Bases: RestClient

A class that provides convenient methods to interact with general REST endpoints like View, table and Event from a Supra RPC node.

api_client

Inherited from RestClient. Used to send HTTP requests to the Supra RPC node.

Type:: supra_sdk.clients.api_client.ApiClient

async events_by_type(event_type, pagination=None)

Retrieves events of a given type.

Parameters:

event_type (str) – The fully qualified name of the event struct e.g. ‘0x1::coin::CoinDeposit’.
pagination (EventsPagination | None) – Pagination options. Default to None.

Returns:

A tuple containing,

list[dict[str, Any]]: List of events.
str: Cursor to retrieve the next page.

Return type:

tuple[list[dict[str, Any]], str]

async get_table_item(table_handle, key_type, value_type, key)

Retrieves an item from a table by key.

Parameters:

table_handle (str) – Table handle to lookup. Should be retrieved using account resources API.
key_type (str) – The type of the table key.
value_type (str) – The type of the table value.
key (str) – The key to fetch from the table.

Returns:

Item associated with the key in the table.

Return type:

dict[str, Any]

async network_chain_id()

Provides the network Chain-ID.

Returns:: Network Chain-ID.
Return type:: int

async view(function, type_arguments, arguments)

Execute a view Move function with the given parameters and return its execution result.

Parameters:

function (str) – Entry function id is string representation of an entry function defined on-chain.
type_arguments (list[str]) – Type arguments of the function.
arguments (list[str]) – Arguments of the function.

Returns:

Execution results of the view function.

Return type:

list[Any]

Rest Client

class supra_sdk.clients.rest.rest_client.RestClient(api_client)

Bases: object

A base class for building category-specific REST API clients.

This class provides a shared interface and a common api_client instance for sending REST API requests. Other REST client classes can inherit from RestClient to reuse this functionality.

api_client

The API client instance used to perform HTTP requests against the REST API.

Type:: supra_sdk.clients.api_client.ApiClient

api_client: ApiClient

Rest Types

class supra_sdk.clients.rest.rest_types.AutomatedTransactionsPagination(ascending=None, block_height=None, count=None)

Bases: object

Pagination parameters for automation transaction endpoint.

ascending: Flag indicating order of lookup. If True, results are in ascending order.

block_height: Start block height to consider for transaction retrieval.

count: Number of items to return, default value is 20 and maximum value is 100. In case of count>100 only 100 items will be returned.

ascending: bool | None = None

block_height: int | None = None

count: int | None = None

to_params()

Converts the pagination configuration to a dictionary of query parameters.

Returns:: Dictionary of parameters for HTTP request.
Return type:: Dict[str, Any]

class supra_sdk.clients.rest.rest_types.EventsPagination(start_height=None, end_height=None, limit=None, start=None)

Bases: object

Pagination parameters for events retrieval endpoint.

start_height

Starting block height (inclusive).

Type:: Optional[int]

end_height

Ending block height (exclusive).

Type:: Optional[int]

limit

Maximum number of events to return. Defaults to 20, max 100.

Type:: Optional[int]

start

The cursor to start the query from.

Type:: Optional[str]

end_height: int | None = None

limit: int | None = None

start: str | None = None

start_height: int | None = None

to_params()

Converts the event query configuration to a dictionary of query parameters.

Returns:: Dictionary of parameters for HTTP request.
Return type:: Dict[str, Any]

class supra_sdk.clients.rest.rest_types.Pagination(count=None, start=None)

Bases: object

Generic pagination parameters.

count: Number of items to return, default value is 20 and maximum value is 100. In case of count>100 only 100 items will be returned.

start: Cursor or starting point specifying where to start for pagination.

count: int | None = None

start: str | int | None = None

to_params()

Converts the pagination configuration to a dictionary of query parameters.

Returns:: Dictionary of parameters for HTTP request.
Return type:: Dict[str, Any]

class supra_sdk.clients.rest.rest_types.PaginationWithOrder(count=None, start=None, ascending=None)

Bases: Pagination

Generic pagination parameters with ordering.

ascending: Flag indicating order of lookup. If True, results are in ascending order.

ascending: bool | None = None

to_params()

Converts the pagination configuration to a dictionary of query parameters.

Returns:: Dictionary of parameters for HTTP request.
Return type:: Dict[str, Any]

class supra_sdk.clients.rest.rest_types.TransactionType(*values)

Bases: str, Enum

Enumeration of transaction types.

This enum represents the type of a transaction and it will be used when querying transactions with block info via BLOCK_BY_HEIGHT_ENDPOINT.

AUTO

Represents transactions associated with the Supra Automation.

Type:: str

USER

Represents a user transaction type.

Type:: str

META

Represents a metadata transaction type.

Type:: str

AUTO = 'auto'

META = 'meta'

USER = 'user'

Supra Client

exception supra_sdk.clients.rest.supra_client.FaucetRequestNotAcceptedError

Bases: Exception

Exception raised when faucet request is not accepted by the faucet rpc node.

class supra_sdk.clients.rest.supra_client.SupraClient(base_url, supra_client_config=None)

Bases: AccountRestClient, TransactionRestClient, BlockRestClient, ConsensusRestClient, FaucetRestClient, GeneralRestClient

Unified client for interacting with all Supra REST API endpoints, as well as generating and submitting transaction payloads in a seamless manner.

This class acts as a single entry point for developers, combining multiple specialized REST clients into one unified interface. With SupraClient, you can access account information, submit and query transactions, retrieve block data, inspect consensus status, request testnet funds from the faucet, and query other general network information — all from a single client instance.

In addition to REST API access, SupraClient provides a convenient set of methods for constructing various types of transaction payloads and handling transaction submission. This significantly simplifies the end-to-end process of building, signing, and submitting transactions to the Supra network.

_chain_id

The chain-id of the network.

Type:: int | None

api_client

Inherited from RestClient. Used to send HTTP requests to the Supra RPC node.

Type:: supra_sdk.clients.api_client.ApiClient

async account_coin_balance(account_address, coin_type)

Provides the given coin_type coin balance associated with the given account.

Parameters:

account_address (AccountAddress) – Address of the account.
coin_type (str) – The type of the coin for which balance needs to be provided.

Returns:

The given coin_type coin balance associated with the given account.

Return type:

int

async account_sequence_number(account_address)

Provides the current sequence number of the given account.

Parameters:: account_address (AccountAddress) – Address of the account.
Returns:: The current sequence number for the given account.
Return type:: int

async account_supra_balance(account_address)

Provides the Supra coin balance associated with the given account.

Parameters:: account_address (AccountAddress) – Address of the account.
Returns:: The Supra coin balance associated with the given account.
Return type:: int

async cancel_automation_task(owner_account, task_index)

Cancels Supra automation task.

Parameters:

owner_account (Account) – Automation task owner.
task_index (int) – The ID of the automation task.

Returns:

Transaction hash.

Return type:

str

async chain_id()

Provides the network Chain-ID.

Returns:: Network Chain-ID.
Return type:: int

async close(): Closes the HTTP client session.

async create_fee_payer_transaction(sender, fee_payer, secondary_accounts, transaction_payload)

Creates a fee-payer authenticator type signed transaction.

This method builds and signs a fee-payer authenticator type transaction, where the main sender, fee payer and one or more secondary accounts sign the same raw transaction.

Parameters:

sender (Account) – The primary account sending the transaction.
fee_payer (Account) – The fee payer account to pay transaction fee.
secondary_accounts (list[Account]) – The secondary accounts that also authorize the transaction.
transaction_payload (TransactionPayload) – The transaction payload.

Returns:

The constructed multi-agent authenticator type signed transaction.

Return type:

SignedTransaction

async create_multi_agent_transaction(sender, secondary_accounts, transaction_payload)

Creates a multi-agent authenticator type signed transaction.

This method builds and signs a multi-agent authenticator type transaction, where the main sender and one or more secondary accounts sign the same raw transaction.

Parameters:

sender (Account) – The primary account sending the transaction.
secondary_accounts (list[Account]) – The secondary accounts that also authorize the transaction.
transaction_payload (TransactionPayload) – The transaction payload.

Returns:

The constructed multi-agent authenticator type signed transaction.

Return type:

SignedTransaction

async create_raw_transaction(sender, transaction_payload, sequence_number=None)

Creates a raw transaction.

This method builds a raw transaction with the provided sender, payload, and optionally a custom sequence number.

Parameters:

sender (Account | AccountAddress) – The account object or its address.
transaction_payload (TransactionPayload) – The transaction payload.
sequence_number (int | None) – The sender’s sequence number. If not provided, it will be fetched automatically. Default to None.

Returns:

The constructed raw transaction object.

Return type:

RawTransaction

async create_signed_transaction(sender, transaction_payload, sequence_number=None)

Creates a signed transaction.

This method builds a raw transaction, signs it using the sender’s key, wraps it in an authenticator, and generates signed transaction payload.

Parameters:

sender (Account) – The account signing the transaction.
transaction_payload (TransactionPayload) – The transaction payload.
sequence_number (int | None) – The sequence number to use. If not provided, the current sequence number will be fetched. Default to None.

Returns:

The constructed signed transaction object.

Return type:

SignedTransaction

async faucet(address, wait_for_faucet=True)

Requests faucet funds to be sent to the given account address.

Parameters:

address (AccountAddress) – The target account address to receive funds.
wait_for_faucet (bool) – Flag indicates whether wait for faucet should be done or not. Default to True.

Returns:

Faucet transaction hash if faucet request is accepted else None.

Return type:

str | None

async publish_package(module_publisher, package_metadata, modules)

Publishes package on a given module publisher account.

Parameters:

module_publisher (Account) – Module publisher account.
package_metadata (bytes) – Metadata of the package, generated after package compilation.
modules (list[bytes]) – List of package’s module bytecode .

Returns:

Transaction hash.

Return type:

str

async register_automation_task(owner_account, automated_function, automation_max_gas_amount, automation_gas_price_cap, automation_fee_cap_for_epoch, automation_expiration_timestamp_secs, automation_aux_data)

Registers Supra automation task.

Parameters:

owner_account (Account) – Account registering an automation task. It will be eligible to cancel or stop task.
automated_function (str) – Automated entry function payload.
automation_max_gas_amount (int) – Max gas allowed for automation.
automation_gas_price_cap (int) – Gas price cap for automation execution.
automation_fee_cap_for_epoch (int) – Maximum total fee for the epoch.
automation_expiration_timestamp_secs (int) – Expiration time for automation.
automation_aux_data (list[bytes]) – Auxiliary data for automation.

Returns:

Transaction hash.

Return type:

str

async simulate_transaction(signed_transaction)

Simulates a given signed transaction.

This method internally replaces valid signatures with null/invalid signatures in the signed transaction payload, once simulation is completed, valid signatures are replaced with invalid signatures, hence, there is no need to provide a payload with invalid signatures.

Parameters:: signed_transaction (SignedTransaction) – Signed transaction object for simulation simulate.
Returns:: Transaction simulation result.
Return type:: dict[str, Any]

async stop_automation_tasks(owner_account, task_ids)

Stops list of Supra automation tasks.

Parameters:

owner_account (Account) – Automation task owner.
task_ids (list[int]) – List of automation task IDs.

Returns:

Transaction hash.

Return type:

str

async submit_transaction(signed_transaction)

Submits a given signed transaction to the Supra network.

This method wraps the given signed_transaction under SupraTransaction, serializes wrapped object using BCS serialization, submits serialized payload on the rpc node endpoint, and returns the transaction hash.

Parameters:: signed_transaction (SignedTransaction) – Signed transaction object to submit transaction.
Returns:: Transaction hash of the submitted transaction.
Return type:: str

transaction_config: TransactionConfig

async transfer_coins(sender, recipient, coin_type, amount, sequence_number=None)

Transfer a given coin type coins to a recipient.

This method builds a coin transfer payload for any supported coin type, signs it with the sender’s account, and submits it to the network.

Parameters:

sender (Account) – Sender account.
recipient (AccountAddress) – Recipient account address.
coin_type (str) – The fully-qualified coin type tag e.g. ‘0x1::supra_coin::SupraCoin’.
amount (int) – The amount of coins to transfer.
sequence_number (int | None) – The sender’s sequence number. If not provided, it will be fetched automatically. Default to None.

Returns:

Transaction hash.

Return type:

str

async transfer_object(owner, object_address, to)

Transfer an object to another account.

This method builds an object transfer payload, signs it with the owner’s account, and submits it to the network.

Parameters:

owner (Account) – The owner account sending the object.
object_address (AccountAddress) – The address of the object to transfer.
to (AccountAddress) – The recipient’s account address.

Returns:

Transaction hash.

Return type:

str

async transfer_supra_coin(sender, recipient, amount, sequence_number=None)

Transfers given amount of SupraCoin to a given recipient.

This method builds an EntryFunction payload for transferring the SupraCoin, signs it with the sender’s account, and submits it to the network.

Parameters:

sender (Account) – Sender account.
recipient (AccountAddress) – Recipient account address.
amount (int) – The amount of coins to transfer.
sequence_number (int | None) – The sender’s sequence number. If not provided, it will be fetched automatically. Default to None.

Returns:

Transaction hash.

Return type:

str

async wait_for_faucet(faucet_tx_hash)

Wait for a faucet transaction till it’s in a pending state and transaction wait timeout is not reached.

Note: This method is similar to the SupraClient.wait_for_transaction, this method uses FaucetClient.faucet_transaction_by_hash method to get transaction data of the faucet transaction, it uses that method because, there is different endpoint meant in rpc node to get the transaction details of the pending faucet transactions.

Parameters:: faucet_tx_hash (str) – The hash of the faucet transaction to wait for.
Returns:: The final transaction data once the faucet transaction is no longer pending.
Return type:: dict[str, Any]

async wait_for_transaction(tx_hash)

Wait for a transaction till it’s in a pending state and transaction wait timeout is not reached.

This method repeatedly checks the transaction status until it is no longer pending or until the configured timeout is reached. Returns the transaction data regardless of success or failure status.

Parameters:: tx_hash (str) – The hash of the transaction to wait for.
Returns:: The final transaction data once the transaction is no longer pending.
Return type:: dict[str, Any]

class supra_sdk.clients.rest.supra_client.SupraClientConfig(http2=False, access_token=None, expiration_ttl=600, gas_unit_price=100, max_gas_amount=500000, transaction_wait_time_in_seconds=20, polling_wait_time_in_seconds=1, wait_for_transaction=True)

Bases: TransactionConfig, ApiClientConfig

Configuration for the Supra client.

This dataclass inherits from both TransactionConfig and ApiClientConfig, allowing a single object to hold both transaction-related parameters and API client connection settings.

class supra_sdk.clients.rest.supra_client.TransactionConfig(expiration_ttl=600, gas_unit_price=100, max_gas_amount=500000, transaction_wait_time_in_seconds=20, polling_wait_time_in_seconds=1, wait_for_transaction=True)

Bases: object

Configuration options for transaction payload generation and polling.

This dataclass defines default parameters that are used in transaction payload generation and polling operation. It is intended to be passed into functions of the SupraClient that involves transaction payload generation and submission.

expiration_ttl

Time-to-live, in seconds, before a transaction expires and is rejected by the network. Defaults to 600.

Type:: int

gas_unit_price

Price per unit of gas used to execute the transaction. Defaults to 100.

Type:: int

max_gas_amount

Maximum number of gas units allowed per transaction. Defaults to 500,000.

Type:: int

transaction_wait_time_in_seconds

Number of seconds to wait for a transaction to be executed before timing out. Defaults to 20.

Type:: int

polling_wait_time_in_seconds

Delay, in seconds, between successive polling attempts when waiting for

Type:: int

transaction confirmation. Defaults to 1.

wait_for_transaction

Whether to wait for the transaction to be confirmed after submission. Defaults to True.

Type:: bool

expiration_ttl: int = 600

gas_unit_price: int = 100

max_gas_amount: int = 500000

polling_wait_time_in_seconds: int = 1

transaction_wait_time_in_seconds: int = 20

wait_for_transaction: bool = True

exception supra_sdk.clients.rest.supra_client.TransactionWaitTimeoutReachedError(tx_hash, transaction_wait_time_in_seconds)

Bases: Exception

Exception raised when the transaction is in ‘Pending’ state even after max transaction wait time.

tx_hash

Transaction hash.

Type:: str

Transaction

class supra_sdk.clients.rest.transaction.TransactionRestClient(api_client)

Bases: RestClient

A class that provides methods to invoke Transaction REST endpoints from a Supra RPC node.

api_client

Inherited from RestClient. Used to send HTTP requests to the Supra RPC node.

Type:: supra_sdk.clients.api_client.ApiClient

async estimate_gas_price()

Provides statistics derived from the gas prices of recently executed transactions.

Returns:: Statistics derived from the gas prices of recently executed transactions.
Return type:: dict[str, Any]

async simulate(transaction)

Simulates a given transaction.

Parameters:: transaction (bytes | dict[str, Any]) – Transaction object for simulation process.
Returns:: Transaction simulation result.
Return type:: dict[str, Any]

async submit(transaction)

Submits a given transaction to the Supra network.

Parameters:: transaction (bytes | dict[str, Any]) – Transaction object to submit transaction.
Returns:: Transaction hash of the submitted transaction.
Return type:: str

async transaction_by_hash(tx_hash)

Retrieves detail of a transaction by given transaction hash.

Parameters:: tx_hash (str) – The hash of the transaction.
Returns:: Detail of a transaction by given transaction hash.
Return type:: dict[str, Any]

async transaction_parameters()

Retrieve limits that a client must respect when composing a transaction.

Returns:: limits that a client must respect when composing a transaction.
Return type:: dict[str, Any]