RpcClient (Class)

WebSocket RPC client for communicating with Kaspa nodes.

Provides methods for querying blockchain state, submitting transactions, and subscribing to real-time notifications. Supports both Borsh and JSON encodings.

encoding property

encoding: str

The RPC encoding format ("borsh" or "json").

is_connected property

is_connected: bool

Whether the client is currently connected to a node.

node_id property

node_id: Optional[str]

The unique identifier of the connected node, or None if not connected via resolver.

resolver property

resolver: Optional[Resolver]

The resolver used for node discovery, or None if not set.

url property

url: Optional[str]

The current WebSocket connection URL, or None if not connected.

__new__

__new__(resolver: Optional[Resolver] = None, url: Optional[str] = None, encoding: str | Encoding | None = Borsh, network_id: Optional[NetworkId] = None) -> RpcClient

Create a new RPC client.

PARAMETER	DESCRIPTION
resolver	Optional resolver for node discovery. TYPE: Optional[Resolver] DEFAULT: None
url	Optional direct node URL. TYPE: Optional[str] DEFAULT: None
encoding	RPC encoding - either a string ("borsh" or "json") or an Encoding enum variant (default: "borsh"). TYPE: str | Encoding | None DEFAULT: Borsh
network_id	Network identifier (default: "mainnet"). TYPE: Optional[NetworkId] DEFAULT: None

RETURNS	DESCRIPTION
RpcClient	A new RpcClient instance. TYPE: RpcClient

RAISES	DESCRIPTION
Exception	If client creation fails.

add_event_listener

add_event_listener(event: NotificationEvent, callback: Any, *args: Any, **kwargs: Any) -> None

Register a callback for RPC events.

PARAMETER	DESCRIPTION
event	Event type as kebab string or NotificationEvent variant. See NotificationEvent for acceptable values. TYPE: NotificationEvent
callback	Function to call when event occurs. TYPE: Any
*args	Additional arguments to pass to callback. TYPE: Any DEFAULT: ()
**kwargs	Additional keyword arguments to pass to callback. TYPE: Any DEFAULT: {}

RAISES	DESCRIPTION
Exception	If the event type is invalid.

add_peer

add_peer(request: AddPeerRequest) -> AddPeerResponse

ban

ban(request: BanRequest) -> BanResponse

connect

connect(block_async_connect: Optional[bool] = None, strategy: Optional[str] = None, url: Optional[str] = None, timeout_duration: Optional[int] = None, retry_interval: Optional[int] = None) -> None

Connect to a Kaspa node (async).

PARAMETER	DESCRIPTION
block_async_connect	Block until connected (default: True). TYPE: Optional[bool] DEFAULT: None
strategy	Connection strategy ("retry" or "fallback", default: "retry"). TYPE: Optional[str] DEFAULT: None
url	Optional URL to connect to (overrides resolver). TYPE: Optional[str] DEFAULT: None
timeout_duration	Connection timeout in milliseconds. TYPE: Optional[int] DEFAULT: None
retry_interval	Retry interval in milliseconds. TYPE: Optional[int] DEFAULT: None

RAISES	DESCRIPTION
Exception	If connection fails.

default_port staticmethod

default_port(encoding: Encoding, network: NetworkType) -> int

Get the default RPC port for a given encoding and network type.

PARAMETER	DESCRIPTION
encoding	RPC encoding format ("borsh" or "json"). TYPE: Encoding
network	Network type (e.g., "mainnet", "testnet-10", "testnet-11"). TYPE: NetworkType

RETURNS	DESCRIPTION
int	The default port number for the specified configuration. TYPE: int

disconnect

disconnect() -> None

Disconnect from the node (async).

RAISES	DESCRIPTION
Exception	If disconnection fails.

estimate_network_hashes_per_second

estimate_network_hashes_per_second(request: EstimateNetworkHashesPerSecondRequest) -> EstimateNetworkHashesPerSecondResponse

get_balance_by_address

get_balance_by_address(request: GetBalanceByAddressRequest) -> GetBalanceByAddressResponse

get_balances_by_addresses

get_balances_by_addresses(request: GetBalancesByAddressesRequest) -> GetBalancesByAddressesResponse

get_block

get_block(request: GetBlockRequest) -> GetBlockResponse

get_block_count

