# DEX API

# Note About Rational Number Type

MM2 now offers the num-rational crate feature. This is used to represent order volumes and prices.

Komodo highly recommends that the developer use the rational number type when calculating an order's price and volume. This avoids rounding and precision errors when calculating numbers, such as 1/3, as these cannot be represented as a finite decimal.

The MM2 API typically will return both the rational number type as well as the decimal representation, but the decimal representation should be considered only a convenience feature for readability.

The number can be represented in the following two JSON formats:

  1. As a fraction object that contains a numerator and a denominator as numeric strings, as follows:
{
  "numer": "10000",
  "denom": "3000"
}
  1. As a unique format supplied by the num-rational crate:
[
  [1, [0, 1]],
  [1, [1]]
]

In the above unique format, the first item [1,[0,1]] is the numerator and the second item [1,[1]] is the denominator.

The numerator and denominator are BigInteger numbers represented as a sign and a uint32 array (where numbers are 32-bit parts of big integer in little-endian order).

[1,[0,1]] represents +0000000000000000000000000000000010000000000000000000000000000000 = 4294967296

[-1,[1,1]] represents -1000000000000000000000000000000010000000000000000000000000000000 = -4294967297

# batch requests

A batch request is a method for sending several unique requests to the network all at once.

The requests are sent as an array filled with request objects. Results are returned in the order of received requests.

TIP

Avoid sending requests that depend on each other. For example, do not send a coin activation and a balance request to that coin in the same batch.

Such requests result in non-deterministic behavior, as the AtomicDEX/MM2 software may or may not execute the requests in the desired order.

# Arguments

Structure Type Description
(none) array of objects request objects to be executed in parallel

# Response

Structure Type Description
(none) array of objects the results, provided in the order of received requests; this may contain null elements

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "[
{\"method\":\"electrum\",\"coin\":\"RICK\",\"servers\":[{\"url\":\"electrum1.cipig.net:10017\"},{\"url\":\"electrum2.cipig.net:10017\"},{\"url\":\"electrum3.cipig.net:10017\"}],\"userpass\":\"$userpass\",\"mm2\":1},
{\"method\":\"electrum\",\"coin\":\"MORTY\",\"servers\":[{\"url\":\"electrum1.cipig.net:10018\"},{\"url\":\"electrum2.cipig.net:10018\"},{\"url\":\"electrum3.cipig.net:10018\"}],\"userpass\":\"$userpass\",\"mm2\":1},
{\"method\":\"electrum\",\"coin\":\"RICK\",\"servers\":[{\"url\":\"electrum1.cipig.net:10017\"},{\"url\":\"electrum2.cipig.net:10017\"},{\"url\":\"electrum3.cipig.net:10017\"}],\"userpass\":\"invalid userpass\",\"mm2\":1}
]"

# buy

buy base rel price volume (match_by order_type base_confs base_nota rel_confs rel_nota)

The buy method issues a buy request and attempts to match an order from the orderbook based on the provided arguments.

TIP

  • Buy and sell methods always create the taker order first. A taker order must pay a dexfee during the swap as it is taking liquidity from the market. The dexfee is calculated as "the greater of either 0.0001 TAKER COIN or 1/777th the size of the desired order". If your GoodTillCancelled order is not matched in 30 seconds, the order is automatically converted to a maker request and stays on the orderbook until the request is matched or cancelled. To always act as a maker, please use the setprice method.
  • To prevent a user from making trades in which the transaction fees may end up costing a significant portion of the value of the trade, we have set a lower limit( 0.00777 ) to the value of a trade. See the description of the volume argument for more info.

# Arguments

Structure Type Description
base string the name of the coin the user desires to receive
rel string the name of the coin the user desires to sell
price numeric string or rational the price in rel the user is willing to pay per one unit of the base coin
volume numeric string or rational the amount of coins the user is willing to receive of the base coin; the following values must be greater than or equal to 0.00777:
  • the argument volume
  • the product of the arguments volume and price
match_by object the created order is matched using this condition. Important: This condition is not applied after a GoodTillCancelled order is converted to a maker request
match_by.type string Any to match with any other order; Orders to select specific uuids; Pubkeys to select specific nodes; default is Any
match_by.data array of strings uuids of orders to match for Orders type; pubkeys of nodes to match for Pubkeys type
order_type object the type of the order
order_type.type string there are two types from which to choose: GoodTillCancelled and FillOrKill. The GoodTillCancelled order is automatically converted to a maker order if the order is not matched in 30 seconds, and this maker order stays in the orderbook until explicitly cancelled. On the other hand, a FillOrKill order is cancelled if it is not matched within 30 seconds. The default type is GoodTillCancelled
base_confs number number of required blockchain confirmations for base coin atomic swap transaction; default to base coin configuration if not set
base_nota bool whether dPoW notarization is required for base coin atomic swap transaction; default to base coin configuration if not set
rel_confs number number of required blockchain confirmations for rel coin atomic swap transaction; default to rel coin configuration if not set
rel_nota bool whether dPoW notarization is required for rel coin atomic swap transaction; default to rel coin configuration if not set

# Response

Structure Type Description
result object the resulting order object
result.action string the action of the request (Buy)
result.base string the base currency of request
result.base_amount string the resulting amount of base currency that is received if the order matches (in decimal representation)
result.base_amount_rat rational the resulting amount of base currency that is received if the order matches (in rational representation)
result.rel string the rel currency of the request
result.rel_amount string the maximum amount of rel coin that is spent in order to buy the base_amount (according to price, in decimal representation)
result.rel_amount_rat rational the maximum amount of rel coin that is spent in order to buy the base_amount (according to price, in rational representation)
result.method string this field is used for internal P2P interactions; the value is always equal to "request"
result.dest_pub_key string reserved for future use. dest_pub_key allows the user to choose the P2P node that is eligible to match with the request. This value defaults to a "zero pubkey", which means anyone can be a match
result.sender_pubkey string the public key of this node
result.uuid string the request uuid
result.match_by object the created order is matched using this condition
result.match_by.type string Any to match with any other order; Orders to select specific uuids; Pubkeys to select specific nodes; Default is Any
result.match_by.data array of strings uuids of orders to match for Orders type; pubkeys of nodes to match for Pubkeys type
result.conf_settings.base_confs number number of required blockchain confirmations for base coin atomic swap transaction
result.conf_settings.base_nota bool whether dPoW notarization is required for base coin atomic swap transaction
result.conf_settings.rel_confs number number of required blockchain confirmations for rel coin atomic swap transaction
result.conf_settings.rel_nota bool whether dPoW notarization is required for rel coin atomic swap transaction

# 📌 Examples

# Command (decimal representation)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"buy\",\"base\":\"HELLO\",\"rel\":\"WORLD\",\"volume\":"\"1\"",\"price\":"\"1\""}"

# Command (rational representation in num-rational crate format)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"buy\",\"base\":\"HELLO\",\"rel\":\"WORLD\",\"volume\":[[1,[1]],[1,[1]]],\"price\":[[1,[1]],[1,[1]]]}"

# Command (rational representation as fraction object)

curl --url "http://127.0.0.1:7783" --data '{
  "userpass":"'$userpass'",
  "method":"buy",
  "base":"HELLO",
  "rel":"WORLD",
  "volume":{
    "numer":"3",
    "denom":"2"
  },
  "price":{
    "numer":"2",
    "denom":"1"
  }
}'

# Command (with confirmations and notarization settings)

curl --url "http://127.0.0.1:7783" --data '{
  "userpass":"'$userpass'",
  "method":"buy",
  "base":"HELLO",
  "rel":"WORLD",
  "volume":{
    "numer":"3",
    "denom":"2"
  },
  "price":{
    "numer":"2",
    "denom":"1"
  },
  "base_confs": 2,
  "base_nota": true,
  "rel_confs": 5,
  "rel_nota": false  
}'

