Matcher Fee

The fee specified in an order must be at least the minimum fee set by the matcher.

If the order is fully executed by an Exchange transaction, all the matcher fee from the order is included in the transaction. If the order is partially executed by an Exchange transaction, the matcher fee is included in the transaction proportionally to the executed amount, that is:

executedAmount * orderMatcherFee / orderAmount.

The remaining matcher fee for the order will be included in other transactions until the order is fully executed.

The matcher receives a fee from each of the counter orders, so the Exchange transaction contains two fields for the matcher fee: from the buy order and the sell order.

Fee Modes

Current version of WX Network matcher charges either dynamic fee (dynamic mode) or percentage fee (percent mode) depending on a certain pair of assets (trading pair).

• For certain asset pairs, an individual percentage fee (percent mode) is set. For example:

  • For the L2MP / ETH pair, the fee is 0.1% of exchange amount, at least the equivalent of 0.01 WAVES.
  • For the WAVES / WBTC promo pair, the fee is 0% of exchange amount, the equivalent of 0.005 WAVES.

  Such a fee is paid in the asset being spent (spending fee asset type) or in WX. For example, if a user spends L2MP to get ETH, they pays the fee in L2MP or WX, and if they spends ETH to get L2MP, then they pays the fee in ETH or WX.

  For some pairs, the fee is asymmetric: its size depends on the asset being spent.

• For pairs containing WAVES, WX, USDT, USDT-ERC20, USDT-BEP20, USDC, USDC-ERC20, USDC-BEP20, ETH, or WBTC (except for pairs from the previous paragraph), the percentage fee (percent mode) is set, which is 0.1% of exchange amount, at least the equivalent of 0.01 WAVES. Payable in WAVES (fixedAsset fee asset type) or WX.

• For other pairs, a dynamic fee (dynamic mode) is applied, which is 0.01 WAVES per order, regardless of the exchange amount. Payable in WAVES or WX.

Matcher API endpoints

You can get the data to calculate the order fee using the following endpoints of the matcher API:

• POST /matcher/orderbook/calculateFee calculates the fee for a certain order parameters.
• GET /matcher/settings prodives the list of trading pairs with percentage fee, parameters and asset rates used in fee calculations, and other matcher settings.
• GET /matcher/settings/rates — provides only asset rates for fee calculations.

⚠️ We recommend to request settings at least once per minute, so that you don't miss the changes of percent pairs.

Request example:

curl -X 'GET' 'https://matcher.wx.network/matcher/settings' -H 'accept: application/json'

Response example:

{
   "orderVersions": [1, 2, 3, 4],
   "success": true,
   "rates": {
      "DGbqkzM6Ds5NAF2B3GHYfyZRmWKt7xLYRYcwpMm7D6V4": 725.3637577238987,
      "HZk1mbfuJpmxU1Fs4AX5MWLVYtctsNcg6e2C6VKqK8zk": 0.12088302939218537,
      ...
      "C1iWsKGqLwjHUndiQ7iXpdmPum9PeCDFfyXBdJJosDRS": 0.5997213538068408
   },
   "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
   "orderFee": {
      "composite": {
         "default": {
            "dynamic": {
               "baseFee": 1000000
            }
         },
         "custom": {
            "7scqyYoVsNrpWbTAc78eRqNVcYLxMPzZs8EQfX7ruJAg-3VuV5WTmDz47Dmdn3QpcYjzbSdipjQE4JMdNe1xZpX13": {
               "percent": {
                  "type": "spending",
                  "minFee": 0.1,
                  "minFeeInWaves": 1000000
               }
            },
            ...
            "GAzAEjApmjMYZKPzri2g2VUXNvTiQGF7KDYZFFsP3AEq-WAVES": {
               "percent": {
                  "type": "spending",
                  "minFee": 10,
                  "minFeeInWaves": 10000000,
                  "price": {
                     "minFee": 0,
                     "minFeeInWaves": 10000000
                  }
               }
            },
            ...
         },
         "verified": {
            "assets": [
               "WAVES",
               "Atqv59EYzjFGuitKVnMRk6H8FukjoV3ktPorbEys25on",
               "G5WWWzzVsWRyzGf32xojbnfp7gXbWrgqJT8RcVWEfLmC",
               ...
               "2Fge5HEBRD3XTeg7Xg3FW5yiB9HVJFQtMXiWMQo72Up6"
            ],
            "settings": {
               "percent": {
                  "type": "fixedAsset",
                  "fixedAsset": "WAVES",
                  "minFee": 0.1,
                  "minFeeInWaves": 1000000
               }
            }
         },
         "discount": {
            "assetId": "Atqv59EYzjFGuitKVnMRk6H8FukjoV3ktPorbEys25on",
            "value": 0
         }
      }
   },
   "networkByte": 87,
   "matcherVersion": "2.5.4",
   "status": "SimpleResponse",
   "priceAssets": [
      "DG2xFkPdDwKUoBkzGAhQtLpSGzfXLiCYPEzeKH2Ad24p", 
      "9LNqjybyCX1oexCub4yY7hdJf6aeP4HeV5LpsjcNHwRR",
      ...
      "AhGJvjtYmRG2pKwXvTh8N6sX1M2wNTpkjxaWKQfzJe7q"
   ]
}

Priority of fee settings

Parameters from the following sections can be used to calculate the order fee, listed in the descending priorities:

1. custom: individual settings for certain asset pairs.
2. verified: settings for pairs that are not in the custom section and contain at least one asset from the verified.assets list. (note: the list does NOT refer to tokens verified by community).
3. default — settings for other pairs.

Percentage Mode Parameters