get_block_count(request: GetBlockCountRequest | None = None) -> GetBlockCountResponse

get_block_dag_info

get_block_dag_info(request: GetBlockDagInfoRequest | None = None) -> GetBlockDagInfoResponse

get_block_template

get_block_template(request: GetBlockTemplateRequest) -> GetBlockTemplateResponse

get_blocks

get_blocks(request: GetBlocksRequest) -> GetBlocksResponse

get_coin_supply

get_coin_supply(request: GetCoinSupplyRequest | None = None) -> GetCoinSupplyResponse

get_connected_peer_info

get_connected_peer_info(request: GetConnectedPeerInfoRequest | None = None) -> GetConnectedPeerInfoResponse

get_connections

get_connections(request: GetConnectionsRequest | None = None) -> GetConnectionsResponse

get_current_block_color

get_current_block_color(request: GetCurrentBlockColorRequest) -> GetCurrentBlockColorResponse

get_current_network

get_current_network(request: GetCurrentNetworkRequest | None = None) -> GetCurrentNetworkResponse

get_daa_score_timestamp_estimate

get_daa_score_timestamp_estimate(request: GetDaaScoreTimestampEstimateRequest) -> GetDaaScoreTimestampEstimateResponse

get_fee_estimate

get_fee_estimate(request: GetFeeEstimateRequest | None = None) -> GetFeeEstimateResponse

get_fee_estimate_experimental

get_fee_estimate_experimental(request: GetFeeEstimateExperimentalRequest) -> GetFeeEstimateExperimentalResponse

get_headers

get_headers(request: GetHeadersRequest) -> GetHeadersResponse

get_info

get_info(request: GetInfoRequest | None = None) -> GetInfoResponse

get_mempool_entries

get_mempool_entries(request: GetMempoolEntriesRequest) -> GetMempoolEntriesResponse

get_mempool_entries_by_addresses

get_mempool_entries_by_addresses(request: GetMempoolEntriesByAddressesRequest) -> GetMempoolEntriesByAddressesResponse

get_mempool_entry

get_mempool_entry(request: GetMempoolEntryRequest) -> GetMempoolEntryResponse

get_metrics

get_metrics(request: GetMetricsRequest | None = None) -> GetMetricsResponse

get_peer_addresses

get_peer_addresses(request: GetPeerAddressesRequest | None = None) -> GetPeerAddressesResponse

get_server_info

get_server_info(request: GetServerInfoRequest | None = None) -> GetServerInfoResponse

get_sink

get_sink(request: GetSinkRequest | None = None) -> GetSinkResponse

get_sink_blue_score

get_sink_blue_score(request: GetSinkBlueScoreRequest | None = None) -> GetSinkBlueScoreResponse

get_subnetwork

get_subnetwork(request: GetSubnetworkRequest) -> GetSubnetworkResponse

get_sync_status

get_sync_status(request: GetSyncStatusRequest | None = None) -> GetSyncStatusResponse

get_system_info

get_system_info(request: GetSystemInfoRequest | None = None) -> GetSystemInfoResponse

get_utxo_return_address

get_utxo_return_address(request: GetUtxoReturnAddressRequest) -> GetUtxoReturnAddressResponse

get_utxos_by_addresses

get_utxos_by_addresses(request: GetUtxosByAddressesRequest) -> GetUtxosByAddressesResponse

get_virtual_chain_from_block

get_virtual_chain_from_block(request: GetVirtualChainFromBlockRequest) -> GetVirtualChainFromBlockResponse

get_virtual_chain_from_block_v2

get_virtual_chain_from_block_v2(request: GetVirtualChainFromBlockV2Request) -> GetVirtualChainFromBlockV2Response

ping

ping(request: PingRequest | None = None) -> PingResponse

remove_all_event_listeners

remove_all_event_listeners() -> None

Remove all registered event listeners.

remove_event_listener

remove_event_listener(event: NotificationEvent, callback: Optional[Any] = None) -> None

Remove an event listener.

PARAMETER	DESCRIPTION
event	Event type as kebab string or NotificationEvent variant. See NotificationEvent for acceptable values. TYPE: NotificationEvent
callback	Specific callback to remove, or None to remove all. TYPE: Optional[Any] DEFAULT: None

RAISES	DESCRIPTION
Exception	If the event type is invalid.

