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 | str) – Address of the account, as an AccountAddress or a hex string.

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:
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 | str) – Address of the account, as an AccountAddress or a hex string.

  • 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 | str) – Address of the account, as an AccountAddress or a hex string.

  • 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 | str) – Address of the account, as an AccountAddress or a hex string.

  • 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 | str) – Address of the account, as an AccountAddress or a hex string.

  • 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 | str) – Address of the account, as an AccountAddress or a hex string.

  • 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 | str) – Address of the account, as an AccountAddress or a hex string.

  • 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 | str) – The height of the block, as a non-negative integer or a string of decimal digits.

  • 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 | str) – The epoch number, as a non-negative integer or a string of decimal digits.

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 | str) – The height of the consensus block to retrieve, as a non-negative integer or a string of decimal digits.

  • 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 | str) – The target account address to receive funds, as an AccountAddress or a hex string.

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 (AccountAddress | str) – Table handle to lookup, as an AccountAddress or a hex string. 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 (Any) – 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.

Type:

bool | None

block_height

Start block height to consider for transaction retrieval.

Type:

int | None

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.

Type:

int | None

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.

Type:

int | None

start

Cursor or starting point specifying where to start for pagination.

Type:

str | int | None

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.

Type:

bool | None

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_sdk.clients.rest.rest_types.address_segment(value, name='address')

Validates an account address and returns it as one path segment.

Parameters:

  • value (AccountAddress | str) – An AccountAddress, or a hex string accepted by AccountAddress.from_str_relaxed.

  • name (str) – Name of the parameter, used in the error message.

Raises:

ValueError – If value is not a valid account address.

Return type:

str

supra_sdk.clients.rest.rest_types.encode_path_segment(value, name='value')

Percent-encodes a caller-supplied value so that it forms exactly one URL path segment.

: and , are valid in a path segment and are left as they are. Every other character that cannot appear in a segment, including /, ?, #, %, <, > and space, is encoded. The node decodes path segments before parsing them, so a Move type such as 0x1::coin::CoinStore<0x1::supra_coin::SupraCoin> reaches it unchanged and is sent as 0x1::coin::CoinStore%3C0x1::supra_coin::SupraCoin%3E.

Parameters:

  • value (str) – The value to place in a path segment.

  • name (str) – Name of the parameter, used in the error message.

Raises:

ValueError – If value is not a non-empty string.

Return type:

str

supra_sdk.clients.rest.rest_types.format_endpoint(template, **values)

Fills the placeholders of an endpoint template with validated, percent-encoded path segments.

Each value is validated and encoded according to its placeholder name: address placeholders (address, account_address, table_handle) as account addresses, names ending in hash as hashes, height and epoch as non-negative integers, and every other name as a plain string encoded as a single segment.

Parameters:

  • template (str) – Endpoint template with {name} placeholders.

  • **values (Any) – One value for each placeholder.

Returns:

The endpoint path, relative to the base URL.

Return type:

str

Raises:

ValueError – If a value is invalid, or the values do not match the template’s placeholders.

supra_sdk.clients.rest.rest_types.hash_segment(value, name='hash')

Validates a hash and returns it as one path segment.

Transaction and block hashes are 32 bytes: 64 hex digits, optionally prefixed with 0x.

Parameters:

  • value (str) – The hash.

  • name (str) – Name of the parameter, used in the error message.

Raises:

ValueError – If value is not 64 hex digits with an optional 0x prefix.

Return type:

str

supra_sdk.clients.rest.rest_types.uint_segment(value, name='value')

Validates a non-negative integer and returns it as one path segment.

Parameters:

  • value (int | str) – A non-negative integer, or a string of decimal digits, e.g. a block height or an epoch.

  • name (str) – Name of the parameter, used in the error message.

Raises:

ValueError – If value is not a non-negative integer or a string of decimal digits.

Return type:

str

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 | str) – Address of the account, as an AccountAddress or a hex string.

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

Raises:
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, max_gas_amount=None)

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.

An explicit max_gas_amount (here or in TransactionConfig) is used as given, otherwise it is estimated by simulating the fee-payer transaction. The fee payer pays for gas, so the estimate needs the fee payer’s SUPRA balance to cover the gas used times the gas unit price. See create_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.

  • max_gas_amount (int | None) – Max gas units for this transaction. None uses the config value or the estimate. Default to None.

