bitshares.bitshares module

class bitshares.bitshares.BitShares(node='', rpcuser='', rpcpassword='', debug=False, skip_wallet_init=False, **kwargs)[source]

Bases: graphenecommon.chain.AbstractGrapheneChain

Connect to the BitShares network.

Parameters:
  • node (str) – Node to connect to (optional)
  • rpcuser (str) – RPC user (optional)
  • rpcpassword (str) – RPC password (optional)
  • nobroadcast (bool) – Do not broadcast a transaction! (optional)
  • debug (bool) – Enable Debugging (optional)
  • keys (array,dict,string) – Predefine the wif keys to shortcut the wallet database (optional)
  • offline (bool) – Boolean to prevent connecting to network (defaults to False) (optional)
  • proposer (str) – Propose a transaction using this proposer (optional)
  • proposal_expiration (int) – Expiration time (in seconds) for the proposal (optional)
  • proposal_review (int) – Review period (in seconds) for the proposal (optional)
  • expiration (int) – Delay in seconds until transactions are supposed to expire (optional)
  • blocking (str) – Wait for broadcasted transactions to be included in a block and return full transaction (can be “head” or “irrversible”)
  • bundle (bool) – Do not broadcast transactions right away, but allow to bundle operations (optional)

Three wallet operation modes are possible:

  • Wallet Database: Here, the bitshareslibs load the keys from the locally stored wallet SQLite database (see storage.py). To use this mode, simply call BitShares() without the keys parameter
  • Providing Keys: Here, you can provide the keys for your accounts manually. All you need to do is add the wif keys for the accounts you want to use as a simple array using the keys parameter to BitShares().
  • Force keys: This more is for advanced users and requires that you know what you are doing. Here, the keys parameter is a dictionary that overwrite the active, owner, or memo keys for any account. This mode is only used for foreign signatures!

If no node is provided, it will connect to the node of http://uptick.rocks. It is highly recommended that you pick your own node instead. Default settings can be changed with:

uptick set node <host>

where <host> starts with ws:// or wss://.

The purpose of this class it to simplify interaction with BitShares.

The idea is to have a class that allows to do this:

from bitshares import BitShares
bitshares = BitShares()
print(bitshares.info())

All that is requires is for the user to have added a key with uptick

uptick addkey

and setting a default author:

uptick set default_account xeroc

This class also deals with edits, votes and reading content.

account_whitelist(account_to_whitelist, lists=None, account=None, **kwargs)[source]

Account whitelisting.

Parameters:
  • account_to_whitelist (str) – The account we want to add to either the white- or the blacklist
  • lists (set) – (defaults to ('white')). Lists the user should be added to. Either empty set, ‘black’, ‘white’ or both.
  • account (str) – (optional) the account to allow access to (defaults to default_account)
allow(foreign, weight=None, permission='active', account=None, threshold=None, **kwargs)[source]

Give additional access to an account by some other public key or account.

Parameters:
  • foreign (str) – The foreign account that will obtain access
  • weight (int) – (optional) The weight to use. If not define, the threshold will be used. If the weight is smaller than the threshold, additional signatures will be required. (defaults to threshold)
  • permission (str) – (optional) The actual permission to modify (defaults to active)
  • account (str) – (optional) the account to allow access to (defaults to default_account)
  • threshold (int) – The threshold that needs to be reached by signatures to be able to interact
approvecommittee(committees, account=None, **kwargs)[source]

Approve a committee.

Parameters:
  • committees (list) – list of committee member name or id
  • account (str) – (optional) the account to allow access to (defaults to default_account)
approveproposal(proposal_ids, account=None, approver=None, **kwargs)[source]

Approve Proposal.

Parameters:
  • proposal_id (list) – Ids of the proposals
  • appprover (str) – The account or key to use for approval (defaults to account)
  • account (str) – (optional) the account to allow access to (defaults to default_account)
approvewitness(witnesses, account=None, **kwargs)[source]

Approve a witness.

Parameters:
  • witnesses (list) – list of Witness name or id
  • account (str) – (optional) the account to allow access to (defaults to default_account)
