Hierarchical Deterministic Address Management

A hierarchical-deterministic (HD) wallet generates a new key pair from a master key pair, allowing for multiple addresses to be generated from the same seed so that change from transactions go to a previously unused address, enhancing privacy and security. The hierarchical structure resembles that of a tree, with the master key “determining” the key pairs that follow it in the hierarchy. If you have activated a coin with the task::enable_utxo::init or task::enable_qtum::init and used the "priv_key_policy": "Trezor" parameter, you can use the methods below to generate new addresses.

get_new_address

If we don't already have too many unused addresses, we can use the get_new_address method to generate a new address. The generated address will be shown in account_balance and init_account_balance RPCs and on the next coin activation.

For hardware wallets (e.g. Trezor), you need to use the task based address creation methods: task::get_new_address::init, task::get_new_address::status, task::get_new_address::user_actionandtask::get_new_address::cancel`.

Arguments

Parameter	Type	Description
coin	string	The ticker of the coin you want to get a new address for
account_id	integer	Generally this will be `0` unless you have multiple accounts registered on your Trezor
chain	string	`Internal`, or `External`. Defaults to `External`. External is used for addresses that are intended to be visible outside of the wallet (e.g. for receiving payments). Internal is used for addresses which are not meant to be visible outside of the wallet and is used to return the leftover change from a transaction.
gap_limit	integer	Optional. The maximum number of empty addresses in a row. Defaults to the value provided on activation or 20 if no value was provided

Response

Parameter	Type	Description
new_address	object	A standard NewAddressInfo object.

Some reasons you might not be able to get a new address are:

EmptyAddressesLimitReached - Last gap_limit addresses are still unused.
AddressLimitReached - Addresses limit reached. Currently, the limit is 2^31

📌 Examples

Command

POST

get_new_address

{
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "method": "get_new_address",
  "params": {
    "coin": "DOC",
    "account_id": 0,
    "chain": "External",
    "gap_limit": 20
  }
}

API-v2task::get_new_address::init

init

POST

task::get_new_address::init

{
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "method": "task::get_new_address::init",
  "params": {
    "coin": "KMD",
    "account_id": 0
  }
}

API-v2task::get_new_address::status

status

Arguments

Parameter	Type	Description
task_id	integer	The identifying number returned when initiating the task.

Status

POST

task::get_new_address::status

{
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "method": "task::get_new_address::status",
  "params": {
    "task_id": 2
  }
}

API-v2task::get_new_address::user_action

user_action

If the task::get_new_address::status returns UserActionRequired, we need to use the task::get_new_address::user_action method to enter our PIN

Arguments

Parameter	Type	Description
task_id	integer	The identifying number returned when initiating the task.
user_action	object	Object containing the params below
user_action.action_type	string	Will be `TrezorPin` for this method
user_action.pin	string (number)	When the Trezor device is displaying a grid of numbers for PIN entry, this param will contain your Trezor pin, as mapped through your keyboard numpad. See the image below for more information.

Response

Parameter	Type	Description
result	string	The outcome of the request.

📌 Examples

Command

User Action

POST

task::get_new_address::user_action

{
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "method": "task::get_new_address::user_action",
  "params": {
    "task_id": 0,
    "user_action": {
      "action_type": "TrezorPin",
      "pin": "862743"
    }
  }
}

API-v2task::get_new_address::cancel

cancel

If you want to cancel the enabling process before it has completed, you can use this method.

Arguments

Structure	Type	Description
task_id	integer	The identifying number returned when initiating the enabling process.

Response

Structure	Type	Description
result	string	Indicates task cancellation was succesful.
error	string	An error message to explain what went wrong.
error_path	string	An indicator of the class or function which reurned the error.
error_trace	string	An indicator of where in the source code the error was thrown.
error_type	string	An enumerated value for the returned error.
error_data	string	The input task ID which resulted in the error.

📌 Examples

Command

Cancel

POST

task::get_new_address::cancel

{
  "userpass": "RPC_UserP@SSW0RD",
  "method": "task::get_new_address::cancel",
  "mmrpc": "2.0",
  "params": {
    "task_id": 3
  }
}

task_scan_for_new_addresses_init

Arguments

Parameter	Type	Description
coin	string	The ticker of the coin you want to scan addresses for
account_id	integer	Optional, HD wallets only. Generally this will be `0` unless you have multiple accounts registered on your HD wallet
gap_limit	integer	Optional. The maximum number of empty addresses in a row. Defaults to the value provided on activation or 20 if no value was provided

Response

Parameter	Type	Description
task_id	integer	An identifying number which is used to query task status.

📌 Examples

Command

POST

get_new_address

{
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "method": "task::scan_for_new_addresses::init",
  "params": {
    "coin": "DGB",
    "account_index": 0,
    "gap_limit": 20
  }
}

task_scan_for_new_addresses_status

Use the task::scan_for_new_addresses::status method to query the status of a HD address scanning task.

Arguments

Parameter	Type	Description
task_id	integer	The identifying number returned when initiating the withdrawal process.
forget_if_finished	boolean	If `false`, will return final response for completed tasks. Optional, defaults to `true`.

Response

Parameter	Type	Description
status	string	Status of the task. `Ok`, `InProgress` or `Error`.
details	string or object	Once complete, a standard ScanAddressesInfo object.

📌 Examples

Command

POST

get_new_address

{
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "method": "task::scan_for_new_addresses::status",
  "params": {
    "task_id": 3
  }
}

On this page

Hierarchical Deterministic Address Management

Status

User Action

Cancel