Returns:

The constructed multi-agent authenticator type signed transaction.

Return type:

SignedTransaction

Raises:

MaxGasEstimationError – If the max gas amount has to be estimated and that fails.

async create_multi_agent_transaction(sender, secondary_accounts, transaction_payload, max_gas_amount=None)

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.

An explicit max_gas_amount (here or in TransactionConfig) is used as given, otherwise it is estimated by simulating the multi-agent transaction, which needs the sender’s SUPRA balance to cover the gas used times the gas unit price. See create_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.

  • max_gas_amount (int | None) – Max gas units for this transaction. None uses the config value or the estimate. Default to None.

Returns:

The constructed multi-agent authenticator type signed transaction.

Return type:

SignedTransaction

Raises:

MaxGasEstimationError – If the max gas amount has to be estimated and that fails.

async create_raw_transaction(sender, transaction_payload, sequence_number=None, max_gas_amount=None, fee_payer=None)

Creates a raw transaction.

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

The transaction expires TransactionConfig.expiration_ttl seconds after the client’s clock. Without an expiration_ttl it expires 5 seconds before the node’s maximum time-to-live (rpc/v3/transactions/parameters, read once per client), so that a node whose clock is up to 5 seconds behind the client’s accepts it.

The max gas amount is max_gas_amount, else TransactionConfig.max_gas_amount, used as given. When neither is set it is estimated: the transaction is simulated with the most gas the sender’s SUPRA balance pays for at the gas unit price (balance // gas_unit_price, at most 2,000,000,000 units), and the max gas amount is the gas used times 1.5, rounded up, at least 1,500 and at most what the balance pays for. The node accepts a transaction only if the sender’s balance covers max_gas_amount * gas_unit_price, so an estimate needs a balance of at least the gas used times the gas unit price. When sender is only an address there is no key to simulate with, and the max gas amount is 20,000 units, at most what the balance pays for. The estimate is made against the node’s committed state. When the simulation reports the sequence number as ahead of the account’s on the chain (a transaction sent behind uncommitted ones), the account’s sequence number is read and the transaction is simulated again with that number; the returned transaction keeps sequence_number. A transaction that depends on an uncommitted one does not simulate to Success even then: set max_gas_amount for it.

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. None fetches it from the node; any integer, including 0, is used as given without a request. Default to None.

  • max_gas_amount (int | None) – Max gas units for this transaction. None uses the config value or the estimate described above. Default to None.

  • fee_payer (Account | AccountAddress | None) – The account that will pay for gas when the transaction is wrapped for a fee payer. Its SUPRA balance, not the sender’s, caps the estimated max gas, and the simulation is made in fee-payer form (with no secondary signers) when both sender and fee_payer are accounts; with only the fee payer’s address there is no key to simulate with and the fallback of 20,000 units applies. It does not change the raw transaction, which is the same for every payer; no balance is read when the max gas is explicit. Default to None.

Returns:

The constructed raw transaction object.

Return type:

RawTransaction

Raises:

MaxGasEstimationError – If the max gas amount has to be estimated and the balance cannot be read, is too low to pay for any gas, or the simulation fails or does not succeed.

async create_signed_transaction(sender, transaction_payload, sequence_number=None, max_gas_amount=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.

The max gas amount and the expiration time follow create_raw_transaction: an explicit max_gas_amount (here or in TransactionConfig) is used as given, otherwise it is estimated by a simulation, which needs the sender’s SUPRA balance to cover the gas used times the gas unit price.

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; 0 is used as given. Default to None.

  • max_gas_amount (int | None) – Max gas units for this transaction. None uses the config value or the estimate. Default to None.

Returns:

The constructed signed transaction object.

Return type:

SignedTransaction

Raises:

MaxGasEstimationError – If the max gas amount has to be estimated and that fails.

async faucet(address, wait_for_faucet=True)

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

Parameters:

  • address (AccountAddress | str) – The target account address to receive funds, as an AccountAddress or a hex string.

  • 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

Raises:
async max_transaction_time_to_live()

Provides the node’s maximum transaction time-to-live in seconds.

The value (max_transaction_time_to_live_seconds of rpc/v3/transactions/parameters) is read from the node once per client and cached. A node that has no such endpoint (404) or an answer without the key gets DEFAULT_MAX_TRANSACTION_TTL_SECONDS (600, the maximum on every network); that fallback is not cached, so the next call reads the node again. Any other failed read raises and is not cached.

Returns:

The largest number of seconds after the node’s clock at which a transaction may expire.

Return type:

int

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

Raises:
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, automation_task_type=None, automation_priority=None)

Registers Supra automation task.

With neither automation_task_type nor automation_priority the task is registered with version 1 of the registration parameters. With either, version 2 is used, and a missing task type is AutomationTaskType.USER.

Parameters:

  • owner_account (Account) – Account registering an automation task. It will be eligible to cancel or stop task.

  • automated_function (EntryFunction) – 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.

  • automation_task_type (AutomationTaskType | None) – USER or SYSTEM. A SYSTEM task can only be registered by an account the registry has authorised for system tasks; other accounts’ registrations abort. Defaults to version 1 parameters (a user task).

  • automation_priority (int | None) – Priority of the task. Without a priority, the registry uses the task’s index as its priority.

Returns:

Transaction hash.

Return type:

str

Raises:
async simulate_transaction(signed_transaction)

Simulates a given signed transaction.

The simulation is sent with the signatures removed, so there is no need to provide a transaction with invalid signatures. The given signed_transaction is never modified, whether the simulation succeeds or fails.

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

Raises:
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.

If TransactionConfig.wait_for_transaction is enabled (the default), the method then waits for the transaction to be final and raises TransactionFailedError unless its status is Success. If it is disabled, the method returns the hash right after submission and the outcome of the transaction is not checked. Use submit_transaction_and_wait to get the final transaction data.

Parameters:

signed_transaction (SignedTransaction) – Signed transaction object to submit transaction.

Returns:

Transaction hash of the submitted transaction.

Return type:

str

Raises:
async submit_transaction_and_wait(signed_transaction)

Submits a signed transaction, waits until it is final and returns its data.

This method always waits, regardless of TransactionConfig.wait_for_transaction.

Parameters:

signed_transaction (SignedTransaction) – Signed transaction object to submit transaction.

Returns:

The transaction data, whose status is Success.

Return type:

dict[str, Any]

Raises:
transaction_config: TransactionConfig
async transfer_coins(sender, recipient, coin_type, amount, sequence_number=None, max_gas_amount=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.

Gas is paid in SUPRA whatever the coin type. Without a max_gas_amount (here or in TransactionConfig) the max gas is estimated by a simulation, which needs the sender’s SUPRA balance to cover the gas used times the gas unit price.

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.

  • max_gas_amount (int | None) – Max gas units for this transaction. None uses the config value or the estimate. Default to None.

Returns:

Transaction hash.

Return type:

str

Raises:
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

Raises:
async transfer_supra_coin(sender, recipient, amount, sequence_number=None, max_gas_amount=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.

Without a max_gas_amount (here or in TransactionConfig) the max gas is estimated by a simulation, which needs the sender’s balance to cover the maximum gas deposit, in addition to the transferred amount. A transfer that creates the recipient uses about 1,000 units, so at the minimum gas unit price of 100,000 quants the gas costs 10^8 quants (1 SUPRA, where 1 SUPRA = 10^8 quants), and the max gas of about 1,500 units (the gas used times 1.5) is a deposit of about 1.5 SUPRA.

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.

  • max_gas_amount (int | None) – Max gas units for this transaction. None uses the config value or the estimate. Default to None.

Returns:

Transaction hash.

Return type:

str

Raises:
async wait_for_faucet(faucet_tx_hash)

Waits until a faucet transaction is final and returns its data.

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. It polls under the same rules as wait_for_transaction: it keeps polling until the status is Success, Fail or Invalid, treats only the node’s “transaction not found” 404 as “not seen yet”, and returns the final data whatever the status is.

Parameters:

faucet_tx_hash (str) – The hash of the faucet transaction to wait for.

Returns:

The final transaction data.

Return type:

dict[str, Any]

Raises:

TransactionWaitTimeoutReachedError – If the transaction is not final within TransactionConfig.transaction_wait_time_in_seconds.

async wait_for_transaction(tx_hash)

Waits until a transaction is final and returns its data.

This method polls the transaction until its status is Success, Fail or Invalid. Any other status keeps it polling: Pending, PendingAfterExecution (the node reports it for a transaction that was executed but may still succeed later, e.g. because its sequence number is too new), a missing status or an unknown one. A 404 whose body is the node’s “transaction not found” message (a JSON object with a message starting “Information not available for” or containing “Cannot find transaction”) means “not seen yet” and polling continues; any other 404, such as a wrong base URL or a missing route, is raised as ApiError. The final data is returned whatever the status is, so the caller must check status.

The wait never starts a poll after TransactionConfig.transaction_wait_time_in_seconds has passed, bounds each poll by the time remaining, and sleeps at most the time remaining between polls. The first poll always happens.

Parameters:

tx_hash (str) – The hash of the transaction to wait for.

Returns:

The final transaction data.

Return type:

dict[str, Any]

Raises:

TransactionWaitTimeoutReachedError – If the transaction is not final within TransactionConfig.transaction_wait_time_in_seconds. The error carries the hash and the last status seen (None if the node never knew the transaction).

class supra_sdk.clients.rest.supra_client.SupraClientConfig(http2=False, access_token=None, expiration_ttl=None, gas_unit_price=None, max_gas_amount=None, 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=None, gas_unit_price=None, max_gas_amount=None, 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, counted from the client’s clock. An integer is used as given, even if it exceeds the node’s maximum (the node then refuses the transaction). None (the default) expires the transaction max_transaction_time_to_live_seconds - 5 seconds after the client’s clock, where the maximum is read once per client from rpc/v3/transactions/parameters (600 on every network; 600 is also used, without caching, when the node answers 404 or omits the value). The node refuses a transaction that expires after its own clock plus the maximum, so the 5-second margin lets the node’s clock be up to 5 seconds behind the client’s.

Type:

int | None

gas_unit_price

Price per unit of gas used to execute the transaction. Defaults to min_configured_gas_price obtained from rpc/v3/transactions/estimate_gas_price endpoint.

Type:

int

max_gas_amount

Maximum number of gas units allowed per transaction. An integer is used as given. None (the default) estimates it for each transaction by simulation: the gas used times 1.5, at least 1,500 units and at most what the sender’s SUPRA balance pays for at the gas unit price. The node accepts a transaction only if the balance covers max_gas_amount * gas_unit_price, and the estimate raises MaxGasEstimationError when the balance cannot pay for the simulation or the simulation does not succeed. Set an integer to skip the simulation.

Type:

int | None

transaction_wait_time_in_seconds

Seconds to wait for a transaction to be final before timing out. Defaults to 20.

Type:

float

polling_wait_time_in_seconds

Delay, in seconds, between successive polling attempts when waiting for transaction confirmation. Defaults to 1.

Type:

float

wait_for_transaction

Whether to wait for the transaction to be final after submission. When enabled, SupraClient.submit_transaction and the helpers built on it raise TransactionFailedError unless the transaction succeeded. When disabled they return the hash right after submission and do not check the outcome. Defaults to True.

Type:

bool

expiration_ttl: int | None = None
gas_unit_price: int | None = None
max_gas_amount: int | None = None
polling_wait_time_in_seconds: float = 1
transaction_wait_time_in_seconds: float = 20
wait_for_transaction: bool = True
exception supra_sdk.clients.rest.supra_client.TransactionFailedError(tx_hash, status, vm_status, transaction_data=None)

Bases: Exception

Exception raised when a submitted transaction reached a final status other than Success.

tx_hash

Transaction hash.

Type:

str

status

Final status of the transaction, e.g. Fail or Invalid.

Type:

str | None

vm_status

Message of the Move VM, e.g. the abort location and code. None if the node reported no Move output, as for a transaction that failed validation.

Type:

str | None

transaction_data

The transaction data as returned by the node.

Type:

dict[str, Any]

exception supra_sdk.clients.rest.supra_client.TransactionWaitTimeoutReachedError(tx_hash, transaction_wait_time_in_seconds, last_status=None)

Bases: Exception

Exception raised when the transaction is not final even after max transaction wait time.

tx_hash

Transaction hash.

Type:

str

last_status

Last status the node reported for the transaction, None if the node never knew the transaction.

Type:

str | None

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]