# Taker API

## Taker

Taker endpoints cover the full fill flow: query open orders sorted by best rate, obtain the required Operator co-signature, encode the fill calldata, and execute on-chain.

For a step-by-step guide, see [Fill a Limit Order](/kyberswap-solutions/limit-order/developer-guides/fill-limit-order.md).

For taker protocol fees and the rate calculation formula, see [Fee Structure.](/developer-guide/limit-order-api/fee-structure.md)

***

### Get Open Orders <a href="#get-open-orders" id="get-open-orders"></a>

`GET /read-partner/api/v1/orders`

Returns open orders for a token pair sorted by best effective rate (descending). The rate accounts for partial fills and protocol fees — see Fee Structure.

## Get Orders By Token Pair

> Returns orders for the queried token pair sorted by best rates in descending order.

```json
{"openapi":"3.0.3","info":{"title":"KyberSwap Limit Order APIs","version":"1.2.0"},"servers":[{"url":"https://limit-order.kyberswap.com"}],"paths":{"/read-partner/api/v1/orders":{"get":{"summary":"Get Orders By Token Pair","tags":["Taker"],"operationId":"get-read-partner-api-v1-orders","description":"Returns orders for the queried token pair sorted by best rates in descending order.","parameters":[{"schema":{"type":"string"},"in":"query","name":"chainId","description":"The chainId of the network to query.","required":true},{"schema":{"type":"string"},"in":"query","name":"makerAsset","description":"The token address of the asset which the Taker expects in return.","required":true},{"schema":{"type":"string"},"in":"query","name":"takerAsset","description":"The token address of the asset which the Taker is exchanging.","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","description":"The response code."},"message":{"type":"string","description":"Server response message."},"data":{"type":"object","required":["orders"],"properties":{"orders":{"type":"array","items":{"type":"object","required":["id","chainId","signature","salt","makerAsset","takerAsset","maker","contractAddress","receiver","allowedSenders","makingAmount","takingAmount","filledMakingAmount","filledTakingAmount","feeConfig","feeRecipient","makerTokenFeePercent","makerAssetData","takerAssetData","getMakerAmount","getTakerAmount","predicate","permit","interaction","expiredAt","availableMakingAmount","makerBalanceAllowance"],"properties":{"id":{"type":"integer","description":"The limit order ID."},"chainId":{"type":"string","description":"The chainId on which the order was created."},"signature":{"type":"string","description":"The signed EIP712 message which created the Maker order."},"salt":{"type":"string","description":"The randomized data fed as an additional input to the create order function."},"makerAsset":{"type":"string","description":"The token address of the asset which the Taker expects in return."},"takerAsset":{"type":"string","description":"The token address of the asset which the Taker is exchanging."},"maker":{"type":"string","description":"The address of the Maker."},"contractAddress":{"type":"string","description":"The address of the Limit Order contract."},"receiver":{"type":"string","description":"The address of the Taker to receive the `makerAsset`."},"allowedSenders":{"type":"string","description":"Defines the addresses who are allowed to fill the order."},"makingAmount":{"type":"string","description":"The amount of `makerAsset` in wei. String representation of uint256 value."},"takingAmount":{"type":"string","description":"The amount of `takerAsset` in wei. String representation of uint256 value."},"filledMakingAmount":{"type":"string","description":"The amount of `makerAsset` which has been filled for this order."},"filledTakingAmount":{"type":"string","description":"The amount of `takerAsset` which has been filled for this order."},"feeConfig":{"type":"string","description":"The hashstring representing the fee configuration for the order."},"feeRecipient":{"type":"string","description":"The address to receive the fees, if any. Fees are configured in `makerTokenFeePercent`."},"makerTokenFeePercent":{"type":"string","description":"Amount of makerToken paid by the taker to the `feeRecipient`. For example, 20% = 0.2 -> makerTokenFeePercent = 0.2 * 10000 = 2000\nFormat: uint32"},"makerAssetData":{"type":"string","description":"ABIv2 encoded data that can be decoded by a specified proxy contract when transferring makerAsset."},"takerAssetData":{"type":"string","description":"ABIv2 encoded data that can be decoded by a specified proxy contract when transferring takerAsset."},"getMakerAmount":{"type":"string","description":"The hexstring representing the `makerAsset` amount."},"getTakerAmount":{"type":"string","description":"The hexstring representing the `takerAsset` amount."},"predicate":{"type":"string","description":"Call data that indicates the validity of the orders logic."},"permit":{"type":"string","description":"Included data if token is able to leverage Permit function (EIP2612) for gasless approvals."},"interaction":{"type":"string","description":"Call data that is sent to an intermediate contract when the order is filled."},"expiredAt":{"type":"integer","description":"The unix timestamp upon which the Maker order will automatically lapse (i.e. expire)."},"availableMakingAmount":{"type":"string","description":"The remaining makingAmount available to be filled"},"makerBalanceAllowance":{"type":"string","description":"The smaller value between maker's balance for makerAsset and maker's allowance for DSLO contract to spend makerAsset"}}}}}}}}}}},"400":{"description":"Bad Request\n- Missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error\n- Error when get price from Price Service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"title":"ErrorResponse","type":"object","properties":{"code":{"type":"integer","description":"Error code"},"message":{"type":"string","description":"Error message"},"errorEntities":{"type":"array","items":{"type":"string"}}},"required":["code","message","errorEntities"]}}}}
```

