Matcher API

Our nodes contain an order matcher which is used to power the decentralized exchange — enabling asset trades that don’t require assets to be transferred from your blockchain account to a separate exchange. All operations within WX Network are secure and validated by blockchain nodes. Any user can run an instance of the open source WX Network.

The matcher exposes its own REST API for accessing the order book and submitting orders. This allows users to implement any kind of trading UI or trading bots.

The reason behind decentralized exchange (WX Network, aka Matcher) is to perform secure exchange of assets issued on Waves blockchain. When a user sends an order to Matcher he doesn't transfer ownership of his money to anyone, his money remains on his account until the order is matched with counter-order. The Matcher creates ExchangeTransaction while the blockchain guarantees that the transaction will be made on the conditions that are not worse than in the user's order. After the transaction is confirmed on blockchain, the user account's balances of assets are changed according to the amount, order execution price, and the Matcher fee.

Please find the matcher API for Mainnet and Testnet:

• Mainnet Matcher API (opens new window)
• Testnet Matcher API (opens new window)

Entities

Here are the main entities the matcher works with:

• Asset
• Asset Pair
• Order
• Order Book
• Exchange transaction
• List of all errors (opens new window)

Asset

Every asset, except WAVES, has an ID.

decimals is a number of decimal places in the asset amount. You can get asset decimals:

• using the GET /assets/details/{assetId} method of the Node API (opens new window)
• clicking on the asset ID on the Trading page in the WX Network (opens new window) interface.

In JSON representation, the amount of asset is multiplied by 10^decimals, so it is always an integer value. For example, decimals of WAVES is 8, so the real amount is multiplied by 10^8. { "WAVES": 677728840 } means 6.77728840 WAVES.

Asset Pair

Asset pair contains two assets of the order.

Example:

"assetPair": {
  "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
  "priceAsset": "8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS"
}

Field name	Description
amountAsset	ID of the first asset that the order sender wants to buy or sell. WAVES, or null, or omitted field means WAVES
priceAsset	ID of the second asset in which the order price is determined. WAVES, or null, or omitted field means WAVES

Asset pair exists independently of which asset is 'spend' and which is 'received'.

For each asset pair, there is exactly one corresponding order book.

What Asset of the Pair to Choose as Price Asset

See the priceAssets list returned by the GET /matcher/settings API method.

1. If both assets are in the priceAssets list, the one which comes first on the list is a price asset.
2. If only one of the assets is present in the list, this asset is a price asset.
3. If both assets are not on the list, their IDs in byte representation should be sorted lexicographically: the first (the smalles) one is a price asset and the second is an amount.

Order

Order is an instruction to buy or sell an asset on WX Network.

You can place Limit Order, Market Order or Stop-limit Order using different API methods. The JSON structures of the limit order and market orders are the same, however, the stop-limit order is different and is only supported in Version 4 of JSON structure.

For both Limit and Market Order, Matcher tries to buy or sell a specified amount of an asset at a price equal to or better than specified. Stop-limit order is basically a limit order with specified stop price and a limit price; when the price on the market reaches the stop price, the limit order is automatically placed in the order book; when the market price reaches the specified limit price, the order gets executed.

If a Limit Order cannot be completely filled by counter-orders matched by price, it would be filled partially and put in the corresponding order book. The placed order will be active in order book for 30 days max until it is completely matched with counter-orders or cancelled by sender.

In a Market Order the sender specifies max price for buy and the min price for sell from the corresponding order book. If the specified price is enough to fully fill the order by counter-orders matched by price, it would be executed at the best price. If the specified price is not enough to fully fill the order, it would be rejected. But if there is not enough amount of the asset in all the counter-orders, it would be filled partially. Market Order has no max duration. When placed, a market order is matched with counter orders until it reaches the specified number of assets or the sender has no more available balance. Finished market orders are removed from order book.

Example of the order version 3:

{
  "version": 3,
  "id": "H3oBpc7phuaMQGM3sgnrcYNyb12DSgJi44ksgEt1vJMT",
  "sender": "3P3ks3wvEySmUAu4JCk2aELfLaaENxCAdw1",
  "senderPublicKey": "6JBcXLr61Tx133i1KRjg31vLNMv6fcuhm1ufN2zAB19N",
  "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
  "assetPair": {
    "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
    "priceAsset": "8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS"
  },
  "orderType": "buy",
  "amount": 997736917,
  "price": 707,
  "timestamp": 1575983051927,
  "expiration": 1578488651926,
  "matcherFee": 13,
  "matcherFeeAssetId": "8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS",
  "signature": "aC76moJRWszKc1u9k9sQtcDWnHtfDh6ZNjoUVqSD3uMXnfFy1rcwhJVDTWQwGqGUKgNYbqPagZVyingRNQ6Gq3L",
  "proofs": [
    "aC76moJRWszKc1u9k9sQtcDWnHtfDh6ZNjoUVqSD3uMXnfFy1rcwhJVDTWQwGqGUKgNYbqPagZVyingRNQ6Gq3L"
  ]
}

Field name	Description
version	A version of order. Should be 3. Order V1 and V2 are deprecated
id	Order ID
sender	Base58-encoded address of order sender
senderPublicKey	Base58-encoded public key of order sender related to the address from which to send/receive assets
matcherPublicKey	Base58-encoded public key of Matcher to whom user authorize to match his order. Use GET /matcher API method to get Matcher public key
assetPair	Asset pair for order. The order will be placed to the corresponding order book
orderType	Order type: "buy" or "sell"
amount	Amount of amountAsset multiplied by 10^amountAssetDecimals. See Asset for more information
price	Price for amountAsset denominated in priceAsset and multiplied by 10^(8 + priceAssetDecimals – amountAssetDecimals). For example, in the ETH/WAVES asset pair the price 12,500,000,000 means that 1 ETH costs 125 WAVES (PriceAssetDecimals and AmountAssetDecimals both equal to 8).
timestamp	Unix time (opens new window) of order creation, in milliseconds. It is used as a nonce for the order.
expiration	Unix time in milliseconds when the order will be expired. Should be more than one minute and less than one month from the current time. Note: Matcher is synchronized with NTP (opens new window). If you are not synced, Matcher can reject an order with the error because the time difference is less than 1 munite or more than 1 month
matcherFee	Fee which goes to Matcher. See Matcher Fee for more information
matcherFeeAssetId	Asset for fee. It should not be specified if it is Waves (or use null)
signature	The signature of the order sender. The first element of the proofs array is automatically set in the field
proofs	Proofs for order validation. Use Curve25519 (opens new window) for obtaining a proof. For signing order the following client libraries (opens new window) can be used

Note:

• Order version 3 does not support attachment field.
• Order version 2 does not support the matcherFeeAssetId field. The matcher fee is paid in WAVES only.
• Order version 1 does not support the matcherFeeAssetId field and the proofs field.

See also: Order Validation, Order Limit Parameters

Example of the order version 4:

{
  "orderType": "buy",
  "version": 4,
  "assetPair": {
    "amountAsset": "WAVES",
    "priceAsset": "DG2xFkPdDwKUoBkzGAhQtLpSGzfXLiCYPEzeKH2Ad24p"
  },
  "price": 55000000,
  "amount": 100000000,
  "timestamp": 1679316905713,
  "expiration": 1681822505713,
  "matcherFee": 39080922,
  "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
  "senderPublicKey": "G9oVDzXqZiJeHUqTE4dX7AD7u9zTHae8c4oxcNwDRjzw",
  "proofs": [
    "4aPvnzVinJeYR5mp78KhnKBprAuy8LZU1xnHKaYJZ5T6xMVcUXtn4mEsd1WQUFXTQzjcBFYzaCWKwJZkadKJRq6F"
  ],
  "matcherFeeAssetId": "Atqv59EYzjFGuitKVnMRk6H8FukjoV3ktPorbEys25on",
  "id": "HYEHXesh2g3RfcHGntGkk8vRa7Ndyks2SmW1ZtG7UsV",
  "priceMode": "assetDecimals",
  "chainId": 87,
  "attachment": "U1GmCKH5jS7hHMmFMQ677SpNwvhUSJJsRkYFTHJmLwkdpppdM8dvQZNL"
}

Decoded attachment example:

{
  "v": 1, //version (int)
  "c": {  //condition (object)
    "t": "sp", //condition type. for now only "stop-price" (string)
    "v": { //value (object)
      "p": 123123 //price (long)
    }
  }
}

Field name	Description
orderType	Order type: "buy" or "sell"
version	A version of order. Should be 4.
assetPair	Asset pair for order. The order will be placed to the corresponding order book
price	Price for amountAsset denominated in priceAsset and multiplied by 10^(8 + priceAssetDecimals – amountAssetDecimals). For example, in the ETH/WAVES asset pair the price 12,500,000,000 means that 1 ETH costs 125 WAVES (PriceAssetDecimals and AmountAssetDecimals both equal to 8).
amount	Amount of amountAsset multiplied by 10^amountAssetDecimals. See Asset for more information
timestamp	Unix time (opens new window) of order creation, in milliseconds. It is used as a nonce for the order.
expiration	Unix time in milliseconds when the order will be expired. Should be more than one minute and less than one month from the current time. Note: Matcher is synchronized with NTP (opens new window). If you are not synced, Matcher can reject an order with the error because the time difference is less than 1 munite or more than 1 month
matcherFee	Fee which goes to Matcher. See Matcher Fee for more information
matcherPublicKey	Base58-encoded public key of Matcher to whom user authorize to match his order. Use GET /matcher API method to get Matcher public key
senderPublicKey	Base58-encoded public key of order sender related to the address from which to send/receive assets
proofs	Proofs for order validation. Use Curve25519 (opens new window) for obtaining a proof. For signing order the following client libraries (opens new window) can be used
matcherFeeAssetId	Asset for fee. It should not be specified if it is Waves (or use null)
id	Order ID
chainId	Network byte
attachment	Base58-encoded attachment

Limit Order

Limit order is the order that a user places in orderbook with specified price limit, so that the exchange transactions are matched with the orders that have the price not worse than the specified:

BUY: price <= limit price SELL: price >= limit price

When a user places limit order, the exchange transaction is sent to network, if the market price (best price of matching order in the orderbook at the current time) reaches the the price set in the limit order or better. Therefore, limit orders can be used to buy at a lower price or to sell at a higher price than the current market price.

For both Limit and Market Order, Matcher tries to buy or sell a specified amount of an asset at a price equal or better than specified.

Market Order

Market order has price and amount fields:

• Price - sets the price limit by which to sell or buy (depending on the type of the order)
• Amount - max number of assets to sell/buy

This kind of order is matched with other orders and the exchange transactions are made before either:

• (1) the specified amount of the asset is reached
• (2) the user has no more spendable balance
• (3) the moment when there is no more matching orders by the specified price limit

In case 2 and 3 - the order is filled partially, then the market order is removed from orderbook. In this case, every time after the end of the matching with the next order, the market order must match with the currently most profitable order.

Market order checks:

In a Market Order the sender should specify the maximum price for buy and the minimum price for sell from the corresponding order book. If the specified price is enough to fully fill the order by counter-orders matched by price, it would be executed at the best price. If the specified price is not enough to fully fill the order, it would be rejected. But if there is not enough amount of the asset in all the counter-orders, it would be filled partially.

Order Book

Order Book is a list of orders for a given asset pair.

Example:

{
  "timestamp": 1576143739568,
  "pair": {
    "amountAsset": "4vSJeAji4F7swJazJdZWau9drG1RjFL8QKSx13F7RjKQ",
    "priceAsset": "WAVES"
  },
  "bids": [
    {
      "amount": 10000000000000,
      "price": 41
    },
    {
      "amount": 2500000000000,
      "price": 40
    },
    {
      "amount": 300000000000000,
      "price": 1
    }
  ],
  "asks": [
    {
      "price": 50,
      "amount": 50000000000
    },
    {
      "amount": 2500000000000,
      "price": 51
    }
  ]
}

Field name	Description
timestamp	Unix time in milliseconds.
pair	Asset pair
bids	List of open buy order levels, each level is represented as a price and a sum of all order amounts at this price. The list is sorted by the price in descending order
asks	List of open sell order levels sorted by the price in ascending order

Order Limit Parameters

Order limit parameters allow to avoid filling the order book with orders that have very low or very high price or amount. The limits can also prohibit the users to slightly change the amount or price in the orders to find the trading pair quicker. The tick size limit allows to place orders with very small price difference in the same tier of the order book. Price tiers are the multiples of the tick size. The tick size limit also offsets the trading bots taking advantage of the trading process by changing the order price to the lowest possible value to fill the orders quicker.

The following limits can be set in order-restrictions section of the node configuration file:

• Min amount (min-amount) – the minimal amount of asset to be specified in the order
• Max amount (max-amount) – the maximum amount of asset to be specified in the order
• Step amount (step-amount) – the amount of asset specified in the order must be the multiple of the step amount parameter value
• Min price (min-price) – the minimal price to be specified in the order
• Max price (max-price) – the maximum price to be specified in the order
• Step price (step-price) – the price specified in the order must be the multiple of the step price parameter value

Example:

order-restrictions = {
"WAVES-8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS": {
min-amount = 0.001
max-amount = 1000000
step-amount = 0.00000001
min-price = 0.001
max-price = 100000
step-price = 0.00000001
},
...
}

Note: Use WAVES as assetId for WAVES asset.

The tick size limit can be set in matching-rules section of the node configuration file. The section should contain the asset pair, the start offset and the tick size value.

Example:

matching-rules = {
  "WAVES-8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS": [
    {
      start-offset = 100
      tick-size    = 0.002
    },
    {
      start-offset = 500
      tick-size    = 0.0025
    }
  ]
}