resolve_finality_conflict

resolve_finality_conflict(request: ResolveFinalityConflictRequest) -> ResolveFinalityConflictResponse

set_network_id

set_network_id(network_id: NetworkId) -> None

Set the network ID for the client.

PARAMETER	DESCRIPTION
network_id	The network identifier. TYPE: NetworkId

RAISES	DESCRIPTION
Exception	If setting the network ID fails.

set_resolver

set_resolver(resolver: Resolver) -> None

Set a new resolver for node discovery.

PARAMETER	DESCRIPTION
resolver	The resolver to use. TYPE: Resolver

RAISES	DESCRIPTION
Exception	If setting the resolver fails.

shutdown

shutdown(request: ShutdownRequest | None = None) -> ShutdownResponse

start

start() -> None

Start the RPC client (async).

RAISES	DESCRIPTION
Exception	If starting fails.

stop

stop() -> None

Stop background RPC services (automatically stopped when invoking RpcClient.disconnect).

submit_block

submit_block(request: SubmitBlockRequest) -> SubmitBlockResponse

submit_transaction

submit_transaction(request: SubmitTransactionRequest) -> SubmitTransactionResponse

submit_transaction_replacement

submit_transaction_replacement(request: SubmitTransactionReplacementRequest) -> SubmitTransactionReplacementResponse

subscribe_block_added

subscribe_block_added() -> None

subscribe_finality_conflict

subscribe_finality_conflict() -> None

subscribe_finality_conflict_resolved

subscribe_finality_conflict_resolved() -> None

subscribe_new_block_template

subscribe_new_block_template() -> None

subscribe_pruning_point_utxo_set_override

subscribe_pruning_point_utxo_set_override() -> None

subscribe_sink_blue_score_changed

subscribe_sink_blue_score_changed() -> None

subscribe_utxos_changed

subscribe_utxos_changed(addresses: Sequence[Address]) -> None

Subscribe to UTXO changes for specific addresses (async).

PARAMETER	DESCRIPTION
addresses	List of addresses to monitor. TYPE: Sequence[Address]

RAISES	DESCRIPTION
Exception	If not connected or subscription fails.

subscribe_virtual_chain_changed

subscribe_virtual_chain_changed(include_accepted_transaction_ids: bool) -> None

Subscribe to virtual chain changes (async).

PARAMETER	DESCRIPTION
include_accepted_transaction_ids	Include transaction IDs in notifications. TYPE: bool

RAISES	DESCRIPTION
Exception	If not connected or subscription fails.

subscribe_virtual_daa_score_changed

subscribe_virtual_daa_score_changed() -> None

trigger_abort

trigger_abort() -> None

Triggers a disconnection on the underlying WebSocket if the WebSocket is in connected state. This is intended for debug purposes only. Can be used to test application reconnection logic.

unban

unban(request: UnbanRequest) -> UnbanResponse

unsubscribe_block_added

unsubscribe_block_added() -> None

unsubscribe_finality_conflict

unsubscribe_finality_conflict() -> None

unsubscribe_finality_conflict_resolved

unsubscribe_finality_conflict_resolved() -> None

unsubscribe_new_block_template

unsubscribe_new_block_template() -> None

unsubscribe_pruning_point_utxo_set_override

unsubscribe_pruning_point_utxo_set_override() -> None

unsubscribe_sink_blue_score_changed

unsubscribe_sink_blue_score_changed() -> None

unsubscribe_utxos_changed

unsubscribe_utxos_changed(addresses: Sequence[Address]) -> None

Unsubscribe from UTXO changes for specific addresses (async).

PARAMETER	DESCRIPTION
addresses	List of addresses to stop monitoring. TYPE: Sequence[Address]

RAISES	DESCRIPTION
Exception	If not connected or unsubscription fails.

unsubscribe_virtual_chain_changed

unsubscribe_virtual_chain_changed(include_accepted_transaction_ids: bool) -> None

Unsubscribe from virtual chain changes (async).

PARAMETER	DESCRIPTION
include_accepted_transaction_ids	Must match the subscription parameter. TYPE: bool

RAISES	DESCRIPTION
Exception	If not connected or unsubscription fails.

unsubscribe_virtual_daa_score_changed

unsubscribe_virtual_daa_score_changed() -> None