Wallet Operations Structures

AccountAddressInfo

The AccountAddressInfo object includes the following items for active addresses in the activation response for a coin in HD mode:

Parameter	Type	Description
address	string	The account address for a specific derivation path under the `account_index`.
derivation_path	string	The BIP44 derivation path of the address.
chain	string	`External` or `Internal`, as defined in the activation request.
balance	object	A standard BalanceInfo object.

The AddressDerivationPath object defines the account / change / address_index of the derivation path used for your wallet. Using different values for account_id or address_id parameters will result in a different address and private key for each combination. The chain parameter is used to specify if the change from a transaction. Set to External 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.

Parameter	Type	Description
account_id	integer	Optional, defaults to `0`. Used as a layer of separation or hierarchy.
chain	string	Optional. Accepted values are `External` (0) and `Internal` (1). Defaults to `External`.
address_id	integer	Optional, defaults to `0`. Used as a layer of separation or hierarchy.

AddressFormat

Structure	Type	Description
format	string (enum)	address format to which the input address should be converted. Possible values: `mixedcase` for ETH/ERC20 coins; `cashaddress` or `standard` for UTXO coins; `contract` or `wallet` for QTUM/QRC20
network	string (enum)	Optional, only used for UTXO coins. Network prefix for `cashaddress` format. Possible values: `bitcoincash` for BCH mainnet; `bchtest` for BCH testnet; `bchreg` for BCH regtest

AddressInfo

The AddressInfo object includes the following items for a given address:

Parameter	Type	Description
balances	object	A standard balanceInfos object. Not included in responses where `get_balances` is `false`
derivation_method	object	A standard DerivationMethod object
pubkey	string	The public key associated with the seed used to launch Komodo DeFi Framework
tickers	array	A list of tokens which were successfully activated. Only included in responses where `get_balances` is `false`

AddressPath

The AddressPath object includes the following items:

Parameter	Type	Description
account_id	integer	The index of the account in the wallet, starting from `0`.
chain	integer	Optional, only used for HD wallets. The `chain` is either `External` or `Internal`, and expressed as an integer with `External` being 0 and `Internal` being 1.
address_id	integer	Optional, only used for HD wallets. The index of the address in the account, starting from `0`.
derivation_path	string	Optional, only used for HD wallets. The derivation path of the address, following the format `m/44'/COIN_ID'/ACCOUNT_ID'/CHAIN/ADDRESS_ID` (or `m/84'/COIN_ID'/ACCOUNT_ID'/CHAIN/ADDRESS_ID` for segwit coins).

BalanceInfo

The BalanceInfo object includes the following items for a given coin or token:

Parameter	Type	Description
spendable	string (numeric)	The available amount of a coin or token which is ready to be traded or withdrawn.
unspendable	string (numeric)	The amount of a coin or token which is awaiting confirmation on the block chain for an incoming or outgoing transaction.

DerivationMethod

The DerivationMethod object includes the following items for a given coin or token:

Parameter	Type	Description
type	string	Defines how keypairs will be generated. Possible values: `Iguana` or `HDWallet`

Using the same seed or private key to generate keypairs using different derivation methods will result in a different address and private key for each method.

Where the value indicates:

Iguana: The coin or token is was activated using Iguana derivation (default).
HDWallet: The coin or token is was activated using a Hierarchical Deterministic (HD) Wallet derivation path.

ExtendedFeeInfo

Structure	Type	Description
coin	string	the fee is paid from the user's balance of this coin. This coin name may differ from the `base` or `rel` coins. For example, ERC20 fees are paid by ETH (gas)
amount	string (numeric)	fee amount (in decimal representation)
amount_rat	rational	fee amount (in rational representation)
amount_fraction	fraction	fee amount (in fraction representation)
amount_fraction	fraction	fee amount (in fraction representation)
paid_from_trading_vol	bool	whether the fee is paid from trading volume and not use actual `coin` balance

FeeInfo

The FeeInfo response object includes the following items for withdraw (v2) requests:

