# Withdraw Tasks

# task_withdraw_init

The task::withdraw::init method generates and signs transaction which will transfer the amount of coin to the address indicated in the to argument. The status of this method can be queried via the withdraw_status method, or .

It will return the transaction hex (via task::withdraw::status), which then needs to be broadcast with the sendrawtransaction to complete the withdrawal. This method is uses the same input fields as the standard v2 withdraw method, with additional optional fields to specify the from address when using a hardware or HD wallet. There are two way to indicate which HW/HD address to send funds from:

  • Using derivation_path as a single input. E.g m/44'/20'/0'/0/2
  • Using account_id (0), chain (External) & address_id (2) inputs. The bracketed values are the equavalent of the derivation path above.

To cancel the transaction generation, use the withdraw_cancel method.

TIP

When used for ZHTLC coins like ARRR or ZOMBIE, it may take some time to complete.

# Arguments

Structure Type Description
coin string The name of the coin the user desires to withdraw
to string Coins are withdrawn to this address
amount string (numeric) The amount the user desires to withdraw, ignored when max=true
memo string Optional, used for ZHTLC and Tendermint coins only. Attaches a memo to the transaction.
from string Optional, used only for transactions using a hardware or HD wallet.
from.derivation_path string Optional, HW/HD wallets only. Follows the format m/44'/COIN_ID'/ACCOUNT_ID'/CHAIN/ADDRESS_ID
from.account_id integer Optional, HW/HD wallets only. Generally this will be 0 unless you have multiple accounts registered on your HW/HD wallet
from.chain string Optional, HW/HD wallets only. Internal, or External. 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.
from.address_id integer Optional, HW/HD wallets only. Check the output from coin activation to find the ID of an address with balance.
max bool Optional. Withdraw the maximum available amount. Defaults to false
fee object Optional. Used only to set a custom fee, otherwise fee value will be derived from a deamon's estimatefee (or similar) RPC method
fee.type string Type of transaction fee; possible values: UtxoFixed or UtxoPerKbyte
fee.amount string (numeric) Fee amount in coin units, used only when type is UtxoFixed (fixed amount not depending on tx size) or UtxoPerKbyte (amount per Kbyte)

# Response

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

# 📌 Examples

# Command

#!/bin/bash
source userpass
curl --url "http://127.0.0.1:7783" --data "{
    \"mmrpc\": \"2.0\",
    \"userpass\": \"${userpass}\",
    \"method\": \"task::withdraw::init\",
    \"params\": {
        \"coin\": \"COIN_NAME\",
        \"to\": \"RECIPIENT_ADDRESS\",
        \"amount\": \"AMOUNT\"
    },
    \"id\": 0
}"

# Command (max = true)

#!/bin/bash
source userpass
curl --url "http://127.0.0.1:7783" --data "{
    \"mmrpc\": \"2.0\",
    \"userpass\": \"${userpass}\",
    \"method\": \"task::withdraw::init\",
    \"params\": {
        \"coin\": \"COIN_NAME\",
        \"to\": \"RECIPIENT_ADDRESS\",
        \"max\": true
    },
    \"id\": 0
}"

# Command (custom UtxoFixed fee)

#!/bin/bash
source userpass
curl --url "http://127.0.0.1:7783" --data "{
    \"mmrpc\": \"2.0\",
    \"userpass\": \"${userpass}\",
    \"method\": \"task::withdraw::init\",
    \"params\": {
        \"coin\": \"COIN_NAME\",
        \"to\": \"RECIPIENT_ADDRESS\",
        \"amount\": \"AMOUNT\",
        \"fee\": {
            \"type\":\"UtxoFixed\",
             \"amount\":\"0.001\"
         }
    },
    \"id\": 0
}"

# Command (custom UtxoPerKbyte fee)

#!/bin/bash
source userpass
curl --url "http://127.0.0.1:7783" --data "{
    \"mmrpc\": \"2.0\",
    \"userpass\": \"${userpass}\",
    \"method\": \"task::withdraw::init\",
    \"params\": {
        \"coin\": \"COIN_NAME\",
        \"to\": \"RECIPIENT_ADDRESS\",
        \"amount\": \"AMOUNT\",
        \"fee\": {
            \"type\":\"UtxoPerKbyte\",
             \"amount\":\"0.00097\"
         }
    },
    \"id\": 0
}"

