Developer Interface

Keys

bitcash.Key

alias of bitcash.wallet.PrivateKey

class bitcash.PrivateKey(wif=None)

This class represents a BitcoinCash private key. Key is an alias.

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 version byte is disregarded. Compression will be used by all new keys.
Raises:TypeError – If wif is not a str.
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_transaction(outputs, fee=None, leftover=None, combine=True, message=None, unspents=None)

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 (int) – The number of satoshi per byte to pay to miners. By default Bitcash will poll https://bitcoincashfees.earn.com and use a fee that will allow your transaction to be confirmed as soon as possible.
  • leftover (str) – The destination that will receive any change from the transaction. By default Bitcash will send any change to the same address you sent from.
  • combine (bool) – Whether or not Bitcash should use all available UTXOs to make future transactions smaller and therefore reduce fees. By default Bitcash will consolidate UTXOs.
  • message (str) – 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 40 bytes.
  • unspents (list of Unspent) – The UTXOs to use as the inputs. By default Bitcash will communicate with the blockchain itself.
Returns:

The signed transaction as hex.

Return type:

str

classmethod from_bytes(bytestr)
Parameters:bytestr (bytes) – A private key previously encoded as hex.
Return type:PrivateKey
classmethod from_der(der)
Parameters:der (bytes) – A private key previously encoded as DER.
Return type:PrivateKey
classmethod from_hex(hexed)
Parameters:hexed (str) – A private key previously encoded as hex.
Return type:PrivateKey
classmethod from_int(num)
Parameters:num (int) – A private key in raw integer form.
Return type:PrivateKey
classmethod from_pem(pem)
Parameters:pem (bytes) – A private key previously encoded as PEM.
Return type:PrivateKey
get_balance(currency='satoshi')

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

Parameters:currency (str) – One of the Supported Currencies.
Return type:str
get_transactions()

Fetches transaction history.

Return type:list of str transaction IDs
get_unspents()

Fetches all available unspent transaction outputs.

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(address, outputs, compressed=True, fee=None, leftover=None, combine=True, message=None, unspents=None)

Prepares a P2PKH transaction for offline signing.

Parameters:
  • 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 (int) –

    The number of satoshi per byte to pay to miners. By default Bitcash will poll https://bitcoincashfees.earn.com and use a fee that will allow your transaction to be confirmed as soon as possible.

  • leftover (str) – The destination that will receive any change from the transaction. By default Bitcash will send any change to the same address you sent from.
  • combine (bool) – Whether or not Bitcash should use all available UTXOs to make future transactions smaller and therefore reduce fees. By default Bitcash will consolidate UTXOs.
  • message (str) – 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 40 bytes.
  • unspents (list of Unspent) – The UTXOs to use as the inputs. By default Bitcash will communicate with the blockchain itself.
Returns:

JSON storing data required to create an offline transaction.

Return type:

str

public_key

The public point serialized to bytes.

public_point

The public point (x, y).

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

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 (int) –

    The number of satoshi per byte to pay to miners. By default Bitcash will poll https://bitcoincashfees.earn.com and use a fee that will allow your transaction to be confirmed as soon as possible.

  • leftover (str) – The destination that will receive any change from the transaction. By default Bitcash will send any change to the same address you sent from.
  • combine (bool) – Whether or not Bitcash should use all available UTXOs to make future transactions smaller and therefore reduce fees. By default Bitcash will consolidate UTXOs.
  • message (str) – 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 40 bytes.
  • unspents (list of Unspent) – The UTXOs to use as the inputs. By default Bitcash will communicate with the blockchain itself.
Returns:

The transaction ID.

Return type:

str

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
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 bitcash.PrivateKeyTestnet(wif=None)

This class represents a testnet BitcoinCash private key. Note: coins on the test network have no monetary value!

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 version byte is disregarded. Compression will be used by all new keys.
Raises:TypeError – If wif is not a str.
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_transaction(outputs, fee=None, leftover=None, combine=True, message=None, unspents=None)

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 (int) –

    The number of satoshi per byte to pay to miners. By default Bitcash will poll https://bitcoincashfees.earn.com and use a fee that will allow your transaction to be confirmed as soon as possible.

  • leftover (str) – The destination that will receive any change from the transaction. By default Bitcash will send any change to the same address you sent from.
  • combine (bool) – Whether or not Bitcash should use all available UTXOs to make future transactions smaller and therefore reduce fees. By default Bitcash will consolidate UTXOs.
  • message (str) – 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 40 bytes.
  • unspents (list of Unspent) – The UTXOs to use as the inputs. By default Bitcash will communicate with the testnet blockchain itself.
Returns:

The signed transaction as hex.

Return type:

str

