# Order

Order is a request for exchange one token (asset) for another sent to matcher. A matcher is a service that executes orders and sends Exchange transactions. Each order contains the public key of the matcher's account and cannot be executed by another matcher.

An order appears on the blockchain only as part of an Exchange transaction. Until the order is fully or partially executed, there is no information about it on the blockchain. For more information on order execution, see the Exchange Transaction article.

To learn how to create an order, see the How to exchange tokens article.

Each matcher independently sets the minimum matcher fee and the list of tokens acceptable as fee assets. See the Matcher Fee for details. A matcher can also have its own restrictions on accepting orders, in addition to the rules for validating orders on the blockchain, such as: banlist of senders and assets, order of assets in a pair, minimum amounts to exchange, etc.

# JSON Representation

Here is the JSON representation of an order in Waves node REST API:

{
   "version": 3,
   "id": "72iHDmfr7VWH1cbuP4FjscUU1kcW8CJ629ctVKMyDLBm",
   "sender": "3PB4PKHZ69qtxtQi4zTjcpisyUbEYgs6CD1",
   "senderPublicKey": "3g4rdPwkZmjSe18MGuZtVLtiN1uQ1fP4eqnHYjApoSU5",
   "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
   "assetPair": {
      "amountAsset": "6nSpVyNH7yM69eg446wrQR94ipbbcmZMU1ENPwanC97g",
      "priceAsset": null
   },
   "orderType": "buy",
   "amount": 15637504,
   "price": 12114051100,
   "timestamp": 1637671821599,
   "expiration": 1637844621599,
   "matcherFee": 300000,
   "signature": "2YjtusNiBzevq23v7wV8tkt5Ri1vtmDAoW5qhRThcpUqqZcyP6joqe7StMXyLaXjM6rYCe1tPMB973Sq9TPRfcsU",
   "proofs": [
      "2YjtusNiBzevq23v7wV8tkt5Ri1vtmDAoW5qhRThcpUqqZcyP6joqe7StMXyLaXjM6rYCe1tPMB973Sq9TPRfcsU"
   ],
   "matcherFeeAssetId": null
}

Field	Description
version	Order version
id	Order ID base58 encoded. The order ID is calculated similarly to the transaction ID, see the Cryptographic practical details article
sender	Address of the order sender: base58 encoded byte array
senderPublicKey	Public key of the order sender: base58 encoded byte array
matcher_public_key	Public key of the matcher the order is sent to: base58 encoded byte array
assetPair.amountAsset	ID of the amount asset (base currency): base58 encoded byte array. `null` means WAVES
assetPair.priceAsset	ID of the price asset (quote currency): base58 encoded byte array. `null` means WAVES
orderType	Order type: • buy: the sender receives the amount asset, • sell: the sender spends the amount asset
amount	Amount of the amount asset: an integer value specified in the atomic units
price	Price for the amount asset nominated in the price asset, multiplied by the factor: • 10⁸ for order version 4 with the `"priceMode": "fixedDecimals"` parameter or without the `"priceMode"` parameter; • 10^{8 + priceAssetDecimals – amountAssetDecimals} for order version 4 with the `"priceMode": "assetDecimals"` parameter and for order version 3, 2, or 1. Here `amountAssetDecimals` and `priceAssetDecimals` are the number of decimal places of amount asset and price asset respectively (token parameter). Integer value. See explanation below
priceMode	Mode of specifying the `price` field. The field is enabled by feature #17 “Ride V6, MetaMask support”
timestamp	Order timestamp: Unix time in milliseconds
expiration	Datetime when the order will be expired: Unix time in milliseconds
matcherFee	Matcher fee: an integer value specified in the atomic units of the fee asset
signature	• Signature of the sender in order version 1. • In later order versions, the first element of the `proofs` array is returned
proofs	Order proofs used for its verification, similar to transaction proofs. Up to 8 proofs, each proof up to 64 bytes base58 encoded. Missed if the order is signed in MetaMask
eip712Signature	For an order signed in MetaMask: ECDSA signature in HEX encoding. MetaMask support is enabled by feature #17 “Ride V6, MetaMask support”. See details in the Sign transactions and orders in MetaMask article
matcherFeeAssetId	ID of the token in which the matcher fee is specified: base58 encoded byte array. `null` means that the fee is specified in WAVES
attachment	Arbitrary data, up to 1024 bytes, base58 encoded. The field is enabled by feature #22 “Light Node”

Explanation:

The above order is a request to buy 15.637504 NSBT at a price not higher than 1.21140511 WAVES for 1 NSBT.

The amount asset is NSBT, amountAssetDecimals is 6.

The price asset is WAVES, priceAssetDecimals is 8.

The amount value in the order is 15.637504 × 10^{amountAssetDecimals} = 15637504.

The price value in the order is 1.21140511 × 10^{8 + priceAssetDecimals – amountAssetDecimals} = 12114051100 (because the order version is 3).

Normalization

All numbers on the blockchain are integers to avoid rounding errors. An order (fully or partially executed) appears on the blockchain as a part of an Exchange transaction, so the amount and price values in the order signed by a user must be integers.

To represent a floating-point value as an integer, you should normalize it, that is, multiply the actual value by some factor of 10ⁿ.

The amount field contains the amount of the asset, so a factor of 10^{amountAssetDecimals} is used for normalization.

However, the price field contains not an amount, but a ratio. The price dimension depends on both assets in the pair, just like the price of apples is measured, for example, in dollars per kilogram, but not in dollars. In the example above, the price unit is WAVES/NSBT. That's why the following the following normalization factor is chosen to normalize the price in order versions 1, 2, 3:

10⁸ × (10^{priceAssetDecimals} / 10^{amountAssetDecimals}) = 10^{8 + priceAssetDecimals – amountAssetDecimals}.

The 10⁸ multiplier is needed because priceAssetDecimals can be less than amountAssetDecimals.

Note that the maximum value of the normalized price is 9,223,372,036,854,775,807, which is the maximum allowed number on the blockchain. If priceAssetDecimals = 8 and amountAssetDecimals = 0, then the normalization factor is 10¹⁶. Therefore, the real price cannot exceed 922.3372036854775807. For example, in case of exchanging a NFT for WAVES, the maximum value of NFT is less than 1000 WAVES. To eliminate this limitation, the order version 4 added the option to select the normalization factor:

10⁸ in "priceMode": "fixedDecimals",
10^{8 + priceAssetDecimals – amountAssetDecimals} in "priceMode": "assetDecimals".

Amount of the price asset

The order specifies only the amount of the amount asset (which is transferred from the seller to the buyer) and the price. Based on these values, the amount of the price asset is calculated (which is transferred from the buyer to the seller in exchange for the amount asset). The amount of the price asset in atomic units is calculated as follows:

in order version 4 with the "priceMode": "fixedDecimals" parameter or without priceMode parameter:

amount × price × 10^{(priceAssetDecimals - amountAssetDecimals - 8)}
in order version 4 with the "priceMode": "assetDecimals" parameter and in order version 3, 2, or 1:

amount × price × 10^-8.

(amount and price are normalized values specified in the order.)

If the result is a value with a fractional part, the fractional part is discarded.

For example, in the order of version 3 listed above, the amount of the price asset is calculated as:

15637504 × 12114051100 × 10^-8 = 1894335225.324544,

after discarding the fractional part the result is 1894335225 in atomic units, which corresponds to 18.94335225 WAVES.

# Order Binary Format

See the Order Binary Format article.

# Ride Structure

The Order structure is used for order handling in smart contracts.