Using wallet and accounts

Since Monero ‘Helium Hydra’ (0.11.x) the wallet handles accounts and deterministically generated addresses, known as subaddresses.

The wallet

The following example shows how to create and retrieve wallet’s accounts and addresses:

In [1]: from monero.wallet import Wallet

In [2]: from monero.backends.jsonrpc import JSONRPCWallet

In [3]: w = Wallet(JSONRPCWallet(port=28088))

In [4]: w.address()
Out[4]: A2GmyHHJ9jtUhPiwoAbR2tXU9LJu2U6fJjcsv3rxgkVRWU6tEYcn6C1NBc7wqCv5V7NW3zeYuzKf6RGGgZTFTpVC4QxAiAX

Accounts and subaddresses

The accounts are stored in wallet’s accounts attribute, which is a list.

Regardless of the version, the wallet by default operates on its account of index 0, which makes it consistent with the behavior of the CLI wallet client.

In [5]: len(w.accounts)
Out[5]: 1

In [6]: w.accounts[0]
Out[6]: <monero.account.Account at 0x7f78992d6898>

In [7]: w.accounts[0].address()
Out[7]: A2GmyHHJ9jtUhPiwoAbR2tXU9LJu2U6fJjcsv3rxgkVRWU6tEYcn6C1NBc7wqCv5V7NW3zeYuzKf6RGGgZTFTpVC4QxAiAX

In [8]: w.addresses()
Out[8]: [A2GmyHHJ9jtUhPiwoAbR2tXU9LJu2U6fJjcsv3rxgkVRWU6tEYcn6C1NBc7wqCv5V7NW3zeYuzKf6RGGgZTFTpVC4QxAiAX]

Creating accounts and addresses

Every wallet can have separate accounts and each account can have numerous addresses. The Wallet.new_account() and Account.new_address() will create new instances, then return a tuple consisting of the subaddress itself, and the subaddress index within the account.

In [9]: w.new_address()
Out[9]: (BenuGf8eyVhjZwdcxEJY1MHrUfqHjPvE3d7Pi4XY5vQz53VnVpB38bCBsf8AS5rJuZhuYrqdG9URc2eFoCNPwLXtLENT4R7, 1)

In [10]: w.addresses()
Out[10]:
[A2GmyHHJ9jtUhPiwoAbR2tXU9LJu2U6fJjcsv3rxgkVRWU6tEYcn6C1NBc7wqCv5V7NW3zeYuzKf6RGGgZTFTpVC4QxAiAX,
 BenuGf8eyVhjZwdcxEJY1MHrUfqHjPvE3d7Pi4XY5vQz53VnVpB38bCBsf8AS5rJuZhuYrqdG9URc2eFoCNPwLXtLENT4R7]

In [11]: w.new_account()
Out[11]: <monero.account.Account at 0x7f7894dffbe0>

In [12]: len(w.accounts)
Out[12]: 2

In [13]: w.accounts[1].address()
Out[13]: Bhd3PRVCnq5T5jjNey2hDSM8DxUgFpNjLUrKAa2iYVhYX71RuCGTekDKZKXoJPAGL763kEXaDSAsvDYb8bV77YT7Jo19GKY

In [14]: w.accounts[1].new_address()
Out[14]: (Bbz5uCtnn3Gaj1YAizaHw1FPeJ6T7kk7uQoeY48SWjezEAyrWScozLxYbqGxsV5L6VJkvw5VwECAuLVJKQtHpA3GFXJNPYu, 1)

In [15]: w.accounts[1].addresses()
Out[15]:
[Bhd3PRVCnq5T5jjNey2hDSM8DxUgFpNjLUrKAa2iYVhYX71RuCGTekDKZKXoJPAGL763kEXaDSAsvDYb8bV77YT7Jo19GKY,
 Bbz5uCtnn3Gaj1YAizaHw1FPeJ6T7kk7uQoeY48SWjezEAyrWScozLxYbqGxsV5L6VJkvw5VwECAuLVJKQtHpA3GFXJNPYu]

