# DEX API

# Note About Rational Number Type

MM2 now offers the num-rational crate (opens new window) 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}
]"

# active_swaps

active_swaps (include_status)

The active_swaps method returns all the swaps that are currently running on the MM2 node.

# Arguments

Structure Type Description
include_status bool whether to include swap statuses in response; defaults to false

# Response

Structure Type Description
result result object
result.uuids array of strings uuids of currently running swaps
result.statuses object (map) the uuid -> swap status map of currently running swaps; null if include_status is false in the request

# 📌 Examples

# Command (without include_status)

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

# Command (include_status = true)

curl --url "http://127.0.0.1:7783" --data '
{
  "userpass":"'$userpass'",
  "method":"active_swaps",
  "include_status": true
}
'

# all_swaps_uuids_by_filter

all_swaps_uuids_by_filter (my_coin other_coin from_timestamp to_timestamp)

The all_swaps_uuids_by_filter method returns all uuids of swaps that match the selected filters. Please note that all filters (my_coin, from_timestamp, etc.) are combined using logical AND.

# Arguments

Structure Type Description
my_coin string return only swaps that match the swap.my_coin = request.my_coin condition
other_coin string return only swaps that match the swap.other_coin = request.other_coin condition
from_timestamp number (timestamp in seconds) return only swaps that match the swap.started_at >= request.from_timestamp condition
to_timestamp number (timestamp in seconds) return only swaps that match the swap.started_at < request.to_timestamp condition

# Response

Structure Type Description
result result object
result.uuids array of strings uuids of swaps that match the selected filters
result.my_coin string my_coin that was set in request
result.other_coin string other_coin that was set in request
result.from_timestamp number from_timestamp that was set in request
result.to_timestamp number to_timestamp that was set in request
result.records_found number the number of found uuids

# 📌 Examples

# Command (select swaps uuids that have my_coin = RICK and other_coin = MORTY)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"all_swaps_uuids_by_filter\"\"my_coin\":\"RICK\",\"other_coin\":\"MORTY\"}"

# Command (select swaps uuids that have my_coin = RICK and started_at >= 1611705600 (January 27, 2021 0:00:00 GMT))

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"all_swaps_uuids_by_filter\",\"my_coin\":\"RICK\",\"from_timestamp\":1611705600}"

# Command (select swaps uuids that have started_at >= 1611705600 (January 27, 2021 0:00:00 GMT) and started_at < 1611792001 (January 28, 2021 0:00:01 GMT))

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"all_swaps_uuids_by_filter\",\"my_coin\":\"RICK\",\"from_timestamp\":1611705600,\"to_timestamp\":1611792001}"

# ban_pubkey

ban_pubkey pubkey reason

The ban_pubkey method bans the selected pubkey ignoring its order matching messages and preventing its orders from displaying in the orderbook.

TIP

Use the secp256k1 pubkey without prefix for this method input. E.g. if pubkey is 022cd3021a2197361fb70b862c412bc8e44cff6951fa1de45ceabfdd9b4c520420 you should submit 2cd3021a2197361fb70b862c412bc8e44cff6951fa1de45ceabfdd9b4c520420.

# Arguments

Structure Type Description
pubkey string the pubkey to ban
reason string the reason of banning

# Response

Structure Type Description
result string whether the ban was successful

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data '{
  "userpass":"'$userpass'",
  "method": "ban_pubkey",
  "pubkey": "2cd3021a2197361fb70b862c412bc8e44cff6951fa1de45ceabfdd9b4c520420",
  "reason": "test",
}'

# best_orders

best_orders coin action volume

The best_orders method returns the best price orders that can fill the volume for all existing pairs with selected coin.

TIP

The response of this method can contain coins that are not activated on the MM2 instance. Activation will be required to proceed with the trade.

# Arguments

Structure Type Description
coin string the ticker of the coin to get best orders
action string whether to buy or sell the selected coin
volume string the amount of coin user is willing to buy or sell

# Response

