The trade flow

1. Alice and Bob enter limit orders in the application.
Alice wants to trade 1 ETH for 400 DAI, and Bob wants to trade 400 DAI for 1 ETH. They both enter limit orders using the off-chain application.
2. The application sends a settlement request transaction to StarkEx.
The application matches the limit orders of Alice and Bob, and sends a settlement request transaction to the StarkEx gateway, using the add_transaction
API with the SettlementRequest
transaction type. The API call includes both orders, including the actual amounts transferred between Alice’s and Bob’s vaults.
The request that the application sends to the StarkEx REST API includes the following information for each party:
vault_id_sell
|
The ID of the vault from which sold funds should be taken. |
vault_id_buy
|
The ID of the vault from which bought funds should be put. |
token_sell
|
The ID of the asset to sell. |
token_buy
|
The ID of the asset to buy. |
amount_sell
|
The quantized amount of the asset to sell. |
amount_buy
|
The quantized amount of the asset to buy. |
fee_info_user
|
Includes:
|
expiration_timestamp
|
The expiration timestamp of the order. |
nonce
|
A nonce, to prevent replay attacks. |
3. StarkEx validates the settlement request.
StarkEx checks the following to validate the settlement request:
-
The ids of the assets of the two orders match.
-
The ratio between the amount to sell and the amount to buy matches the ratio that each party signed on. Both Alice and Bob want to trade at a ratio of 1 ETH to 400 DAI.
-
Each of the orders in the settlement request is signed by a Stark key that corresponds to the order’s vault ID.
-
The balance in each vault ID is sufficient to fulfill the trade.
-
The maximum fee that both parties are willing to pay for the transaction is not less than the actual fee.
-
Neither order has already been fulfilled, and the amount to be traded does not cause Alice or Bob to transfer more than what they signed on in the order.
-
The settlement request has not expired.
4. StarkEx includes the settlement in a batch.
If the settlement request is valid, the settlement is included in a batch to be submitted on-chain along with a validity proof.
Implementing a trade in your application
To implement trade functionality in your application, use the add_transaction
API with the SettlementRequest
transaction type.
The StarkEx REST API reference includes all necessary information.
Additional resources
-
StarkEx REST API reference
-
Message encoding for information on the structure of a limit order
-
State update for information on the on-chain state update