The start offset is the sequence number of the event of placing or cancelling the order by the user. The offset is the same for all the order books and does not depend on the asset pair. The start-offset parameter allows to plan switching on/changing the tick size and allows to avoid the scenario when the state of the order book before restarting the matcher is different from the state after the restarting (in case when the tick size was changed during the restart).

Tick Size

Order levels for an asset pair are defined based on tick size. A tick size is the minimum price movement of an asset pair.

The price in the buy order is rounded down to the tick size. For example, if tick size equals to 0.1, a buy order with the price 125.37 is put to level with the price 125.3.

The price in the sell order is rounded up to the tick size. For example, if tick size equals to 0.1, a sell order with the price 125.62 is put to level with the price 125.7.

To get the tick size for a given asset pair use the GET /matcher/orderbook/{amountAsset}/{priceAsset}/info API method.

Exchange Transaction

Exchange Transaction is created by the Matсher when order execution if performed. The transaction is signed by the Matcher's private key and sent to the Waves network to be included in the blockchain.

Example:

{
  "senderPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
  "amount": 99434230,
  "fee": 300000,
  "type": 7,
  "version": 2,
  "sellMatcherFee": 298302,
  "sender": "3PEjHv3JGjcWNpYEEkif2w8NXV4kbhnoGgu",
  "feeAssetId": null,
  "proofs": [
    "62N8HzSjZ1XVYLqbVnruei4JGWjXzF36Lyhue8Ytb3YFbP2cQBiKTcWE8AvZyyVfwDrPvmS1ZXnA8Es99Lv3X8x"
  ],
  "price": 707,
  "id": "EJ4VD4kCTS4ZHjG3AJ6reEfzBuCgkZFn5nuLnf97bjTQ",
  "order2": {
    ...
  },
  "order1": {
    ...
  },
  "buyMatcherFee": 1,
  "timestamp": 1575986151520,
  "height": 1833113
}

Field Name	Description
senderPublicKey	Base58-encoded public key of a transaction sender (Matcher)
amount	Executed amount of the amountAsset multiplied by 10^amountAssetDecimals that is matched from both orders
fee	Fee for the transaction to be included in a block by a miner. It is paid from the Matcher's account
type	Transaction type ID: 7
version	Transaction version. Should be 2. V1 is deprecated. The blockchain must support Smart Account Trading (feature 10)
sellMatcherFee	Amount fee for matching from sell order. Transferred to Matcher's account balance. See Matcher Fee
sender	Base58-encoded address of a transaction sender (Matcher)
feeAssetId	null means WAVES
proofs	Proofs for transaction validation
price	Price for amountAsset denominated in priceAsset and multiplied by 10^(8 + priceAssetDecimals – amountAssetDecimals)
id	Transaction ID
order2	Sell order executed in this transaction
order1	Buy order executed in this transaction
buyMatcherFee	Amount fee for matching from buy order. Transferred to Matcher's account balance. See Matcher Fee
timestamp	Transaction creation timestamp
height	Height of the block in which the transaction is included. This field is automatically added by Node API.

See also: Exchange Transaction Validation

API Methods

• Place Limit Order
• Place Market Order
• Cancel Order
• Get Order Status
• Get Order History by Public Key
• Get Order History by Asset Pair and Public Key
• Get All Order History by Address
• Get Order by ID and Address (X-API-Key)
• Get Order by ID and Public Key (Signature)
• Get Tradable Balance
• Get Order Book
• Get Order Book Info
• Get Market Status
• Get Fee Rates
• Get Matcher Settings
• Get Matcher Public Key
• Get Current Offset
• Get Last Offset
• Get Oldest Snapshot Offset
• Get All Snapshot Offsets
• Save Snapshots
• Reserved Balance
• Delete Order Book
• Get Transactions By Order
• Force Cancel Order
• Upsert Rate
• Delete Rate
• Calculate Fee

Place Limit Order

Place a new limit order (buy or sell).

POST /matcher/orderbook

Request body contains JSON representation of an order.

Response example version 3:

{
  "success": true,
  "message": {
    "version": 3,
    "id": "FvwtRb62aCTqMo7R73xMZDMVLbyS949Gw1FdE3rp1a4W",
    "sender": "3P8pGyzZL9AUuFs9YRYPDV3vm73T48ptZxs",
    "senderPublicKey": "FuChbN7t3gvW5esgARFytKNVuHSCZpXSYf1y3eDSruEN",
    "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
    "assetPair": {
      "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
      "priceAsset": "8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS"
    },
    "orderType": "buy",
    "amount": 997736917,
    "price": 707,
    "timestamp": 1575983051927,
    "expiration": 1578488651926,
    "matcherFee": 13,
    "matcherFeeAssetId": "8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS",
    "signature": "3djG8HHtmuwp3RtuC1MSEiZQdFMNsxwmMmUysHLHYAyybRdTx7Un4BMgWf6dGznw7pnjeE6pBhNKinr2YfGFLPpN",
    "proofs": [
      "3djG8HHtmuwp3RtuC1MSEiZQdFMNsxwmMmUysHLYAyybRdTx7Un4BMgWf6dGznw7pnjeE6pBhNKinr2YfGFLPpN"
    ]
  },
  "status": "OrderAccepted"
}

For successfully placed order the success field is always true and the status field is always OrderAccepted.

Response example version 4:

{
  "success": true,
  "message": {
    "version": 4,
    "id": "HYEHXesh2g3RfcHGntGkk8vRa7Ndyks2SmW1ZtG7UsV",
    "sender": "3PDM3YNwii9tPRtA4TYGZp9jD1kHQKtubts",
    "senderPublicKey": "G9oVDzXqZiJeHUqTE4dX7AD7u9zTHae8c4oxcNwDRjzw",
    "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
    "assetPair": {
      "amountAsset": "WAVES",
      "priceAsset": "DG2xFkPdDwKUoBkzGAhQtLpSGzfXLiCYPEzeKH2Ad24p"
    },
    "orderType": "buy",
    "amount": 100000000,
    "price": 55000000,
    "timestamp": 1679316905713,
    "expiration": 1681822505713,
    "matcherFee": 39080922,
    "signature": "4aPvnzVinJeYR5mp78KhnKBprAuy8LZU1xnHKaYJZ5T6xMVcUXtn4mEsd1WQUFXTQzjcBFYzaCWKwJZkadKJRq6F",
    "proofs": [
      "4aPvnzVinJeYR5mp78KhnKBprAuy8LZU1xnHKaYJZ5T6xMVcUXtn4mEsd1WQUFXTQzjcBFYzaCWKwJZkadKJRq6F"
    ],
    "matcherFeeAssetId": "Atqv59EYzjFGuitKVnMRk6H8FukjoV3ktPorbEys25on",
    "eip712Signature": null,
    "priceMode": "assetDecimals",
    "attachment": "U1GmCKH5jS7hHMmFMQ677SpNwvhUSJJsRkYFTHJmLwkdpppdM8dvQZNL"
  },
  "status": "OrderAccepted"
}

