Order

The order property of an SDK instance supports querying, creating, pausing, resuming, and canceling orders.

Creating Orders

Creating an order is pretty simple now that you have in/out tokens and an algo.

let r = await sdk.order.prepare({
    tokenIn, //WETH
    tokenOut, //MATIC,
    amountIn: ethers.utils.parseUnits("20", tokenIn.decimals),
    algo,
    tags: [
       {
          name: "my_order_id",
          value: "abcd-efgh-ijkl"
       }
    ]
});

Once you have the tokens and algo, you can easily prepare an order for submission. You'll notice a new parameter: tags.

Tags

Orders can be tagged with name/value pairs to give you a way of associating the orders with your own internal accounting or processing. Any order queries will return the tags attached to every order.

The result of the prepare function is an object that either contains an "error" property, or an "order" property. The order property references an order object ready to submit. The order object also has a "quote" property that you can evaluate if you didn't previously request a quote.

Once you've decided all looks good, and there are no errors, the order object has a "submit" function that will send the order to Dexible for execution.

let r = await sdk.order.prepare({
    tokenIn, //WETH
    tokenOut, //MATIC,
    amountIn: ethers.utils.parseUnits("20", tokenIn.decimals),
    algo,
    tags: [
       {
          name: "my_order_id",
          value: "abcd-efgh-ijkl"
       }
    ]
});
if(r.error) {
   throw new Error(r.error);
}
await r.order.submit();

Querying Orders

You can also use the order sub-property to query for all your active and historical orders or for a specific order once you know its id. Here is an example:

let orders = await sdk.order.getAll({
    state: 'all', //or 'active'
    limit: 100, //optional
    offset: 0 //optional
});

This will return the first 100 orders owned by the wallet connected to the SDK orders with the following JSON structure:

{
  "id": 1,
  "state": "CANCELED",
  "token_in": "0xd0a1e359811322d97991e03f863a0c30c2cf029c",
  "token_out": "0x4f96fe3b7a6cf9725f59d353f723c1bdb64ca6aa",
  "amount_in": "5193000000000000000",
  "network_id": 42,
  "quote_id": 8,
  "tags": [],
  "algo": {
    "name": "Market"
  },
  "policies": [
    {
      "name": "Slippage",
      "params": {
        "amount": "0.5"
      }
    },
    {
      "name": "GasCost",
      "params": {
        "amount": "0",
        "gasType": "relative",
        "deviation": "0"
      }
    },
    {
      "name": "FailLimit",
      "params": {
        "maxFailures": 1
      }
    }
  ],
  "quote": {
    "rounds": "1",
    "amount_in_per_round": "1000000000000000000",
    "amount_out_per_round": "661299875487234764089"
  },
  "fill_summary": {
    "fees": "3115800000000000",
    "gas_fees": "1230000000000000",
    "fee_token": "0xd0a1e359811322d97991e03f863a0c30c2cf029c",
    "total_attempts": 2,
    "tokens_spent": "3115800000000000000",
    "tokens_received": "4254057289802560054820",
    "progress": 0.6,
    "has_pending_txn": false,
    "txns": [
      {
        "hash": "0x...",
        "status": true,
        "timestamp": 1626807188637
      },
      {
        "hash": "0x...",
        "status": true,
        "timestamp": 1626807218862
      }
    ]
  },
  "execution_status": [
    {
      "policy": "StopPrice",
      "passed": true,
      "reason": "Price 1370.047003547976 is at or below trigger price 1375"
    },
    {
      "policy": "GasCost",
      "passed": true,
      "reason": "Relative gas price always applies"
    },
    {
      "policy": "FailLimit",
      "passed": true,
      "reason": "Failure count below max failures"
    }
  ],
  "status_changes": [
    {
      "reason": "User changed state",
      "old_status": null,
      "new_status": "CANCELED",
      "timestamp": 1626807204622
    }
  ]
}

There is quite a bit of detail attached to an order. Most of the fields match what was used to create the order (tokens, amounts, etc). But many things get attached to the order as it executes in Dexible. We'll briefly cover those here.

Fill Summary

The fill summary gives you a quick summary of what has been filled with the order so far. In this example, it shows basis points fee (fees) of 0.0031158 WETH and .00123 WETH paid for gas (gas_fees). The fees are expressed in the fee token address, which is WETH in this example. It shows that it's 60% complete (progress) with 2 rounds finished. It shows how much of the input tokens have been spent and how many output tokens have been received. Finally, it shows the txn hash for all transactions that were submitted so far.

Execution Status

As the order executes, Dexible records detailed information about the order. Each policy evaluation records changes and the reason why the pass/fail outcome changed. In this example, we can see three policies: StopPrice, GasCost, and FailLimit. The StopPrice says that it passed and provides the price point it was triggered at to make it pass. The GasCost checks gas prices and in this case, since we used relative/fast gas price, it always passes. Finally, the FailLimit policy did not find more than 30% of the total rounds failing, so it passed as well. If a policy status is "fail", it means the policy conditions prevented the order from proceeding to the next round.

Status Changes

Anytime the order status changes, such as being paused, cancelled, or resumed, a status change log is created to let you know why the order state changed. In this example, the trader canceled the order before it was complete.