DEX API

Note About Rational Number Type

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

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

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

The number is represented in JSON as follows:

[[1,[0,1]],[1,[1]]]

The first item, [1,[0,1]], is the numerator.

The second item, [1,[1]], is the denominator.

The numerator and denominator are BigInteger numbers represented as a sign and 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

buy

buy base rel price volume

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

Buy and sell methods always create the taker order first. Therefore, you must pay an additional 1/777 fee of the trade amount during the swap when taking liquidity from the market. If your 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.

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

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 will be received if the order matches (in decimal representation)
result.base_amount_rat rational the resulting amount of base currency that will be 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 will be spent to buy the base_amount (according to price, in decimal representation)
result.rel_amount_rat rational the maximum amount of rel coin that will be spent 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 will allow the user to choose the P2P node that will be 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

📌 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)

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

cancel_all_orders

cancel_order cancel_by

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

Arguments

Structure Type Description
cancel_by object orders matching this condition are cancelled
cancel_by.type string All to cancel all orders; Pair to cancel all orders for specific coin pairs; Coin to cancel all orders for a specific coin
cancel_by.data object additional data the cancel condition; present with Pair and Coin types
cancel_by.data.base string base coin of the pair; Pair type only
cancel_by.data.rel string rel coin of the pair; Pair type only
cancel_by.data.ticker string order will be 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\"}"

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.

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

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

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

Notes on the MM2 Parameter

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

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

  • 0 = non-functioning
  • 1 = functioning

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

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

Guide to Submitting Coin Test Results

Examples of the Parameter Settings

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

"mm2" : 1

For terminal interface examples, see the examples section below.

Arguments

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

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
locked_by_swaps string (numeric) the number of coins locked by ongoing swaps. There is a time gap between the start of the swap and the sending of the actual swap transaction (MM2 locks the coins virtually to prevent the user from using the same funds across several ongoing swaps)
coin string the ticker of the enabled coin
required_confirmations number MM2 will wait for the this number of transaction confirmations during the swap
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}"

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.

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

Notes on the mm2 Parameter

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

Link to mm2 explanatory section

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

Using AtomicDEX Software on an ETH-Based Network

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

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

Link to repository code for Ethereum-based networks

Arguments

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

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
locked_by_swaps string (numeric) the number of coins locked by ongoing swaps. There is a time gap between the start of the swap and the sending of the actual swap transaction (MM2 locks the coins virtually to prevent the user from using the same funds across several ongoing swaps)
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
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 (for Ethereum and ERC20-based blockchains)

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\"enable\",\"coin\":\"ETH\",\"urls\":[\"http://195.201.0.6:8545\"],\"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://195.201.0.6:8545\"],\"swap_contract_address\":\"0x7Bc1bBDD6A0a722fC9bffC49c921B685ECB84b94\",\"gas_station_url\":\"https://ethgasstation.info/json/ethgasAPI.json\"}"

Command (With mm2 argument)

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

get_enabled_coins

get_enabled_coins

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

Arguments

Structure Type Description
(none)

Response

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

📌 Examples

Command

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

get_trade_fee

get_trade_fee coin

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

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

Arguments

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

Response

Structure Type Description
result object an object containing the relevant information
result.coin string the fee will be 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

📌 Examples

Command (BTC)

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

Command (ETH)

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

Command (ERC20)

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

help

help()

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

Arguments

Structure Type Description
(none)

Response

Structure Type Description
(returns the full docs in terminal)

import_swaps

import_swaps swaps

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

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

Arguments

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

Response

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

📌 Examples

Command

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

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
locked_by_swaps string (numeric) the number of coins locked by ongoing swaps. There is a time gap between the start of the swap and the sending of the actual swap transaction (MM2 locks the coins virtually to prevent the user from using the same funds across several ongoing swaps)
coin string the name of the coin

📌 Examples

Command

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

my_orders

my_orders()

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

Arguments

Structure Type Description
(none)

Response

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

📌 Examples

Command

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

my_recent_swaps

(from_uuid limit=10)

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

Arguments

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

Response

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

📌 Examples

Command

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

my_swap_status

uuid

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

Arguments

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

Response

Structure Type Description
events array of objects the events that occurred during the swap
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

📌 Examples

Command

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

my_tx_history

(from_id limit=10)

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

Arguments

Structure Type Description
coin string the name of the coin for the history request
limit number limits the number of returned transactions
from_id string MM2 will skip records until it reaches this ID, skipping the from_id as well; track the internal_id of the last displayed transaction to find the value of this field for the next page

Response

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

📌 Examples

Command

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

order_status

order_status uuid

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

Arguments

Structure Type Description
uuid string uuid of order to display

Response

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

📌 Examples

Command

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

orderbook

orderbook base rel (duration=number)

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

Arguments

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

Response

Structure Type Description
bids array an array of objects containing outstanding bids
numbids number the number of outstanding bids
biddepth number deprecated
asks array an array of objects containing outstanding asks
coin string the name of the base coin; the user desires this
address string the address offering the trade
price string (decimal) the price in rel the user is willing to pay per one unit of the base coin
price_rat rational the price in rational representation
maxvolume string (decimal) the maximum amount of base coin the offer provider is willing to sell
max_volume_rat rational the max volume in rational representation
pubkey string the pubkey of the offer provider
age number the age of the offer
zcredits number the zeroconf deposit amount
numasks number the total number of asks
askdepth number the depth of the ask requests
base string the name of the coin the user desires to receive
rel string the name of the coin the user will trade
timestamp number the timestamp of the orderbook request
netid number the id of the network on which the request is made (default is 0)

📌 Examples

Command

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

recover_funds_of_swap

recover_funds_of_swap uuid

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

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

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

Arguments

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

Response

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

📌 Examples

Command

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

sell

sell base rel price volume

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

Buy and sell methods always create the taker order first. Therefore, you must pay an additional 1/777 fee of the trade amount during the swap when taking liquidity from market. If your 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.

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

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 will be sold if the order matches (in decimal representation)
result.base_amount_rat rational the resulting amount of base currency that will be 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 will be received 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 will be received 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 will allow the user to choose the P2P node that is be eligible to match with the request. This value defaults to "zero pubkey", which means that anyone can match
result.sender_pubkey string the public key of our node
result.uuid string the request uuid

📌 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)

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

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)

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.

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

Response

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

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

set_required_confirmations

set_required_confirmations coin confirmations

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

Note

Please note that 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}"

stop

stop()

The stop method stops the MM2 software.

Arguments

Structure Type Description
(none)

Response

Structure Type Description
(none)

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 will be 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 will be 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 will be withdrawn to this address; this may contain the my_address address, where change from UTXO coins is sent
my_balance_change string (numeric) the expected balance of change in my_address after the transaction broadcasts
received_by_me string (numeric) the amount of coins received by my_address after the transaction broadcasts; the value may be above zero when the transaction requires that MM2 send change to my_address
spent_by_me string (numeric) the amount of coins spent by my_address; this value differ from the request amount, as the transaction fee is added here
total_amount string (numeric) the total amount of coins transferred
fee_details object the fee details of the generated transaction; this value differs for utxo and ETH/ERC20 coins, check the examples for more details
tx_hash string the hash of the generated transaction
tx_hex string transaction bytes in hexadecimal format; use this value as input for the send_raw_transaction method

📌 Examples

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

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

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

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

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

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

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

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

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

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

Command (max = true)

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