Structure Type Description
result object (map) the ticker -> array of order entries map

where order entry has the following structure

Structure Type Description
coin string the ticker of the coin
address string the address offering the trade
price string (decimal) the price the user is willing to buy or sell per one unit of the coin from request
price_rat rational the price in num-rational crate format
price_fraction object (fraction) the price represented as an object
maxvolume string (decimal) the maximum amount of base 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
min_volume string (decimal) the minimum amount of base coin the offer provider is willing to sell
min_volume_rat rational the min volume in num-rational crate format
min_volume_fraction object (rational) the min 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 (deprecated)
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
base_max_volume string (decimal) the maximum amount of base coin the offer provider is willing to buy or sell
base_max_volume_rat rational the base_max_volume in num-rational crate format
base_max_volume_fraction object (rational) the base_max_volume represented as an object
base_min_volume string (decimal) the minimum amount of base coin the offer provider is willing to buy or sell
base_min_volume_rat rational the base_min_volume in num-rational crate format
base_min_volume_fraction object (rational) the base_min_volume represented as an object
rel_max_volume string (decimal) the maximum amount of rel coin the offer provider is willing to buy or sell
rel_max_volume_rat rational the rel_max_volume max volume in num-rational crate format
rel_max_volume_fraction object (rational) the rel_max_volume max volume represented as an object
rel_min_volume string (decimal) the minimum amount of rel coin the offer provider is willing to buy or sell
rel_min_volume_rat rational the rel_min_volume in num-rational crate format
rel_min_volume_fraction object (rational) the rel_min_volume represented as an object

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data '{
  "userpass":"'$userpass'",
  "method": "best_orders",
  "coin": "RICK",
  "action": "buy",
  "volume": "1"
}'

# buy

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

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 Minimum transaction amount (dust) TAKER COIN or 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 to the value of a trade. See the description of the volume and min_volume arguments 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 the min_trading_vol of the corresponding coin:
  • the argument volume
  • the product of the arguments volume and price
min_volume numeric string or rational (optional) the amount of base coin that will be used as min_volume of GoodTillCancelled order after conversion to maker; the following values must be greater than or equal to the min_trading_vol of the corresponding coin:
  • the argument min_volume
  • the product of the arguments min_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_all_orders 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 and QRC20 tokens 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 (opens new window) 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 (opens new window)

# 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.

# Using AtomicDEX Software on an Qtum Network

The following information can assist the user/developer in using QRC20 tokens with AtomicDEX software on the Qtum network:

To use AtomicDEX software on another Qtum-based network, deploy the Etomic swap contract code from the repository linked below. Use of this code requires a Qtum node setup.

Link to repository code for Ethereum-based networks (opens new window)

TIP

Smart contract deployment is similar to creating QRC20 tokens (opens new window).

# 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
swap_contract_address string (required for QRC20 only) address of etomic swap smart contract

# 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; does not include unspendable_balance
unspendable_balance string (numeric) the coin balance that is unspendable at the moment (e.g. if the address has immature UTXOs)
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
mature_confirmations number (optional) the number of coinbase transaction confirmations required to become mature; UTXO coins only
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}"

# Command (For QRC20 tokens)

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

# 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.

TIP

To enable QRC20 token using the enable method, make sure the Qtum blockchain daemon is configured correctly. MM2 requires the following options to be in the qtum.conf:

logevents=1
txindex=1
addressindex=1

If a QRC20 token is based on Qtum testnet/regtest, please make sure that the coins file has the property "network": "testnet" or "network": "regtest". See the example below.

{
  "coin":"QRC20",
  "pubtype":120,
  "p2shtype":50,
  "wiftype":128,
  "segwit":true,
  "txfee":0,
  "mm2":1,
  "mature_confirmations":500,
  "required_confirmations":1,
  "network":"testnet",
  "protocol":{
    "type":"QRC20",
    "protocol_data":{
      "platform":"tQTUM",
      "contract_address":"0xd362e096e873eb7907e205fadc6175c6fec7bc44"
    }
  }
}

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. (opens new window)