Parameter	Type	Description
type	string	Type of transaction fee. Possible values: `UtxoFixed`, `UtxoPerKbyte`, `UtxoPriority`, `EthGas`, `Qrc20Gas`, `CosmosGas`
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)
priority	string	Used only when type is `UtxoPriority`. Possible values: 'Low', 'Normal', 'High'.
gas_price	string (numeric)	Used only when fee type is `Qrc20Gas` or `EthGas`; sets the gas price in `gwei` units.
gas_price	number (double)	Used only when fee type is `CosmosGas`; sets the gas price.
gas	number (integer)	Used only when fee type is `EthGas`; sets the gas limit for transaction
gas_limit	number (integer)	Used only when fee type is `Qrc20Gas` or `CosmosGas`; sets the gas limit for transaction

HdCoinKeys

Returned from the get_private_keys method, when "mode": "hd".

Structure	Type	Description
coin	string	the coin ticker
addresses	array of HdKeysInfo	array of derived addresses and keys

HdKeysInfo

Structure	Type	Description
derivation_path	string	BIP44 derivation path used
pubkey	string	public key
address	string	derived address
priv_key	string	private key in appropriate format
viewing_key	string (optional)	viewing key for ZHTLC coins like ARRR

IguanaKeysInfo

Returned from the get_private_keys method, when "mode": "iguana".

Structure	Type	Description
coin	string	the coin ticker
pubkey	string	public key
address	string	coin address
priv_key	string	private key in WIF or appropriate format

HistoryTarget

Used to specify a HD wallet account_id or address_id for my_tx_history v2 requests.

Parameter	Type	Description
type	string	Filters results by `account_id` or `address_id` part of the derivation path.
account_id	integer	`ACCOUNT_ID` child in the `m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID` BIP44 derivation path.
address_id	integer	Only required when `type` is `address_id`. `ADDRESS_ID` child in the `m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID` BIP44 derivation path.
chain	string	Only required when `type` is `address_id`. `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.

InputTxns

The InputTxns object includes the following items:

Parameter	Type	Description
tx_hash	string	The transaction id of an unspent transaction from the same wallet output.
index	integer	The output index of this unspent transaction output.
script_pub_key	string	The scriptpubkey of this unspent transaction output.
amount	float	The value of this unspent transaction output.

NewAddressInfo

The NewAddressInfo response object includes the following items for request in HD mode:

Parameter	Type	Description
address	string	The account address for a specific derivation path under the `account_index`.
derivation_path	string	The BIP44 derivation path of the address. If there are no more addresses with balances within the gap limit, the address index will increment.
balance	object	A standard BalanceInfo object.
chain	string	`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.

PayForGas

The PayForGas object includes the following items:

Parameter	Type	Description
tx_type	string	ETH/EVM coins and tokens only. Options are `Legacy` or `Eip1559`. The type of transaction values being configured.
gas_price	decimal	Only used if tx_type is `Legacy`. Values are in Gwei. The maximium price per gas unit the user is willing to pay for the transaction.
max_fee_per_gas	decimal	Only used if tx_type is `Eip1559`. Values are in Gwei. The maximum amount to pay per unit of gas to get your transaction included in a block.
max_priority_fee_per_gas	decimal	Only used if tx_type is `Eip1559`. Values are in Gwei. This is paid directly to the miner, and can be set by the user to attract minimal delay in transaction confirmation.
min_wait_time	integer	Optional, only used if tx_type is `Eip1559`. Estimated minimum transaction wait time in mempool (in ms) for this priority level.
max_wait_time	integer	Optional, only used if tx_type is `Eip1559`. Estimated maximum transaction wait time in mempool (in ms) for this priority level.