# Command (HW/HD wallet: derivation path option)

curl --url "http://127.0.0.1:7783" --data "{
    \"userpass\": \"$userpass\",
    \"mmrpc\": \"2.0\",
    \"method\": \"task::withdraw::init\",
    \"params\": {
        \"coin\": \"COIN_NAME\",
        \"to\": \"ADDRESS_OF_RECIPIENT\",
        \"amount\": AMOUNT_TO_SEND,
        \"from\": {
            \"derivation_path\": \"DERIVATION_PATH\"
        }
    }
}"

# Command (HW/HD wallet: account_id, chain & address_id option)

curl --url "http://127.0.0.1:7783" --data "{
    \"userpass\": \"$userpass\",
    \"mmrpc\": \"2.0\",
    \"method\": \"task::withdraw::init\",
    \"params\": {
        \"coin\": \"COIN_NAME\",
        \"to\": \"ADDRESS_OF_RECIPIENT\",
        \"amount\": AMOUNT_TO_SEND,
        \"from\": {
            \"account_id\": 0,
            \"chain\": \"External\",
            \"address_id\": ADDRESS_ID
        }
    }
}"

# task_withdraw_status

To get the status of your withdrawal transaction generation, use the task::withdraw::status method. Once ready, it will provide the raw hex used to broadcast your transaction with sendrawtransaction. The response returned is the same as what is returned from the standard v2 withdraw method

# Arguments

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

# Response

Structure Type Description
status string A short indication of how the withdrawal is progressing.
details object Depending on the state of withdrawal progress, this will contain different information as shown in the responses below.
details.coin string The ticker of the coin to be withdrawn.
details.to array of strings Coins are withdrawn to these addresses; this may contain the my_address address, where change from UTXO coins is sent.
details.from array of strings Coins are withdrawn from this address; the array contains a single element, but transactions may be sent from several addresses (UTXO coins)
details.my_balance_change string (numeric) The expected balance of change in my_address after the transaction broadcasts.
details.received_by_me string (numeric) The amount of coins received by my_address after the transaction broadcasts; the value may be above zero when the transaction requires that the AtomicDEX API send change to my_address
details.spent_by_me string (numeric) The amount of coins spent by my_address. This value differ from the request amount, as the transaction fee is taken into account.
details.total_amount string (numeric) The total amount of coins transferred.
details.fee_details object The fee details of the generated transaction. fee_details.type is "Utxo" for Z coins. fee_details.coin will be the same as details.coin, and fee_details.amount will be a numeric value.
details.tx_hash string The hash of the generated transaction.
details.tx_hex string Transaction bytes in hexadecimal format. Use this value as input for the send_raw_transaction method.
details.transaction_type string A value to indicate the type of transaction. Most often this will be StandardTransfer.
details.kmd_rewards object (optional) If supported (e.g. when withdrawing KMD), an object containing information about accrued rewards.
details.kmd_rewards.amount string (numeric, optional) The amount of accrued rewards
details.kmd_rewards.claimed_by_me bool (optional) Whether or not the rewards been claimed by me.

# 📌 Examples

# Command

#!/bin/bash
source userpass
curl --url "http://127.0.0.1:7783" --data "{
    \"mmrpc\": \"2.0\",
    \"userpass\": \"$userpass\",
    \"method\": \"task::withdraw::status\",
    \"params\": {
        \"task_id\": TASK_ID,
        \"forget_if_finished\": false
    },
    \"id\":0
}"

# task_withdraw_cancel

Use the task::withdraw::cancel method to cancel the withdrawal preparation task.

# Arguments

Structure Type Description
task_id integer The identifying number returned when initiating the withdraw 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

#!/bin/bash
source userpass
curl --url "http://127.0.0.1:7783" --data "
{
    \"userpass\": \"${userpass}\",
    \"method\": \"task::withdraw::cancel\",
    \"mmrpc\": \"2.0\",
    \"params\": {
<<<<<<< HEAD
        \"task_id\": 6
=======
        \"task_id\": TASK_ID
>>>>>>> master
    }
}"
echo

← ZHTLC Coins →