# Command (GoodTillCancelled type)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"buy\",\"base\":\"BASE\",\"rel\":\"REL\",\"volume\":[[1,[1]],[1,[1]]],\"price\":[[1,[1]],[1,[1]]],\"order_type\":{\"type\":\"GoodTillCancelled\"}}"

# Command (FillOrKill type)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"buy\",\"base\":\"BASE\",\"rel\":\"REL\",\"volume\":[[1,[1]],[1,[1]]],\"price\":[[1,[1]],[1,[1]]],\"order_type\":{\"type\":\"FillOrKill\"}}"

# Command (match by Any)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"buy\",\"base\":\"BASE\",\"rel\":\"REL\",\"volume\":[[1,[1]],[1,[1]]],\"price\":[[1,[1]],[1,[1]]],\"match_by\":{\"type\":\"Any\"}}"

# Command (match by Pubkeys)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"buy\",\"base\":\"BASE\",\"rel\":\"REL\",\"volume\":[[1,[1]],[1,[1]]],\"price\":[[1,[1]],[1,[1]]],\"match_by\":{\"type\":\"Pubkeys\",\"data\":[\"1ab7edc96abaefb358b52c583048eaaeb8ea42609d096d6cddfafa02fa510c6a\"]}}"

# Command (match by Orders)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"buy\",\"base\":\"BASE\",\"rel\":\"REL\",\"volume\":[[1,[1]],[1,[1]]],\"price\":[[1,[1]],[1,[1]]],\"match_by\":{\"type\":\"Orders\",\"data\":[\"d14452bb-e82d-44a0-86b0-10d4cdcb8b24\"]}}"

# cancel_all_orders

cancel_order cancel_by

The cancel_all_orders cancels the active orders created by the MM2 node by specified condition.

# Arguments

Structure Type Description
cancel_by object orders matching this condition are cancelled
cancel_by.type string All to cancel all orders; Pair to cancel all orders for specific coin pairs; Coin to cancel all orders for a specific coin
cancel_by.data object additional data the cancel condition; present with Pair and Coin types
cancel_by.data.base string base coin of the pair; Pair type only
cancel_by.data.rel string rel coin of the pair; Pair type only
cancel_by.data.ticker string order is cancelled if it uses ticker as base or rel; Coin type only

# Response

Structure Type Description
result object
result.cancelled array of strings (uuids) uuids of cancelled orders
result.currently_matching array of strings (uuids) uuids of the orders being matched with other orders; these are not cancelled even if they fit cancel condition

# 📌 Examples

# Command (All orders)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"cancel_all_orders\",\"cancel_by\":{\"type\":\"All\"}}"

# Command (Cancel by pair)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"cancel_all_orders\",\"cancel_by\":{\"type\":\"Pair\",\"data\":{\"base\":\"RICK\",\"rel\":\"MORTY\"}}}"

# Command (Cancel by coin)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"cancel_all_orders\",\"cancel_by\":{\"type\":\"Coin\",\"data\":{\"ticker\":\"RICK\"}}}"

# cancel_order

cancel_order uuid

The cancel_order cancels the active order created by the MM2 node.

# Arguments

Structure Type Description
uuid string the uuid of the order the user desires to cancel

# Response

Structure Type Description
result string indicates the status of operation

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"cancel_order\",\"uuid\":\"6a242691-6c05-474a-85c1-5b3f42278f41\"}"

# coins_needed_for_kick_start

coins_needed_for_kick_start()

If MM2 is stopped while making a swap/having the active order it will attempt to kick-start them on next launch and continue from the point where it's stopped. coins_needed_for_kick_start returns the tickers of coins that should be activated ASAP after MM2 is started to continue the interrupted swaps. Consider calling this method on MM2 startup and activate the returned coins using enable or electrum methods.

# Arguments

Structure Type Description
(none)

# Response

Structure Type Description
result array of strings tickers of coins that should be activated to kick-start swaps and orders

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"coins_needed_for_kick_start\"}"

# convertaddress

convertaddress coin from to_address_format

The convertaddress method converts an input address to a specified address format.

For example, this method can be used to convert a BCH address from legacy to cash address format and vice versa.

Or this can be used to convert an ETH address from single to mixed case checksum format.

# Arguments

Structure Type Description
coin string the name of the coin address context
from string input address
to_address_format object address format to which the input address should be converted
to_address_format.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
to_address_format.network string (enum) network prefix for cashaddress format. Possible values: bitcoincash for BCH mainnet; bchtest for BCH testnet; bchreg for BCH regtest

# Response

Structure Type Description
result.address string the result of address conversion

# disable_coin

disable_coin coin

The disable_coin method deactivates the previously enabled coin. MM2 also cancels all active orders that use the selected coin. The method will return an error in the following cases:

  • The coin is not enabled
  • The coin is used by active swaps
  • The coin is used by a currently matching order. In this case, other orders might still be cancelled

# Arguments

Structure Type Description
coin string the ticker of coin to disable

# Response

Structure Type Description
result.coin string the ticker of deactivated coin
result.cancelled_orders array of strings uuids of cancelled orders
swaps array of strings uuids of active swaps that use the selected coin; present only in error cases
orders.matching array of strings uuids of matching orders that use the selected coin; present only in error cases
orders.cancelled array of strings uuids of orders that were successfully cancelled despite the error

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"disable_coin\",\"coin\":\"RICK\"}"

# electrum

electrum coin servers (mm2 tx_history=false)

Important

This command must be executed at the initiation of each MM2 instance. Also, AtomicDEX software requires the mm2 parameter to be set for each coin; the methods to activate the parameter vary. See below for further information.

TIP

Electrum mode is available for utxo-based coins only; this includes Bitcoin and Bitcoin-based forks. Electrum mode is not available for ETH/ERC20.

The electrum method enables a coin by connecting the user's software instance to the coin blockchain using electrum technology (e.g. lite mode). This allows the user to avoid syncing the entire blockchain to their local machine.

Each coin can be enabled only once, and in either Electrum or Native mode. The DEX software does not allow a coin to be active in both modes at once.

# Notes on the MM2 Parameter

For each coin, Komodo software requires the user/developer to set the mm2 parameter. This can be achieved either in the coins for more details), or via the electrum and enable methods.

The value of the mm2 parameter informs the software as to whether the coin is expected to function.

  • 0 = non-functioning
  • 1 = functioning

TIP

GUI software developers may refer to the coins file in this link for the default coin json configuration.

Volunteers are welcome to test coins with AtomicDEX software at any time. After testing a coin, please create a pull request with the desired coin configuration and successful swap details using the guide linked below.

Guide to Submitting Coin Test Results

# Examples of the Parameter Settings

Set the value of the mm2 parameter in the coins file as follows:

"mm2" : 1

For terminal interface examples, see the examples section below.

# Arguments

Structure Type Description
coin string the name of the coin you want to enable
servers array of objects the list of Electrum servers to which you want to connect
servers.url string server url
servers.protocol string the transport protocol that MM2 will use to connect to the server. Possible values: TCP, SSL. Default value: TCP
servers.disable_cert_verification bool when set to true, this disables server SSL/TLS certificate verification (e.g. to use self-signed certificate). Default value is false. Use at your own risk
mm2 number (required if not set in the coins file) this property informs the AtomicDEX software as to whether the coin is expected to function; accepted values are either 0 or 1
tx_history bool whether the node should enable tx_history preloading as a background process; this must be set to true if you plan to use the my_tx_history API
required_confirmations number the number of confirmations for which MM2 must wait for the selected coin to perform the atomic swap transactions
requires_notarization bool whether the node should wait for a notarization of the selected coin that is performing the atomic swap transactions applicable only for coins using Komodo dPoW