Eip1559 allows users to save on gas fees. To use this feature for a coin/token, its entry in your coins file must include fields for chain_id and max_eth_tx_type. To allow eip-1559 transactions, max_eth_tx_type should be set to 2. To find the chain_id for an [EVM network(https://blog.thirdweb.com/evm-compatible-blockchains-and-ethereum-virtual-machine/)], refer to chainlist.org. There is also a new gas_fee_estimator parameter in the coins file, which can be set to Provider or Simple.

By default, Simple gas fee estimation suggests a fee based on fee history. If set gas_fee_estimator is set to Provider, users must set the gas_api setting in their MM2.json file to source recommended fee values from third party providers Infura or Blocknative.

To set or view the current swap transaction fee policy, use the get_swap_transaction_fee_policy and set_swap_transaction_fee_policy methods.

For more information about EIP1559, refer to https://www.blocknative.com/blog/eip-1559-fees

StakingDetails

The StakingDetails object includes the following items:

Parameter	Type	Description
type	string	The coin type. Currently, only 'Cosmos' and `Qtum` are supported.
validator_address	string	The address of the validator to delegate staking to.
amount	string	The amount of coins to stake send to the validator for delegated staking (Cosmos only - QTUM will stake your whole balance).

StakingInfoDetails

The StakingInfoDetails object includes the following items:

Parameter	Type	Description
type	string	The coin type. Currently, only 'Cosmos' is supported.
filter_by_status	string	Return only validators matching a specific status. Options are `Bonded`, `Unbonded`, and `All`. Defaults to `Bonded`.
limit	integer	Optional, defaults to `10`. The number of validators displayed per page in response.
page_number	integer	Optional, defaults to `1`. The page offset for items in response.

ClaimingDetails

The ClaimingDetails object includes the following items:

Parameter	Type	Description
type	string	The coin type. Currently, only 'Cosmos' and `Qtum` are supported.
validator_address	string	The address of the validator to delegate staking to.
force	boolean	Defaults to `false`. If `true`, will process unprofitable transactions (reward value less than network fees)

PrivKeyPolicy

The PrivKeyPolicy object includes the following items:

Parameter	Type	Description
type	string	Options are `ContextPrivKey`, `WalletConnect`, `Metamask`, or `Trezor`. Defaults to `ContextPrivKey`.
data	list	`WalletConnect` type only. The `session_topic` hex string, returned from the response to wc_new_connection.

RawTxInfo

The RawTxInfo object includes the following items:

Parameter	Type	Description
tx_hex	string	UTXO only. The raw unsigned hex of a proposed transaction.
prev_txns	list	UTXO only. A list of standard InputTxns objects.
to	string	ETH/EVM only. A destination address to send the funds to.
value	string	ETH/EVM only. The amount of funds to be sent as a string with a `0x` prefix, in wei units.
gas_limit	string	ETH/EVM only. The maximum gas to be used for sending the transaction, in gwei units.
pay_for_gas	object	Optional, ETH/EVM only. Used for EIP-1559 fee policy config. A standard PayForGas object.

ScanAddressesInfo

The ScanAddressesInfo response object includes the following items for request in HD mode:

Parameter	Type	Description
account_index	integer	`ACCOUNT_ID` child in the `m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID` BIP44 derivation path. Please don't confuse with the global account.
derivation_path	string	The BIP44 derivation path of the account.
new_addresses	list	A list of standard NewAddressInfo objects.

TotalFeeInfo

Structure	Type	Description
coin	string	the fee is paid from the user's balance of this coin. This coin name may differ from the `base` or `rel` coins. For example, ERC20 fees are paid by ETH (gas)
amount	string (numeric)	fee amount (in decimal representation)
amount_rat	rational	fee amount (in rational representation)
amount_fraction	fraction	fee amount (in fraction representation)
required_balance	string (numeric)	the required `coin` balance to pay the fee
required_balance_rat	rational	`required_balance` in rational representation
required_balance_fraction	fraction	`required_balance` in fraction representation

WithdrawFee

The WithdrawFee object varies depending on the coin or token type. Refer to the examples to view the object structure for each type.

Parameter	Type	Description
type	string	The fee type. Either `Utxo`, `Tendermint`, `Qrc20` or `Eth`.
amount	numeric string	`Utxo` or `Tendermint` type only. The fee amount.
coin	string	The coin which will be used to pay the transaction fee.
gas	integer	`Eth` type only. The amount of gas to be used for the transaction.
gas_price	numeric string	`Eth` or `Qrc20` type only. Price per unit of gas to be used for the transaction.
gas_limit	numeric string	`Tendermint` or `Qrc20` type only. Maximum gas to be used for the transaction.
miner_fee	numeric string	`Tendermint` type only. Fee to mine the transaction.
total_fee	numeric string	`Eth` type only. Gas price multiplied by gas amount.
total_gas_fee	numeric string	`Qrc20` type only. Gas price multiplied by gas amount.

WalletAccountInfo

The WalletAccountInfo object includes the following items in the activation response for a coin in HD mode:

Parameter	Type	Description
account_index	integer	`ACCOUNT_ID` child in the `m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID` BIP44 derivation path. Please don't confuse with the global account.
derivation_path	string	Derivation path up to the `COIN` child. E.g. `"m/44'/141'/0'"`
total_balance	object	A standard BalanceInfo object.
addresses	list	A list of standard AccountAddressInfo objects.

{
    "account_index": 0,
    "derivation_path": "m/44'/141'/0'",
    "total_balance": {
        "spendable": "23.08710255",
        "unspendable": "0"
    },
    "addresses": [
        ...
    ]
}

WalletBalanceInfo

The WalletBalanceInfo object includes the following items in the activation response for a coin in HD mode:

Parameter	Type	Description
wallet_type	string	In HD wallet mode, this will return `HD`.
accounts	object	A standard WalletAccountInfo object.

{
    "wallet_balance": {
        "wallet_type": "HD",
        "accounts": [
            ...
        ]
    }
}

WithdrawFromInfo

The WithdrawFromInfo response object includes the following items for HD Wallet withdraw (v2) requests. You can use either the derivation_path on its own, or the account_id, chain and address_id together.

Parameter	Type	Description
derivation_path	string	The BIP44 derivation path of the address.
account_id	integer	`ACCOUNT_ID` child in the `m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID` BIP44 derivation path. Please don't confuse with the global account.
address_id	integer	`ADDRESS_ID` child in the `m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID` BIP44 derivation path.
chain	string	`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.

Error types

NotSufficientBalance

The available balance is not sufficient to transfer the specified amount.

Structure	Type	Description
coin	string	the name of the coin which balance is not sufficient. This coin name may differ from the requested coin. For example, ERC20 fees are paid by ETH (gas)
available	string (numeric)	the balance available for transfer
required	string (numeric)	the amount required to transfer the specified amount. This amount is necessary but may not be sufficient

Response (NotSufficientBalance error)

{
  "mmrpc": "2.0",
  "error": "Not enough DOC to withdraw: available 69.75066225, required at least 1000.00001",
  "error_path": "utxo_common",
  "error_trace": "utxo_common:1379] utxo_common:449]",
  "error_type": "NotSufficientBalance",
  "error_data": {
    "coin": "DOC",
    "available": "69.75066225",
    "required": "1000.00001"
  },
  "id": 0
}

ZeroBalanceToWithdrawMax

The available balance is zero.

Structure	Type	Description
(none)

AmountTooLow

The specified amount is too low. Required at least threshold.

Structure	Type	Description
amount	string (numeric)	the amount the user was willing to transfer
threshold	string (numeric)	the `amount` has not to be less than the `threshold`

InvalidAddress

The specified to address is not valid.

Structure	Type	Description
(none)	string	the error description

InvalidFeePolicy

The specified fee is not valid.

Structure	Type	Description
(none)	string	the error description

Response (InvalidFeePolicy error - attempt to use EthGas for UTXO coin)

{
  "mmrpc": "2.0",
  "error": "Invalid fee policy: Expected 'UtxoFixed' or 'UtxoPerKbyte' fee types, found EthGas",
  "error_path": "utxo_common",
  "error_trace": "utxo_common:1371]",
  "error_type": "InvalidFeePolicy",
  "error_data": "Expected 'UtxoFixed' or 'UtxoPerKbyte' fee types, found EthGas",
  "id": 0
}

Response (InvalidFeePolicy error - attempt to use UtxoFixed or UtxoPerKbyte for ETH coin)

{
  "mmrpc": "2.0",
  "error": "Invalid fee policy: Expected 'EthGas' fee type, found UtxoFixed",
  "error_path": "eth",
  "error_trace": "eth:535]",
  "error_type": "InvalidFeePolicy",
  "error_data": "Expected 'EthGas' fee type, found UtxoFixed",
  "id": 0
}

On this page

Wallet Operations Structures