Developer Interface

Keys

bitsv.Key

alias of bitsv.wallet.PrivateKey

class bitsv.PrivateKey(wif=None, network='main')

This class represents a Bitcoin SV private key. Key is an alias. Select from network = ‘main’, ‘test’ or ‘stn’ for mainnet, testnet or scaling-testnet respectively. Defaults to mainnet.

Parameters

  • wif (str) – A private key serialized to the Wallet Import Format. If the argument is not supplied, a new private key will be created. The WIF compression flag will be adhered to, but the prefix byte is disregarded. Compression will be used by all new keys.

  • network (str) – ‘main’, ‘test’ or ‘stn’

Raises

TypeError – If wif is not a str.

property address

The public address you share with others to receive funds.

balance_as(currency)

Returns your balance as a formatted string in a particular currency.

Parameters

currency (str) – One of the Supported Currencies.

Return type

str

create_op_return_tx(list_of_pushdata, outputs=None, fee=1, unspents=None, leftover=None, combine=False)

Creates a rawtx with OP_RETURN metadata ready for broadcast.

list_of_pushdata : a list of tuples (pushdata, encoding) where encoding is either “hex” or “utf-8” fee : sat/byte (defaults to ~bitsv.network.fees.DEFAULT_FEE_MEDIUM)

rawtx

list_of_pushdata = [(‘6d01’, ‘hex’),

(‘bitPUSHER’, ‘utf-8’)]

as per memo.cash protocol @ https://memo.cash/protocol this results in a “Set name” action to “bitPUSHER”

Parameters

  • outputs (list of tuple) – A sequence of outputs you wish to send in the form (destination, amount, currency). The amount can be either an int, float, or string as long as it is a valid input to decimal.Decimal. The currency must be supported.

  • fee (float) – The number of satoshi per byte to pay to miners. By default BitSV will use a fee of ~bitsv.network.fees.DEFAULT_FEE_MEDIUM

  • leftover (str) – The destination that will receive any change from the transaction. By default BitSV will send any change to the same address you sent from.

  • combine (bool) – Whether or not BitSV should use all available UTXOs to make future transactions smaller and therefore reduce fees. By default BitSV will consolidate UTXOs.

  • unspents (list of Unspent) – The UTXOs to use as the inputs. By default BitSV will communicate with the blockchain itself.

  • list_of_pushdata –

    List indicating pushdata to be included in op_return as e.g.: [(‘6d01’, ‘hex’),

    (‘hello’, ‘utf-8’)]

:type list_of_pushdata:list of tuples

create_transaction(outputs, fee=None, leftover=None, combine=True, message=None, unspents=None, custom_pushdata=False)

Creates a signed P2PKH transaction.

Parameters

  • outputs (list of tuple) – A sequence of outputs you wish to send in the form (destination, amount, currency). The amount can be either an int, float, or string as long as it is a valid input to decimal.Decimal. The currency must be supported.

  • fee (float) – The number of satoshi per byte to pay to miners. By default BitSV will use a fee of ~bitsv.network.fees.DEFAULT_FEE_MEDIUM.

  • leftover (str) – The destination that will receive any change from the transaction. By default BitSV will send any change to the same address you sent from.

  • combine (bool) – Whether or not BitSV should use all available UTXOs to make future transactions smaller and therefore reduce fees. By default BitSV will consolidate UTXOs.

  • message (str if custom_pushdata = False; list of tuple if custom_pushdata = True) – A message to include in the transaction. This will be stored in the blockchain forever. Due to size limits, each message will be stored in chunks of 100kb.

  • unspents (list of Unspent) – The UTXOs to use as the inputs. By default BitSV will communicate with the blockchain itself.

  • custom_pushdata (bool) – Adds control over push_data elements inside of the op_return by adding the “custom_pushdata” = True / False parameter as a “switch” to the send() function and the create_transaction() functions.

Returns

The signed transaction as hex.

Return type

str