As mentioned above, the wallet by default operates on the first account, so w.new_address() is equivalent to w.accounts[0].new_address().

In the next chapter we will learn about addresses.

API reference

class monero.wallet.Wallet(backend)

Monero wallet.

Provides interface to operate on a wallet.

A wallet consists of accounts. Fresh wallets start with only one account but you may create more. Although it’s possible to combine funds from different accounts, or even wallets, in a single transaction, this code closely follows the idea of separation introduced in the original wallet software.

The list of accounts will be initialized under the accounts attribute.

The wallet exposes a number of methods that operate on the default account (of index 0).

Parameters:backend – a wallet backend
address()

Returns wallet’s master address.

Return type:Address
addresses()

Returns all addresses of the default account.

Return type:list of Address and SubAddress
balance(unlocked=False)

Returns specified balance.

Parameters:unlocked – if True, return the unlocked balance, otherwise return total balance
Return type:Decimal
balances()

Returns a tuple of balance and unlocked balance.

Return type:(Decimal, Decimal)
confirmations(txn_or_pmt)

Returns the number of confirmations for given Transaction or Payment object.

Return type:int
export_key_images()

Exports signed key images as a list of dicts.

Return type:[dict, dict, ..]
export_outputs()

Exports outputs in hexadecimal format.

Return type:str
get_address(major, minor)

Calculates sub-address for account index (major) and address index within the account (minor).

Return type:BaseAddress
height()

Returns the height of the wallet.

Return type:int
import_key_images(key_images_hex)

Imports key images from a list of dicts. Returns tuple of (height, spent, unspent).

Return type:(int, Decimal, Decimal)
import_outputs(outputs_hex)

Imports outputs in hexadecimal format. Returns number of imported outputs.

Return type:int
new_account(label=None)

Creates new account, appends it to the Wallet’s account list and returns it.

Parameters:label – account label as str
Return type:Account
new_address(label=None)

Creates a new address in the default account.

Return type:tuple of subaddress, subaddress index (minor): (SubAddress, int)
refresh()

Reloads the wallet and its accounts. By default, this method is called only once, on Wallet initialization. When the wallet is accessed by multiple clients or exists in multiple instances, calling refresh() will be necessary to update the list of accounts.

seed()

Returns word seed.

Return type:str
spend_key()

Returns private spend key. None if wallet is view-only.

Return type:str or None
sweep_all(address, priority=2, payment_id=None, subaddr_indices=None, unlock_time=0, relay=True)

Sends all unlocked balance from the default account to an address. Returns a list of resulting transactions.

Parameters:
  • address – destination Address or subtype
  • priority – transaction priority, implies fee. The priority can be a number from 1 to 4 (unimportant, normal, elevated, priority) or a constant from monero.prio.
  • payment_id – ID for the payment (must be None if IntegratedAddress is used as the destination)
  • subaddr_indices – a sequence of subaddress indices to sweep from. Empty sequence or None means sweep all positive balances.
  • unlock_time – the extra unlock delay
  • relay – if True, the wallet will relay the transaction(s) to the network immediately; when False, it will only return the transaction(s) so they might be broadcast later
Return type:

list of Transaction

transfer(address, amount, priority=2, payment_id=None, unlock_time=0, relay=True)

Sends a transfer from the default account. Returns a list of resulting transactions.

Parameters:
  • address – destination Address or subtype
  • amount – amount to send
  • priority – transaction priority, implies fee. The priority can be a number from 1 to 4 (unimportant, normal, elevated, priority) or a constant from monero.prio.
  • payment_id – ID for the payment (must be None if IntegratedAddress is used as the destination)
  • unlock_time – the extra unlock delay
  • relay – if True, the wallet will relay the transaction(s) to the network immediately; when False, it will only return the transaction(s) so they might be broadcast later