# Response

Structure Type Description
address string the address of the user's coin wallet, based on the user's passphrase
balance string (numeric) the amount of coin the user holds in their wallet
coin string the ticker of the enabled coin
required_confirmations number the number of transaction confirmations for which MM2 must wait during the atomic swap process
requires_notarization bool whether the node must wait for a notarization of the selected coin that is performing the atomic swap transactions; applicable only for coins using Komodo dPoW
result string the result of the request; this value either indicates success, or an error, or another type of failure

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"electrum\",\"coin\":\"HELLOWORLD\",\"servers\":[{\"url\":\"localhost:20025\",\"protocol\":\"SSL\",\"disable_cert_verification\":true},{\"url\":\"localhost:10025\"}]}"

# Command (With mm2 argument)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"electrum\",\"coin\":\"HELLOWORLD\",\"servers\":[{\"url\":\"localhost:20025\",\"protocol\":\"SSL\",\"disable_cert_verification\":true},{\"url\":\"localhost:10025\"}],\"mm2\":1}"

# Command (With required_confirmations and requires_notarization arguments)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"electrum\",\"coin\":\"HELLOWORLD\",\"servers\":[{\"url\":\"localhost:20025\",\"protocol\":\"SSL\",\"disable_cert_verification\":true},{\"url\":\"localhost:10025\"}],\"required_confirmations\":10,\"requires_notarization\":true}"

# enable

enable coin (urls swap_contract_address mm2 tx_history=false)

Important

AtomicDEX software requires the mm2 parameter to be set for each coin; the methods to activate the parameter vary. See below for further information.

The enable method enables a coin by connecting the user's software instance to the coin blockchain using the native coin daemon.

Each coin can be enabled only once, and in either Electrum or Native mode. The DEX software does not allow a coin to be active in both modes at once.

For utxo-based coins the daemon of this blockchain must also be running on the user's machine for enable to function.

Note

The MM2 node's coin address needs to be imported manually into the coin daemon using the importaddress call.

ETH/ERC20 coins are also enabled by the enable method, but a local installation of an ETH node is not required.

# Notes on the mm2 Parameter

Please refer to the mm2 explanatory section in the electrum method for information about setting the mm2 parameter and testing new coins.

Link to mm2 explanatory section

For terminal interface examples using the mm2 parameter with the enable method, see the examples section below.

# Using AtomicDEX Software on an ETH-Based Network

The following information can assist the user/developer in connecting AtomicDEX software to the Ethereum network:

To use AtomicDEX software on another Ethereum-based network, such as the Kovan testnet or ETC, deploy the Etomic swap contract code from the repository linked below. Use of this code requires either an ETH node setup or access to a public service such as Infura.

Link to repository code for Ethereum-based networks

# Arguments

Structure Type Description
coin string the name of the coin the user desires to enable
urls array of strings (required for ETH/ERC20) urls of Ethereum RPC nodes to which the user desires to connect
swap_contract_address string (required for ETH/ERC20) address of etomic swap smart contract
gas_station_url string (optional for ETH/ERC20) url of ETH gas station API; MM2 uses eth_gasPrice RPC API by default; when this parameter is set, MM2 will request the current gas price from Station for new transactions, and this often results in lower fees
mm2 number (required if not set in the coins file) this property informs the AtomicDEX software as to whether the coin is expected to function; accepted values are either 0 or 1
tx_history bool whether the node should enable tx_history preloading as a background process; this must be set to true if you plan to use the my_tx_history API
required_confirmations number the number of confirmations for which MM2 must wait for the selected coin to perform the atomic swap transactions; applicable only for coins using Komodo dPoW
requires_notarization bool whether the node should wait for a notarization of the selected coin that is performing the atomic swap transactions applicable only for coins using Komodo dPoW

# Response

Structure Type Description
address string the address of the user's coin wallet, based on the user's passphrase
balance string (numeric) the amount of coin the user holds in their wallet
coin string the ticker of enabled coin
required_confirmations number MM2 will wait for the this number of coin's transaction confirmations during the swap
requires_notarization bool whether the node must wait for a notarization of the selected coin that is performing the atomic swap transactions
result string the result of the request; this value either indicates success, or an error or other type of failure

# 📌 Examples

# Command (for Bitcoin-based blockchains)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"enable\",\"coin\":\"HELLOWORLD\"}"

# Command (With required_confirmations and requires_notarization arguments)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"enable\",\"coin\":\"HELLOWORLD\",\"required_confirmations\":10,\"requires_notarization\":true}"

# Command (for Ethereum and ERC20-based blockchains)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"enable\",\"coin\":\"ETH\",\"urls\":[\"http://eth-ropsten.cipig.net:8645\"],\"swap_contract_address\":\"0x7Bc1bBDD6A0a722fC9bffC49c921B685ECB84b94\"}"

# Command (for Ethereum and ERC20-based blockchains with gas_station_url)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"enable\",\"coin\":\"ETH\",\"urls\":[\"http://eth-ropsten.cipig.net:8645\"],\"swap_contract_address\":\"0x7Bc1bBDD6A0a722fC9bffC49c921B685ECB84b94\",\"gas_station_url\":\"https://ethgasstation.info/json/ethgasAPI.json\"}"

# Command (With mm2 argument)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"enable\",\"coin\":\"HELLOWORLD\",\"mm2\":1}"

# get_enabled_coins

get_enabled_coins

The get_enabled_coins method returns data of coins that are currently enabled on the user's MM2 node.

# Arguments

Structure Type Description
(none)

# Response

Structure Type Description
result array of objects tickers and addresses of enabled coins
result.address string the user's address for this coin
result.ticker string the ticker name of this coin

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"get_enabled_coins\"}"

# get_trade_fee

get_trade_fee coin

The get_trade_fee method returns the approximate amount of the miner fee that is paid per swap transaction.

This amount should be multiplied by 2 and deducted from the volume on buy/sell calls when the user is about to trade the entire balance of the selected coin.

# Arguments

Structure Type Description
coin string the name of the coin for the requested trade fee

# Response

Structure Type Description
result object an object containing the relevant information
result.coin string the fee is paid from the user's balance of this coin. This coin name may differ from the requested coin. For example ERC20 fees are paid by ETH (gas)
result.amount string (numeric) the approximate fee amount to be paid per swap transaction in decimal representation
result.amount_rat rational the approximate fee amount to be paid per swap transaction in rational representation
result.amount_fraction fraction the approximate fee amount to be paid per swap transaction in fraction representation

# 📌 Examples

# Command (BTC)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"get_trade_fee\",\"coin\":\"BTC\"}"

# Command (ETH)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"get_trade_fee\",\"coin\":\"ETH\"}"

# Command (ERC20)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"get_trade_fee\",\"coin\":\"BAT\"}"

# help

help()

The help method returns the full API documentation in the terminal.

# Arguments

Structure Type Description
(none)

# Response

Structure Type Description
(returns the full docs in terminal)

# import_swaps

import_swaps swaps

The import_swaps method imports to the local database the swaps data that was exported from another MM2 instance.

Use this method in combination with my_swap_status or my_recent_swaps to copy the swap history between different devices.

# Arguments

Structure Type Description
swaps array of objects swaps data; each record has the format of the my_swap_status response

# Response

