# 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.
TIP
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.
TIP
Electrum mode is available for utxo-based coins only; this includes Bitcoin and Bitcoin-based forks. Electrum mode is not available for ETH/ERC20.
The electrum method enables a coin by connecting the user's software instance to the coin blockchain using electrum technology (e.g. lite mode). This allows the user to avoid syncing the entire blockchain to their local machine.
Each coin can be enabled only once, and in either Electrum or Native mode. The DEX software does not allow a coin to be active in both modes at once.
# Notes on the MM2 Parameter
For each coin, Komodo software requires the user/developer to set the mm2 parameter. This can be achieved either in the coins for more details), or via the electrum and enable methods.
The value of the mm2 parameter informs the software as to whether the coin is expected to function.
0=non-functioning1=functioning
TIP
GUI software developers may refer to the coins file in this link for the default coin json configuration.
Volunteers are welcome to test coins with AtomicDEX software at any time. After testing a coin, please create a pull request with the desired coin configuration and successful swap details using the guide linked below.
Guide to Submitting Coin Test Results
# Examples of the Parameter Settings
Set the value of the mm2 parameter in the coins file as follows:
"mm2" : 1
For terminal interface examples, see the examples section below.
# Arguments
| Structure | Type | Description |
|---|---|---|
| coin | string | the name of the coin you want to enable |
| servers | array of objects | the list of Electrum servers to which you want to connect |
| servers.url | string | server url |
| servers.protocol | string | the transport protocol that MM2 will use to connect to the server. Possible values: TCP, SSL. Default value: TCP |
| servers.disable_cert_verification | bool | when set to true, this disables server SSL/TLS certificate verification (e.g. to use self-signed certificate). Default value is false. Use at your own risk |
| mm2 | number (required if not set in the coins file) | this property informs the AtomicDEX software as to whether the coin is expected to function; accepted values are either 0 or 1 |
| tx_history | bool | whether the node should enable tx_history preloading as a background process; this must be set to true if you plan to use the my_tx_history API |
# 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.
Note
The MM2 node's coin address needs to be imported manually into the coin daemon using the importaddress call.
ETH/ERC20 coins are also enabled by the enable method, but a local installation of an ETH node is not required.
# Notes on the mm2 Parameter
Please refer to the mm2 explanatory section in the electrum method for information about setting the mm2 parameter and testing new coins.
Link to mm2 explanatory section
For terminal interface examples using the mm2 parameter with the enable method, see the examples section below.
# Using AtomicDEX Software on an ETH-Based Network
The following information can assist the user/developer in connecting AtomicDEX software to the Ethereum network:
- Swap smart contract on the ETH mainnet: 0x8500AFc0bc5214728082163326C2FF0C73f4a871
- Main-net nodes maintained by the Komodo team: http://eth1.cipig.net:8555, http://eth2.cipig.net:8555, http://eth3.cipig.net:8555
- Swap smart contract on the Ropsten testnet: 0x7Bc1bBDD6A0a722fC9bffC49c921B685ECB84b94
- Ropsten node maintained by the Komodo team: http://195.201.0.6:8545
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 |
| events.type | string | an event type; the list of event types with their data structure is available below |
| events.data | object | additional data of the event; the list of events with their data structure is available below |
| success_events | array of strings | a list of events that gained a success swap state; the contents are listed in the order in which they should occur in the events array |
| error_events | array of strings | a list of events that fell into an error swap state; if at least 1 of the events happens, the swap is considered a failure |
| type | string | whether the node acted as a market Maker or Taker |
| uuid | string | swap uuid |
| gui | string (optional) | information about gui; copied from MM2 configuration |
| mm_version | string (optional) | MM2 version |
| maker_coin | string (optional) | ticker of maker coin |
| taker_coin | string (optional) | ticker of taker coin |
| maker_amount | string (numeric, optional) | the amount of coins to be swapped by maker |
| taker_amount | string (numeric, optional) | the amount of coins to be swapped by taker |
| my_info | object (optional) | this object maps event data to make displaying swap data in a GUI simpler (my_coin, my_amount, etc.) |
| recoverable | bool | whether the swap can be recovered using the recover_funds_of_swap API command. Important note: MM2 does not record the state regarding whether the swap was recovered or not. MM2 allows as many calls to the recover_funds_of_swap method as necessary, in case of errors |
# Maker Swap Events
# Taker swap events
# 📌 Examples
# Command
curl --url "http://127.0.0.1:7783" --data "{\"method\":\"my_swap_status\",\"params\":{\"uuid\":\"d14452bb-e82d-44a0-86b0-10d4cdcb8b24\"},\"userpass\":\"$userpass\"}"
# my_tx_history
(from_id limit=10)
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 |
| 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 (in seconds) |
| zcredits | number | the zeroconf deposit amount |
| numasks | number | the total number of asks |
| askdepth | number | the depth of the ask requests |
| base | string | the name of the coin the user desires to receive |
| rel | string | the name of the coin the user will trade |
| timestamp | number | the timestamp of the orderbook request |
| netid | number | the id of the network on which the request is made (default is 0) |
# 📌 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.
TIP
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\"}"