classmethod from_bytes(bytestr)
Parameters:bytestr (bytes) – A private key previously encoded as hex.
Return type:PrivateKeyTestnet
classmethod from_der(der)
Parameters:der (bytes) – A private key previously encoded as DER.
Return type:PrivateKeyTestnet
classmethod from_hex(hexed)
Parameters:hexed (str) – A private key previously encoded as hex.
Return type:PrivateKeyTestnet
classmethod from_int(num)
Parameters:num (int) – A private key in raw integer form.
Return type:PrivateKeyTestnet
classmethod from_pem(pem)
Parameters:pem (bytes) – A private key previously encoded as PEM.
Return type:PrivateKeyTestnet
get_balance(currency='satoshi')

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

Parameters:currency (str) – One of the Supported Currencies.
Return type:str
get_transactions()

Fetches transaction history.

Return type:list of str transaction IDs
get_unspents()

Fetches all available unspent transaction outputs.

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(address, outputs, compressed=True, fee=None, leftover=None, combine=True, message=None, unspents=None)

Prepares a P2PKH transaction for offline signing.

Parameters:
  • 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 (int) –

    The number of satoshi per byte to pay to miners. By default Bitcash will poll https://bitcoincashfees.earn.com and use a fee that will allow your transaction to be confirmed as soon as possible.

  • leftover (str) – The destination that will receive any change from the transaction. By default Bitcash will send any change to the same address you sent from.
  • combine (bool) – Whether or not Bitcash should use all available UTXOs to make future transactions smaller and therefore reduce fees. By default Bitcash will consolidate UTXOs.
  • message (str) – 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 40 bytes.
  • unspents (list of Unspent) – The UTXOs to use as the inputs. By default Bitcash will communicate with the blockchain itself.
Returns:

JSON storing data required to create an offline transaction.

Return type:

str

public_key

The public point serialized to bytes.

public_point

The public point (x, y).

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

Creates a signed P2PKH transaction and attempts to broadcast it on the testnet 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 (int) –

    The number of satoshi per byte to pay to miners. By default Bitcash will poll https://bitcoincashfees.earn.com and use a fee that will allow your transaction to be confirmed as soon as possible.

  • leftover (str) – The destination that will receive any change from the transaction. By default Bitcash will send any change to the same address you sent from.
  • combine (bool) – Whether or not Bitcash should use all available UTXOs to make future transactions smaller and therefore reduce fees. By default Bitcash will consolidate UTXOs.
  • message (str) – 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 40 bytes.
  • unspents (list of Unspent) – The UTXOs to use as the inputs. By default Bitcash will communicate with the testnet blockchain itself.
Returns:

The transaction ID.

Return type:

str

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
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 bitcash.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 version 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
public_key

The public point serialized to bytes.

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 bitcash.network.NetworkAPI
BROADCAST_TX_MAIN = [<bound method InsightAPI.broadcast_tx of <class 'bitcash.network.services.CashExplorerBitcoinDotComAPI'>>, <bound method InsightAPI.broadcast_tx of <class 'bitcash.network.services.BlockdozerAPI'>>]
BROADCAST_TX_TEST = [<bound method BlockdozerAPI.broadcast_tx_testnet of <class 'bitcash.network.services.BlockdozerAPI'>>]
GET_BALANCE_MAIN = [<bound method CashExplorerBitcoinDotComAPI.get_balance of <class 'bitcash.network.services.CashExplorerBitcoinDotComAPI'>>, <bound method InsightAPI.get_balance of <class 'bitcash.network.services.BlockdozerAPI'>>]
GET_BALANCE_TEST = [<bound method BlockdozerAPI.get_balance_testnet of <class 'bitcash.network.services.BlockdozerAPI'>>]
GET_TRANSACTIONS_MAIN = [<bound method CashExplorerBitcoinDotComAPI.get_transactions of <class 'bitcash.network.services.CashExplorerBitcoinDotComAPI'>>, <bound method InsightAPI.get_transactions of <class 'bitcash.network.services.BlockdozerAPI'>>]
GET_TRANSACTIONS_TEST = [<bound method BlockdozerAPI.get_transactions_testnet of <class 'bitcash.network.services.BlockdozerAPI'>>]
GET_TX_AMOUNT = []
GET_UNSPENT_MAIN = [<bound method CashExplorerBitcoinDotComAPI.get_unspent of <class 'bitcash.network.services.CashExplorerBitcoinDotComAPI'>>, <bound method InsightAPI.get_unspent of <class 'bitcash.network.services.BlockdozerAPI'>>]
GET_UNSPENT_TEST = [<bound method BlockdozerAPI.get_unspent_testnet of <class 'bitcash.network.services.BlockdozerAPI'>>]
IGNORED_ERRORS = (<class 'ConnectionError'>, <class 'requests.exceptions.ConnectionError'>, <class 'requests.exceptions.Timeout'>, <class 'requests.exceptions.ReadTimeout'>)
classmethod 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.
classmethod broadcast_tx_testnet(tx_hex)

Broadcasts a transaction to the test network’s blockchain.

Parameters:tx_hex (str) – A signed transaction in hex form.
Raises:ConnectionError – If all API services fail.
classmethod get_balance(address)

Gets the balance of an address in satoshi.