classmethod from_bytes(bytestr, network='main')
Parameters

  • bytestr (bytes) – A private key previously encoded as hex.

  • network (str) – ‘main’, ‘test’ or ‘stn’

Return type

PrivateKey

classmethod from_der(der, network='main')
Parameters

  • der (bytes) – A private key previously encoded as DER.

  • network (str) – ‘main’, ‘test’ or ‘stn’

Return type

PrivateKey

classmethod from_hex(hexed, network='main')
Parameters

  • hexed (str) – A private key previously encoded as hex.

  • network (str) – ‘main’, ‘test’ or ‘stn’

Return type

PrivateKey

classmethod from_int(num, network='main')
Parameters

  • num (int) – A private key in raw integer form.

  • network (str) – ‘main’, ‘test’ or ‘stn’

Return type

PrivateKey

classmethod from_pem(pem, network='main')
Parameters

  • pem (bytes) – A private key previously encoded as PEM.

  • network (str) – ‘main’, ‘test’ or ‘stn’

Return type

PrivateKey

get_balance(currency='satoshi')

Fetches the current balance. get_unspents() and returns it using balance_as().

Parameters

currency (str) – One of the Supported Currencies.

Return type

str

get_transaction(txid)

Gets a single transaction. :param txid: txid for transaction you want information about :type txid: str

get_transactions()

Fetches transaction history. :param from_index: First index from transactions list to start collecting from :param to_index: Final index to finish collecting transactions from :rtype: list of str transaction IDs

get_unspents()

Gets all unspent transaction outputs belonging to an address.

Parameters

  • address (str) – The address in question.

  • address – Address to get utxos for

  • sort – ‘value:desc’ or ‘value:asc’ to sort unspents by descending/ascending order respectively

Raises

ConnectionError – If all API services fail.

Return type

list of Unspent

is_compressed()

Returns whether or not this private key corresponds to a compressed public key.

Return type

bool

classmethod prepare_transaction(sender_address, outputs, network, compressed=True, fee=None, leftover=None, combine=True, message=None, unspents=None, custom_pushdata=False)

Prepares a P2PKH transaction for offline signing.

Parameters

  • network – The network (‘main’, ‘test’, ‘stn’)

  • sender_address (str) – The address the funds will be sent from.

  • outputs (list of tuple) – A sequence of outputs you wish to send in the form (destination, amount, currency). The amount can be either an int, float, or string as long as it is a valid input to decimal.Decimal. The currency must be supported.

  • compressed (bool) – Whether or not the address corresponds to a compressed public key. This influences the fee.

  • fee (float) – The number of satoshi per byte to pay to miners. By default BitSV will use a fee of ~bitsv.network.fees.DEFAULT_FEE_MEDIUM

  • leftover (str) – The destination that will receive any change from the transaction. By default BitSV will send any change to the same address you sent from.

  • combine (bool) – Whether or not BitSV should use all available UTXOs to make future transactions smaller and therefore reduce fees. By default BitSV will consolidate UTXOs.

  • message (str if custom_pushdata = False; list of tuple if custom_pushdata = True) – A message to include in the transaction. This will be stored in the blockchain forever. Due to size limits, each message will be stored in chunks of 100kb bytes.

  • unspents (list of Unspent) – The UTXOs to use as the inputs. By default BitSV will communicate with the blockchain itself.

  • custom_pushdata (bool) – Adds control over push_data elements inside of the op_return by adding the “custom_pushdata” = True / False parameter as a “switch” to the send() function and the create_transaction() functions.

Returns

JSON storing data required to create an offline transaction.

Return type

str

property public_key

The public point serialized to bytes.

property public_point

The public point (x, y).

property scriptcode
send(outputs, fee=None, leftover=None, combine=True, message=None, unspents=None, custom_pushdata=False)

Creates a signed P2PKH transaction and attempts to broadcast it on the blockchain. This accepts the same arguments as create_transaction().