***

### Get Operator Signature <a href="#get-operator-signature" id="get-operator-signature"></a>

`GET /read-partner/api/v1/orders/operator-signature`

Returns the KyberSwap Operator co-signature for one or more orders. This signature is required as part of the fill calldata and is short-lived — fetch it immediately before building the fill transaction.

## Request Operator Signature For Maker Orders

> Takers will need to request for KyberSwap Operator signature for target Maker orders which they are planning to fill. The returned operator signature will be required when encoding the Taker fill order for both \`/read-ks/api/v1/encode/fill-batch-orders-to\` and \`/read-ks/api/v1/encode/fill-order-to\`.

```json
{"openapi":"3.0.3","info":{"title":"KyberSwap Limit Order APIs","version":"1.2.0"},"servers":[{"url":"https://limit-order.kyberswap.com"}],"paths":{"/read-partner/api/v1/orders/operator-signature":{"get":{"summary":"Request Operator Signature For Maker Orders","tags":["Taker"],"operationId":"post-read-partner-api-v1-orders-operator-signature","description":"Takers will need to request for KyberSwap Operator signature for target Maker orders which they are planning to fill. The returned operator signature will be required when encoding the Taker fill order for both `/read-ks/api/v1/encode/fill-batch-orders-to` and `/read-ks/api/v1/encode/fill-order-to`.","parameters":[{"schema":{"type":"string"},"in":"query","name":"chainId","required":true,"description":"The chainId on which the order is being filled. Only supports EVM chains."},{"schema":{"type":"string"},"in":"query","name":"orderIds","required":true,"description":"The order IDs to be cancelled gaslessly."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","description":"The response code."},"message":{"type":"string","description":"Server response message."},"data":{"type":"array","items":{"type":"object","required":["id","chainId","operatorSignature","operatorSignatureExpiredAt"],"properties":{"id":{"type":"integer","description":"ID of Maker order to be filled."},"chainId":{"type":"string","description":"Chain which order to be filled is on."},"operatorSignature":{"type":"string","description":"The signature of the operator for the requested order id."},"operatorSignatureExpiredAt":{"type":"integer","description":"The unix timestamp at which the Operator's signature expires."}}}}}}}}},"400":{"description":"Bad Request\n- Missing required fields\n- Orders don't have the same maker or chainId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found\n- Not found order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict\n- Duplicate orderId in request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"title":"ErrorResponse","type":"object","properties":{"code":{"type":"integer","description":"Error code"},"message":{"type":"string","description":"Error message"},"errorEntities":{"type":"array","items":{"type":"string"}}},"required":["code","message","errorEntities"]}}}}
```

***

### Encode Fill Order <a href="#encode-fill-order" id="encode-fill-order"></a>

`POST /read-ks/api/v1/encode/fill-order-to`

Returns encoded calldata to fill a **single** order on-chain. The encoded data is sent as `data` in the transaction to the Limit Order contract.

| Field               | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| `orderId`           | The order to fill                                                       |
| `takingAmount`      | Amount of `takerAsset` to provide (can be partial)                      |
| `thresholdAmount`   | Minimum `makingAmount` to receive — reverts if not met (slippage guard) |
| `target`            | Address to receive the `makerAsset`                                     |
| `operatorSignature` | From `GET /read-partner/api/v1/orders/operator-signature`               |

## Generate Encoded Data To Fill Order

> Request for the encoded fill order data from KyberSwap. This data can then be executed on-chain from the signer's wallet.

```json
{"openapi":"3.0.3","info":{"title":"KyberSwap Limit Order APIs","version":"1.2.0"},"servers":[{"url":"https://limit-order.kyberswap.com"}],"paths":{"/read-ks/api/v1/encode/fill-order-to":{"post":{"summary":"Generate Encoded Data To Fill Order","tags":["Taker"],"operationId":"post-read-ks-api-v1-encode-fill-order-to","description":"Request for the encoded fill order data from KyberSwap. This data can then be executed on-chain from the signer's wallet.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["orderId","takingAmount","thresholdAmount","target","operatorSignature"],"properties":{"orderId":{"type":"integer","description":"The ID of the order to be filled."},"takingAmount":{"type":"string","description":"The amount of `takerAsset` in wei. String representation of uint256 value."},"thresholdAmount":{"type":"string","description":"If thresholdAmount != 0, the order will be filled \nif and only if (actualTakingAmount / actualMakingAmount) <= (thresholdAmount / requestedMakingAmount)."},"target":{"type":"string","description":"The Taker wallet address which will receive the `makerAsset`."},"operatorSignature":{"type":"string","description":"The Operator signature obtained from `/read-partner/api/v1/orders/operator-signature`. The order must be signed by the operator before it can be filled."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","description":"The response code."},"message":{"type":"string","description":"Server response message."},"data":{"type":"object","required":["encodedData"],"properties":{"encodedData":{"type":"string","description":"The fill order encoded data to be used as the on-chain tx call data."}}}}}}}},"400":{"description":"Bad Request\n- Missing required fields\n- orderId is invalid format\n- takingAmount, thresholdAmount is not uint256\n- target is not ETH address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found\n- Not found orderId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"title":"ErrorResponse","type":"object","properties":{"code":{"type":"integer","description":"Error code"},"message":{"type":"string","description":"Error message"},"errorEntities":{"type":"array","items":{"type":"string"}}},"required":["code","message","errorEntities"]}}}}
```

***

### Encode Fill Batch Orders <a href="#encode-fill-batch-orders" id="encode-fill-batch-orders"></a>

`POST /read-ks/api/v1/encode/fill-batch-orders-to`

Returns encoded calldata to fill **multiple** orders in a single on-chain transaction. The `orderIds` array and `operatorSignatures` array must be in the same order.

## Generate Encoded Data To Fill Batch Order

> Request for the encoded fill batch order data from KyberSwap. This data can then be executed on-chain from the signer's wallet.

```json
{"openapi":"3.0.3","info":{"title":"KyberSwap Limit Order APIs","version":"1.2.0"},"servers":[{"url":"https://limit-order.kyberswap.com"}],"paths":{"/read-ks/api/v1/encode/fill-batch-orders-to":{"post":{"summary":"Generate Encoded Data To Fill Batch Order","tags":["Taker"],"operationId":"post-read-ks-api-v1-encode-fill-batch-orders-to","description":"Request for the encoded fill batch order data from KyberSwap. This data can then be executed on-chain from the signer's wallet.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["orderIds","takingAmount","thresholdAmount","target","operatorSignatures"],"properties":{"orderIds":{"type":"array","description":"The order IDs to be filled in the batch order.","items":{"type":"integer"}},"takingAmount":{"type":"string","description":"The amount of `takerAsset` in wei. String representation of uint256 value."},"thresholdAmount":{"type":"string","description":"If thresholdAmount != 0, the order will be filled \nif and only if (actualTakingAmount / actualMakingAmount) <= (thresholdAmount / requestedMakingAmount)."},"target":{"type":"string","description":"The Taker wallet address which will receive the `makerAsset`."},"operatorSignatures":{"type":"array","description":"The Operator signature obtained from `/read-partner/api/v1/orders/operator-signature`. The order must be signed by the operator before it can be filled. Operator signature order must match `orderIds`.","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","description":"The response code."},"message":{"type":"string","description":"Server response message."},"data":{"type":"object","required":["encodedData"],"properties":{"encodedData":{"type":"string","description":"The fill batch order encoded data to be used as the on-chain tx call data."}}}}}}}},"400":{"description":"Bad Request\n- Missing required fields\n- takingAmount, thresholdAmount is not uint256\n- target is not ETH address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found\n- Not found order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict\n- Duplicate order ids in request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"title":"ErrorResponse","type":"object","properties":{"code":{"type":"integer","description":"Error code"},"message":{"type":"string","description":"Error message"},"errorEntities":{"type":"array","items":{"type":"string"}}},"required":["code","message","errorEntities"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kyberswap.com/developer-guide/limit-order-api/api-reference/taker-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.