Creating a Sell Order

If you want to buy some tokens on 21X DLT Exchange, you need to follow these steps:

Step 1: Encode the order data

First, you need to encode the order data of price and quantity into a payload data structure. The price is the amount of quote tokens you ask for each unit of the base token you want to sell. The quantity is the number of base tokens you want to sell. You can use the following formula to encode the order data:

scaled_quantity = quantity * baseTokenInternalScale
scaled_price = price * quoteTokenInternalScale
order_data = (scaled_quantity << 256) | scaled_price

Internal scales help achieve consistent form for the user interface and transactional engine. They are available through the API endpoint getTradingPair.

This can be considered as the basic setup. Optionally, the order book offers additional order flags that you can use to control the way in which your order is processed.

For example, if you want to sell 100 tokens at a price of 0.01 currency tokens each, the base (asset) internal scale is 10 000 000 000, the quote (currency) internal scales is 10 000, and your order is a Limit Order with BookOrCancel condition which should live for 90 days, you can encode the order data as:

scaled_quantity = 0.01 * 10 000 000 000
scaled_price = 100 * 10 000
full_word = 256
order_data = (scaled_quantity << full_word) | scaled_price

order_type = 0
execution_condition = 2 
lifetime = 90
order_data = order_data << full_word | order_type
order_data = order_data << full_word | execution_condition
order_data = order_data << full_word | lifetime

Step 2: Calculate the quantity to approve

Next, you need to calculate the quantity of base tokens that you need to approve for the exchange to spend on your behalf. This calculation is done in the (base) token's native scale. For sell orders, this is the total number of base tokens that you are willing to sell. You can use the following formula to calculate the quantity to approve:

quantity_to_approve = order_quantity * baseTokenNativeScale

For example, if you want to sell 99 tokens, you can calculate the quantity to approve as:

quantity_to_approve = 99 * 1 000 000 000 000 000 000

assuming that baseTokenNativeScale returned by the API endpoint for the corresponding trading pair is 1 000 000 000 000 000 000 (10^18).

Step 3: Prepare additional payload data

There are two additional pieces of order payload that are optional, but can be used to control the behavior of the system.

The cross-identifier can be set to an arbitrary 32bit number that is checked during order matching. Orders that were sent from the same wallet but have different cross-identifiers will not trigger an order rejection because of a self-trade. If the cross-identifier is not provided, it defaults to 0.

The reporting_data can take 256 bits of arbitrary data (encoded as an integer value). The 21X backend will use the last (least significant) 32 bits of the reportingData to try to determine an execution decision maker by cross-referencing them to the referenceNumber field of applicable persons. If successful, the person will be included in the report as the decision maker, otherwise the decision maker will stay empty.

The rest of reporting_data will not be interpreted by the 21X backend, so you can store any data in there, for example to match the order to your own system later on.

Step 4: Approve the allowance

Then, you need to call the approve function of the product token contract to set the allowance of the exchange contract. The approve function takes two arguments: the address of the spender and the amount of tokens to allow. The amount is simply the quantity you want to sell in the product token's native scale. You can use the following code snippet to approve the allowance:

from web3 import Web3
w3 = Web3(Web3.HTTPProvider('http://localhost:8545')) # connect to your local node
my_wallet = '0x123456789abcdef' # your wallet address
base_token_address = '0xabcdef123456789' # the address of the base token contract
exchange_address = '0x789abcdef123456' # the address of the order book smart contract
base_token_contract = w3.eth.contract(address=base_token_address, abi=base_token_abi) # load the base token contract
approve_tx = base_token_contract.functions.approve(exchange_address, quantity_to_approve).buildTransaction({'from': my_wallet}) # build the approve transaction
signed_tx = w3.eth.account.sign_transaction(approve_tx, private_key=my_private_key) # sign the transaction with your private key
tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction) # send the transaction
w3.eth.wait_for_transaction_receipt(tx_hash) # wait for the transaction to go through

Step 5: Create a sell order

Finally, you need to call the newSellOrder function of the order book contract to create a sell order. The newSellOrder function takes three arguments: the encoded order data (mandatory), the reporting data and the cross-identifier. You can use the following code snippet to create a sell order:

order_book_address = '0x456789abcdef123' # the address of the order book contract
order_book_contract = w3.eth.contract(address=order_book_address, abi=order_book_abi) # load the order book contract
reporting_data = '' # no explicit reporting information
cross_identifier = 0 # self-trade prevention active
sell_order_tx = order_book_contract.functions.newSellOrder(order_data, reporting_data, cross_identifier).buildTransaction({'from': my_wallet}) # build the buy order transaction
signed_tx = w3.eth.account.sign_transaction(sell_order_tx, private_key=my_private_key) # sign the transaction with your private key
tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction) # send the transaction
w3.eth.wait_for_transaction_receipt(tx_hash) # wait for the transaction to go through

Congratulations! You have successfully created a sell order on 21X DLT Exchange