Return type:

list of Transaction

transfer_multiple(destinations, priority=2, payment_id=None, unlock_time=0, relay=True)

Sends a batch of transfers from the default account. Returns a list of resulting transactions and amounts.

Parameters:
  • destinations – a list of destination and amount pairs: [(address, amount), …]
  • priority – transaction priority, implies fee. The priority can be a number from 1 to 4 (unimportant, normal, elevated, priority) or a constant from monero.prio.
  • payment_id – ID for the payment (must be None if IntegratedAddress is used as a destination)
  • unlock_time – the extra unlock delay
  • relay – if True, the wallet will relay the transaction(s) to the network immediately; when False, it will only return the transaction(s) so they might be broadcast later
Return type:

list of transaction and amount pairs: [(Transaction, Decimal), …]

view_key()

Returns private view key.

Return type:str
class monero.account.Account(backend, index, label=None)

Monero account.

Provides interface to operate on a wallet’s account.

Accounts belong to a Wallet and act like separate sub-wallets. No funds can be moved between accounts off-chain (without a transaction).

Parameters:
  • backend – a wallet backend
  • index – the account’s index within the wallet
  • label – optional account label as str
address()

Return account’s main address.

Return type:SubAddress
addresses()

Returns all addresses of the account.

Return type:list
balance(unlocked=False)

Returns specified balance.

Parameters:unlocked – if True, return the unlocked balance, otherwise return total balance
Return type:Decimal
balances()

Returns a tuple of balance and unlocked balance.

Return type:(Decimal, Decimal)
new_address(label=None)

Creates a new address.

Parameters:label – address label as str
Return type:tuple of subaddress, subaddress index (minor): (SubAddress, int)
sweep_all(address, priority=2, payment_id=None, subaddr_indices=None, unlock_time=0, relay=True)

Sends all unlocked balance to an address. Returns a list of resulting transactions.

Parameters:
  • address – destination Address or subtype
  • priority – transaction priority, implies fee. The priority can be a number from 1 to 4 (unimportant, normal, elevated, priority) or a constant from monero.prio.
  • payment_id – ID for the payment (must be None if IntegratedAddress is used as the destination)
  • subaddr_indices – a sequence of subaddress indices to sweep from. Empty sequence or None means sweep all positive balances.
  • unlock_time – the extra unlock delay
  • relay – if True, the wallet will relay the transaction(s) to the network immediately; when False, it will only return the transaction(s) so they might be broadcast later
Return type:

list of Transaction

transfer(address, amount, priority=2, payment_id=None, unlock_time=0, relay=True)

Sends a transfer. Returns a list of resulting transactions.

Parameters:
  • address – destination Address or subtype
  • amount – amount to send
  • priority – transaction priority, implies fee. The priority can be a number from 1 to 4 (unimportant, normal, elevated, priority) or a constant from monero.prio.
  • payment_id – ID for the payment (must be None if IntegratedAddress is used as the destination)
  • unlock_time – the extra unlock delay
  • relay – if True, the wallet will relay the transaction(s) to the network immediately; when False, it will only return the transaction(s) so they might be broadcasted later
Return type:

list of Transaction

transfer_multiple(destinations, priority=2, payment_id=None, unlock_time=0, relay=True)

Sends a batch of transfers. Returns a list of resulting transactions.

Parameters:
  • destinations – a list of destination and amount pairs: [(Address, Decimal), …]
  • priority – transaction priority, implies fee. The priority can be a number from 1 to 4 (unimportant, normal, elevated, priority) or a constant from monero.prio.
  • payment_id – ID for the payment (must be None if IntegratedAddress is used as the destination)
  • unlock_time – the extra unlock delay
  • relay – if True, the wallet will relay the transaction(s) to the network immediately; when False, it will only return the transaction(s) so they might be broadcast later
Return type:

list of transaction and amount pairs: [(Transaction, Decimal), …]