Link to repository code for Ethereum-based networks (opens new window)

# 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 (opens new window); MM2 uses eth_gasPrice RPC API (opens new window) 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; does not include unspendable_balance
unspendable_balance string (numeric) the coin balance that is unspendable at the moment (e.g. if the address has immature UTXOs)
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
mature_confirmations number (optional) the number of coinbase transaction confirmations required to become mature; UTXO coins only
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 (deprecated)

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. This aspect is currently under development.

TIP

This function is deprecated. Please consider using trade_preimage v2.0 instead.

Note

To send QRC20 Maker/Taker payment, you may need to allow the Etomic Swap (opens new window) smart contract to withdraw amounts from your account using the approve (opens new window) call. In the worst case, you should call the approve twice (reduce allowance to 0 and set it to a required value) before the erc20Payment (opens new window) is called.

Gas Limit 100000 and Gas Price 40 are sufficient for one smart contract call.

As a result, the value returned by the get_trade_fee for a QRC20 token includes gas fee 3 * 100000 * 40 = 12000000 that can be used in the worst case.

# 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":{"tx_hash":"0c07be4dda88d8d75374496aa0f27e12f55363ce8d558cb5feecc828545e5f87","tx_hex":"0400008085202f890146b98696761d5e8667ffd665b73e13a8400baab4b22230a7ede0e4708597ee9c000000006a473044022077acb70e5940dfe789faa77e72b34f098abbf0974ea94a0380db157e243965230220614ec4966db0a122b0e7c23aa0707459b3b4f8241bb630c635cf6e943e96362e012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff02f0da0700000000001976a914ca1e04745e8ca0c60d8c5881531d51bec470743f88ac68630700000000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ac5e3a835d000000000000000000000000000000"},"type":"TakerFeeSent"},"timestamp":1568881250689},{"event":{"data":{"tx_hash":"31d97b3359bdbdfbd241e7706c90691e4d7c0b7abd27f2b22121be7f71c5fd06","tx_hex":"0400008085202f8901b4679094d4bf74f52c9004107cb9641a658213d5e9950e42a8805824e801ffc7010000006b483045022100b2e49f8bdc5a4b6c404e10150872dbec89a46deb13a837d3251c0299fe1066ca022012cbe6663106f92aefce88238b25b53aadd3522df8290ced869c3cc23559cc23012102631dcf1d4b1b693aa8c2751afc68e4794b1e5996566cfc701a663f8b7bbbe640ffffffff0200a3e1110000000017a91476e1998b0cd18da5f128e5bb695c36fbe6d957e98764c987c9bf0000001976a91464ae8510aac9546d5e7704e31ce177451386455588ac753a835d000000000000000000000000000000"},"type":"MakerPaymentReceived"},"timestamp":1568881291571},{"event":{"type":"MakerPaymentWaitConfirmStarted"},"timestamp":1568881291571},{"event":{"type":"MakerPaymentValidatedAndConfirmed"},"timestamp":1568881291985},{"event":{"data":{"tx_hash":"95926ab204049edeadb370c17a1168d9d79ee5747d8d832f73cfddf1c74f3961","tx_hex":"0400008085202f8902875f5e5428c8ecfeb58c558dce6353f5127ef2a06a497453d7d888da4dbe070c010000006a4730440220416059356dc6dde0ddbee206e456698d7e54c3afa92132ecbf332e8c937e5383022068a41d9c208e8812204d4b0d21749b2684d0eea513467295e359e03c5132e719012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff46b98696761d5e8667ffd665b73e13a8400baab4b22230a7ede0e4708597ee9c010000006b483045022100a990c798d0f96fd5ff7029fd5318f3c742837400d9f09a002e7f5bb1aeaf4e5a0220517dbc16713411e5c99bb0172f295a54c97aaf4d64de145eb3c5fa0fc38b67ff012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff020084d7170000000017a9144d57b4930e6c86493034f17aa05464773625de1c877bd0de03010000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ac8c3a835d000000000000000000000000000000"},"type":"TakerPaymentSent"},"timestamp":1568881296904},{"event":{"data":{"secret":"fb968d5460399f20ffd09906dc8f65c21fbb5cb8077a8e6d7126d0526586ca96","transaction":{"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.*.type string the type of the ban; possible values: Manual or FailedSwap
result.*.caused_by_swap string (optional) the uuid of the swap that triggered the ban; present only for the FailedSwap type
result.*.caused_by_event object (optional) the swap event that triggered the ban; present only for the FailedSwap type
result.*.reason string (optional) the reason for the Manual ban

