Order#

Order is the instruction from the account to matcher to buy or sell a token on the exchange.

Asset Pair#

Each order contains amount asset / price asset pair, also called asset pair.

Example

"assetPair": {
    "amountAsset": "3QvxP6YFBKpWJSMAfYtL8Niv8KmmKsnpb9uQwQpg8QN2",
    "priceAsset": "null"
}

Asset Pair Fields

Asset Pair Fields#

Field name

Description

amountAsset

ID of the pair’s first asset, that the order’s sender wants to buy or sell.

priceAsset

ID of the pair’s second asset, in which the price of the order is expressed. null value means that asset is DecentralCoins.

Order’s Amount and Price#

In the user interface, the amount and price are usually presented as values with a fractional part (for example, \(0.74585728\) DecentralCoins), i.e. in the denormalized form. The denormalized form is convenient for humans, but not for calculations. To solve the problem of calculation accuracy, the normalization is performed.

In the user interface, the amount and price are usually presented as values with a fractional part (for example, \(0.74585728\) DecentralCoins), i.e. in the denormalized form. The denormalized form is convenient for humans, but not for calculations. To solve the problem of calculation accuracy, the normalization is performed, i.e. amount and price are represented as an integer. So, \(0.74585728\) DecentralCoins is \(0.74585728 × 10^{8}\) or \(74585728\) Decentralites. In this case, the exponent is \(8\), because DecentralCoins has \(8\) decimals after the decimal point. Other assets may have different amount of decimals. For example, TDX has 2 decimals.

Amount#

Consider buying \(2.13\) TDX at the price of \(0.35016774\) DecentralCoins for one TDX. Here the asset pair is TDX / DecentralCoins. The amount in the order is the number of units sold or bought in conventional «pennies». This value in the current case is \(213\), since \(2.13\) TDX \(= 2.13 × 10^{2}\) = 213` «pennies» of TDX. So, to bring the amount to the normalized form, it is multiplied by \(10^{amountAssetDecimals}\).

Price#

Price is the value of 1 unit of the amount asset, expressed in the price asset. In the TDX / DecentralCoins example above, this is the price in DecentralCoins for 1 TDX. To normalize price, it is multiplied by:

  • In orders of versions 1, 2, 3: \(10^{(8 + priceAssetDecimals - amountAssetDecimals)}\).

  • In orders of version 4: at \(10^{8}\).

The exponent of \(8\) is selected because there cannot be an asset with the exceeding quantity of decimals on the DecentralChain blockchain. The matcher algorithm has a limitation in relation to price: the last N digits of the normalized price must be zeros (N is price_decimals minus amount_decimals). If this is not so, then the matcher rejects the order on placement.

Price Asset Quantity Calculation#

The quantity of price asset in normalized form which:

  • Will be given by sender if order is BUY.

  • Will be acquired by sender if order is SELL.

Is calculated by the following formula: amount × price × \(10^{(priceAssetDecimals - amountAssetDecimals - 8)}\).

  • In orders of versions 1, 2, 3: amount × price × \(10^{-8}\)

  • In orders of version 4: amount × price × \(10^{(priceAssetDecimals - amountAssetDecimals - 8)}\).

If the result of the calculation is a value with a fractional part, then the fractional part is discarded. Designations in the above formula:

  • Amount — amount in normalized form.

  • Price — price in normalized form.

  • PriceAssetDecimals — the number of decimal places of the price asset.

  • AmountAssetDecimals — the number of decimal places of the amount asset.

Order Cancellation#

The order sender may cancel the order before it is executed. Unexecuted orders are automatically canceled at the date and time specified by the order sender.

Order Expiration Date#

Order expiration date is the date and time of automatic cancellation of an unexecuted order. The date is specified in milliseconds which have passed since the beginning of the unix epoch. The expiration time can’t be earlier than matcher time + \(1\) minute and later than matcher time + \(30\) days.

Order Timestamp#

Order timestamp is the time when the matcher added the order to the order book. The time is specified in milliseconds that have passed since the beginning of the unix epoch.

Order Binary Format#

See the order binary format page.