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.const.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.const.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.const.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.const.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.const.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.const.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), …]