• English
  • Русский

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

# Entities

Here are the main entities the matcher works with:

# Asset

Every asset, except WAVES, has an ID.

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

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

# Serialize Order

Serializes an order: converts its JSON representation into a binary one (byte array). The binary representation is essential to generate a proof, which is a Curve25519 (opens new window) signature of the order bytes with the sender's private key.

POST /matcher/orders/serialize/

Request body contains JSON representation of an order except proofs.

Response body contains the binary representation base58-encoded.

# 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

Provides the current asset rates used to calculate order fees (amount of asset per 1 WAVES).

GET /matcher/settings/rates

Response JSON example:

{
   "DGbqkzM6Ds5NAF2B3GHYfyZRmWKt7xLYRYcwpMm7D6V4": 438.6616843229651,
   "Atqv59EYzjFGuitKVnMRk6H8FukjoV3ktPorbEys25on": 129.74000408278798,
   "WAVES": 1
}

In this example, the WX rate is 129.74000408278798, so

Fee_WX = Fee_WAVES × 129.74000408278798

In an order a normalized fee value must be specified:

Fee_In_Asset_In_Order = Fee_WAVES × Rate_For_Asset × 10^asset_decimals

Read more about asset_decimals (opens new window).

For example, if the order fee is equivalent to 0.01 WAVES and is paid in WX, the order should include the following value (rounded up to the nearest integer):

Fee_In_WX_In_Order = 0.01 × 129.74000408278798 × 10^8 = 129 740 005

# Get Matcher Settings

GET /matcher/settings

Response JSON 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"
            ],
            "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"
   ]
}

Response parameters:

Field name Description
orderVersions Order versions that are supported by Matcher
rates Current asset rates used to calculate order fees. See the Get Fee Rates section above for details
matcherPublicKey Matcher public key base58-encoded
orderFee Parameters used to calculate order fees. See the Matcher Fee article for details
networkByte Chain ID (opens new window) that affects the forming of an address
priceAssets List of the price assets used to determine which asset is a price asset in an asset pair. See the Asset Pair section above for details

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

Matcher Settings
Order Validation