Place Market Order

Place a new market order (buy or sell).

POST /matcher/orderbook/market

Request body contains JSON representation of an order.

Response body is the same as described in Place Limit Order.

For succesfully placed order the success field is always true and the status field is always OrderAccepted

Cancel Order

Cancel previously submitted order if it's not already filled completely. After an order is canceled it's removed from matcher's order book.

Cancel a Single Order

POST /matcher/orderbook/{amountAsset}/{priceAsset}/cancel

{
  "sender": "string",
  "orderId": "string",
  "signature": "string"
}

Request parameters:

Field name	Description
amountAsset	ID of the first asset in pair, or WAVES
priceAsset	ID of the second asset in pair, or WAVES
sender	Base58-encoded public key of order sender related to the address from which to spend/receive assets
orderId	Accepted order ID that sender wants to cancel
signature	Curve25519 (opens new window) signature of [sender public key bytes joined with order ID bytes]. For signing order the following client libraries (opens new window) can be used

Request example:

{
  "sender": "GHdnRxFWaMS7Wn39V1QneBe1N2WeovrbAYJ6ZRuXnuCc",
  "orderId": "2vs2ZqcdNfpoNSZfpBmtmJ2MBdYvjfS2s6Y4QuZNFsin",
  "signature": "3qE4ByvZTEPURVejNatVbBumCwAXTtquGRWmLaBjDs3WYc2u2CCUJNsF6BEZkYLtzsbncd1Qe4MKF5BdaKKNy6ed"
}

Response example:

{
  "orderId": "2vs2ZqcdNfpoNSZfpBmtmJ2MBdYvjfS2s6Y4QuZNFsin",
  "success": true,
  "status": "OrderCanceled"
}

Cancel All the Orders for the Specified Asset Pair

POST /matcher/orderbook/{amountAsset}/{priceAsset}/cancel

{
  "sender": "string",
  "timestamp": long,
  "signature": "string"
}

Request parameters:

Field name	Description
amountAsset	ID of the first asset in pair, or WAVES
priceAsset	ID of the second asset in pair, or WAVES
sender	Base58-encoded public key of order sender related to the address from which to spend/receive assets
timestamp	Unix time in milliseconds. It is used as a nonce
signature	Curve25519 (opens new window) signature of [sender public key bytes joined with timestamp bytes in the big-endian (opens new window) represenatation]. For signing order the following client libraries (opens new window) can be used

Request example:

{
  "sender": "5iePe4u2dHiRsAUeYjq83qpQoe7eKVeTxpLxYjFak8yQ",
  "timestamp": 1576684813260,
  "signature": "hZF8AQnaXkZwm5tAwdEA86k34AaZh82PjPexoQD9EPeejSAXMck8J4Q6Urf4ih2VCxssdXwVcVeUSrdicPmw3h6"
}

Response example:

  "success": true,
  "message": [
    [
      {
        "orderId": "8q1xW92Z7yd8u5j6kCfMydc8CCxNpmCVHUd97knh69Xw",
        "success": true,
        "status": "OrderCanceled"
      },
      {
        "orderId": "Hq6HpmkeY8bYh5grYHUBncUD8haBGDpns1CtirQr5qPs",
        "success": true,
        "status": "OrderCanceled"
      },
      {
        "orderId": "FWuTQ7qsGXTiA2QzAJERakaisNBSN7Dvya1DTqPgr78K",
        "success": true,
        "status": "OrderCanceled"
      },
      {
        "orderId": "4MsKTThrLJgSGdrz7hCYQZDJbcbrYKrgBjyCkAEyLgBJ",
        "success": true,
        "status": "OrderCanceled"
      }
    ]
  ],
  "status": "BatchCancelCompleted"
}

In the response, every item of message array represents a result of a single order cancellation.

Cancel All the Orders

POST /matcher/orderbook/cancel

{
  "sender": "string",
  "timestamp": long,
  "signature": "string"
}

Request parameters:

Field name	Description
sender	Base58-encoded public key of order sender related to the address from which to spend/receive assets
timestamp	Unix time in milliseconds. It is used as a nonce
signature	Curve25519 (opens new window) signature of [sender public key bytes joined with timestamp bytes in the big-endian (opens new window) represenatation]. For signing order the following client libraries (opens new window) can be used

Request and response body are the same as described in Cancel All the Orders for the Specified Asset Pair (only the URL is different).

Get Order Status

Get order status. Status is returned for orders submitted not earlier than 30 days ago. For earlier orders, Matcher can return NOT_FOUND.

GET /matcher/orderbook/{amountAsset}/{priceAsset}/{orderId}

Request parameters:

Field name	Description
amountAsset	ID of the first asset in pair, or WAVES
priceAsset	ID of the second asset in pair, or WAVES
orderId	Order ID to get status of

Response JSON example:

{
  "status": "PartiallyFilled",
  "filledAmount": 30000000000,
  "filledFee": 90000
}

Possible statuses:

Order Status	Description
Accepted	Order is accepted but is not filled yet
NotFound	Order with the given ID and asset pair is not found for the last 30 days
PartiallyFilled	Order is partially filled. Already filled amount is provided in filledAmount field, already paid Matcher fee is provided in filledFee field
Filled	Order is completely filled
Cancelled	Order was canceled. Already filled amount is provided in filledAmount field, already paid Matcher fee is provided in filledFee field

Get Order History by Public Key

Get order history for a given public key.

GET /matcher/orderbook/{publicKey}[?activeOnly=true]
Timestamp: {timestamp}
Signature: {signature}

Request parameters:

Field name	Description
publicKey	Base58-encoded public key of order sender
Timestamp	Unix time in milliseconds. It is used as a nonce
signature	Curve25519 (opens new window) signature of [sender public key bytes joined with timestamp bytes in the big-endian (opens new window) represenatation]. For signing order the following client libraries (opens new window) can be used

Possible query parameters:

activeOnly (false by default) - true or false. If true, then the list of active orders is returned.

Response example:

[
  {
    "id": "7VEr4T9icqopHWLawGAZ7AQiJbjAcnzXn65ekYvbpwnN",
    "type": "buy",
    "orderType": "limit",
    "amount": 7757865201004347,
    "fee": 6345852410462127,
    "price": 489,
    "timestamp": 1578074613225,
    "filled": 0,
    "filledFee": 0,
    "feeAsset": null,
    "status": "Accepted",
    "assetPair": {
      "amountAsset": "6rRegyHpdvZBENW4mowKYtKMDs2xpxmMbyNMRMZaZQ7",
      "priceAsset": "8pFqaP5CtPB4kP87gpu2T7vB4LxdfoH9e5mSPQduhCc"
    }
    "avgWeighedPrice": 489
  }
]

Response parameters:

Field name	Description
id	Order ID
type	Order type: "buy" or "sell"
orderType	Limit or market order
amount	Amount of amountAsset multiplied by 10^amountAssetDecimals. See Asset for more information
fee	Fee for the transaction
price	Price for amountAsset denominated in priceAsset and multiplied by 10^(8 + priceAssetDecimals – amountAssetDecimals)
timestamp	Unix time (opens new window) of order creation, in milliseconds. It is used as a nonce for the order
filled	Order is completely filled
filledFee	Already paid Matcher fee
feeAsset	The fee asset. If not specified (or null) then it is Waves
status	Order status
assetPair	The asset pair. See Asset Pair for more information
amountAsset	The amount asset
priceAsset	The price asset
avgWeighedPrice	Average weighted execution price. Calculated as follows: (cop1*ea1+cop2*ea2+...+copN*eaN)/filled amount, where cop1 = counter order 1 price, cop2 = counter order 2 price, ea1 = executed amount 1

Get Order History by Asset Pair and Public Key

Orders history for an asset pair and a public key. Returns account orders for a specified public key, filtered by the specified asset pair.

GET /matcher/orderbook/[amountAsset]/[priceAsset]/publicKey/[publicKey]

The request must contain the following headers:

Timestamp - current time. Signature - signature in base58: sender_public_key_bytes + timestamp_bytes.

Possible query parameters:

activeOnly (false by default) - true or false. If true, then the list of active orders is returned.

Response example:

[
  {
    "id": "7VEr4T9icqopHWLawGAZ7AQiJbjAcnzXn65ekYvbpwnN",
    "type": "buy",
    "orderType": "limit",
    "amount": 7757865201004347,
    "fee": 6345852410462127,
    "price": 489,
    "timestamp": 1578074613225,
    "filled": 0,
    "filledFee": 0,
    "feeAsset": null,
    "status": "Accepted",
    "assetPair": {
      "amountAsset": "6rRegyHpdvZBENW4mowKYtKMDs2xpxmMbyNMRMZaZQ7",
      "priceAsset": "8pFqaP5CtPB4kP87gpu2T7vB4LxdfoH9e5mSPQduhCc"
    }
    "avgWeighedPrice": 489
  }
]

See response parameters in Get Order History by Public Key.

Get All Order History by Address

History of orders by address. Returns all orders of the account with the specified address.

Note: This is system/admin method that requires API key.

GET /matcher/orders/[address]

Possible query parameters:

activeOnly (false by default) - true or false. If true, then the list of active orders is returned.

Response example:

[
  {
    "id": "7VEr4T9icqopHWLawGAZ7AQiJbjAcnzXn65ekYvbpwnN",
    "type": "buy",
    "orderType": "limit",
    "amount": 7757865201004347,
    "fee": 6345852410462127,
    "price": 489,
    "timestamp": 1578074613225,
    "filled": 0,
    "filledFee": 0,
    "feeAsset": null,
    "status": "Accepted",
    "assetPair": {
      "amountAsset": "6rRegyHpdvZBENW4mowKYtKMDs2xpxmMbyNMRMZaZQ7",
      "priceAsset": "8pFqaP5CtPB4kP87gpu2T7vB4LxdfoH9e5mSPQduhCc"
    }
    "avgWeighedPrice": 489
  }
]

See response parameters in Get Order History by Public Key.

Get Order by ID and Address

Returns order by address and order ID.

GET /orders/[address]/[orderId]

The request must contain X-API-Key header.

Response example:

{
  "id": "7VEr4T9icqopHWLawGAZ7AQiJbjAcnzXn65ekYvbpwnN",
  "type": "buy",
  "orderType": "limit",
  "amount": 7757865201004347,
  "fee": 6345852410462127,
  "price": 489,
  "timestamp": 1578074613225,
  "filled": 0,
  "filledFee": 0,
  "feeAsset": null,
  "status": "Accepted",
  "assetPair": {
    "amountAsset": "6rRegyHpdvZBENW4mowKYtKMDs2xpxmMbyNMRMZaZQ7",
    "priceAsset": "8pFqaP5CtPB4kP87gpu2T7vB4LxdfoH9e5mSPQduhCc"
  },
  "avgWeighedPrice": 489
}

The response parameters are the same as described in Get Order History by Public Key method but the resulting response is either one element or OrderNotFound error.

Get Order by ID and Public Key

Returns order by public key and order ID.

GET /orderbook/[publicKey]/[orderId]

The request must contain signature in base58: sender_public_key_bytes + timestamp_bytes

Response example:

{
  "id": "7VEr4T9icqopHWLawGAZ7AQiJbjAcnzXn65ekYvbpwnN",
  "type": "buy",
  "orderType": "limit",
  "amount": 7757865201004347,
  "fee": 6345852410462127,
  "price": 489,
  "timestamp": 1578074613225,
  "filled": 0,
  "filledFee": 0,
  "feeAsset": null,
  "status": "Accepted",
  "assetPair": {
    "amountAsset": "6rRegyHpdvZBENW4mowKYtKMDs2xpxmMbyNMRMZaZQ7",
    "priceAsset": "8pFqaP5CtPB4kP87gpu2T7vB4LxdfoH9e5mSPQduhCc"
  },
  "avgWeighedPrice": 489
}

The response parameters are the same as described in Get Order History by Public Key method but the resulting response is either one element or OrderNotFound error.

Get Tradable Balance

How much a wallet can spend in orders on the given pair. See Tradable Balance for more information.

GET /matcher/orderbook/{amountAsset}/{priceAsset}/tradableBalance/{address}

Response JSON example:

{
  "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8": 1997736917,
  "WAVES": 677728840
}

Amount of asset in JSON representation is multipied by 10^assetDecimals. So, in pair 4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8/WAVES the sender can spend 19.19.97736917 WEST and 6.77728840 WAVES. See Asset for more information.

Get Order Book

Get order book for the specified asset pair.

GET /matcher/orderbook/{amountAsset}/{PriceAssed}[?depth={depth}]

Request parameters:

Field name	Description
amountAsset	ID of the first asset in pair, or WAVES
priceAsset	ID of the second asset in pair, or WAVES
depth	[Optional] Limit the number of bid/ask levels returned

Notes about depth:

• The default and maximum depth is 100.
• You can specify either 10 or 100. If you choose another value, the near biggest will be chosen. For example, if you choose 3, you will get 10 records in bids and asks.
• These numbers can be changed in the future.

Response body contains JSON representation of order book.

Get Order Book Info

Get order restrictions for the specified asset pair.

GET /matcher/orderbook/{amountAsset}/{priceAsset}/info

Request parameters:

Field name	Description
amountAsset	ID of the first asset in pair, or WAVES
priceAsset	ID of the second asset in pair, or WAVES

Response example:

{
  restrictions = {
    "WAVES-8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS": {
      "min-amount": 0.001,
      "max-amount": 1000000,
      "step-amount": 0.00000001,
      "min-price": 0.001,
      "max-price": 100000,
      "step-price": 0.00000001
    }
  },
  "matchingRules": {
    "tickSize": "0.00000001"
  }
}

Response parameters:

Field name	Description
restrictions	Restrictions on the orders. null means that there are no restrictions
min-amount	The minimum order amount for the asset pair
max-amount	The maximum order amount for the asset pair
step-amount	Amounts in all the orders for the asset pair should be multiples of this step
min-price	The minimum order price for the asset pair
max-price	The maximum order price for the asset pair
step-price	Prices in all the orders for the asset pair should be multiples of this step
tickSize	The minimum price movement of an asset pair. See Tick Size for more information

Get Market Status

Get current market data such as last trade, best bid and ask.

GET /matcher/orderbook/{amountAsset}/{priceAsset}/status

Request parameters:

Field name	Description
amountAsset	ID of the first asset in pair, or WAVES
priceAsset	ID of the second asset in pair, or WAVES

Response example:

{
  "lastPrice": 921,
  "lastAmount": 100000000,
  "lastSide": "sell",
  "bid": 670,
  "bidAmount": 33379253731,
  "ask": 962,
  "askAmount": 1099442390
}

Response parameters:

Field name	Description
lastPrice	Price in the last ExchangeTransaction created.
lastAmount	Amount of amountAsset in the last ExchangeTransaction created
lastSide	Type of the last order executed by Matcher
bid	The best price of buy orders in the order book
bidAmount	Total amount of amountAsset multiplied by 10^amountAssetDecimals in buy orders on the best price level
ask	The best price of sell orders in the order book
askAmount	Total amount of amountAsset multiplied by 10^amountAssetDecimals in sell orders on the best price level

Get Fee Rates

Get current fee rates of assets.

Order sender can pay Matcher fee in any asset represented in the response.

GET /matcher/settings/rates

Response JSON example:

{
  "474jTeYx2r2Va35794tCScAXWJG9hU2HcgxzMowaZUnu": 0.0020016,
  "8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS": 0.00004062,
  "WAVES": 1
}

In this example, the ETH/WAVES rate is 0.0020016, so Fee_ETH = Fee_WAVES × 0.0020016.

In an order one should specify Fee_In_Asset_In_Order = Fee_WAVES × Rate_For_Asset × 10^asset_decimals, because matcher requires "normalized" values. Read more about asset_decimals (opens new window).

In this case (if there are no asset or matcher scripts involved) in an order one should specify the following value:

Fee_In_ETH_In_Order = 0.003 × 0.0020016 × 10^8 = 600.48 = 601 (rounded up)

Get Matcher Settings

GET /matcher/settings

Response JSON example (testnet):

{
  "orderVersions": [
    1,
    2,
    3
  ],
  "success": true,
  "rates": {
    "BrmjyAWT5jjr3Wpsiyivyvg5vDuzoX2s93WgiexXetB3": 0.003656,
    "5Sh9KghfkZyhjwuodovDhB6PghDUGBHiAPZ4MkrPgKtX": 9.256942,
    "EMAMLxDnv3xiz8RXg8Btj33jcEw3wLczL3JKYYmuubpc": 8.155223,
    "25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT": 20.08102,
    "WAVES": 1,
    "DWgwcZTMhSvnyYCoWLRUXXSH1RSkzThXLJhww9gwkqdn": 0.00023809,
    "3KFXBGGLCjA5Z2DuW4Dq9fDDrHjJJP1ZEkaoajSzuKsC": 1.42575
  },
  "matcherPublicKey": "8QUAqtTckM5B8gvcuP7mMswat9SjKUuafJMusEoSn1Gy",
  "orderFee": {
    "composite": {
      "default": {
        "dynamic": {
          "baseFee": 1000000
        }
      },
      "custom": {
        "5Sh9KghfkZyhjwuodovDhB6PghDUGBHiAPZ4MkrPgKtX-25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT": {
          "percent": {
            "type": "spending",
            "minFee": 0.1,
            "minFeeInWaves": 1000000
          }
        },
        "BrmjyAWT5jjr3Wpsiyivyvg5vDuzoX2s93WgiexXetB3-25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT": {
          "percent": {
            "type": "spending",
            "minFee": 0.1,
            "minFeeInWaves": 1000000
          }
        },
        "EMAMLxDnv3xiz8RXg8Btj33jcEw3wLczL3JKYYmuubpc-25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT": {
          "percent": {
            "type": "spending",
            "minFee": 0.1,
            "minFeeInWaves": 1000000
          }
        },
        "DWgwcZTMhSvnyYCoWLRUXXSH1RSkzThXLJhww9gwkqdn-25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT": {
          "percent": {
            "type": "spending",
            "minFee": 0.1,
            "minFeeInWaves": 1000000
          }
        },
        "WAVES-25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT": {
          "percent": {
            "type": "spending",
            "minFee": 0.1,
            "minFeeInWaves": 1000000
          }
        }
      },
      "discount": {
        "assetId": "EMAMLxDnv3xiz8RXg8Btj33jcEw3wLczL3JKYYmuubpc",
        "value": 50
      }
    }
  },
  "networkByte": 84,
  "matcherVersion": "2.3.10-22-g5a1a8057b",
  "status": "SimpleResponse",
  "priceAssets": [
    "AsuWyM9MUUsMmWkK7jS48L3ky6gA1pxx7QtEYPbfLjAJ",
    "25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT",
    "3KFXBGGLCjA5Z2DuW4Dq9fDDrHjJJP1ZEkaoajSzuKsC",
    "D6N2rAqWN6ZCWnCeNFWLGqqjS6nJLeK4m19XiuhdDenr",
    "DWgwcZTMhSvnyYCoWLRUXXSH1RSkzThXLJhww9gwkqdn",
    "EBJDs3MRUiK35xbj59ejsf5Z4wH9oz6FuHvSCHVQqZHS",
    "WAVES",
    "25BEcPNiopW1ioBveCZTaDTVPci2o9ZLkqCELHC2GYoZ",
    "BrmjyAWT5jjr3Wpsiyivyvg5vDuzoX2s93WgiexXetB3",
    "BNdAstuFogzSyN2rY3beJbnBYwYcu7RzTHFjW88g8roK",
    "CFg2KQfkUgUVM2jFCMC5Xh8T8zrebvPc4HjHPfAugU1S",
    "8HT8tXwrXAYqwm8XrZ2hywWWTUAXxobHB5DakVC1y6jn",
    "7itsmgdmomeTXvZzaaxqF3346h4FhciRoWceEw9asNV3",
    "DGgBtwVoXKAKKvV2ayUpSoPzTJxt7jo9KiXMJRzTH2ET",
    "FvKx3cerSVYGfXKFvUgp7koNuTAcLs8DmtmwRrFVCqJv",
    "3P8gkhcLhFQvBkDzMnWeqqwvq3qxkpTNQPs4LUQ95tKD",
    "8oPbSCKFHkXBy1hCGSg9pJkSARE7zhTQTLpc8KZwdtr7"
  ]
}

Response parameters:

Field name	Description
orderFee	Order fee mode. Can be "dynamic" or "percent". Read more about dynamic and percent mode
priceAssets	List of the price assets. See Asset Pair for more information
baseFee	Matcher fee for completely executed order specified in WAVELETs. See Matcher Fee for more information
rates	Current fee rates of assets. See Get Fee Rates for more information
orderVersions	Order versions that are supported by Matcher
matcherPublicKey	Matcher public key in Base58
networkByte	Chain ID (opens new window) (blockchain setting that affects the forming of an address)
assetId	ID of the fee asset
minFee	Minimum fee in smallest units of the specified asset
type	The type of fee asset. Can be "amount" - the amountAsset, "price" - the priceAsset, "spending" - the asset that is spent (for example, for BUY-order of WAVES/BTC it will be BTC) or "receiving" - the asset that will be received

Get Matcher Public Key

GET /matcher

Response example:

GZXGbB4Tn4iSBGRuoufWMwNa6KkNxeYtXk7tT97xghU8

Get Current Offset

The current offset in the queue.

Note: This is system/admin method that requires API key.

Returns the number of processed commands. Possible commands:

Placing order Cancelling order Deleting order book

GET /matcher/debug/currentOffset

Request example:

curl --header 'X-API-Key: foobar' 'https://matcher.waves.exchange/matcher/debug/currentOffset'

where "X-API-Key" - is the matcher API key.

Response example:

20323255542

Get Last Offset

The last offset in the queue. Number of registered commands. The commands are sent to the queue after validation, then the matcher (or several matchers) subtracts them from the queue and processes them by moving currentOffset.

Note: This is system/admin method that requires API key.

GET /matcher/debug/lastOffset

Response example:

30150375999

Get Oldest Snapshot Offset

Offset of the oldest snapshot.

Note: This is system/admin method that requires API key.

Registered commands are in the same queue. Each matcher reads and processes them and then changes their internal state. All commands are addressed to an order book. For example, for a command to cancel an order the processing is that we are trying to remove this order from the order book. The order book without this order is the new state of the order book. On the start of the matcher, we could re-read all the commands in the whole history and, thus, restore the state of all order books as they were before the restart, but this is slow, so we do snapshots from time to time - casts of a state with a note "this snapshot is made on such an offset". Then for a given order book, we can ignore commands with an offset less than the snapshot offset. The old snapshots are not needed, so we only have one snapshot for each order book.

The most important thing is why this REST API method is needed. The state of the matcher can be restored from the state of all order books, so to restore it, you need to restore all the order books. We could just subtract all the commands from the queue, the order books would ignore the “junk” anyway, but it is still not fast enough. Therefore, we start reading from the offset, from which it makes sense to read, namely, from the offset of the oldest snapshot among all the order books.

GET /matcher/debug/oldestSnapshotOffset

Response example:

1000000

Get All Snapshot Offsets

Returns offsets of all order books.

Note: This is system/admin method that requires API key.

GET /matcher/debug/allSnapshotOffsets

Response example:

{
  "WAVES-6T9WPGs6b3jwZBPY6MEFmSqLDqdyBkHnZxhvweS4ffbo": 100,
  "5MztYaKDhTPLZxJkckUaHPKQkc917sCKCALKChAfungp-WAVES": 120
}

Save Snapshots

Creates snapshots of all order books.

Note: This is system/admin method that requires API key.

Initiates forced creation of snapshots of all order books. The response from the matcher will come immediately, without waiting for all snapshots to be made. You can track progress through getAllSnapshotOffsets.

This method can be useful with some updates. In this case, before sending request it is necessary to stop receiving new commands.

POST /matcher/debug/saveSnapshots

Response example:

{
  "message": "Saving started"
}

Reserved Balance

Returns the balance of the reserved assets for the account of the specified public key.

GET /matcher/balance/reserved/[publicKey]

Response example:

{ "WAVES": 350 }

Delete Order Book

Important: Before deleting an order book, stop trading on this pair.

Note: This is system/admin method that requires API key.

DELETE /matcher/orderbook/[amountAsset]/[priceAsset]

Returns empty order book.

Response example:

{
  "timestamp": 1576143739568,
  "pair": {
    "amountAsset": "4vSJeAji4F7swJazJdZWau9drG1RjFL8QKSx13F7RjKQ",
    "priceAsset": "WAVES"
  },
  "bids": [],
  "asks": []
}

Get Transactions By Order

Returns transactions by order id.

GET /matcher/transactions/[orderId]

Returns the list of all the transactions that contain the order. The following transaction format is used.

Response example (for mainnet order F8HRQv7LzHUeaE3UetpKxiN7ue1tDmvMAD8VKJyaXeMb):