# 📌 Examples

# Command

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

# min_trading_vol

min_trading_vol coin

The min_trading_vol method returns the minimum required volume for buy/sell/setprice methods for the selected coin.

# Arguments

Structure Type Description
coin string the name of the coin to retrieve the minimum trading volume

# Response

Structure Type Description
result object result object
result.coin string the coin ticker from the request
result.min_trading_vol string (decimal) the minimum trading volume threshold in decimal representation
result.min_trading_vol_rat rational the minimum trading volume threshold in rational representation
result.min_trading_vol_fraction fraction the minimum trading volume threshold in fraction representation

# 📌 Examples

# Command

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

# 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
result 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; does not include unspendable_balance
unspendable_balance string (numeric) the coin balance that is unspendable at the moment (e.g. if the address has immature UTXOs)
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

my_recent_swaps (from_uuid page_number=1 limit=10 my_coin other_coin from_timestamp to_timestamp)

The my_recent_swaps method returns the data of the most recent atomic swaps executed by the MM2 node. Please note that all filters (my_coin, from_timestamp, etc.) are combined using logical AND.

# Arguments

Structure Type Description
limit number limits the number of returned swaps. The default is 10.
from_uuid string MM2 will skip records until this uuid, skipping the from_uuid as well; The from_uuid approach is convenient for infinite scrolling implementation
page_number number MM2 will return limit swaps from the selected page; This param will be ignored if from_uuid is set.
my_coin string return only swaps that match the swap.my_coin = request.my_coin condition
other_coin string return only swaps that match the swap.other_coin = request.other_coin condition
from_timestamp number (timestamp in seconds) return only swaps that match the swap.started_at >= request.from_timestamp condition
to_timestamp number (timestamp in seconds) return only swaps that match the swap.started_at < request.to_timestamp condition

# 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 or (page_number - 1) * limit; the value is 0 if from_uuid or page_number were not set or page_number is 1)
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 with the selected filters
page_number number the page_number that was set in the request; if both page_number and from_uuid are not set in request it will default to 1; if from_uuid is present in request this value will be always null
total_pages number total pages available with the selected filters and limit
found_records number the number of returned swaps

# 📌 Examples

# Command (limit + from_uuid)

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

# Command (limit + page_number)

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

# Command (select swaps that have my_coin = RICK and other_coin = MORTY)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"my_recent_swaps\",\"limit\":2,\"my_coin\":\"RICK\",\"other_coin\":\"MORTY\"}"

# Command (select swaps that have my_coin = RICK and started_at >= 1611705600 (January 27, 2021 0:00:00 GMT))

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"my_recent_swaps\",\"limit\":2,\"my_coin\":\"RICK\",\"from_timestamp\":1611705600}"

# Command (select swaps that have started_at >= 1611705600 (January 27, 2021 0:00:00 GMT) and started_at < 1611792001 (January 28, 2021 0:00:01 GMT))

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"my_recent_swaps\",\"limit\":2,\"my_coin\":\"RICK\",\"from_timestamp\":1611705600,\"to_timestamp\":1611792001}"

# 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
my_order_uuid string (uuid, optional) the uuid of order that matched to start the swap

# 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

my_tx_history (from_id limit=10 max=false page_number)

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
page_number number MM2 will return limit swaps from the selected page; This param will be ignored if from_uuid is set.

