Creating a Buy 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 are willing to pay for each unit of the base token you want to buy. The quantity is the number of base tokens you want to buy. 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 buy 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 scale 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 currency tokens that you need to approve for the exchange to spend on your behalf. This calculation is done in the (quote) token's native scale. For buy orders, this is the total amount of quote tokens that you are willing to pay for your order, plus necessary fees. You can use the following formula to calculate the quantity to approve:

quantity_to_approve = price * order_quantity * (1.0 + max(maker_commission, taker_commission) / 10000) * quoteTokenNativeScale

For example, if you want to buy 100 tokens at a price of 0.01 quote (currency) tokens each, and the commission values are 20 basis points each, you can calculate the quantity to approve as:

quantity_to_approve = 0.01 * 100 * 1.002 * 1 000 000

assuming that quoteTokenNativeScale returned by the API endpoint for the corresponding trading pair is 1 000 000.

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 currency 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. 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
quote_token_address = '0xabcdef123456789' # the address of the quote token contract
exchange_address = '0x789abcdef123456' # the address of the order book smart contract
quote_token_contract = w3.eth.contract(address=quote_token_address, abi=currency_token_abi) # load the quote token contract
approve_tx = quote_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 buy order

Finally, you need to call the newBuyOrder function of the order book contract to create a buy order. The newBuyOrder 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 buy 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
buy_order_tx = order_book_contract.functions.newBuyOrder(order_data, reporting_data, cross_identifier).buildTransaction({'from': my_wallet}) # build the buy order transaction
signed_tx = w3.eth.account.sign_transaction(buy_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 buy order on 21X DLT Exchange