Structure Type Description
result.imported array of strings uuids of swaps that were successfully imported
result.imported map uuids of swaps that failed to import; includes error message

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"import_swaps\",\"swaps\":[{"error_events":["StartFailed","NegotiateFailed","TakerFeeSendFailed","MakerPaymentValidateFailed","TakerPaymentTransactionFailed","TakerPaymentDataSendFailed","TakerPaymentWaitForSpendFailed","MakerPaymentSpendFailed","TakerPaymentRefunded","TakerPaymentRefundFailed"],"events":[{"event":{"data":{"lock_duration":7800,"maker":"631dcf1d4b1b693aa8c2751afc68e4794b1e5996566cfc701a663f8b7bbbe640","maker_amount":"3","maker_coin":"BEER","maker_coin_start_block":156186,"maker_payment_confirmations":0,"maker_payment_wait":1568883784,"my_persistent_pub":"02031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3","started_at":1568881184,"taker_amount":"4","taker_coin":"ETOMIC","taker_coin_start_block":175041,"taker_payment_confirmations":1,"taker_payment_lock":1568888984,"uuid":"07ce08bf-3db9-4dd8-a671-854affc1b7a3"},"type":"Started"},"timestamp":1568881185316},{"event":{"data":{"maker_payment_locktime":1568896784,"maker_pubkey":"02631dcf1d4b1b693aa8c2751afc68e4794b1e5996566cfc701a663f8b7bbbe640","secret_hash":"eba736c5cc9bb33dee15b4a9c855a7831a484d84"},"type":"Negotiated"},"timestamp":1568881246025},{"event":{"data":{"block_height":0,"coin":"ETOMIC","fee_details":{"amount":"0.00001"},"from":["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"],"internal_id":"0c07be4dda88d8d75374496aa0f27e12f55363ce8d558cb5feecc828545e5f87","my_balance_change":"-0.005158","received_by_me":"0.004842","spent_by_me":"0.01","timestamp":0,"to":["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW","RThtXup6Zo7LZAi8kRWgjAyi1s4u6U9Cpf"],"total_amount":"0.01","tx_hash":"0c07be4dda88d8d75374496aa0f27e12f55363ce8d558cb5feecc828545e5f87","tx_hex":"0400008085202f890146b98696761d5e8667ffd665b73e13a8400baab4b22230a7ede0e4708597ee9c000000006a473044022077acb70e5940dfe789faa77e72b34f098abbf0974ea94a0380db157e243965230220614ec4966db0a122b0e7c23aa0707459b3b4f8241bb630c635cf6e943e96362e012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff02f0da0700000000001976a914ca1e04745e8ca0c60d8c5881531d51bec470743f88ac68630700000000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ac5e3a835d000000000000000000000000000000"},"type":"TakerFeeSent"},"timestamp":1568881250689},{"event":{"data":{"block_height":0,"coin":"BEER","fee_details":{"amount":"0.00001"},"from":["RJTYiYeJ8eVvJ53n2YbrVmxWNNMVZjDGLh"],"internal_id":"31d97b3359bdbdfbd241e7706c90691e4d7c0b7abd27f2b22121be7f71c5fd06","my_balance_change":"0","received_by_me":"0","spent_by_me":"0","timestamp":0,"to":["RJTYiYeJ8eVvJ53n2YbrVmxWNNMVZjDGLh","bPZrgpAviZUYUmECtwdocqpFy1VEV7pL7d"],"total_amount":"8240.19873868","tx_hash":"31d97b3359bdbdfbd241e7706c90691e4d7c0b7abd27f2b22121be7f71c5fd06","tx_hex":"0400008085202f8901b4679094d4bf74f52c9004107cb9641a658213d5e9950e42a8805824e801ffc7010000006b483045022100b2e49f8bdc5a4b6c404e10150872dbec89a46deb13a837d3251c0299fe1066ca022012cbe6663106f92aefce88238b25b53aadd3522df8290ced869c3cc23559cc23012102631dcf1d4b1b693aa8c2751afc68e4794b1e5996566cfc701a663f8b7bbbe640ffffffff0200a3e1110000000017a91476e1998b0cd18da5f128e5bb695c36fbe6d957e98764c987c9bf0000001976a91464ae8510aac9546d5e7704e31ce177451386455588ac753a835d000000000000000000000000000000"},"type":"MakerPaymentReceived"},"timestamp":1568881291571},{"event":{"type":"MakerPaymentWaitConfirmStarted"},"timestamp":1568881291571},{"event":{"type":"MakerPaymentValidatedAndConfirmed"},"timestamp":1568881291985},{"event":{"data":{"block_height":0,"coin":"ETOMIC","fee_details":{"amount":"0.00001"},"from":["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"],"internal_id":"95926ab204049edeadb370c17a1168d9d79ee5747d8d832f73cfddf1c74f3961","my_balance_change":"-4.00001","received_by_me":"43.59901307","spent_by_me":"47.59902307","timestamp":0,"to":["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW","bKnDnsrM3eR8d9vWHfd3LP1dcV1RskE7x5"],"total_amount":"47.59902307","tx_hash":"95926ab204049edeadb370c17a1168d9d79ee5747d8d832f73cfddf1c74f3961","tx_hex":"0400008085202f8902875f5e5428c8ecfeb58c558dce6353f5127ef2a06a497453d7d888da4dbe070c010000006a4730440220416059356dc6dde0ddbee206e456698d7e54c3afa92132ecbf332e8c937e5383022068a41d9c208e8812204d4b0d21749b2684d0eea513467295e359e03c5132e719012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff46b98696761d5e8667ffd665b73e13a8400baab4b22230a7ede0e4708597ee9c010000006b483045022100a990c798d0f96fd5ff7029fd5318f3c742837400d9f09a002e7f5bb1aeaf4e5a0220517dbc16713411e5c99bb0172f295a54c97aaf4d64de145eb3c5fa0fc38b67ff012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff020084d7170000000017a9144d57b4930e6c86493034f17aa05464773625de1c877bd0de03010000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ac8c3a835d000000000000000000000000000000"},"type":"TakerPaymentSent"},"timestamp":1568881296904},{"event":{"data":{"secret":"fb968d5460399f20ffd09906dc8f65c21fbb5cb8077a8e6d7126d0526586ca96","transaction":{"block_height":0,"coin":"ETOMIC","fee_details":{"amount":"0.00001"},"from":["bKnDnsrM3eR8d9vWHfd3LP1dcV1RskE7x5"],"internal_id":"68f5ec617bd9a4a24d7af0ce9762d87f7baadc13a66739fd4a2575630ecc1827","my_balance_change":"0","received_by_me":"0","spent_by_me":"0","timestamp":0,"to":["RJTYiYeJ8eVvJ53n2YbrVmxWNNMVZjDGLh"],"total_amount":"4","tx_hash":"68f5ec617bd9a4a24d7af0ce9762d87f7baadc13a66739fd4a2575630ecc1827","tx_hex":"0400008085202f890161394fc7f1ddcf732f838d7d74e59ed7d968117ac170b3adde9e0404b26a929500000000d8483045022100a33d976cf509d6f9e66c297db30c0f44cced2241ee9c01c5ec8d3cbbf3d41172022039a6e02c3a3c85e3861ab1d2f13ba52677a3b1344483b2ae443723ba5bb1353f0120fb968d5460399f20ffd09906dc8f65c21fbb5cb8077a8e6d7126d0526586ca96004c6b63049858835db1752102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ac6782012088a914eba736c5cc9bb33dee15b4a9c855a7831a484d84882102631dcf1d4b1b693aa8c2751afc68e4794b1e5996566cfc701a663f8b7bbbe640ac68ffffffff011880d717000000001976a91464ae8510aac9546d5e7704e31ce177451386455588ac942c835d000000000000000000000000000000"}},"type":"TakerPaymentSpent"},"timestamp":1568881328643},{"event":{"data":{"error":"taker_swap:798] utxo:950] utxo:950] error"},"type":"MakerPaymentSpendFailed"},"timestamp":1568881328645},{"event":{"type":"Finished"},"timestamp":1568881328648}],"my_info":{"my_amount":"4","my_coin":"ETOMIC","other_amount":"3","other_coin":"BEER","started_at":1568881184},"recoverable":true,"success_events":["Started","Negotiated","TakerFeeSent","MakerPaymentReceived","MakerPaymentWaitConfirmStarted","MakerPaymentValidatedAndConfirmed","TakerPaymentSent","TakerPaymentSpent","MakerPaymentSpent","Finished"],"type":"Taker","uuid":"07ce08bf-3db9-4dd8-a671-854affc1b7a3"}]}"