# 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
page_number number the page_number that was set in the request
total_pages number total pages available with the selected limit
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 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

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

# Response

Structure Type Description
asks array of Order an array of objects containing outstanding asks
bids array of Order an array of objects containing outstanding bids
numbids number the number of outstanding bids
biddepth number deprecated
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)
total_asks_base_vol string (decimal) the base volumes sum of all asks
total_asks_base_vol_rat rational the total_asks_base_vol in num-rational crate format
total_asks_base_vol_fraction fraction the total_asks_base_vol represented as an object
total_asks_rel_vol string (decimal) the rel volumes sum of all asks
total_asks_rel_vol_rat rational the total_asks_rel_vol in num-rational crate format
total_asks_rel_vol_fraction fraction the total_asks_rel_vol represented as an object
total_bids_base_vol string (decimal) the base volumes sum of all bids
total_bids_base_vol_rat rational the total_bids_base_vol in num-rational crate format
total_bids_base_vol_fraction fraction the total_bids_base_vol represented as an object
total_bids_rel_vol string (decimal) the rel volumes sum of all bids
total_bids_rel_vol_rat rational the total_bids_rel_vol in num-rational crate format
total_bids_rel_vol_fraction fraction the total_bids_rel_vol represented as an object

Where Order object structure is as follows

Structure Type Description
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
min_volume string (decimal) the minimum amount of base coin the offer provider is willing to sell
min_volume_rat rational the min volume in num-rational crate format
min_volume_fraction object (rational) the min 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
uuid string the uuid of order
is_mine bool whether the order is placed by me
base_max_volume string (decimal) the maximum amount of base coin the offer provider is willing to buy or sell
base_max_volume_rat rational the base max volume in num-rational crate format
base_max_volume_fraction object (rational) the base max volume represented as an object
base_min_volume string (decimal) the minimum amount of base coin the offer provider is willing to buy or sell
base_min_volume_rat rational the base min volume in num-rational crate format
base_min_volume_fraction object (rational) the base min volume represented as an object
rel_max_volume string (decimal) the maximum amount of rel coin the offer provider is willing to buy or sell
rel_max_volume_rat rational the rel max volume in num-rational crate format
rel_max_volume_fraction object (rational) the rel max volume represented as an object
rel_min_volume string (decimal) the minimum amount of rel coin the offer provider is willing to buy or sell
rel_min_volume_rat rational the rel min volume in num-rational crate format
rel_min_volume_fraction object (rational) the rel min volume represented as an object
base_max_volume_aggr string (decimal) the base max volume aggregated at the price level; the sum of base volumes of the current order and all orders with a worse price
base_max_volume_aggr_rat rational the base_max_volume_aggr in num-rational crate format
base_max_volume_aggr_fraction object (rational) the base_max_volume_aggr represented as an object
rel_max_volume_aggr string (decimal) the rel max volume aggregated at the price level; the sum of rel volumes of the current order and all orders with a worse price
rel_max_volume_aggr_rat rational the rel_max_volume_aggr in num-rational crate format
rel_max_volume_aggr_fraction object (rational) the rel_max_volume_aggr represented as an object

# 📌 Examples

# Command

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

# orderbook_depth

orderbook_depth pairs

The orderbook_depth method returns the number of asks and bids for the specified trading pairs.

# Arguments

Structure Type Description
pairs array an array of trading pairs

# Response

Important

The pairs in the response are not guaranteed to be in the order of pairs in the request.

Structure Type Description
result array of PairDepth an array of pair depth objects

Where PairDepth object structure is as follows

Structure Type Description
pair array of 2 strings the orderbook pair
depth.asks number the number of asks
depth.bids number the number of bids

# 📌 Examples

# Command

curl --url "http://127.0.0.1:7783" --data '
{
  "userpass":"'$userpass'",
  "method":"orderbook_depth",
  "pairs":[["RICK","MORTY"],["BTC","KMD"],["DOGE","KMD"]]
}
'

# orders_history_by_filter

