# trade_preimage
The trade_preimage
method returns the approximate fee amounts that are paid per the whole swap.
Depending on the parameters, the function returns different results:
- If the
swap_method
isbuy
orsell
, then the result will include thetaker_fee
and thefee_to_send_taker_fee
. Thetaker_fee
amount is paid from thebase
coin balance if theswap_method
issell
, else it is paid from therel
coin balance; - If the
max
field is true, then the result will include thevolume
.
Note
This method can be used instead of max_taker_vol, if the max
field is true and the swap_method
is buy
or sell
.
Use the resulting volume
as an argument of the buy
or sell
requests.
Important
Use the trade_preimage
request with max = true
and swap_method = "setprice"
arguments to approximate the fee amounts only. Do not use the resulting volume
as an argument of the setprice
.
# Arguments
Structure | Type | Description |
---|---|---|
base | string | the base currency of the request |
rel | string | the rel currency of the request |
swap_method | string | the name of the method whose preimage is requested. Possible values: buy , sell , setprice |
price | numeric string or rational | the price in rel the user is willing to pay per one unit of the base coin |
volume | numeric string or rational (optional) | the amount the user is willing to trade; ignored if max = true and swap_method = setprice , otherwise, it must be set |
max | bool (optional) | whether to return the maximum available volume for setprice method; must not be set or false if swap_method is buy or sell |
# Result
Structure | Type | Description |
---|---|---|
result | object | an object containing the relevant information |
result.base_coin_fee | object (ExtendedFeeInfo ) | the approximate miner fee is paid per the whole swap concerning the base coin |
result.rel_coin_fee | object (ExtendedFeeInfo ) | the approximate miner fee is paid per the whole swap concerning the rel coin |
result.volume | string (numeric, optional) | the max available volume that can be traded (in decimal representation); empty if the max argument is missing or false |
result.volume_rat | rational (optional) | the max available volume that can be traded (in rational representation); empty if the max argument is missing or false |
result.volume_fraction | fraction (optional) | the max available volume that can be traded (in fraction representation); empty if the max argument is missing or false |
result.taker_fee | object (optional, ExtendedFeeInfo ) | the dex fee to be paid by Taker; empty if swap_method is setprice |
result.fee_to_send_taker_fee | object (optional, ExtendedFeeInfo ) | the approximate miner fee is paid to send the dex fee; empty if swap_method is setprice |
result.total_fees | array of ExtendedFeeInfo objects | each element is a sum of fees required to be paid from user's balance of corresponding ExtendedFeeInfo.coin ; the elements are unique by coin |
Where the ExtendedFeeInfo
has
Structure | Type | Description |
---|---|---|
coin | string | the fee is paid from the user's balance of this coin. This coin name may differ from the base or rel coins. For example, ERC20 fees are paid by ETH (gas) |
amount | string (numeric) | fee amount (in decimal representation) |
amount_rat | rational | fee amount (in rational representation) |
amount_fraction | fraction | fee amount (in fraction representation) |
paid_from_trading_vol | boolean | If true , fees are deducted from the payment amount for the spend/refund UTXO HTLC transaction. If false , fees are not deducted from the traded volume. This is where an additional miner fee is needed to broadcast a swap transaction and/or where gas paid (e.g in ETH for an ERC20 trade) - in this case, user requires a sufficient current ETH balance to cover the fees before they can initiate the swap. |
# ⚠️ Error types
# NotSufficientBalance
The available
balance of the coin
is not sufficient to start the swap.
Structure | Type | Description |
---|---|---|
coin | string | the name of the coin which balance is not sufficient |
available | string (numeric) | the balance available for swap, including the amount locked by other swaps |
required | string (numeric) | the amount required to start the swap. This amount is necessary but may not be sufficient |
locked_by_swaps | string (numeric, optional) | the amount locked by other swaps |
# NotSufficientBaseCoinBalance
The available balance of the base coin
is not sufficient to pay transaction fees.
For example, ERC20 fees are paid by ETH (gas), and this error type is returned if the ETH coin balance is not sufficient to start the swap.
Structure | Type | Description |
---|---|---|
coin | string | the name of the base coin which balance is not sufficient |
available | string (numeric) | the balance available for swap, including the amount locked by other swaps |
required | string (numeric) | the amount required to start the swap. This amount is necessary but may not be sufficient |
locked_by_swaps | string (numeric, optional) | the amount is locked by other swaps |
# VolumeTooLow
The specified volume
is too low. Required at least threshold
.
Note
If the coin
field returned in Response is the same as the rel
argument in Request, then the base volume threshold can be calculated as follows:
base_coin_threshold = rel_vol_threshold / price
Structure | Type | Description |
---|---|---|
coin | string | either base or rel coin specified in Request |
volume | string (numeric) | the amount the user was willing to trade in coin |
threshold | string (numeric) | the volume has not to be less than this amount |
# NoSuchCoin
The specified coin was not found or is not activated yet.
Structure | Type | Description |
---|---|---|
coin | string | either base or rel coin specified in Request |
# CoinIsWalletOnly
The specified coin is wallet only and cannot be participated in the swap.
Structure | Type | Description |
---|---|---|
coin | string | either base or rel coin specified in Request |
# BaseEqualRel
The coin is wallet only and cannot be participated in the swap.
Structure | Type | Description |
---|---|---|
(none) |
# InvalidParam
Incorrect use of the param
parameter in Request.
Structure | Type | Description |
---|---|---|
param | string | the name of the parameter in Request |
reason | string | the reason why the parameter is used incorrectly |
# PriceTooLow
The specified price
is too low.
Structure | Type | Description |
---|---|---|
price | string (numeric) | the price in rel the user was willing to receive per one unit of the base coin |
threshold | string (numeric) | the price has not to be less than this amount |
# Transport
The request was failed due to a network error.
Structure | Type | Description |
---|---|---|
(none) | string | the transport error description |
# InternalError
The request was failed due to a AtomicDEX API internal error.
Structure | Type | Description |
---|---|---|
(none) | string | the internal error description |
# 📌 Examples
# Command (setprice)
curl --url "http://127.0.0.1:7783" --data "{\"mmrpc\":\"2.0\",\"userpass\":\"$userpass\",\"method\":\"trade_preimage\",\"params\":{\"base\":\"BTC\",\"rel\":\"RICK\",\"price\":\"1\",\"volume\":\"0.1\",\"swap_method\":\"setprice\"},\"id\":0}"
# Response
{
"mmrpc": "2.0",
"result": {
"base_coin_fee": {
"coin": "KMD",
"amount": "0.00001",
"amount_fraction": {
"numer": "1",
"denom": "100000"
},
"amount_rat": [ [ 1, [ 1 ] ], [ 1, [ 100000 ] ] ],
"paid_from_trading_vol": false
},
"rel_coin_fee": {
"coin": "DGB",
"amount": "0.00030782",
"amount_fraction": {
"numer": "15391",
"denom": "50000000"
},
"amount_rat": [ [ 1, [ 15391 ] ], [ 1, [ 50000000 ] ] ],
"paid_from_trading_vol": true
},
"volume": "1138.46868712",
"volume_fraction": {
"numer": "14230858589",
"denom": "12500000"
},
"volume_rat": [ [ 1, [ 1345956701, 3 ] ], [ 1, [ 12500000 ] ] ],
"total_fees": [
{
"coin": "KMD",
"amount": "0.00001",
"amount_fraction": {
"numer": "1",
"denom": "100000"
},
"amount_rat": [ [ 1, [ 1 ] ], [ 1, [ 100000 ] ] ],
"required_balance": "0.00001",
"required_balance_fraction": {
"numer": "1",
"denom": "100000"
},
"required_balance_rat": [ [ 1, [ 1 ] ], [ 1, [ 100000 ] ] ]
},
{
"coin": "DGB",
"amount": "0.00030782",
"amount_fraction": {
"numer": "15391",
"denom": "50000000"
},
"amount_rat": [ [ 1, [ 15391 ] ], [ 1, [ 50000000 ] ] ],
"required_balance": "0",
"required_balance_fraction": {
"numer": "0",
"denom": "1"
},
"required_balance_rat": [ [ 0, [] ], [ 1, [ 1 ] ] ]
}
]
},
"id": 0
}
# Command (buy)
curl --url "http://127.0.0.1:7783" --data "{\"mmrpc\":\"2.0\",\"userpass\":\"$userpass\",\"method\":\"trade_preimage\",\"params\":{\"base\":\"BTC\",\"rel\":\"RICK\",\"price\":\"1\",\"volume\":\"0.1\",\"swap_method\":\"buy\"},\"id\":0}"
# Response
{
"mmrpc": "2.0",
"result": {
"base_coin_fee": {
"amount": "0.00042049",
"amount_fraction": {
"denom": "100000000",
"numer": "42049"
},
"amount_rat": [ [ 1, [ 42049 ] ], [ 1, [ 100000000 ] ] ],
"coin": "BTC",
"paid_from_trading_vol": true
},
"rel_coin_fee": {
"amount": "0.0001",
"amount_fraction": {
"denom": "10000",
"numer": "1"
},
"amount_rat": [ [ 1, [ 1 ] ], [ 1, [ 10000 ] ] ],
"coin": "RICK",
"paid_from_trading_vol": false
},
"taker_fee": {
"amount": "0.00012870012870012872",
"amount_fraction": {
"denom": "7770",
"numer": "1"
},
"amount_rat": [ [ 1, [ 1 ] ], [ 1, [ 7770 ] ] ],
"coin": "RICK",
"paid_from_trading_vol": false
},
"fee_to_send_taker_fee": {
"amount": "0.0001",
"amount_fraction": {
"denom": "10000",
"numer": "1"
},
"amount_rat": [ [ 1, [ 1 ] ], [ 1, [ 10000 ] ] ],
"coin": "RICK",
"paid_from_trading_vol": false
},
"total_fees": [
{
"coin": "RICK",
"amount": "0.001307001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287",
"amount_fraction": {
"numer": "50777",
"denom": "38850000"
},
"amount_rat": [ [ 1, [ 50777 ] ], [ 1, [ 38850000 ] ] ],
"required_balance": "0.001307001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287",
"required_balance_fraction": {
"numer": "50777",
"denom": "38850000"
},
"required_balance_rat": [ [ 1, [ 50777 ] ], [ 1, [ 38850000 ] ] ]
},
{
"coin": "tBTC",
"amount": "0.00042049",
"amount_fraction": {
"denom": "100000000",
"numer": "42049"
},
"amount_rat": [ [ 1, [ 42049 ] ], [ 1, [ 100000000 ] ] ],
"required_balance": "0",
"required_balance_fraction": {
"numer": "0",
"denom": "1"
},
"required_balance_rat": [ [ 0, [] ], [ 1, [ 1 ] ] ]
}
]
},
"id": 0
}
# Command (sell, max)
curl --url "http://127.0.0.1:7783" --data "{\"mmrpc\":\"2.0\",\"userpass\":\"$userpass\",\"method\":\"trade_preimage\",\"params\":{\"base\":\"BTC\",\"rel\":\"RICK\",\"price\":\"1\",\"volume\":\"2.21363478\",\"swap_method\":\"sell\"},\"id\":0}"
# Response
{
"mmrpc": "2.0",
"result": {
"base_coin_fee": {
"amount": "0.00042049",
"amount_fraction": {
"denom": "100000000",
"numer": "42049"
},
"amount_rat": [ [ 1, [ 42049 ] ], [ 1, [ 100000000 ] ] ],
"coin": "BTC",
"paid_from_trading_vol": false
},
"rel_coin_fee": {
"coin": "RICK",
"amount": "0.00001",
"amount_fraction": {
"numer": "1",
"denom": "100000"
},
"amount_rat": [ [ 1, [ 1 ] ], [ 1, [ 100000 ] ] ],
"paid_from_trading_vol": true
},
"taker_fee": {
"amount": "0.0028489508108108107",
"amount_fraction": {
"denom": "1850000000",
"numer": "5270559"
},
"amount_rat": [ [ 1, [ 5270559 ] ], [ 1, [ 1850000000 ] ] ],
"coin": "BTC",
"paid_from_trading_vol": false
},
"fee_to_send_taker_fee": {
"amount": "0.00033219",
"amount_fraction": {
"denom": "100000000",
"numer": "33219"
},
"amount_rat": [ [ 1, [ 33219 ] ], [ 1, [ 100000000 ] ] ],
"coin": "BTC",
"paid_from_trading_vol": false
},
"total_fees": [
{
"coin": "RICK",
"amount": "0.00001",
"amount_fraction": {
"numer": "1",
"denom": "100000"
},
"amount_rat": [ [ 1, [ 1 ] ], [ 1, [ 100000 ] ] ],
"required_balance": "0",
"required_balance_fraction": {
"numer": "0",
"denom": "1"
},
"required_balance_rat": [ [ 0, [] ], [ 1, [ 1 ] ] ]
},
{
"coin": "BTC",
"amount": "0.0036016308108108106",
"amount_fraction": {
"denom": "1850000000",
"numer": "6663017"
},
"amount_rat": [ [ 1, [ 6663017 ] ], [ 1, [ 1850000000 ] ] ],
"required_balance": "0.0036016308108108106",
"required_balance_fraction": {
"denom": "1850000000",
"numer": "6663017"
},
"required_balance_rat": [ [ 1, [ 6663017 ] ], [ 1, [ 1850000000 ] ] ]
}
]
},
"id": 0
}
# Command (ERC20 and QRC20)
curl --url "http://127.0.0.1:7783" --data "{\"mmrpc\":\"2.0\",\"userpass\":\"$userpass\",\"method\":\"trade_preimage\",\"params\":{\"base\":\"BAT\",\"rel\":\"QC\",\"price\":\"1\",\"volume\":\"2.21363478\",\"swap_method\":\"setprice\"},\"id\":0}"
# Response
{
"mmrpc": "2.0",
"result": {
"base_coin_fee": {
"amount": "0.0045",
"amount_fraction": {
"denom": "2000",
"numer": "9"
},
"amount_rat": [ [ 1, [ 9 ] ], [ 1, [ 2000 ] ] ],
"coin": "ETH",
"paid_from_trading_vol": false
},
"rel_coin_fee": {
"amount": "0.00325",
"amount_fraction": {
"denom": "4000",
"numer": "13"
},
"amount_rat": [ [ 0, [ 13 ] ], [ 1, [ 4000 ] ] ],
"coin": "QTUM",
"paid_from_trading_vol": false
},
"total_fees": [
{
"amount": "0.003",
"amount_fraction": {
"denom": "1000",
"numer": "3"
},
"amount_rat": [ [ 1, [ 3 ] ], [ 1, [ 1000 ] ] ],
"required_balance": "0.003",
"required_balance_fraction": {
"denom": "1000",
"numer": "3"
},
"required_balance_rat": [ [ 1, [ 3 ] ], [ 1, [ 1000 ] ] ],
"coin": "ETH"
},
{
"amount": "0.00325",
"amount_fraction": {
"denom": "4000",
"numer": "13"
},
"amount_rat": [ [ 0, [ 13 ] ], [ 1, [ 4000 ] ] ],
"required_balance": "0.00325",
"required_balance_fraction": {
"denom": "4000",
"numer": "13"
},
"required_balance_rat": [ [ 0, [ 13 ] ], [ 1, [ 4000 ] ] ],
"coin": "QTUM"
}
]
},
"id": 0
}
# Response (NotSufficientBalance error)
{
"mmrpc": "2.0",
"error": "Not enough BTC for swap: available 0.000015, required at least 0.10012, locked by swaps None",
"error_path": "maker_swap",
"error_trace": "maker_swap:1540] maker_swap:1641]",
"error_type": "NotSufficientBalance",
"error_data": {
"coin":"BTC",
"available":"0.000015",
"required":"0.10012",
"locked_by_swaps":"0"
},
"id": 0
}
# Response (VolumeTooLow error)
{
"mmrpc": "2.0",
"error":"The volume 0.00001 of the RICK coin less than minimum transaction amount 0.0001",
"error_path": "maker_swap",
"error_trace": "maker_swap:1599]",
"error_type": "VolumeTooLow",
"error_data": {
"coin": "RICK",
"volume": "0.00001",
"threshold": "0.0001"
},
"id": 0
}
# Response (Transport error)
{
"mmrpc": "2.0",
"error": "Transport error: JsonRpcError { client_info: 'coin: tBTC', request: JsonRpcRequest { jsonrpc: '2.0', id: '31', method: 'blockchain.estimatefee', params: [Number(1), String('ECONOMICAL')] }, error: Transport('rpc_clients:1237] rpc_clients:1239] ['rpc_clients:2047] common:1385] future timed out']') }",
"error_path": "taker_swap.utxo_common",
"error_trace": "taker_swap:1599] utxo_common:1990] utxo_common:166]",
"error_type": "Transport",
"error_data": "JsonRpcError { client_info: 'coin: tBTC', request: JsonRpcRequest { jsonrpc: '2.0', id: '31', method: 'blockchain.estimatefee', params: [Number(1), String('ECONOMICAL')] }, error: Transport('rpc_clients:1237] rpc_clients:1239] ['rpc_clients:2047] common:1385] future timed out']') }",
"id": 0
}
# Response (incorrect use of "max" error)
{
"mmrpc": "2.0",
"error": "Incorrect use of the 'max' parameter: 'max' cannot be used with 'sell' or 'buy' method",
"error_path": "taker_swap",
"error_trace": "taker_swap:1602]",
"error_type": "InvalidParam",
"error_data": {
"param": "max",
"reason": "'max' cannot be used with 'sell' or 'buy' method"
},
"id": 0
}