latest contributor to this doc

Last Edit: @gcharang ,

task::enable_utxo

API-v2task::enable_utxo::init

UTXO coins are activated using this method. For QTUM coins, refer to task::enable_qtum::init

ParameterTypeDescription
tickerstringThe ticker of the coin you want to enable.
activation_paramsobjectAn object containing the actvation parameters below.
.priv_key_policystringDefaults to ContextPrivkey. Set as Trezor to activate in Trezor mode.
.min_addresses_numberintegerHow many additional addreesses to generate at a minimum.
.scan_policystringWhether or not to scan for new addresses. Select from do_not_scan, scan_if_new_wallet or scan. Note that scan will result in multple requests to the AtomicDEX-API.
.gap_limitintegerThe max number of empty addresses in a row. If transactions were sent to an address outside the gap_limit, they will not be identified when scanning.
.modeobjectAn object containing RPC type and data parameters as below.
..rpcstringUTXO RPC mode. Options: { "rpc":"Native" } if running a native blockchain node, or "rpc":"Electrum" to use electrum RPCs. If using electrum, a list of electrum servers is required under rpc_data.servers
..rpc_dataobjectAn object containing electrum server information.
...serverslistA list of electrum server URLs
....urlobjectThe url and port of a coins electrum server
....ws_urlobjectOptional. Used to define electrum server url/port for websocket connections.
....protocolobjectDefines electrum server protocol as TCP or SSL. Defaults to TCP
....disable_cert_verificationbooleanOptional. For SSL electrum connections, this will allow expired certificates.

ParameterTypeDescription
task_idintegerAn identifying number which is used to query task status.

POST
task::enable_utxo::init
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "task::enable_utxo::init",
  "params": {
    "ticker": "KMD",
    "activation_params": {
      "mode": {
        "rpc": "Electrum",
        "rpc_data": {
          "servers": [
            {
              "url": "electrum2.cipig.net:10001"
            },
            {
              "url": "electrum3.cipig.net:20001",
              "ws_url": "electrum3.cipig.net:30001",
              "protocol": "SSL"
            }
          ]
        }
      },
      "scan_policy": "scan_if_new_wallet",
      "priv_key_policy": "Trezor",
      "min_addresses_number": 3,
      "gap_limit": 20
    }
  }
}
API-v2task::enable_utxo::status

After running the task::enable_utxo::init method, we can query the status of activation to check its progress. The response will return the following:

  • Result of the task (success or error)
  • Progress status (what state the task is in)
  • Required user action (what user should do before the task can continue)

ParameterTypeDescription
task_idintegerThe identifying number returned when initiating the initialisation process.
forget_if_finishedbooleanIf false, will return final response for completed tasks. Optional, defaults to true.

POST
task::enable_utxo::status
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "task::enable_utxo::status",
  "params": {
    "task_id": 0,
    "forget_if_finished": false
  }
}

ParameterTypeDescription
statusstringA short indication of how the requested process is progressing.
details.resultobjectDepending on the state of process progress, this will contain different information as detailed in the items below.
.tickerstringThe ticker of the coin being activated
.current_blockintegerThe block height of the coin being activated
.wallet_balanceobjectInformation about the addresses of the coin being activated
..wallet_typestringIn Trezor mode, this will return HD
..accountslistA list of addresses and related information for the coin being activated
...account_indexintegerACCOUNT_ID child in the m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID BIP44 derivation path. Please don't confuse with mm2 global Iguana/HD/HW account.
...derivation_pathstringDerivation path up to the COIN child. E.g. "m/44'/141'/0'"
...total_balanceobjectCombined total spendable and unconfirmed balances of all account addresses
....spendablestring(numeric)Combined total spendable balance of all account addreesses
....unspendablestring(numeric)Combined total unspendable balance of all account addreesses
...addresseslistA list of addresses in the account for the coin being activated
....addressstringOne of the addresses in the account for the coin being activated
....derivation_pathstringThe BIP44 derivation path of the address.
....chainstringReturns External when CHAIN=0 in the m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID derivation path. Returns Internal when CHAIN=1 in the m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID derivation path. External is used for addresses that are meant 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 for return transaction change.
....balanceobjectContains the spendable and unspendable balance for this address
.....spendablestring(numeric)Spendable balance for this address
.....unspendablestring(numeric)Unspendable balance for this address (e.g. from unconfirmed incoming transactions)

ParameterTypeDescription
statusstringA short indication of how the requested process is progressing.
details.resultobjectDepending on the state of process progress, this will contain different information as detailed in the items below.
.tickerstringThe ticker of the coin being activated
.current_blockintegerThe block height of the coin being activated
.wallet_balanceobjectInformation about the addresses of the coin being activated
..wallet_typestringIn Trezor mode, this will return HD
..addressstringOne of the addresses in the account for the coin being activated
..balanceobjectContains the spendable and unspendable balance for this address
...spendablestring(numeric)Spendable balance for this address
...unspendablestring(numeric)Unspendable balance for this address (e.g. from unconfirmed incoming transactions)

ParameterTypeDescription
statusstringWill return InProgress if task is not yet comepleted
detailsstringAn indication of the current step of the activation process

Possible In Progress Cases:

  • ActivatingCoin: The first step of activation. It does not require any action from the user.
  • RequestingWalletBalance: The first step of activation, while initial balances info is being requested. It does not require any action from the user.
  • Finishing: Activation process completed
  • WaitingForTrezorToConnect: Waiting for the user to plugin a Trezor device
  • FollowHwDeviceInstructions: Waiting for the user to follow the instructions on the device

ParameterTypeDescription
statusstringA short indication of how the requested process is progressing.
details.resultobjectDepending on the state of process progress, this will contain different information as detailed in the items below.
.errorstringThe ticker of the coin being activated
.error_pathstringUsed for debugging. A reference to the function in code base which returned the error
.error_tracestringUsed for debugging. A trace of lines of code which led to the returned error
.error_typestringAn enumerated error identifier to indicate the category of error
.error_datastringAdditonal context for the error type

Possible Error Cases:

  • TaskTimedOut - Timed out waiting for coin activation, connecting to the device trezor or for user to confirm pubkey)
  • CoinCreationError - Error during activation. E.g. incorrect or inactive electrum servers.
  • HwError - This is the most important error type. Unlike other error types, HwError requires the GUI / User to check the details in error_data field to know which action is required. View the HwError error type details for more info.
API-v2task::enable_utxo::user_action

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

ParameterTypeDescription
task_idintegerThe identifying number returned when initiating the initialisation process.
user_actionobjectObject containing the params below
user_action.action_typestringWill be TrezorPin for this method
user_action.pinstring (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.
Trezor Pin

ParameterTypeDescription
resultstringThe outcome of the request.

POST
task::enable_utxo::user_action
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "task::enable_utxo::user_action",
  "params": {
    "task_id": 0,
    "user_action": {
      "action_type": "TrezorPin",
      "pin": "862743"
    }
  }
}