• type: which asset is used to pay the fee. Possible values are:

  • spending: the asset being spent. This means that the fee for a sell order is paid in the amount asset, and the fee for a buy order is paid in the price asset;
  • receiving: the asset being received;
  • amount: the amount asset;
  • price: the price asset;
  • fixedAsset: the asset specified in the fixedAsset field.

  Note: fee of any type can also be paid in WX token.

• fixedAsset: fee asset for "type": "fixedAsset".

• minFee: the minimum fee as a percentage of the order amount: 0.1 means 0.1%.

• minFeeInWaves: the minimum fee in WAVES. Regardless of the order amount, the fee must be greater than or equal to the equivalent of minFeeInWaves.

• amount: the minimum fee for a sell order, that is, in case of spending amountAsset.

• price: the minimum fee for a buy order, that is, in case of spending priceAsset.

Asymmetric Fee

For a percentage fee pair, only one of the amount and price structures (or neither) can be present. Settings nested within amount and price take precedence over the minFee and minFeeInWaves settings at the level above.

In the example above, the price structure is specified for the PETE-WAVES pair. It means that:

• for buy orders in this pair (where priceAsset WAVES is spent), the settings from price.minFee and price.minFeeinWaves are applied: the fee is 0% of the exchange amount, the equivalent of 0.1 WAVES;
• for sell orders in this pair (where amountAsset PETE is spent) settings at the level above are applied: the fee is 10% of the exchange amount, at least the equivalent of 0.1 WAVES.

Fee in WX token

Regardless of fee mode and type of fee asset set for a trading pair, the fee can be paid in WX token.

discount section describes parameters of fees paid with WX (discount asset):

• asset: ID of WX token.
• value: discount percentage: 0 (no discount at this time).

Calculating minimum order fee

Constants

PriceConstantExp = 8
PriceConstant = 10 ** PriceConstantExp

Functions

correctedRate(rate, assetDecimals) = rate * 10 ** (assetDecimals - PriceConstantExp)

Dynamic fee mode

Fee calculation involves the baseFee parameter and WX rate (see the response of the GET /matcher/settings endpoint above).

Fee paid in WAVES:

baseFee + 400000 * scripts_count

scripts_count is the number of smart script runs that are required to validate the order.

Fee paid in WX (discount asset):

rate = correctedRate(rates[discountAsset], discountAssetDecimals)

(baseFee + 400000 * scripts_count) * correctedRate * (100 - discount) / 100

Percent fee mode

Fee calculation involves the parameters minFee, minFeeInWaves and asset rates (see the response of the GET /matcher/settings endpoint above).

For a sell order

Fee in the amount asset:

order.amount * minFee / 100

Fee in WX (discount asset):

discountAssetRate = correctedRate(rates[discountAsset], discountAssetDecimals)
amountAssetRate = correctedRate(rates[amountAsset], amountAssetDecimals)

order.amount * minFee / 100 * (discountAssetRate / amountAssetRate) * (100 - discount) / 100

For a buy order

Fee in the price asset:

order.amount * order.price / PriceConstant * minFee / 100

Fee in WX (discount asset):

discountAssetRate = correctedRate(rates[discountAsset], discountAssetDecimals)
priceAssetRate = correctedRate(rates[priceAsset], priceAssetDecimals)

order.amount * order.price / PriceConstant * minFee / 100 * (discountAssetRate / priceAssetRate) * (100 - discount) / 100

Check minFeeInWaves

The commission per order must be at least the equivalent of minFeeInWaves. To compare the fee calculated using minFee and minFeeInWaves, multiply minFeeInWaves by the corrected FeeAssetRate. The discount also applies to minFeeInWaves when using the discount asset to pay fees.

Example

The following settings are used in the example:

{
   "percent" : {
      "type" : "spending",
      "minFee" : 0.14,
      "minFeeInWaves" : 300000
   }
}

Lets trade 0.00032173 BTC by 42611.43 XTN per BTC. Consider that smart contracts are not involved.

pair = BTC/XTN

price = 42611430000

amount = 32173

Order amount is:

• in the price asset: 13.709237 XTN

• in the amount asset: 0.00032173 BTC

rates[BTC] = 0.000329

rates[XTN] = 13.9

rates[discountAsset] = 10.534

Corrected rates:

• priceAsset = rates[XTN] * 10 ** (-2) = 0.1390

• amountAsset = rates[BTC] = 0.000329

• discountAsset = rates[discountAsset] = 10.534

minFee = 0.14%

minFeeInWaves = 300000

discount = 50%

priceAssetDecimals = 6

amountAssetDecimals = 8

discountAssetDecimals = 8

minFeeInWaves converted:

• priceAsset = 41700

• amountAsset = 98

• discountAsset = 3160200

For the sell order

Fee in the amount asset:

32173 * 0.14 / 100 = 45 (0.00000045 BTC ~ 0.019 XTN)

Fee in the discount asset:

32173 * 0.14 / 100 * (10.534 / 0.000329) * (100 - 50) / 100 = 721085

For the buy order

Fee in the price asset:

32173 * 42611430000 / 100000000 * 0.14 / 100 = 19193 (0.019 XTN)

Fee in the discountAsset:

32173 * 42611430000 / 100000000 * 0.14 / 100 * (10.534 / 0.139) * (100 - 50) / 100 = 727267

Check minFeeInWaves

When paying in the price asset:

300000 * 0.139 = 41700 (0.041700 XTN)

When paying in the amount asset:

300000 * 0.000329 = 99 (0.00000099 BTC)

When paying in the discount asset:

300000 * 10.534 * (100 - 50) / 100 = 1580100 (0.015801 discountAsset)

Since the fee calculated using minFee is less than minFeeInWaves, the minimum order fee is equivalent to minFeeInWaves.