orders_history_by_filter (order_type initial_action base rel from_price to_price from_volume to_volume from_timestamp to_timestamp was_taker status include_details)

The orders_history_by_filter method returns all orders whether active or inactive that match the selected filters. Please note that all filters (order_type initial_action, etc.) are combined using logical AND.

# Arguments

Structure Type Description
order_type string return only orders that match the request.order_type; order_type can be "Maker" or "Taker"
initial_action string return only orders that match the request.initial_action; initial_action can be "Sell" or "Buy". Note that maker order initial_action is considered "Sell"
base string return only orders that match the order.base = request.base condition
rel string return only orders that match the order.rel = request.rel condition
from_price numeric string or rational return only orders that match the order.price >= request.from_price condition
to_price numeric string or rational return only orders that match the order.price <= request.to_price condition
from_volume numeric string or rational return only orders that match the order.volume >= request.from_volume condition
to_volume numeric string or rational return only orders that match the order.volume <= request.to_volume condition
from_timestamp number (timestamp in seconds) return only orders that match the order.created_at >= request.from_timestamp condition
to_timestamp number (timestamp in seconds) return only orders that match the order.created_at <= request.to_timestamp condition
was_taker bool return only GoodTillCancelled orders that got converted from taker to maker
status string return only orders that match the request.status; status can be:
  • For active maker order Created, Updated
  • For active taker order Created
  • For inactive maker order Fulfilled, Insufficient Balance, Cancelled
  • For inactive taker order Fulfilled, Timed Out, Cancelled
include_details bool whether to include complete order details in response; defaults to false

# Response

Structure Type Description
result result object
result.orders array of order objects array of orders that match the selected filters with minimal details
result.orders.uuid string uuid of the order
result.orders.order_type string type of the order; "Maker" or "Taker"
result.orders.base string base coin of the order
result.orders.rel string rel coin of the order
result.orders.price number (decimal) price of the order
result.orders.volume number (decimal) volume of the order
result.orders.created_at number unix timestamp in milliseconds, indicating the order creation time
result.orders.last_updated number unix timestamp in milliseconds, indicating the time the order was last updated
result.orders.was_taker number 1 if the order was a "Taker" order that got converted to "Maker", 0 otherwise
result.orders.status string status of the Order
result.details array of order details objects array of complete order details for every order that matches the selected filters; returns [] if include_details is false or not included in the request.
result.details.type string type of the order; "Maker" or "Taker"
result.details.order object the order details object
result.details.order.changes_history array array containing previous details that was changed for this order as objects, available only for maker orders that was updated with update_maker_order method
found_records number the number of returned orders
warnings array array containing warnings objects
warnings.uuid string uuid of the order that produced this warning
warnings.warning string warning message

# 📌 Examples

# Command (select orders from history that have order_type = Taker and initial_action = Buy)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"orders_history_by_filter\",\"order_type\":\"Taker\",\"initial_action\":\"Buy\"}"

# Command (select orders from history that have base = RICK and rel = MORTY)

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

# Command (select orders from history that have base = RICK and price >= 1 and volume <= 1)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"orders_history_by_filter\",\"base\":\"RICK\",\"from_price\":1,\"to_volume\":1}"

# Command (select orders from history that was_taker and created_at >= 1611705600 (January 27, 2021 0:00:00 GMT))

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"orders_history_by_filter\",\"was_taker\":true,\"from_timestamp\":1611705600}"

# Command (select orders with details from history that was cancelled because it timed-out)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"orders_history_by_filter\",\"status\":\"Timed Out\",\"include_details\":true}"

# 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 Minimum transaction amount (dust) TAKER COIN or 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 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 the min_trading_vol of the corresponding coin:
  • the argument volume
  • the product of the arguments volume and price
min_volume numeric string or rational (optional) the amount of base coin that will be used as min_volume of GoodTillCancelled order after conversion to maker; the following values must be greater than or equal to the min_trading_vol of the corresponding coin:
  • the argument min_volume
  • the product of the arguments min_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 min_volume)

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 to the value of a trade. See the description of the volume and min_volume arguments 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 the min_trading_vol of the corresponding coin:
  • the argument volume
  • the product of the arguments volume and price