approveworker(workers, account=None, **kwargs)[source]

Approve a worker.

Parameters:
  • workers (list) – list of worker member name or id
  • account (str) – (optional) the account to allow access to (defaults to default_account)
asset_settle(amount, account=None, **kwargs)[source]
bid_collateral(additional_collateral, debt_covered, account=None, **kwargs)[source]
broadcast(tx=None)

Broadcast a transaction to the Blockchain

Parameters:tx (tx) – Signed transaction to broadcast
cancel(orderNumbers, account=None, **kwargs)[source]

Cancels an order you have placed in a given market. Requires only the “orderNumbers”. An order number takes the form 1.7.xxx.

Parameters:orderNumbers (str) – The Order Object ide of the form 1.7.xxxx
clear()
clear_cache()

Clear Caches

connect(node='', rpcuser='', rpcpassword='', **kwargs)

Connect to blockchain network (internal use only)

create_account(account_name, registrar=None, referrer='1.2.35641', referrer_percent=50, owner_key=None, active_key=None, memo_key=None, owner_account=None, active_account=None, password=None, additional_owner_keys=None, additional_active_keys=None, additional_owner_accounts=None, additional_active_accounts=None, proxy_account='proxy-to-self', storekeys=True, **kwargs)[source]

Create new account on BitShares.