Parameters:address (str) – The address in question.
Raises:ConnectionError – If all API services fail.
Return type:int
classmethod get_balance_testnet(address)

Gets the balance of an address on the test network in satoshi.

Parameters:address (str) – The address in question.
Raises:ConnectionError – If all API services fail.
Return type:int
classmethod 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
classmethod get_transactions_testnet(address)

Gets the ID of all transactions related to an address on the test network.

Parameters:address (str) – The address in question.
Raises:ConnectionError – If all API services fail.
Return type:list of str
classmethod get_tx_amount(txid, txindex)

Gets the ID of all transactions related to an address.

Parameters:
  • txid (str) – The transaction id in question.
  • txindex (str) – The transaction index in question.
Raises:

ConnectionError – If all API services fail.

Return type:

list of str

classmethod get_unspent(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
classmethod get_unspent_testnet(address)

Gets all unspent transaction outputs belonging to an address on the test network.

Parameters:address (str) – The address in question.
Raises:ConnectionError – If all API services fail.
Return type:list of Unspent
class bitcash.network.meta.Unspent(amount, confirmations, script, txid, txindex)

Represents an unspent transaction output (UTXO).

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

Exchange Rates

bitcash.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

bitcash.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

bitcash.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

bitcash.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

class bitcash.network.rates.RatesAPI

Each method converts exactly 1 unit of the currency to the equivalent number of satoshi.

AUD_RATES = []
BRL_RATES = []
CAD_RATES = []
CHF_RATES = []
CLP_RATES = []
CNY_RATES = []
DKK_RATES = []
EUR_RATES = []
GBP_RATES = []
HKD_RATES = []
IGNORED_ERRORS = (<class 'requests.exceptions.ConnectionError'>, <class 'requests.exceptions.Timeout'>)
ISK_RATES = []
JPY_RATES = []
KRW_RATES = []
NZD_RATES = []
PLN_RATES = []
RUB_RATES = []
SEK_RATES = []
SGD_RATES = []
THB_RATES = []
TWD_RATES = []
USD_RATES = []
classmethod aud_to_satoshi()
classmethod brl_to_satoshi()
classmethod cad_to_satoshi()
classmethod chf_to_satoshi()
classmethod clp_to_satoshi()
classmethod cny_to_satoshi()
classmethod dkk_to_satoshi()
classmethod eur_to_satoshi()
classmethod gbp_to_satoshi()
classmethod hkd_to_satoshi()
classmethod isk_to_satoshi()
classmethod jpy_to_satoshi()
classmethod krw_to_satoshi()
classmethod nzd_to_satoshi()
classmethod pln_to_satoshi()
classmethod rub_to_satoshi()
classmethod sek_to_satoshi()
classmethod sgd_to_satoshi()
classmethod thb_to_satoshi()
classmethod twd_to_satoshi()
classmethod usd_to_satoshi()
class bitcash.network.rates.BitpayRates
SINGLE_RATE = 'https://bitcashpay.com/api/rates/'
classmethod aud_to_satoshi()
classmethod brl_to_satoshi()
classmethod cad_to_satoshi()
classmethod chf_to_satoshi()
classmethod clp_to_satoshi()
classmethod cny_to_satoshi()
classmethod currency_to_satoshi(currency)
classmethod dkk_to_satoshi()
classmethod eur_to_satoshi()
classmethod gbp_to_satoshi()
classmethod hkd_to_satoshi()
classmethod isk_to_satoshi()
classmethod jpy_to_satoshi()
classmethod krw_to_satoshi()
classmethod nzd_to_satoshi()
classmethod pln_to_satoshi()
classmethod rub_to_satoshi()
classmethod sek_to_satoshi()
classmethod sgd_to_satoshi()
classmethod thb_to_satoshi()
classmethod twd_to_satoshi()
classmethod usd_to_satoshi()
class bitcash.network.rates.BlockchainRates
SINGLE_RATE = 'https://blockchain.info/tobch?currency={}&value=1'
classmethod aud_to_satoshi()
classmethod brl_to_satoshi()
classmethod cad_to_satoshi()
classmethod chf_to_satoshi()
classmethod clp_to_satoshi()
classmethod cny_to_satoshi()
classmethod currency_to_satoshi(currency)
classmethod dkk_to_satoshi()
classmethod eur_to_satoshi()
classmethod gbp_to_satoshi()
classmethod hkd_to_satoshi()
classmethod isk_to_satoshi()
classmethod jpy_to_satoshi()
classmethod krw_to_satoshi()
classmethod nzd_to_satoshi()
classmethod pln_to_satoshi()
classmethod rub_to_satoshi()
classmethod sek_to_satoshi()
classmethod sgd_to_satoshi()
classmethod thb_to_satoshi()
classmethod twd_to_satoshi()
classmethod usd_to_satoshi()

Fees

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

Gets the recommended satoshi per byte fee.

Parameters:speed (string) – One of: ‘fast’, ‘medium’, ‘slow’.
Return type:int

Utilities

bitcash.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 bitcash.exceptions.InsufficientFunds