nimiqclient.nimiq_client.NimiqClient¶

class nimiqclient.nimiq_client.NimiqClient(scheme='http', user='', password='', host='127.0.0.1', port=8648)[source]¶

Bases: object

API client for the Nimiq JSON RPC server.

Parameters

scheme (str, optional) – Protocol squeme, “http” or “https”.
user (str, optional) – Authorized user.
password (str, optional) – Password for the authorized user.
host (str, optional) – Host IP address.
port (int, optional) – Host port.

Methods

`accounts`	Returns a list of addresses owned by client.
`block_number`	Returns the height of most recent block.
`consensus`	Returns information on the current consensus state.
`constant`	Returns the value of the constant.
`create_account`	Creates a new account and stores its private key in the client store.
`create_raw_transaction`	Creates and signs a transaction without sending it.
`get_account`	Returns details for the account of given address.
`get_balance`	Returns the balance of the account of given address.
`get_block_by_hash`	Returns information about a block by hash.
`get_block_by_number`	Returns information about a block by block number.
`get_block_template`	Returns a template to build the next block for mining.
`get_block_transaction_count_by_hash`	Returns the number of transactions in a block from a block matching the given block hash.
`get_block_transaction_count_by_number`	Returns the number of transactions in a block matching the given block number.
`get_raw_transaction_info`	Deserializes hex-encoded transaction and returns a transaction object.
`get_transaction_by_block_hash_and_index`	Returns information about a transaction by block hash and transaction index position.
`get_transaction_by_block_number_and_index`	Returns information about a transaction by block number and transaction index position.
`get_transaction_by_hash`	Returns the information about a transaction requested by transaction hash.
`get_transaction_receipt`	Returns the receipt of a transaction by transaction hash.
`get_transactions_by_address`	Returns the latest transactions successfully performed by or for an address.
`get_work`	Returns instructions to mine the next block.
`hashrate`	Returns the number of hashes per second that the node is mining with.
`is_mining`	Returns true if client is actively mining new blocks.
`mempool`	Returns information on the current mempool situation.
`mempool_content`	Returns transactions that are currently in the mempool.
`min_fee_per_byte`	Returns the minimum fee per byte.
`miner_address`	Returns the miner address.
`miner_threads`	Returns the number of CPU threads for the miner.
`peer_count`	Returns number of peers currently connected to the client.
`peer_list`	Returns list of peers known to the client.
`peer_state`	Returns the state of the peer.
`pool`	Returns the mining pool.
`pool_confirmed_balance`	Returns the confirmed mining pool balance.
`pool_connection_state`	Returns the connection state to mining pool.
`reset_constant`	Resets the constant to default value.
`send_raw_transaction`	Sends a signed message call transaction or a contract creation, if the data field contains code.
`send_transaction`	Creates new message call transaction or a contract creation, if the data field contains code.
`set_constant`	Overrides the value of a constant.
`set_log`	Sets the log level of the node.
`set_min_fee_per_byte`	Sets the minimum fee per byte.
`set_miner_threads`	Sets the number of CPU threads for the miner.
`set_mining`	Sets the client mining state.
`set_peer_state`	Returns the state of the peer.
`set_pool`	Sets the mining pool.
`submit_block`	Submits a block to the node.
`syncing`	Returns an object with data about the sync status or False.

accounts()[source]¶

Returns a list of addresses owned by client.

Returns: List of Accounts owned by the client.
Return type: list of (Account or VestingContract or HTLC)

block_number()[source]¶

Returns the height of most recent block.

Returns: The current block height the client is on.
Return type: int

consensus()[source]¶

Returns information on the current consensus state.

Returns: Consensus state. “established” is the value for a good state, other values indicate bad.
Return type: ConsensusState

constant(constant)[source]¶

Returns the value of the constant.

Parameters: constant (str) – The class and name of the constant (format should be “Class.CONSTANT”).
Returns: The value of the constant.
Return type: int

create_account()[source]¶

Creates a new account and stores its private key in the client store.

Returns: Information on the wallet that was created using the command.
Return type: Wallet

create_raw_transaction(transaction)[source]¶

Creates and signs a transaction without sending it. The transaction can then be send via sendRawTransaction() without accidentally replaying it.

Parameters: transaction (OutgoingTransaction) – The transaction object.
Returns: Hex-encoded transaction.
Return type: str

get_account(address)[source]¶