Parameters

  • outputs (list of tuple) – A sequence of outputs you wish to send in the form (destination, amount, currency). The amount can be either an int, float, or string as long as it is a valid input to decimal.Decimal. The currency must be supported.

  • fee (float) – The number of satoshi per byte to pay to miners. By default BitSV will use a fee of ~bitsv.network.fees.DEFAULT_FEE_MEDIUM.

  • leftover (str) – The destination that will receive any change from the transaction. By default BitSV will send any change to the same address you sent from.

  • combine (bool) – Whether or not BitSV should use all available UTXOs to make future transactions smaller and therefore reduce fees. By default BitSV will consolidate UTXOs.

  • message (str if custom_pushdata = False; list of tuple if custom_pushdata = True) – A message to include in the transaction. This will be stored in the blockchain forever. Due to size limits, each message will be stored in chunks of 100kb.

  • unspents (list of Unspent) – The UTXOs to use as the inputs. By default BitSV will communicate with the blockchain itself.

  • custom_pushdata (bool) – Adds control over push_data elements inside of the op_return by adding the “custom_pushdata” = True / False parameter as a “switch” to the send() function and the create_transaction() functions.

Returns

The transaction ID.

Return type

str

send_op_return(list_of_pushdata, outputs=None, fee=1, unspents=None, leftover=None, combine=False)

Sends a rawtx with OP_RETURN metadata ready for broadcast.

list_of_pushdata : a list of tuples (pushdata, encoding) where encoding is either “hex” or “utf-8” fee : sat/byte (defaults to ~bitsv.network.fees.DEFAULT_FEE_MEDIUM)

rawtx

list_of_pushdata = [(‘6d01’, ‘hex’),

(‘bitPUSHER’, ‘utf-8’)]

as per memo.cash protocol @ https://memo.cash/protocol this results in a “Set name” action to “bitPUSHER”

Parameters

  • outputs (list of tuple) – A sequence of outputs you wish to send in the form (destination, amount, currency). The amount can be either an int, float, or string as long as it is a valid input to decimal.Decimal. The currency must be supported.

  • fee (float) – The number of satoshi per byte to pay to miners. By default BitSV will use a fee of ~bitsv.network.fees.DEFAULT_FEE_MEDIUM

  • leftover (str) – The destination that will receive any change from the transaction. By default BitSV will send any change to the same address you sent from.

  • combine (bool) – Whether or not BitSV should use all available UTXOs to make future transactions smaller and therefore reduce fees. By default BitSV will consolidate UTXOs.

  • unspents (list of Unspent) – The UTXOs to use as the inputs. By default BitSV will communicate with the blockchain itself.

  • list_of_pushdata –

    List indicating pushdata to be included in op_return as e.g.: [(‘6d01’, ‘hex’),

    (‘hello’, ‘utf-8’)]

:type list_of_pushdata:list of tuples

sign(data)

Signs some data which can be verified later by others using the public key.

Parameters

data (bytes) – The message to sign.

Returns

A signature compliant with BIP-62.

Return type

bytes

sign_transaction(tx_data)

Creates a signed P2PKH transaction using previously prepared transaction data.

Parameters

tx_data (str) – Output of prepare_transaction().

Returns

The signed transaction as hex.

Return type

str

sweep(receiving_address, combine=True, message=None, unspents=None, custom_pushdata=False)

Send all bitcoins associated with private key to the receiving address.

If unspents are specified, it will only send the remainder from these utxos to the receiving address (after tx creation).

The ‘low-level’ / more versatile way of doing this is to pass this address to the “leftover” parameter of PrivateKey.send()

to_bytes()
Return type

bytes

to_der()
Return type

bytes

to_hex()
Return type

str

to_int()
Return type

int

to_pem()
Return type

bytes

to_wif()
verify(signature, data)

Verifies some data was signed by this private key.

Parameters

  • signature (bytes) – The signature to verify.

  • data (bytes) – The data that was supposedly signed.

Return type

bool

class bitsv.wallet.BaseKey(wif=None)

This class represents a point on the elliptic curve secp256k1 and provides all necessary cryptographic functionality. You shouldn’t use this class directly.

Parameters

