The trade flow

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:

  • The maximum fee that each party is willing to pay for the transaction.

  • The token in which the fee should be paid.

  • The id of the vault paying the fee.
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