Returns details for the account of given address.

Parameters: address (str) – Address to get account details.
Returns: Details about the account. Returns the default empty basic account for non-existing accounts.
Return type: Account or VestingContract or HTLC

get_balance(address)[source]¶

Returns the balance of the account of given address.

Parameters: address (str) – Address to check for balance.
Returns: The current balance at the specified address (in smalest unit).
Return type: int

get_block_by_hash(hash, include_transactions=None)[source]¶

Returns information about a block by hash.

Parameters

hash (str) – Hash of the block to gather information on.
include_transactions (bool, optional) – If True it returns the full transaction objects, if False only the hashes of the transactions.

Returns

A block object or None when no block was found.

Return type

Block or None

get_block_by_number(height, include_transactions=None)[source]¶

Returns information about a block by block number.

Parameters

height (int) – The height of the block to gather information on.
include_transactions (bool, optional) – If True it returns the full transaction objects, if False only the hashes of the transactions.

Returns

A block object or None when no block was found.

Return type

Block or None

get_block_template(address=None, extra_data='')[source]¶

Returns a template to build the next block for mining. This will consider pool instructions when connected to a pool. If address and extra_data are provided the values are overriden.

Parameters

address (str) – The address to use as a miner for this block. This overrides the address provided during startup or from the pool.
extra_data (str) – Hex-encoded value for the extra data field. This overrides the extra data provided during startup or from the pool.

Returns

A block template object.

Return type

BlockTemplate

get_block_transaction_count_by_hash(hash)[source]¶

Returns the number of transactions in a block from a block matching the given block hash.

Parameters: hash (str) – Hash of the block.
Returns: Number of transactions in the block found, or None, when no block was found.
Return type: int or None

get_block_transaction_count_by_number(height)[source]¶

Returns the number of transactions in a block matching the given block number.

Parameters: height (int) – Height of the block.
Returns: Number of transactions in the block found, or None, when no block was found.
Return type: int or None

get_raw_transaction_info(transaction)[source]¶

Deserializes hex-encoded transaction and returns a transaction object.

Parameters: transaction (str) – The hex encoded signed transaction.
Returns: The transaction object.
Return type: Transaction

get_transaction_by_block_hash_and_index(hash, index)[source]¶

Returns information about a transaction by block hash and transaction index position.

Parameters

hash (str) – Hash of the block containing the transaction.
index (int) – Index of the transaction in the block.

Returns

A transaction object or None when no transaction was found.

Return type

Transaction or None

get_transaction_by_block_number_and_index(height, index)[source]¶

Returns information about a transaction by block number and transaction index position.

Parameters

height (int) – Height of the block containing the transaction.
index (int) – Index of the transaction in the block.

Returns

A transaction object or None when no transaction was found.

Return type

Transaction or None

get_transaction_by_hash(hash)[source]¶

Returns the information about a transaction requested by transaction hash.

Parameters: hash (str) – Hash of a transaction.
Returns: A transaction object or None when no transaction was found.
Return type: Transaction or None

get_transaction_receipt(hash)[source]¶

Returns the receipt of a transaction by transaction hash.

Parameters: hash (str) – Hash of a transaction.
Returns: A transaction receipt object, or None when no receipt was found.
Return type: TransactionReceipt or None

get_transactions_by_address(address, number_of_transactions=None)[source]¶

Returns the latest transactions successfully performed by or for an address. Note that this information might change when blocks are rewinded on the local state due to forks.

Parameters

address (str) – Address of which transactions should be gathered.
number_of_transactions (int, optional) – Number of transactions that shall be returned.

Returns

List of transactions linked to the requested address.

Return type

list of (Transaction)

get_work(address=None, extra_data='')[source]¶

Returns instructions to mine the next block. This will consider pool instructions when connected to a pool.

Parameters

address (str) – The address to use as a miner for this block. This overrides the address provided during startup or from the pool.
extra_data (str) – Hex-encoded value for the extra data field. This overrides the extra data provided during startup or from the pool.

Returns

Mining work instructions.

Return type

WorkInstructions

hashrate()[source]¶

Returns the number of hashes per second that the node is mining with.

Returns: Number of hashes per second.
Return type: float

is_mining()[source]¶

Returns true if client is actively mining new blocks.

Returns: True if the client is mining, otherwise False.
Return type: bool

mempool()[source]¶