wif (str) – A private key serialized to the Wallet Import Format. If the argument is not supplied, a new private key will be created. The WIF compression flag will be adhered to, but the prefix byte is disregarded. Compression will be used by all new keys.

Raises

TypeError – If wif is not a str.

is_compressed()

Returns whether or not this private key corresponds to a compressed public key.

Return type

bool

property public_key

The public point serialized to bytes.

property public_point

The public point (x, y).

sign(data)

Signs some data which can be verified later by others using the public key.

Parameters

data (bytes) – The message to sign.

Returns

A signature compliant with BIP-62.

Return type

bytes

to_bytes()
Return type

bytes

to_der()
Return type

bytes

to_hex()
Return type

str

to_int()
Return type

int

to_pem()
Return type

bytes

verify(signature, data)

Verifies some data was signed by this private key.

Parameters

  • signature (bytes) – The signature to verify.

  • data (bytes) – The data that was supposedly signed.

Return type

bool

Network

class bitsv.network.NetworkAPI(network)

A Class for handling network API redundancy.

Parameters

network (str) – ‘main’, ‘test’ or ‘stn’ –> feeds into the bitsv.network.NetworkAPI class for redundancy

broadcast_tx(tx_hex)

Broadcasts a transaction to the blockchain.

Parameters

tx_hex (str) – A signed transaction in hex form.

Raises

ConnectionError – If all API services fail.

get_balance(address)

Gets the balance of an address in satoshis.

Parameters

address (str) – The address in question.

Raises

ConnectionError – If all API services fail.

Return type

int

get_transaction(txid)

Gets the full transaction details.

Parameters

txid (str) – The transaction id in question.

Raises

ConnectionError – If all API services fail.

Return type

Transaction

get_transactions(address)

Gets the ID of all transactions related to an address.

Parameters

address (str) – The address in question.

Raises

ConnectionError – If all API services fail.

Return type

list of str

get_unspents(address)

Gets all unspent transaction outputs belonging to an address.

Parameters

address (str) – The address in question.

Raises

ConnectionError – If all API services fail.

Return type

list of Unspent

invoke_api_call(call_list, param)

Tries to invoke all api, raise exception if all fail.

retry_wrapper_call(api_call, param)
class bitsv.network.meta.Unspent(amount, confirmations, txid, txindex)

Represents an unspent transaction output (UTXO).

amount
confirmations
classmethod from_dict(d)
to_dict()
txid
txindex

Exchange Rates

bitsv.network.currency_to_satoshi(amount, currency)

Converts a given amount of currency to the equivalent number of satoshi. The amount can be either an int, float, or string as long as it is a valid input to decimal.Decimal.

Parameters
Return type

int

bitsv.network.currency_to_satoshi_cached(amount, currency)

Converts a given amount of currency to the equivalent number of satoshi. The amount can be either an int, float, or string as long as it is a valid input to decimal.Decimal. Results are cached using a decorator for 60 seconds by default. See Cache Times.

Parameters
Return type

int

bitsv.network.satoshi_to_currency(num, currency)

Converts a given number of satoshi to another currency as a formatted string rounded down to the proper number of decimal places.

Parameters
Return type

str

bitsv.network.satoshi_to_currency_cached(num, currency)

Converts a given number of satoshi to another currency as a formatted string rounded down to the proper number of decimal places. Results are cached using a decorator for 60 seconds by default. See Cache Times.

Parameters
Return type

str

Fees

bitsv.network.get_fee(speed='medium')

Gets the recommended satoshi per byte fee.

Parameters

speed (string) – One of: ‘fast’, ‘medium’, ‘slow’.

Return type

float

Utilities

bitsv.verify_sig(signature, data, public_key)

Verifies some data was signed by the owner of a public key.

Parameters

  • signature (bytes) – The signature to verify.

  • data (bytes) – The data that was supposedly signed.

  • public_key (bytes) – The public key.

Returns

True if all checks pass, False otherwise.

Exceptions

exception bitsv.exceptions.InsufficientFunds