# kmd_rewards_info

kmd_rewards_info

The kmd_rewards_info method returns information about the active user rewards that can be claimed by an address's unspent outputs.

Note

This method only works when the KMD coin is activated.

# Arguments

Structure Type Description
(none)

# Response

Structure Type Description
result array of objects the rewards info; each element corresponds to an unspent output and contains detailed information about the active user rewards corresponding to it
result.tx_hash string the hash of the transaction
result.height number (integer, optional) the height of the block in which the transaction was included (empty if the tx is not mined yet)
result.output_index number (integer) the zero-based index of the output in the transaction’s list of outputs
result.amount string (numeric) the transaction output’s value
result.locktime number (integer) the transaction output's locktime
result.accrued_rewards object the amount of accrued rewards if they exist or the reason for their non existence
result.accrue_start_at number (integer, optional) the rewards start to accrue at this time for the given transaction (empty if the rewards will never accrue to it)
result.accrue_stop_at number (integer, optional) the rewards stop to accrue at this time for the given transaction (empty if the tx is not mined yet or if rewards will never accrue to it)

Where the result.accrued_rewards has either

Structure Type Description
Accrued string (numeric) the amount of accrued rewards

or

Structure Type Description
NotAccruedReason string the reason why rewards are not accrued

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783/" --data "{"userpass":"$userpass","method":"kmd_rewards_info"}"

# list_banned_pubkeys

list_banned_pubkeys

The list_banned_pubkeys method returns a list of public keys of nodes that are banned from interacting with the node executing the method.

Banned nodes cannot complete orders and order matching requests with the node executing the method.

TIP

Some cases of swap failures give cause for banning a node. For example, a market taker may not follow the atomic-swap protocol by not sending the dex fee. The list_banned_pubkeys method is useful in these circumstances.

# Arguments

Structure Type Description
(none)

# Response

Structure Type Description
result map of objects (key - pubkey in hexadecimal representation) the list of pubkeys banned by current node
result.*.caused_by_swap string the uuid of the swap that triggered the ban
result.*.caused_by_event object the swap event that triggered the ban

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"list_banned_pubkeys\"}"

# max_taker_vol

max_taker_vol coin

The max_taker_vol method returns the maximum available volume for buy/sell methods for selected coin. This takes the dex fee and blockchain miner fees into account. The result should be used as is for sell method or divided by price for buy method.

# Arguments

Structure Type Description
coin string the name of the coin to retrieve the max available taker volume

# Response

Structure Type Description
coin fraction the max available taker volume in fraction representation

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"method\":\"max_taker_vol\",\"coin\":\"RICK\",\"userpass\":\"$userpass\",\"mm2\":1}"

# my_balance

my_balance coin

The my_balance method returns the current balance of the specified coin.

# Arguments

Structure Type Description
coin string the name of the coin to retrieve the balance

# Response

Structure Type Description
address string the address that holds the coins
balance string (numeric) the number of coins in the address
coin string the name of the coin

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"my_balance\",\"coin\":\"HELLOWORLD\"}"

# my_orders

my_orders()

The my_orders method returns the data of all active orders created by the MM2 node.

# Arguments

Structure Type Description
(none)

# Response

Structure Type Description
maker_orders map of objects orders that are currently active in market-maker mode
taker_orders map of objects orders that are currently active in market-taker mode

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"my_orders\"}"

# my_recent_swaps

(from_uuid limit=10)

The my_recent_swaps method returns the data of the most recent atomic swaps executed by the MM2 node.

# Arguments

Structure Type Description
limit number limits the number of returned swaps
from_uuid string MM2 will skip records until this uuid, skipping the from_uuid as well

# Response

