Fill Limit Order

Overview

Takers are able to fill any signed Maker order within the KyberSwap Limit Order order books by executing the fill order on-chain. By utilizing KyberSwap Limit Order APIs, Takers gain access to slippage-free liquidity sources which are secured via on-chain settlement.

Please refer to Off-Chain Relay, On-Chain Settlement for more detail on this design.

Sequence Diagram

KyberSwap exposes 2 API options for Takers looking to fill orders on-chain:

• /read-ks/api/v1/encode/fill-order-to: Encode the fill order data to be sent on-chain. This API can be used to fill a single order.

• /read-ks/api/v1/encode/fill-batch-orders-to: Encode the fill batch order data to be sent on-chain. This API can be used to fill multiple orders.

In order to fill an order, Takers will first have to request an Operator signature via:

• /read-partner/api/v1/orders/operator-signature: Get the KyberSwap Operator to sign the target orders so that it can be filled.

In addition to the above, Takers are also able to query active or open order(s) to aid with filtering orders to fill:

• /read-partner/api/v1/orders: Returns orders for the queried token pair sorted by best rates in descending order.

TypeScript Example

Step 1: Get orders by best rates

We can use the /read-partner/api/v1/orders to get the list of "active" or "open" orders by token pair:

const targetPathConfig = {
    params: {
        chainId: ChainId.MATIC,
        makerAsset: makerAsset.address, // USDC
        takerAsset: takerAsset.address  // KNC  
    }
};

getOrders.ts

Note that the returned orders will be sorted according to the best rates in descending order. The makerAsset and takerAsset are defined in the constants.ts file to enable convenient reuse across various operations.

Step 2: Get the Operator signature for the target order

For the purposes of this guide, we will be taking the first returned order to fill:

const orders = await getOrders();
const targetOrders = orders.filter(order => 
    order.maker.toLowerCase() == signerAddress.toLowerCase() &&
    order.makerAsset.toLowerCase() == makerAsset.address.toLowerCase() &&
    order.takerAsset.toLowerCase() == takerAsset.address.toLowerCase()
);
const targetOrderId = Number(targetOrders[0].id);

getOperatorSignature.ts

With our target orderId, we can then request for the Operator signature by calling /read-partner/api/v1/orders/operator-signature with the following parameters:

const targetPathConfig = {
    params: {
        chainId: ChainId.MATIC.toString(),
        orderIds: targetOrderId
    }
};

getOperatorSignature.ts

For each orderId requested, the KyberSwap LO Service will return an operatorSignature which will be required as part of the fill order transaction.

Step 3: Check Limit Order contract spending allowance

Before executing the fill order, we will first need to ensure that the LO smart contract has sufficient allowance to spend the taker's ERC20 token. In this example, we will be filling half of the Maker order requested takingAmount:

const orders = await getOrders();
const targetOrder = orders.filter(order => order.id == targetOrderId.toString());
const takingAmount = Number(targetOrder[0].takingAmount)/2;

postFillOrder.ts

If there is insufficient spending allowance, we can then request for a higher allowance via the takerAsset ERC20 token contract using our getTokenApproval() helper function:

if (Number(limitOrderContractAllowance) < spendingAmount) {
    console.log(`Insufficient allowance, getting approval for ${await tokenContract.symbol()}...`);
    try {
        // Call the ERC20 approve method
        const approvalTx = await tokenContract.approve(
            spenderAddress, 
            BigInt(spendingAmount), 
            {maxFeePerGas: 100000000000, maxPriorityFeePerGas: 100000000000}
            );

        // Wait for the approve tx to be executed
        const approvalTxReceipt = await approvalTx.wait();
        console.log(`Approve tx executed with hash: ${approvalTxReceipt?.hash}`);

    } catch(error) {
        console.log(error);
    }
};    

approval.ts

Step 4: Format the fill order request body

To get the encoded data, we will then need to format the /read-ks/api/v1/encode/fill-order-to request body. Note the operatorSignature that was returned in step 2:

const requestBody: FillOrderBody = {
    orderId: Number(targetOrderId),
    takingAmount: takingAmount.toString(),
    thresholdAmount: '0',
    target: signerAddress,
    operatorSignature: operatorSignature[0].operatorSignature
};

postFillOrder.ts

Step 5: Post the encode data request

With the fill order prepared, we can then request the encoded data via /read-ks/api/v1/encode/fill-order-to:

const {data} = await axios.post(
    LimitOrderDomain+targetPath,
    requestBody
);

This will return the fill order encoded data which will be used as the calldata when executing the transaction on-chain.

Step 6: Execute the fill order transaction on-chain

To execute the transaction, we can use our ethers.js signer instance to send the transaction with the required gas fees:

const fillOrderTx = await signer.sendTransaction({
    data: data.data.encodedData,
    to: limitOrderContract,
    from: signerAddress,
    maxFeePerGas: 100000000000,
    maxPriorityFeePerGas: 100000000000
});

postFillOrder.ts

A transaction hash will be returned once the cancel order has been executed. You can copy this hash into a scanner (i.e. PolygonScan) and see that your transaction has been successfully completed by the network.