[
  {
    "senderPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
    "amount": 143748861,
    "fee": 300000,
    "type": 7,
    "version": 2,
    "sellMatcherFee": 37142,
    "sender": "3PEjHv3JGjcWNpYEEkif2w8NXV4kbhnoGgu",
    "feeAssetId": null,
    "proofs": [
      "4WpVKo7s8FgV8y4NG5qStsbZHhwU5c5JBW2RNN1GhwNkPwDfQVhyShSCJw5DyJfzFjrzUi6hwqrm8vcWTadJM4mt"
    ],
    "price": 6051001,
    "id": "CYnpQjUmg6Zog1qoQCEymhUbEJx5xWSnn5UHMsM1nXLL",
    "order2": {
      "version": 1,
      "id": "F8HRQv7LzHUeaE3UetpKxiN7ue1tDmvMAD8VKJyaXeMb",
      "sender": "3P3jStCJsrqgxCeNu5rhXmgQ6qgvdzNmHn5",
      "senderPublicKey": "9wUzxjWd1miFxohhLtMyLMMAny1Ha5M3GLvSFFwB4m7u",
      "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
      "assetPair": {
        "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
        "priceAsset": null
      },
      "orderType": "sell",
      "amount": 1161045582,
      "price": 6050625,
      "timestamp": 1580120181196,
      "expiration": 1582625781196,
      "matcherFee": 300000,
      "signature": "2nVvFtmsvMj32LuQqgVGDYt5tjFYNv1vdEVRceztakKaH4fLo9D4VQMYJU8Kscg46xHLmRhA9HRAkxVxMkiE8QvA",
      "proofs": [
        "2nVvFtmsvMj32LuQqgVGDYt5tjFYNv1vdEVRceztakKaH4fLo9D4VQMYJU8Kscg46xHLmRhA9HRAkxVxMkiE8QvA"
      ]
    },
    "order1": {
      "version": 2,
      "id": "Bj2TGtbzQ8r11vYMT79vSHbYdAyxKSEcjc5tEUgmyNkE",
      "sender": "3PFBsj8qw2trA3a9XLaUurpqVQMnZdPvHNG",
      "senderPublicKey": "tQfmt5yyFPaWJQ5wrFNfpecAjXqz3qaB8dTEM4aaWj2",
      "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
      "assetPair": {
        "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
        "priceAsset": null
      },
      "orderType": "buy",
      "amount": 13313799552,
      "price": 6051001,
      "timestamp": 1580119693927,
      "expiration": 1582625293926,
      "matcherFee": 300000,
      "signature": "29kbTDR4b5g4LByEbPibhyYpWWqPDGeSBVHGj5gELAB4KbCbKp8CLajyZVTCJV96fsQ8Sxpjbh3UT7WG9uaMgWTV",
      "proofs": [
        "29kbTDR4b5g4LByEbPibhyYpWWqPDGeSBVHGj5gELAB4KbCbKp8CLajyZVTCJV96fsQ8Sxpjbh3UT7WG9uaMgWTV"
      ]
    },
    "buyMatcherFee": 3239,
    "timestamp": 1580120181256
  },
  {
    "senderPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
    "amount": 1017296712,
    "fee": 300000,
    "type": 7,
    "version": 2,
    "sellMatcherFee": 262857,
    "sender": "3PEjHv3JGjcWNpYEEkif2w8NXV4kbhnoGgu",
    "feeAssetId": null,
    "proofs": [
      "5wvaB6z7PojKU7LvubkaMzjcoDtxuhTTP2mzgPdpr8dHgwS2LJb4a2KX15tRQXzY5dcbCCEc9q6wiRibTtmW4epX"
    ],
    "price": 6051000,
    "id": "GXSSX7j8pZWMoWgFZn8gqL4te4aFPfParhxFHeDPp9Nq",
    "order2": {
      "version": 1,
      "id": "F8HRQv7LzHUeaE3UetpKxiN7ue1tDmvMAD8VKJyaXeMb",
      "sender": "3P3jStCJsrqgxCeNu5rhXmgQ6qgvdzNmHn5",
      "senderPublicKey": "9wUzxjWd1miFxohhLtMyLMMAny1Ha5M3GLvSFFwB4m7u",
      "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
      "assetPair": {
        "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
        "priceAsset": null
      },
      "orderType": "sell",
      "amount": 1161045582,
      "price": 6050625,
      "timestamp": 1580120181196,
      "expiration": 1582625781196,
      "matcherFee": 300000,
      "signature": "2nVvFtmsvMj32LuQqgVGDYt5tjFYNv1vdEVRceztakKaH4fLo9D4VQMYJU8Kscg46xHLmRhA9HRAkxVxMkiE8QvA",
      "proofs": [
        "2nVvFtmsvMj32LuQqgVGDYt5tjFYNv1vdEVRceztakKaH4fLo9D4VQMYJU8Kscg46xHLmRhA9HRAkxVxMkiE8QvA"
      ]
    },
    "order1": {
      "version": 2,
      "id": "AUnmye7T3gCgGV6x9Kyoet93MTjY8mRCUumBqEHhLq8x",
      "sender": "3PAtZYEC9aPKWuSk6n9UAUQfMEHebiBFmjH",
      "senderPublicKey": "33Sn6veKXe2b2PcRtm8iSEmrQyFprD9LWVEQfeCa1f4D",
      "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
      "assetPair": {
        "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
        "priceAsset": null
      },
      "orderType": "buy",
      "amount": 1000000000000,
      "price": 6051000,
      "timestamp": 1580116419182,
      "expiration": 1582622019181,
      "matcherFee": 300000,
      "signature": "mgqQR1ZY4d4BAc2iEXxpfzzLjCemNgQadWuA1p17sE6ZGe8tmdxk88yqFRi15656QD5LKmLM5czmqg1UBgg2s7t",
      "proofs": [
        "mgqQR1ZY4d4BAc2iEXxpfzzLjCemNgQadWuA1p17sE6ZGe8tmdxk88yqFRi15656QD5LKmLM5czmqg1UBgg2s7t"
      ]
    },
    "buyMatcherFee": 305,
    "timestamp": 1580120181256
  }
]

Force Cancel Order

Similar to Cancel a Single Order, but does not require public key and signature.

Note: This is system/admin method that requires API key.

POST /matcher/orders/cancel/[orderId]

Upsert Rate

Setup rate by asset.

Note: This is system/admin method that requires API key.

The functionality of rates allows to pay fee for an order in Waves or other assets, such as BTC, if the exchange allows it.

How to caclulate rates:

1. You calculate the fee for the order in Waves (taking scripts into account. The base fee of 0.003 Waves + 0.004 for each script run). You can check if an asset has script by requesting the info from the node by the asset ID. Scripts can not be removed from an asset or added to an asset that does not have it.

2. Multiply the resulting number by the rate of the desired asset (for example, BTC) to get the fee for the order.

3. In the order, specify the calculated fee and the asset ID (for example, matcherFeeAssetId = BTC)

The upsertRate method allows to:

• Add new rate for an asset if it is not specified
• Update existing rate

This action updates the list of existing rates.

PUT /matcher/settings/rates/[assetId]

Response example, when adding rate:

{
  "message": "The rate 0.0055 for the asset 42KBAA1CMC7vV7AfHKVapTgNJS1T48YFoi92zU2pLhAF added"
}

Response example, when updating rate:

{
  "message": "The rate for the asset 42KBAA1CMC7vV7AfHKVapTgNJS1T48YFoi92zU2pLhAF updated, old value = 0.0055, new value = 0.0067"
}

Delete Rate

Delete rate to remove the fee in specified asset.

Note: This is system/admin method that requires API key.

This action updates the list of existing rates.

DELETE /matcher/settings/rates/[assetId]

Response example:

{
  "message": "The rate for the asset 4SsamnLQ9ETZR9jj5AvyucjUeuLp44uAHmokNm1VoY6L deleted, old value = 0.0067"
}

Calculate Fee

Returns calculated fee for a given pair of assets (amountAsset and priceAsset).

POST /matcher/orderbook/{amountAsset}/{priceAsset}/calculateFee

Request parameters:

Field name	Description
orderType	Type of order. sell or buy
price	Order price. The price for amountAsset denominated in priceAsset and multiplied by 10^(8 + priceAssetDecimals – amountAssetDecimals)
amount	Order amount. The amount of amountAsset multiplied by 10^amountAssetDecimals. See Asset for more information

Request example (testnet):

curl -X 'POST' \
  'https://matcher-testnet.waves.exchange/matcher/orderbook/EMAMLxDnv3xiz8RXg8Btj33jcEw3wLczL3JKYYmuubpc/3KFXBGGLCjA5Z2DuW4Dq9fDDrHjJJP1ZEkaoajSzuKsC/calculateFee' \
  -H 'Content-Type: application/json' \
  -d '{ "orderType": "sell", "amount": 1000000, "price": 328611200 }'

Response example (testnet):

{
  "base" : {
    "feeAssetId" : "3KFXBGGLCjA5Z2DuW4Dq9fDDrHjJJP1ZEkaoajSzuKsC",
    "matcherFee" : 100500
  },
 
  "discount" : {
    "feeAssetId" : "EMAMLxDnv3xiz8RXg8Btj33jcEw3wLczL3JKYYmuubpc",
    "matcherFee" : 50250
  },
}

SDK

Use the WavesJ (opens new window) client library to interact with Matcher.