Structure Type Description
swaps array of objects swaps data; each record has the format of the my_swap_status response
from_uuid string the from_uuid that was set in the request; this value is null if nothing was set
skipped number the number of skipped records (i.e. the position of from_uuid in the list + 1; the value is 0 if from_uuid was not set
limit number the limit that was set in the request; note that the actual number of swaps can differ from the specified limit (e.g. on the last page)
total number total number of swaps available

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"my_recent_swaps\",\"from_uuid\":\"e299c6ece7a7ddc42444eda64d46b163eaa992da65ce6de24eb812d715184e4c\",\"limit\":2}"

# my_swap_status

uuid

The my_swap_status method returns the data of an atomic swap executed on a MM2 node.

# Arguments

Structure Type Description
params uuid string the uuid of swap, typically received from the buy/sell call

# Response

Structure Type Description
events array of objects the events that occurred during the swap
events.type string an event type; the list of event types with their data structure is available below
events.data object additional data of the event; the list of events with their data structure is available below
success_events array of strings a list of events that gained a success swap state; the contents are listed in the order in which they should occur in the events array
error_events array of strings a list of events that fell into an error swap state; if at least 1 of the events happens, the swap is considered a failure
type string whether the node acted as a market Maker or Taker
uuid string swap uuid
gui string (optional) information about gui; copied from MM2 configuration
mm_version string (optional) MM2 version
maker_coin string (optional) ticker of maker coin
taker_coin string (optional) ticker of taker coin
maker_amount string (numeric, optional) the amount of coins to be swapped by maker
taker_amount string (numeric, optional) the amount of coins to be swapped by taker
my_info object (optional) this object maps event data to make displaying swap data in a GUI simpler (my_coin, my_amount, etc.)
recoverable bool whether the swap can be recovered using the recover_funds_of_swap API command. Important note: MM2 does not record the state regarding whether the swap was recovered or not. MM2 allows as many calls to the recover_funds_of_swap method as necessary, in case of errors

# Maker Swap Events

# Taker swap events

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"method\":\"my_swap_status\",\"params\":{\"uuid\":\"d14452bb-e82d-44a0-86b0-10d4cdcb8b24\"},\"userpass\":\"$userpass\"}"

# my_tx_history

(from_id limit=10 max=false)

The my_tx_history method returns the blockchain transactions involving the MM2 node's coin address.

The coin that is used must have tx_history set to true in its enable or electrum call.

# Arguments

Structure Type Description
coin string the name of the coin for the history request
limit number limits the number of returned transactions; ignored if max = true
max bool whether to return all available records; defaults to false
from_id string MM2 will skip records until it reaches this ID, skipping the from_id as well; track the internal_id of the last displayed transaction to find the value of this field for the next page

# Response

Structure Type Description
transactions array of objects transactions data
from_id string the from_id specified in the request; this value is null if from_id was not set
skipped number the number of skipped records (i.e. the position of from_id in the list + 1); this value is 0 if from_id was not set
limit number the limit that was set in the request; note that the actual number of transactions can differ from the specified limit (e.g. on the last page)
total number the total number of transactions available
current_block number the number of the latest block of coin blockchain
sync_status object provides the information that helps to track the progress of transaction history preloading at background
sync_status.state string current state of sync; possible values: NotEnabled, NotStarted, InProgress, Error, Finished
sync_status.additional_info object additional info that helps to track the progress; present for InProgress and Error states only
sync_status.additional_info.blocks_left number present for ETH/ERC20 coins only; displays the number of blocks left to be processed for InProgress state
sync_status.additional_info.transactions_left number present for UTXO coins only; displays the number of transactions left to be processed for InProgress state
sync_status.additional_info.code number displays the error code for Error state
sync_status.additional_info.message number displays the error message for Error state

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"my_tx_history\",\"coin\":\"RICK\",\"limit\":1,\"from_id\":\"1d5c1b67f8ebd3fc480e25a1d60791bece278f5d1245c5f9474c91a142fee8e1\"}"

# Command (max = true)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"my_tx_history\",\"coin\":\"RICK\",\"max\":true,\"from_id\":\"1d5c1b67f8ebd3fc480e25a1d60791bece278f5d1245c5f9474c91a142fee8e1\"}"

# order_status

order_status uuid

The order_status method returns the data of the active order with the selected uuid created by the MM2 node.

# Arguments

Structure Type Description
uuid string uuid of order to display

# Response

Structure Type Description
type string type of the order ("Maker" or "Taker")
order object order data

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"order_status\",\"uuid\":\"c3b3105c-e914-4ed7-9f1c-604783b054a1\"}"

# orderbook

orderbook base rel (duration=number)

The orderbook method requests from the network the currently available orders for the specified trading pair.

# Arguments

Structure Type Description
base string base currency of a pair
rel string "related" currency, also can be called "quote currency" according to exchange terms
duration number deprecated

# Response

Structure Type Description
bids array an array of objects containing outstanding bids
numbids number the number of outstanding bids
biddepth number deprecated
asks array an array of objects containing outstanding asks
coin string the name of the base coin; the user desires this
address string the address offering the trade
price string (decimal) the price in rel the user is willing to pay per one unit of the base coin
price_rat rational the price in num-rational crate format
price_fraction object (rational) the price represented as an object
maxvolume string (decimal) the maximum amount of base coin the offer provider is willing to sell
max_volume_rat rational the max volume in num-rational crate format
max_volume_fraction object (rational) the max volume represented as an object
pubkey string the pubkey of the offer provider
age number the age of the offer (in seconds)
zcredits number the zeroconf deposit amount
numasks number the total number of asks
askdepth number the depth of the ask requests
base string the name of the coin the user desires to receive
rel string the name of the coin the user will trade
timestamp number the timestamp of the orderbook request
netid number the id of the network on which the request is made (default is 0)
uuid string the uuid of order
is_mine bool whether the order is placed by me

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"orderbook\",\"base\":\"HELLO\",\"rel\":\"WORLD\"}"

# recover_funds_of_swap

recover_funds_of_swap uuid

In certain cases, a swap can finish with an error wherein the user's funds are stuck on the swap-payment address. (This address is the P2SH address when executing on a utxo-based blockchain, or an etomic-swap smart contract when executing on an ETH/ERC20 blockchain.)

This error can occur when one side of the trade does not follow the protocol (for any reason). The error persists as attempts to refund the payment fail due to network connection issues between the MM2 node and the coin's RPC server.

In this scenario, the recover_funds_of_swap method instructs the MM2 software to attempt to reclaim the user funds from the swap-payment address, if possible.

# Arguments

Structure Type Description
params.uuid string uuid of the swap to recover the funds

# Response

Structure Type Description
result.action string the action executed to unlock the funds. Can be either SpentOtherPayment or RefundedMyPayment
result.coin string the balance of this coin will be unstuck by the recovering transaction
result.tx_hash string the hash of the recovering transaction
result.tx_hex string raw bytes of the recovering transaction in hexadecimal representation

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"recover_funds_of_swap\",\"params\":{\"uuid\":\"6343b2b1-c896-47d4-b0f2-a11798f654ed\"}}"

# sell

sell base rel price volume (match_by order_type base_confs base_nota rel_confs rel_nota)

The sell method issues a sell request and attempts to match an order from the orderbook based on the provided arguments.

TIP

  • Buy and sell methods always create the taker order first. A taker order must pay a dexfee during the swap as it is taking liquidity from the market. The dexfee is calculated as "the greater of either 0.0001 TAKER COIN or 1/777th the size of the desired order". If your GoodTillCancelled order is not matched in 30 seconds, the order is automatically converted to a maker request and stays on the orderbook until the request is matched or cancelled. To always act as a maker, please use the setprice method.
  • To prevent a user from making trades in which the transaction fees may end up costing a significant portion of the value of the trade, we have set a lower limit( 0.00777 ) to the value of a trade. See the description of the volume argument for more info.

# Arguments

Structure Type Description
base string the name of the coin the user desires to sell
rel string the name of the coin the user desires to receive
price numeric string or rational the price in rel the user is willing to receive per one unit of the base coin
volume numeric string or rational the amount of coins the user is willing to sell of the base coin; the following values must be greater than or equal to 0.00777:
  • the argument volume
  • the product of the arguments volume and price
match_by object the created order is matched using this condition; important: this condition is not applied after GoodTillCancelled order conversion to maker request
match_by.type string Any to match with any other order; Orders to select specific uuids; Pubkeys to select specific nodes; Default is Any
match_by.data array of strings uuids of orders to match for Orders type; pubkeys of nodes to match for Pubkeys type
order_type object the type of the order
order_type.type string there are two types from which to choose: GoodTillCancelled and FillOrKill. The GoodTillCancelled order is automatically converted to a maker order if the order is not matched in 30 seconds, and this maker order stays in the orderbook until explicitly cancelled. On the other hand, a FillOrKill order is cancelled if it is not matched within 30 seconds. The default type is GoodTillCancelled
base_confs number number of required blockchain confirmations for base coin atomic swap transaction; default to base coin configuration if not set
base_nota bool whether dPoW notarization is required for base coin atomic swap transaction; default to base coin configuration if not set
rel_confs number number of required blockchain confirmations for rel coin atomic swap transaction; default to rel coin configuration if not set
rel_nota bool whether dPoW notarization is required for rel coin atomic swap transaction; default to rel coin configuration if not set

# Response

Structure Type Description
result object the resulting order object
result.action string the action of the request (Sell)
result.base string the base currency of the request
result.base_amount string the resulting amount of base currency that is sold if the order matches (in decimal representation)
result.base_amount_rat rational the resulting amount of base currency that is sold if the order matches (in rational representation)
result.rel string the rel currency of the request
result.rel_amount string the minimum amount of rel coin that must be received in order to sell the base_amount of base (according to price, in decimal representation)
result.rel_amount_rat rational the minimum amount of rel coin that must be received in order to sell the base_amount of base (according to price, in rational representation)
result.method string this field is used for internal P2P interactions; the value is always equal to "request"
result.dest_pub_key string reserved for future use. The dest_pub_key allows the user to choose the P2P node that is eligible to match with the request. This value defaults to "zero pubkey", meaning that anyone can match
result.sender_pubkey string the public key of our node
result.uuid string the request uuid
result.match_by object the created order is matched using this condition
result.match_by.type string Any to match with any other order; Orders to select specific uuids; Pubkeys to select specific nodes; Default is Any
result.match_by.data array of strings uuids of orders to match for Orders type; pubkeys of nodes to match for Pubkeys type
result.conf_settings.base_confs number number of required blockchain confirmations for base coin atomic swap transaction
result.conf_settings.base_nota bool whether dPoW notarization is required for base coin atomic swap transaction
result.conf_settings.rel_confs number number of required blockchain confirmations for rel coin atomic swap transaction
result.conf_settings.rel_nota bool whether dPoW notarization is required for rel coin atomic swap transaction

# 📌 Examples

# Command (decimal representation)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"sell\",\"base\":\"BASE\",\"rel\":\"REL\",\"volume\":"\"1\"",\"price\":"\"1\""}"

# Command (rational representation in num-rational crate format)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"sell\",\"base\":\"BASE\",\"rel\":\"REL\",\"volume\":[[1,[1]],[1,[1]]],\"price\":[[1,[1]],[1,[1]]]}"

# Command (rational representation as a fraction object)

curl --url "http://127.0.0.1:7783" --data '{
  "userpass":"'$userpass'",
  "method":"sell",
  "base":"HELLO",
  "rel":"WORLD",
  "volume":{
    "numer":"3",
    "denom":"2"
  },
  "price":{
    "numer":"2",
    "denom":"1"
  }
}'