min_volume numeric string or rational the minimum amount of base coin available for the order; it must be less or equal than volume param; the following values must be greater than or equal to the min_trading_vol of the corresponding coin:
  • the argument min_volume
  • the product of the arguments min_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.updated_at number unix timestamp in milliseconds, indicating the order update 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 min_volume)

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"
  },  
  "min_volume":"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)

# trade_preimage (deprecated)

trade_preimage

The trade_preimage method returns the approximate fee amounts that are paid per the whole swap. Depending on the parameters, the function returns different results:

  • If the swap_method is buy or sell, then the result will include the taker_fee and the fee_to_send_taker_fee. The taker_fee amount is paid from the base coin balance if the swap_method is sell, else it is paid from the rel coin balance;
  • If the max field is true, then the result will include the volume.

Note

This method can be used instead of max_taker_vol, if the max field is true and the swap_method is buy or sell. Use the resulting volume as an argument of the buy or sell requests.

Important

Use the trade_preimage request with max = true and swap_method = "setprice" arguments to approximate the fee amounts only. Do not use the resulting volume as an argument of the setprice.

TIP

This function is deprecated. Please consider using trade_preimage v2.0 instead.

# Arguments

Structure Type Description
base string the base currency of the request
rel string the rel currency of the request
swap_method string the name of the method whose preimage is requested. Possible values: buy, sell, setprice
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 (optional) the amount the user is willing to trade; ignored if max = true and swap_method = setprice, otherwise, it must be set
max bool (optional) whether to return the maximum available volume for setprice method; must not be set or false if swap_method is buy or sell

# Response

Structure Type Description
result object an object containing the relevant information
result.base_coin_fee object (ExtendedFeeInfo) the approximate miner fee is paid per the whole swap concerning the base coin
result.rel_coin_fee object (ExtendedFeeInfo) the approximate miner fee is paid per the whole swap concerning the rel coin
result.volume string (numeric, optional) the max available volume that can be traded (in decimal representation); empty if the max argument is missing or false
result.volume_rat rational (optional) the max available volume that can be traded (in rational representation); empty if the max argument is missing or false
result.volume_fraction fraction (optional) the max available volume that can be traded (in fraction representation); empty if the max argument is missing or false
result.taker_fee object (optional, ExtendedFeeInfo) the dex fee to be paid by Taker; empty if swap_method is setprice
result.fee_to_send_taker_fee object (optional, ExtendedFeeInfo) the approximate miner fee is paid to send the dex fee; empty if swap_method is setprice
result.total_fees array of TotalFeeInfo objects each element is a sum of fees required to be paid from user's balance of corresponding ExtendedFeeInfo.coin; the elements are unique by coin

The ExtendedFeeInfo structure is as follows:

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

The TotalFeeInfo structure is as follows:

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

# 📌 Examples

# Command (setprice)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"trade_preimage\",\"base\":\"RICK\",\"rel\":\"BTC\",\"price\":\"1\",\"volume\":\"0.1\",\"swap_method\":\"setprice\"}"

# Command (buy)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"trade_preimage\",\"base\":\"BTC\",\"rel\":\"RICK\",\"price\":\"1\",\"volume\":\"0.1\",\"swap_method\":\"buy\"}"

# Command (ERC20 and QRC20)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"trade_preimage\",\"base\":\"BAT\",\"rel\":\"QC\",\"price\":\"1\",\"volume\":\"2.21363478\",\"swap_method\":\"setprice\"}"

# 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\"]}}"

# update_maker_order

update_maker_order uuid (new_price volume_delta max base_confs base_nota rel_confs rel_nota min_volume)

The update_maker_order method updates an active order on the orderbook created before by setprice, and it relies on this node acting as a maker, also called a Bob node.

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 to the value of a trade. See the description of the volume_delta and min_volume arguments for more info.