Returns information on the current mempool situation. This will provide an overview of the number of transactions sorted into buckets based on their fee per byte (in smallest unit).

Returns: Mempool information.
Return type: MempoolInfo

mempool_content(include_transactions=None)[source]¶

Returns transactions that are currently in the mempool.

Parameters: include_transactions (bool, optional) – If True includes full transactions, if False includes only transaction hashes.
Returns: List of transactions (either represented by the transaction hash or a transaction object).
Return type: list of (Transaction or str)

min_fee_per_byte()[source]¶

Returns the minimum fee per byte.

Returns: The new minimum fee per byte.
Return type: int

miner_address()[source]¶

Returns the miner address.

Returns: The miner address configured on the node.
Return type: str

miner_threads()[source]¶

Returns the number of CPU threads for the miner.

Returns: The number of threads allocated for mining.
Return type: int

peer_count()[source]¶

Returns number of peers currently connected to the client.

Returns: Number of connected peers.
Return type: int

peer_list()[source]¶

Returns list of peers known to the client.

Returns: The list of peers.
Return type: list of (Peer)

peer_state(address)[source]¶

Returns the state of the peer.

Parameters: address (str) – The address of the peer.
Returns: The current state of the peer.
Return type: Peer

pool()[source]¶

Returns the mining pool.

Returns: The mining pool connection string, or None if not enabled.
Return type: str or None

pool_confirmed_balance()[source]¶

Returns the confirmed mining pool balance.

Returns: The confirmed mining pool balance (in smallest unit).
Return type: int

pool_connection_state()[source]¶

Returns the connection state to mining pool.

Returns: The mining pool connection state.
Return type: PoolConnectionState

reset_constant(constant)[source]¶

Resets the constant to default value.

Parameters: constant (str) – Name of the constant.
Returns: The new value of the constant.
Return type: int

send_raw_transaction(transaction)[source]¶

Sends a signed message call transaction or a contract creation, if the data field contains code.

Parameters: transaction (str) – The hex encoded signed transaction
Returns: The Hex-encoded transaction hash.
Return type: str

send_transaction(transaction)[source]¶

Creates new message call transaction or a contract creation, if the data field contains code.

Parameters: transaction (OutgoingTransaction) – The transaction object.
Returns: The Hex-encoded transaction hash.
Return type: str

set_constant(constant, value=None)[source]¶

Overrides the value of a constant. It sets the constant to the given value. To reset the constant use reset_constant() instead.

Parameters

constant (str) – The class and name of the constant (format should be “Class.CONSTANT”).
value (int, optional) – The new value of the constant.

Returns

The new value of the constant.

Return type

int

set_log(tag, level)[source]¶

Sets the log level of the node.

Parameters

tag (str) – Tag: If “*” the log level is set globally, otherwise the log level is applied only on this tag.
level (LogLevel) – Minimum log level to display.

Returns

True if the log level was changed, False otherwise.

Return type

bool

set_min_fee_per_byte(fee=None)[source]¶

Sets the minimum fee per byte.

Parameters: fee (int, optional) – The new minimum fee per byte.
Returns: The new minimum fee per byte.
Return type: int

set_miner_threads(threads=None)[source]¶

Sets the number of CPU threads for the miner.

Parameters: threads (int, optional) – The number of threads to allocate for mining.
Returns: The new number of threads allocated for mining.
Return type: int

set_mining(state=None)[source]¶

Sets the client mining state.

Parameters: state (bool) – The state to be set.
Returns: True if the client is mining, otherwise False.
Return type: bool

set_peer_state(address, command=None)[source]¶

Returns the state of the peer.

Parameters

address (str) – The address of the peer.
command (PeerStateCommand) – The command to send.

Returns

The new state of the peer.

Return type

Peer

set_pool(address=None)[source]¶

Sets the mining pool.

Parameters: address (str, optional) – The mining pool connection string (“url:port”) or boolean to enable/disable pool mining.
Returns: The new mining pool connection string, or None if not enabled.
Return type: str or None

submit_block(block)[source]¶

Submits a block to the node. When the block is valid, the node will forward it to other nodes in the network.

Parameters: block (Block) – Hex-encoded full block (including header, interlink and body). When submitting work from getWork, remember to include the suffix.

syncing()[source]¶

Returns an object with data about the sync status or False.

Returns: An object with sync status data or False, when not syncing.
Return type: SyncStatus