# Command (with confirmations and notarization settings)

curl --url "http://127.0.0.1:7783" --data '{
  "userpass":"'$userpass'",
  "method":"sell",
  "base":"HELLO",
  "rel":"WORLD",
  "volume":{
    "numer":"3",
    "denom":"2"
  },
  "price":{
    "numer":"2",
    "denom":"1"
  },
  "base_confs": 2,
  "base_nota": true,
  "rel_confs": 5,
  "rel_nota": false
}'

# Command (GoodTillCancelled type)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"sell\",\"base\":\"BASE\",\"rel\":\"REL\",\"volume\":[[1,[1]],[1,[1]]],\"price\":[[1,[1]],[1,[1]]],\"order_type\":{\"type\":\"GoodTillCancelled\"}}"

# Command (FillOrKill type)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"sell\",\"base\":\"BASE\",\"rel\":\"REL\",\"volume\":[[1,[1]],[1,[1]]],\"price\":[[1,[1]],[1,[1]]],\"order_type\":{\"type\":\"FillOrKill\"}}"

# Command (match by Any)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"sell\",\"base\":\"BASE\",\"rel\":\"REL\",\"volume\":[[1,[1]],[1,[1]]],\"price\":[[1,[1]],[1,[1]]],\"match_by\":{\"type\":\"Any\"}}"

# Command (match by Pubkeys)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"sell\",\"base\":\"BASE\",\"rel\":\"REL\",\"volume\":[[1,[1]],[1,[1]]],\"price\":[[1,[1]],[1,[1]]],\"match_by\":{\"type\":\"Pubkeys\",\"data\":[\"1ab7edc96abaefb358b52c583048eaaeb8ea42609d096d6cddfafa02fa510c6a\"]}}"

# Command (match by Orders)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"sell\",\"base\":\"BASE\",\"rel\":\"REL\",\"volume\":[[1,[1]],[1,[1]]],\"price\":[[1,[1]],[1,[1]]],\"match_by\":{\"type\":\"Orders\",\"data\":[\"d14452bb-e82d-44a0-86b0-10d4cdcb8b24\"]}}"

# send_raw_transaction

send_raw_transaction coin tx_hex

The send_raw_transaction method broadcasts the transaction to the network of selected coin.

# Arguments

Structure Type Description
coin string the name of the coin network on which to broadcast the transaction
tx_hex string the transaction bytes in hexadecimal format; this is typically generated by the withdraw method

# Response

Structure Type Description
tx_hash string the hash of the broadcast transaction

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"method\":\"send_raw_transaction\",\"coin\":\"KMD\",\"tx_hex\":\"0400008085202f8902d6a5b976db5e5c9e8f9ead50713b25f22cd061edc8ff0ff1049fd2cd775ba087000000006b483045022100bf2073c1ecfef3fc78f272045f46a722591401f61c2d2fac87fc474a17df7c3102200ca1bd0664ba75f3383e5cbbe96127ad534a86238dbea256e000b0fe2067ab8c012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffffd04d4e07ac5dacd08fb76e08d2a435fc4fe2b16eb0158695c820b44f42f044cb010000006a47304402200a0c21e8c0ae4a740f3663fe08aeff02cea6495157d531045b58d2dd79fb802702202f80dddd264db33f55e49799363997a175d39a91242a95f268c40f7ced97030b012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff0200e1f505000000001976a91405aab5342166f8594baf17a7d9bef5d56744332788acc3b3ca27000000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ac00000000000000000000000000000000000000\",\"userpass\":\"$userpass\"}"

# setprice

setprice base rel price (volume max cancel_previous=true base_confs base_nota rel_confs rel_nota)

The setprice method places an order on the orderbook, and it relies on this node acting as a maker, also called a Bob node.

The setprice order is always considered a sell, for internal implementation convenience.

TIP

To prevent a user from making trades in which the transaction fees may end up costing a significant portion of the value of the trade, we have set a lower limit( 0.00777 ) to the value of a trade. See the description of the volume argument for more info.

# Arguments

Structure Type Description
base string the name of the coin the user desires to sell
rel string the name of the coin the user desires to receive
price numeric string or rational the price in rel the user is willing to receive per one unit of the base coin
volume numeric string or rational the maximum amount of base coin available for the order, ignored if max is true; the following values must be greater than or equal to 0.00777:
  • the argument volume
  • the product of the arguments volume and price
max bool MM2 will use the entire coin balance for the order, taking 0.001 coins into reserve to account for fees
cancel_previous bool MM2 will cancel all existing orders for the selected pair by default; set this value to false to prevent this behavior
base_confs number number of required blockchain confirmations for base coin atomic swap transaction; default to base coin configuration if not set
base_nota bool whether dPoW notarization is required for base coin atomic swap transaction; default to base coin configuration if not set
rel_confs number number of required blockchain confirmations for rel coin atomic swap transaction; default to rel coin configuration if not set
rel_nota bool whether dPoW notarization is required for rel coin atomic swap transaction; default to rel coin configuration if not set

# Response

Structure Type Description
result object the resulting order object
result.base string the base coin of the order
result.rel string the rel coin of the order
result.price string (numeric) the expected amount of rel coin to be received per 1 unit of base coin; decimal representation
result.price_rat rational the expected amount of rel coin to be received per 1 unit of base coin; rational representation
result.max_base_vol string (numeric) the maximum volume of base coin available to trade; decimal representation
result.max_base_vol_rat rational the maximum volume of base coin available to trade; rational representation
result.min_base_vol string (numeric) MM2 won't match with other orders that attempt to trade less than min_base_vol; decimal representation
result.min_base_vol_rat rational MM2 won't match with other orders that attempt to trade less than min_base_vol; rational representation
result.created_at number unix timestamp in milliseconds, indicating the order creation time
result.matches object contains the map of ongoing matches with other orders, empty as the order was recently created
result.started_swaps array of strings uuids of swaps that were initiated by the order
result.uuid string uuid of the created order
result.conf_settings.base_confs number number of required blockchain confirmations for base coin atomic swap transaction
result.conf_settings.base_nota bool whether dPoW notarization is required for base coin atomic swap transaction
result.conf_settings.rel_confs number number of required blockchain confirmations for rel coin atomic swap transaction
result.conf_settings.rel_nota bool whether dPoW notarization is required for rel coin atomic swap transaction

# 📌 Examples

# Command (with volume)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"setprice\",\"base\":\"BASE\",\"rel\":\"REL\",\"price\":\"0.9\",\"volume\":\"1\"}"

# Command (max = true)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"setprice\",\"base\":\"BASE\",\"rel\":\"REL\",\"price\":\"0.9\",\"max\":true}"

# Command (rational representation in num-rational crate format)

curl --url "http://127.0.0.1:7783" --data '{
  "userpass":"'$userpass'",
  "method":"setprice",
  "base":"HELLO",
  "rel":"WORLD",
  "volume":[[1,[1]],[1,[1]]],
  "price":[[1,[1]],[1,[1]]]
}'