# Arguments

Structure Type Description
uuid string the uuid of the order the user desires to update
new_price numeric string or rational (optional) the price in rel the user is willing to receive per one unit of the base coin
volume_delta numeric string or rational (optional) volume added to or subtracted from the max_base_vol of the order to be updated, resulting in the new volume which is 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 the min_trading_vol of the corresponding coin:
  • the new volume which is the max_base_vol of the order to be updated plus volume_delta
  • the product of the new volume and the argument new_price
min_volume numeric string or rational (optional) the minimum amount of base coin available for the order; it must be less or equal than the new volume; the following values must be greater than or equal to the min_trading_vol of the corresponding coin:
  • the argument min_volume
  • the product of the arguments min_volume and new_price
max bool (optional) MM2 will use the entire coin balance for the order, taking 0.001 coins into reserve to account for fees
base_confs number (optional) number of required blockchain confirmations for base coin atomic swap transaction; default to base coin configuration if not set
base_nota bool (optional) whether dPoW notarization is required for base coin atomic swap transaction; default to base coin configuration if not set
rel_confs number (optional) number of required blockchain confirmations for rel coin atomic swap transaction; default to rel coin configuration if not set
rel_nota bool (optional) 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.updated_at number unix timestamp in milliseconds, indicating the order update 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 updated 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\":\"update_maker_order\",\"uuid\":\"6a242691-6c05-474a-85c1-5b3f42278f41\",\"new_price\":\"0.9\",\"volume_delta\":\"1\"}"

# Command (max = true)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"update_maker_order\",\"uuid\":\"6a242691-6c05-474a-85c1-5b3f42278f41\",\"new_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":"update_maker_order",
  "uuid":"6a242691-6c05-474a-85c1-5b3f42278f41",
  "volume_delta":[[1,[1]],[1,[1]]],
  "new_price":[[1,[1]],[1,[1]]]
}'

# Command (rational representation as fraction object)

curl --url "http://127.0.0.1:7783" --data '{
  "userpass":"'$userpass'",
  "method":"update_maker_order",
  "uuid":"6a242691-6c05-474a-85c1-5b3f42278f41",
  "volume_delta":{
    "numer":"3",
    "denom":"2"
  },
  "new_price":{
    "numer":"2",
    "denom":"1"
  }
}'

# Command (with min_volume)

curl --url "http://127.0.0.1:7783" --data '{
  "userpass":"'$userpass'",
  "method":"update_maker_order",
  "uuid":"6a242691-6c05-474a-85c1-5b3f42278f41",
  "volume_delta":{
    "numer":"3",
    "denom":"2"
  },
  "new_price":{
    "numer":"2",
    "denom":"1"
  },  
  "min_volume":"1"
}'

# Command (with confirmations and notarization settings)

curl --url "http://127.0.0.1:7783" --data '{
  "userpass":"'$userpass'",
  "method":"update_maker_order",
  "uuid":"6a242691-6c05-474a-85c1-5b3f42278f41",
  "volume_delta":{
    "numer":"3",
    "denom":"2"
  },
  "new_price":{
    "numer":"2",
    "denom":"1"
  },
  "base_confs": 2,
  "base_nota": true,
  "rel_confs": 5,
  "rel_nota": false  
}'

# 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
coin string the name of the coin the user wants to withdraw
kmd_rewards object (optional) an object containing information about accrued rewards; always exists if the coin is KMD
kmd_rewards.amount string (numeric, optional) the amount of accrued rewards
kmd_rewards.claimed_by_me bool (optional) whether the rewards been claimed by me

# 📌 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\"}"

# Command (QRC20)

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

# Command (QRC20, with gas fee)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"withdraw\",\"coin\":\"QRC20\",\"to\":\"qHmJ3KA6ZAjR9wGjpFASn4gtUSeFAqdZgs\",\"amount\":10,\"fee\":{\"type\":\"Qrc20Gas\",\"gas_limit\":250000,\"gas_price\":40}}"

←