The brainkey/password can be used to recover all generated keys (see bitsharesbase.account for more details.

By default, this call will use default_account to register a new name account_name with all keys being derived from a new brain key that will be returned. The corresponding keys will automatically be installed in the wallet.

Warning

Don’t call this method unless you know what you are doing! Be sure to understand what this method does and where to find the private keys for your account.

Note

Please note that this imports private keys (if password is present) into the wallet by default. However, it does not import the owner key for security reasons. Do NOT expect to be able to recover it from the wallet if you lose your password!

Parameters:
  • account_name (str) – (required) new account name
  • registrar (str) – which account should pay the registration fee (defaults to default_account)
  • owner_key (str) – Main owner key
  • active_key (str) – Main active key
  • memo_key (str) – Main memo_key
  • password (str) – Alternatively to providing keys, one can provide a password from which the keys will be derived
  • additional_owner_keys (array) – Additional owner public keys
  • additional_active_keys (array) – Additional active public keys
  • additional_owner_accounts (array) – Additional owner account names
  • additional_active_accounts (array) – Additional acctive account names
  • storekeys (bool) – Store new keys in the wallet (default: True)
Raises:

AccountExistsException – if the account already exists on the blockchain

create_asset(symbol, precision, max_supply, description='', is_bitasset=False, is_prediction_market=False, market_fee_percent=0, max_market_fee=None, permissions=None, flags=None, whitelist_authorities=None, blacklist_authorities=None, whitelist_markets=None, blacklist_markets=None, bitasset_options=None, account=None, **kwargs)[source]

Create a new asset.

Parameters:
  • symbol (str) – Asset symbol
  • precision (int) – Asset precision
  • max_supply (int) – Asset max supply
  • description (str) – (optional) Asset description
  • is_bitasset (bool) – (optional) True = bitasset, False = UIA (default: False)
  • is_prediction_market (bool) – (optional) True: PD, False = plain smartcoin (default: False)
  • market_fee_percent (float) – (optional) Charge market fee (0-100) (default: 0)
  • max_market_fee (float) – (optional) Absolute amount of max market fee, value of this option should be a whole number (default: same as max_supply)
  • permissions (dict) – (optional) Asset permissions
  • flags (dict) – (optional) Enabled asset flags
  • whitelist_authorities (list) – (optional) List of accounts that serve as whitelist authorities
  • blacklist_authorities (list) – (optional) List of accounts that serve as blacklist authorities
  • whitelist_markets (list) – (optional) List of assets to allow trading with
  • blacklist_markets (list) – (optional) List of assets to prevent trading with
  • bitasset_options (dict) – (optional) Bitasset settings
  • account (str) – (optional) the issuer account to (defaults to default_account)
create_committee_member(url='', account=None, **kwargs)[source]

Create a committee member.

Parameters:
  • url (str) – URL to read more about the worker
  • account (str) – (optional) the account to allow access to (defaults to default_account)
create_liquidity_pool(asset_a, asset_b, share_asset, taker_fee_percent, withdrawal_fee_percent, account=None, **kwargs)[source]

Create a liquidity pool

Parameters:
  • asset_a (str) – First asset in the pool pair.
  • asset_b (str) – Second asset in the pool pair.
  • share_asset (str) – The asset which represents shares in the pool.

For asset parameters, these can be either symbols or asset_id strings. Note that network expects asset_a to have a lower-numbered asset_id than asset_b.

Parameters:
  • taker_fee_percent (float) – The pool’s taker fee percentage.
  • withdrawal_fee_percent (float) – The pool’s withdrawal fee percent.

For percentages, meaningful range is [0.00, 100.00], where 1% is represented as 1.0. Smallest non-zero value recognized by BitShares chain is 0.01 for 0.01%.

create_voting_ticket(target_type, amount_to_lock, account=None, **kwargs)[source]

Create a voting ticket

Parameters:
  • target_type (int,str) – Lock period target. Should be a string from operations.ticket_type_strings or the index of the intended string.
  • amount_to_lock (Amount) – Amount to lock up for the duration selected in target_type.
create_worker(name, daily_pay, end, url='', begin=None, payment_type='vesting', pay_vesting_period_days=0, account=None, **kwargs)[source]

Create a worker.

This removes the shares from the supply

Required

Parameters:
  • name (str) – Name of the worke
  • daily_pay (bitshares.amount.Amount) – The amount to be paid daily
  • end (datetime) – Date/time of end of the worker

Optional

Parameters:
  • url (str) – URL to read more about the worker
  • begin (datetime) – Date/time of begin of the worker
  • payment_type (string) – [“burn”, “refund”, “vesting”] (default: “vesting”)
  • pay_vesting_period_days (int) – Days of vesting (default: 0)
  • account (str) – (optional) the account to allow access to (defaults to default_account)
define_classes()[source]
delete_liquidity_pool(pool, account=None, **kwargs)[source]

Delete a liquidity pool

Parameters:pool (str,Asset) – The liquidity pool to delete. Can be the pool id as a string, or can be an Asset, asset_id, or symbol of the share asset for the pool.
deposit_into_liquidity_pool(pool, amount_a, amount_b, account=None, **kwargs)[source]

Deposit assets into a liquidity pool

Parameters:
  • pool (str,Asset) – The liquidity pool to use. Can be the pool id as a string, or can be an Asset, asset_id, or symbol of the share asset for the pool.
  • amount_a (Amount) –
  • amount_b (Amount) –
disallow(foreign, permission='active', account=None, threshold=None, **kwargs)[source]

Remove additional access to an account by some other public key or account.

Parameters:
  • foreign (str) – The foreign account that will obtain access
  • permission (str) – (optional) The actual permission to modify (defaults to active)
  • account (str) – (optional) the account to allow access to (defaults to default_account)
  • threshold (int) – The threshold that needs to be reached by signatures to be able to interact
disapprovecommittee(committees, account=None, **kwargs)[source]

Disapprove a committee.

Parameters:
  • committees (list) – list of committee name or id
  • account (str) – (optional) the account to allow access to (defaults to default_account)
disapproveproposal(proposal_ids, account=None, approver=None, **kwargs)[source]

Disapprove Proposal.

Parameters:
  • proposal_ids (list) – Ids of the proposals
  • account (str) – (optional) the account to allow access to (defaults to default_account)
disapprovewitness(witnesses, account=None, **kwargs)[source]

Disapprove a witness.

Parameters:
  • witnesses (list) – list of Witness name or id
  • account (str) – (optional) the account to allow access to (defaults to default_account)
disapproveworker(workers, account=None, **kwargs)[source]

Disapprove a worker.

Parameters:
  • workers (list) – list of worker name or id
  • account (str) – (optional) the account to allow access to (defaults to default_account)
exchange_with_liquidity_pool(pool, amount_to_sell, min_to_receive, account=None, **kwargs)[source]

Exchange assets against a liquidity pool

Parameters:
  • pool (str,Asset) – The liquidity pool to use. Can be the pool id as a string, or can be an Asset, asset_id, or symbol of the share asset for the pool.
  • amount_to_sell (Amount) –
  • min_to_receive (Amount) –
finalizeOp(ops, account, permission, **kwargs)

This method obtains the required private keys if present in the wallet, finalizes the transaction, signs it and broadacasts it

Parameters:
  • ops (operation) – The operation (or list of operaions) to broadcast
  • account (operation) – The account that authorizes the operation
  • permission (string) – The required permission for signing (active, owner, posting)
  • append_to (object) – This allows to provide an instance of ProposalsBuilder (see new_proposal()) or TransactionBuilder (see new_tx()) to specify where to put a specific operation.
… note:: append_to is exposed to every method used in the
this class

… note:

If ``ops`` is a list of operation, they all need to be
signable by the same key! Thus, you cannot combine ops
that require active permission with ops that require
posting permission. Neither can you use different
accounts for different operations!
… note:: This uses txbuffer as instance of
transactionbuilder.TransactionBuilder. You may want to use your own txbuffer
fund_fee_pool(symbol, amount, account=None, **kwargs)[source]

Fund the fee pool of an asset.

Parameters:
  • symbol (str) – The symbol to fund the fee pool of
  • amount (float) – The amount to be burned.
  • account (str) – (optional) the account to allow access to (defaults to default_account)
htlc_create(amount, to, *args, hash_type=None, hash_hex=None, expiration=3600, preimage=None, preimage_length=0, account=None, **kwargs)[source]

Create an HTLC contract.

Parameters:
  • amount (Amount) – Amount to lock
  • to (str) – Recipient
  • expiration (int) – Contract duration in seconds
  • hash_hex (str) – Hash as string of hex digits
  • preimage (str) – Preimage as ascii string. Note hex digits would be interpretted as ascii text, not as bytes. Not generally recommended to use this option. Options hash_hex and preimage are mutually exclusive.
  • preimage_length (int) – If non-zero, htlc contract will require preimage of exact length. Generally OK to leave this as zero. Note if preimage param is provided, this value SHOULD be either zero or match exactly the length of the preimage, else an irredeemable htlc will be created. Optionally, a sentinal value of -1 can be used to compute length automatically from the preimage param.
htlc_redeem(htlc_id, preimage, encoding='utf-8', account=None, **kwargs)[source]

Redeem an htlc contract

Parameters:
  • preimage (str) – The preimage that unlocks the htlc
  • encoding (str) – “utf-8”, …, or “hex”
info()

Returns the global properties

is_connected()
newWallet(pwd)
new_proposal(parent=None, proposer=None, proposal_expiration=None, proposal_review=None, **kwargs)
new_tx(*args, **kwargs)

Let’s obtain a new txbuffer

Returns int txid:
 id of the new txbuffer
new_wallet(pwd)

Create a new wallet. This method is basically only calls wallet.Wallet.create().

Parameters:pwd (str) – Password to use for the new wallet
Raises:exceptions.WalletExists – if there is already a wallet created
prefix

Contains the prefix of the blockchain

propbuffer

Return the default proposal buffer

proposal(proposer=None, proposal_expiration=None, proposal_review=None)

Return the default proposal buffer

… note:: If any parameter is set, the default proposal
parameters will be changed!
publish_price_feed(symbol, settlement_price, cer=None, mssr=110, mcr=200, account=None)[source]

Publish a price feed for a market-pegged asset.

Parameters:
  • symbol (str) – Symbol of the asset to publish feed for
  • settlement_price (bitshares.price.Price) – Price for settlement
  • cer (bitshares.price.Price) – Core exchange Rate (default settlement_price + 5%)
  • mssr (float) – Percentage for max short squeeze ratio (default: 110%)
  • mcr (float) – Percentage for maintenance collateral ratio (default: 200%)
  • account (str) – (optional) the account to allow access to (defaults to default_account)

Note

The account needs to be allowed to produce a price feed for symbol. For witness produced feeds this means account is a witness account!

reserve(amount, account=None, **kwargs)[source]

Reserve/Burn an amount of this shares.

This removes the shares from the supply

Parameters:
  • amount (bitshares.amount.Amount) – The amount to be burned.
  • account (str) – (optional) the account to allow access to (defaults to default_account)
set_blocking(block=True)

This sets a flag that forces the broadcast to block until the transactions made it into a block

set_default_account(account)

Set the default account to be used

set_proxy(proxy_account, account=None, **kwargs)[source]

Set a specific proxy for account.

Parameters:
  • proxy_account (bitshares.account.Account) – Account to be proxied
  • account (str) – (optional) the account to allow access to (defaults to default_account)
set_shared_instance()

This method allows to set the current instance as default

sign(tx=None, wifs=[])

Sign a provided transaction witht he provided key(s)

Parameters:
  • tx (dict) – The transaction to be signed and returned
  • wifs (string) – One or many wif keys to use for signing a transaction. If not present, the keys will be loaded from the wallet as defined in “missing_signatures” key of the transactions.
transfer(to, amount, asset, memo='', account=None, **kwargs)[source]

Transfer an asset to another account.

Parameters:
  • to (str) – Recipient
  • amount (float) – Amount to transfer
  • asset (str) – Asset to transfer
  • memo (str) – (optional) Memo, may begin with # for encrypted messaging
  • account (str) – (optional) the source account for the transfer if not default_account
tx()

Returns the default transaction buffer

txbuffer

Returns the currently active tx buffer

unlock(*args, **kwargs)

Unlock the internal wallet

unset_proxy(account=None, **kwargs)[source]

Unset the proxy account to start voting yourself.

update_cer(symbol, cer, account=None)[source]

Update the Core Exchange Rate (CER) of an asset.

Parameters:
  • symbol (str) – Symbol of the asset to publish feed for
  • cer (bitshares.price.Price) – Core exchange Rate
  • account (str) – (optional) the account to allow access to (defaults to default_account)
update_memo_key(key, account=None, **kwargs)[source]

Update an account’s memo public key.

This method does not add any private keys to your wallet but merely changes the memo public key.

Parameters:
  • key (str) – New memo public key
  • account (str) – (optional) the account to allow access to (defaults to default_account)
update_voting_ticket(ticket_id, new_target_type, amount_to_update, account=None, **kwargs)[source]

Update a voting ticket

Parameters:
  • ticket_id (str) – Id (e.g. “1.18.xxx”) of the ticket to update.
  • target_type (int,str) – New lock period target. Should be a string from operations.ticket_type_strings or the index of the intended string.
  • amount_to_update (Amount,None) – Amount to move over to the new lock-up target. (Optional - absence implies update whole amount.)
update_witness(witness_identifier, url=None, key=None, **kwargs)[source]

Upgrade a witness account.

Parameters:
  • witness_identifier (str) – Identifier for the witness
  • url (str) – New URL for the witness
  • key (str) – Public Key for the signing
upgrade_account(account=None, **kwargs)[source]

Upgrade an account to Lifetime membership.

Parameters:account (str) – (optional) the account to allow access to (defaults to default_account)
vesting_balance_withdraw(vesting_id, amount=None, account=None, **kwargs)[source]

Withdraw vesting balance.

Parameters:
  • vesting_id (str) – Id of the vesting object
  • Amount (bitshares.amount.Amount) – to withdraw (“all” if not provided”)
  • account (str) – (optional) the account to allow access to (defaults to default_account)
withdraw_from_liquidity_pool(pool, share_amount, account=None, **kwargs)[source]

Withdraw stake from a liquidity pool

Parameters:
  • pool (str,Asset) – The liquidity pool to use. Can be the pool id as a string, or can be an Asset, asset_id, or symbol of the share asset for the pool.
  • share_amount (Amount) – Amount of share asset to redeem. Must be a quantity of the pool’s share_asset.