# Command (rational representation as fraction object)

curl --url "http://127.0.0.1:7783" --data '{
  "userpass":"'$userpass'",
  "method":"setprice",
  "base":"HELLO",
  "rel":"WORLD",
  "volume":{
    "numer":"3",
    "denom":"2"
  },
  "price":{
    "numer":"2",
    "denom":"1"
  }
}'

# Command (with confirmations and notarization settings)

curl --url "http://127.0.0.1:7783" --data '{
  "userpass":"'$userpass'",
  "method":"setprice",
  "base":"HELLO",
  "rel":"WORLD",
  "volume":{
    "numer":"3",
    "denom":"2"
  },
  "price":{
    "numer":"2",
    "denom":"1"
  },
  "base_confs": 2,
  "base_nota": true,
  "rel_confs": 5,
  "rel_nota": false  
}'

# set_required_confirmations

set_required_confirmations coin confirmations

The set_required_confirmations method sets the number of confirmations for which MM2 must wait for the selected coin.

Note

This setting is not persistent. The value must be reset in the coins file on restart.

# Arguments

Structure Type Description
coin string the ticker of the selected coin
confirmations number the number of confirmations to require

# Response

Structure Type Description
result.coin string the coin selected in the request
result.confirmations number the number of confirmations in the request

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"set_required_confirmations\",\"coin\":\"RICK\",\"confirmations\":3}"

# set_requires_notarization

set_requires_notarization coin requires_notarization

The set_requires_notarization method indicates whether MM2 must wait for a dPoW notarization of the given atomic swap transactions.

Note

This setting is not persistent. The value must be reset in the coins file on restart.

# Arguments

Structure Type Description
coin string the ticker of the selected coin
requires_notarization bool whether the node should wait for dPoW notarization of atomic swap transactions

# Response

Structure Type Description
result.coin string the coin selected in the request
result.requires_notarization bool whether the node must wait for a dPoW notarization of the atomic swap transactions

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"set_requires_notarization\",\"coin\":\"RICK\",\"requires_notarization\":true}"

# show_priv_key

show_priv_key coin

The show_priv_key method returns the private key of the specified coin in a format compatible with coin wallets. The output can be used for the importprivkey method (UTXO coins) or as a private key for MyEtherWallet (ETH/ERC20).

# Arguments

Structure Type Description
coin string the name of the coin of the private key to show

# Response

Structure Type Description
coin string the name of the coin
priv_key string the private key of the coin

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"show_priv_key\",\"coin\":\"HELLOWORLD\"}"

# stop

stop()

The stop method stops the MM2 software.

# Arguments

Structure Type Description
(none)

# Response

Structure Type Description
(none)

# unban_pubkeys

unban_pubkeys unban_by

The unban_pubkeys method removes the selected pubkeys from the black list, allowing the node executing the method to receive orders and order matching requests from the unbanned nodes.

# Arguments

Structure Type Description
unban_by object pubkeys matching this condition are removed from the black list
unban_by.type string All to unban all pubkeys; Few to unban several selected pubkeys
cancel_by.data array of strings (hexadecimal) pubkeys that should be removed from the black list; must be present with Few type

# Response

Structure Type Description
result object
result.still_banned map of objects the pubkeys that remain banned
result.unbanned map of objects data of unbanned pubkeys
result.were_not_banned array of strings the pubkeys that were not black listed before the unban_pubkeys call

# 📌 Examples

# Command (All pubkeys)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"unban_pubkeys\",\"unban_by\":{\"type\":\"All\"}}"

# Command (Unban selected pubkeys)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"unban_pubkeys\",\"unban_by\":{\"type\":\"Few\",\"data\":[\"15d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732\",\"16d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732\"]}}"

# validateaddress

validateaddress coin address

The validateaddress method checks if an input string is a valid address of the specified coin.

# Arguments

Structure Type Description
coin string the coin to validate address for
address string the input string to validate

# Response

Structure Type Description
result.is_valid bool whether input string is a valid coin address
result.reason string (optional) the reason why input string is not a valid address

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783/" --data "{"userpass":"$userpass","method":"validateaddress","coin":"RICK","address","RRnMcSeKiLrNdbp91qNVQwwXx5azD4S4CD"}"

# version

version()

The version method returns the MM2 version.

# Arguments

Structure Type Description
(none)

# Response

Structure Type Description
result string the MM2 version

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data "{\"method\":\"version\",\"userpass\":\"$userpass\"}"

# withdraw

withdraw coin to (amount max)

The withdraw method generates, signs, and returns a transaction that transfers the amount of coin to the address indicated in the to argument.

This method generates a raw transaction which should then be broadcast using send_raw_transaction.

# 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
max bool withdraw the maximum available amount
fee.type string type of transaction fee; possible values: UtxoFixed, UtxoPerKbyte, EthGas
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)
fee.gas_price string (numeric) used only when fee type is EthGas; sets the gas price in gwei units
fee.gas number (integer) used only when fee type is EthGas; sets the gas limit for transaction

# Response

Structure Type Description
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)
to array of strings coins are withdrawn to this address; this may contain the my_address address, where change from UTXO coins is sent
my_balance_change string (numeric) the expected balance of change in my_address after the transaction broadcasts
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 MM2 send change to my_address
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 added here
total_amount string (numeric) the total amount of coins transferred
fee_details object the fee details of the generated transaction; this value differs for utxo and ETH/ERC20 coins, check the examples for more details
tx_hash string the hash of the generated transaction
tx_hex string transaction bytes in hexadecimal format; use this value as input for the send_raw_transaction method

# 📌 Examples

# Command (BTC, KMD, and other BTC-based forks)

curl --url "http://127.0.0.1:7783" --data "{\"method\":\"withdraw\",\"coin\":\"KMD\",\"to\":\"RJTYiYeJ8eVvJ53n2YbrVmxWNNMVZjDGLh\",\"amount\":\"10\",\"userpass\":\"$userpass\"}"

# Command (BTC, KMD, and other BTC-based forks, fixed fee)

curl --url "http://127.0.0.1:7783" --data "{\"method\":\"withdraw\",\"coin\":\"RICK\",\"to\":\"R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW\",\"amount\":\"1.0\",\"fee\":{\"type\":\"UtxoFixed\",\"amount\":\"0.1\"}}"

# Command (BTC, KMD, and other BTC-based forks, 1 RICK per Kbyte)

curl --url "http://127.0.0.1:7783" --data "{\"method\":\"withdraw\",\"coin\":\"RICK\",\"to\":\"R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW\",\"amount\":\"1.0\",\"fee\":{\"type\":\"UtxoPerKbyte\",\"amount\":\"1\"}}"

# Command (ETH, ERC20, and other ETH-based forks)

curl --url "http://127.0.0.1:7783" --data "{\"method\":\"withdraw\",\"coin\":\"ETH\",\"to\":\"0xbab36286672fbdc7b250804bf6d14be0df69fa28\",\"amount\":10,\"userpass\":\"$userpass\"}"

# Command (ETH, ERC20, and other ETH-based forks, with gas fee)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"withdraw\",\"coin\":\"$1\",\"to\":\"$2\",\"amount\":\"$3\",\"fee\":{\"type\":\"EthGas\",\"gas_price\":\"3.5\",\"gas\":55000}}"

# Command (max = true)

curl --url "http://127.0.0.1:7783" --data "{\"method\":\"withdraw\",\"coin\":\"ETH\",\"to\":\"0xbab36286672fbdc7b250804bf6d14be0df69fa28\",\"max\":true,\"userpass\":\"$userpass\"}"

←