Taker APIs

KyberSwap Limit Order Taker APIs

Download OpenAPI specification:

98KB

LimitOrderAPIs_v1.2.yaml

Taker APIs

API statuses and support

KyberSwap APIs uses the following statuses to minimize version miscommunications and ensure an uninterrupted service for the end user:

• Latest: API is functional and supported. This is the recommended version for all integrators (new and existing).

• Legacy: API remains functional with support for bugs only. No new feature updates.

• Deprecated: API is no longer functional and is not supported.

For all developers, it is highly recommended that you refer to the API with the Latest tag to ensure access to the latest features as well as improved service quality and efficiency. APIs which are planned to be sunset will be tagged Legacy during the transition period and thereafter moved to Deprecated.

The KyberSwap Docs will continue to maintain information regarding Legacy and Deprecated APIs.

Limit Order protocol fees

To support the continued development of the Limit Orders feature, KyberSwap will charge variable taker fees for orders filled on the following chains:

• Ethereum (ChainID: 1)

• BSC (ChainID: 56)

• Arbitrum (ChainID: 42161)

• Polygon (ChainID: 137)

• Optimism (ChainID: 10)

• Avalanche (ChainID: 43114)

• Fantom (ChainID: 250)

• Base (ChainID: 8453)

• ZkSync (ChainID: 324)

• Linea (ChainID: 59144)

• Mantle (ChainID: 5000)

• Scroll (ChainID: 534352)

• Blast (ChainID: 81457)

The fees charged will be according to the most exotic token in the trading pair. The section below lists the fees whereby the highest fee category will apply based on the classification of the input and output tokens. There are 6 categories of tokens with an additional special category for trades involving KNC.

Super stable (0.01%)

• Ethereum (ChainID: 1)

  • USDC: 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

  • USDT: 0xdac17f958d2ee523a2206206994597c13d831ec7

  • DAI: 0x6b175474e89094c44da98b954eedeac495271d0f

• BSC (ChainID: 56)

  • USDC: 0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d

  • USDT: 0x55d398326f99059ff775485246999027b3197955

  • DAI: 0x1af3f329e8be154074d8769d1ffa4ee058b1dbc3

  • BUSD: 0xe9e7cea3dedca5984780bafc599bd69add087d56

• Arbitrum (ChainID: 42161)

  • USDT: 0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9

  • USDC: 0xaf88d065e77c8cC2239327C5EDb3A432268e5831

  • DAI: 0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1

• Polygon (ChainID: 137)

  • USDT: 0xc2132d05d31c914a87c6611c10748aeb04b58e8f

  • USDC: 0x2791bca1f2de4661ed88a30c99a7a9449aa84174

  • DAI: 0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063

• Optimism (ChainID: 10)

  • USDT: 0x94b008aa00579c1307b0ef2c499ad98a8ce58e58

  • USDC: 0x7f5c764cbc14f9669b88837ca1490cca17c31607

  • DAI: 0xda10009cbd5d07dd0cecc66161fc93d7c9000da1

• Avalanche (ChainID: 43114)

  • USDT: 0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7

  • USDC: 0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E

  • DAI.e: 0xd586E7F844cEa2F87f50152665BCbc2C279D8d70

  • USDT.e: 0xc7198437980c041c805A1EDcbA50c1Ce5db95118

  • USDC.e: 0xA7D7079b0FEaD91F3e65f86E8915Cb59c1a4C664

• Fantom (ChainID: 250)

  • fUSDT: 0x049d68029688eabf473097a2fc38ef61633a3c7a

  • USDC: 0x04068DA6C83AFCFA0e13ba15A6696662335D5B75

  • DAI: 0x8D11eC38a3EB5E956B052f67Da8Bdc9bef8Abf3E

Stable (0.02%)

• Ethereum (ChainID: 1)

  • MAI: 0x8D6CeBD76f18E1558D4DB88138e2DeFB3909fAD6

  • BOB: 0xB0B195aEFA3650A6908f15CdaC7D92F8a5791B0B

  • MIM: 0x99D8a9C45b2ecA8864373A26D1459e3Dff1e17F3

• BSC (ChainID: 56)

  • MAI: 0x3F56e0c36d275367b8C502090EDF38289b3dEa0d

  • BOB: 0xB0B195aEFA3650A6908f15CdaC7D92F8a5791B0B

  • MIM: 0xfE19F0B51438fd612f6FD59C1dbB3eA319f433Ba

• Arbitrum (ChainID: 42161)

  • MAI: 0x3F56e0c36d275367b8C502090EDF38289b3dEa0d

  • MIM: 0xFEa7a6a0B346362BF88A9e4A88416B77a57D6c2A

• Polygon (ChainID: 137)

  • MAI: 0xa3Fa99A148fA48D14Ed51d610c367C61876997F1

  • BOB: 0xB0B195aEFA3650A6908f15CdaC7D92F8a5791B0B

  • MIM: 0x49a0400587A7F65072c87c4910449fDcC5c47242

• Optimism (ChainID: 10)

  • MAI: 0xdFA46478F9e5EA86d57387849598dbFB2e964b02

  • BOB: 0xB0B195aEFA3650A6908f15CdaC7D92F8a5791B0B

• Avalanche (ChainID: 43114)

  • MAI: 0x5c49b268c9841AFF1Cc3B0a418ff5c3442eE3F3b

  • YUSD: 0x111111111111ed1D73f860F57b2798b683f2d325

  • MIM: 0x130966628846BFd36ff31a822705796e8cb8C18D

• Fantom (ChainID: 250)

  • MAI: 0xfB98B335551a418cD0737375a2ea0ded62Ea213b

  • MIM: 0x82f0B8B456c1A451378467398982d4834b6829c1

Normal (0.1%)

• Top 200 tokens by market cap (identified via multiple on and off-chain services), excluding tokens under the super stable, stable, and KNC categories.

Exotic (0.3%)

• All remaining tokens not covered in the super stable, stable, normal, and KNC categories.

High Volatility (0.5%)

• Tokens that have been added in the Token Catalog from 2 weeks to 1 month.

Super High Volatility (1%)

• Tokens that have been added in the Token Catalog for less than 2 weeks.

KNC (0.05%)

• Trades to and from KNC will be charged a flat 0.05% fee.

Rates calculation

rate =\frac{(\text{makingAmount}-\text{makingAmountFilled})*(1-\text{makerTokenFee%})*(\text{makerAssetPriceUSD}-\text{gasPriceUSD})}{(\text{takingAmount}-\text{takingAmountFilled})*\text{takerAssetPriceUSD}}

Latest

Developer Guide

Please refer to Fill Limit Order for the relevant sequence diagram as well as a TypeScript example.

Query Order(s)

Get Orders By Token Pair

get

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

Query parameters

chainIdstringRequired

The chainId of the network to query.

makerAssetstringRequired

The token address of the asset which the Taker expects in return.

takerAssetstringRequired

The token address of the asset which the Taker is exchanging.

Responses

200

OK

application/json

400

Bad Request - Missing required fields

application/json

500

Internal Server Error - Error when get price from Price Service

application/json

get

HTTPcURLJavaScriptPython

GET /read-partner/api/v1/orders HTTP/1.1
Host: limit-order.kyberswap.com
Accept: */*

{
  "value": {
    "code": 0,
    "message": "Successfully",
    "data": {
      "orders": [
        {
          "id": "22444,",
          "chainId": "137",
          "signature": "27c31b3a272e79db13b5e75fddff71b070346cf3a3e5d619ceb766fed82d80e32f3e565c1b741f4a2d0cc44132b18551322f2657a274a2782022bdac7fecd2d21b",
          "salt": "23992172604416598893041149026939778295",
          "makerAsset": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
          "takerAsset": "0x1c954e8fe737f99f68fa1ccda3e51ebdb291948c",
          "maker": "0x2bfc3a4ef52fe6cd2c5236da08005c59eafb43a7",
          "contractAddress": "0xcab2fa2eeab7065b45cbcf6e3936dde2506b4f6c",
          "receiver": "0x2bfc3a4ef52fe6cd2c5236da08005c59eafb43a7",
          "allowedSenders": "0x2bfc3a4ef52fe6cd2c5236da08005c59eafb43a7",
          "makingAmount": "10000",
          "takingAmount": "20000000000000000",
          "filledMakingAmount": "0",
          "filledTakingAmount": "0",
          "feeConfig": "73529011378642731556159749336395186902652258478889",
          "feeRecipient": "0x4f82e73edb06d29ff62c91ec8f5ff06571bdeb29",
          "makerTokenFeePercent": "5",
          "makerAssetData": "",
          "takerAssetData": "",
          "getMakerAmount": "f4a215c3000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df820000",
          "getTakerAmount": "296637bf000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df820000",
          "predicate": "961d5b1e000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000cab2fa2eeab7065b45cbcf6e3936dde2506b4f6c000000000000000000000000cab2fa2eeab7065b45cbcf6e3936dde2506b4f6c0000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000044cf6fc6e30000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a7000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002463592c2b000000000000000000000000000000000000000000000000000000006530d1dd00000000000000000000000000000000000000000000000000000000",
          "permit": "",
          "interaction": "",
          "expiredAt": 1697698269,
          "availableMakingAmount": "7000",
          "makerBalanceAllowance": "7000"
        }
      ]
    }
  }
}

Get Operator Signature

Request Operator Signature For Maker Orders

get

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.

Query parameters

chainIdstringRequired

The chainId on which the order is being filled. Only supports EVM chains.

orderIdsstringRequired

The order IDs to be cancelled gaslessly.

Responses

200

OK

application/json

400

Bad Request - Missing required fields - Orders don't have the same maker or chainId

application/json

404

Not Found - Not found order

application/json

409

Conflict - Duplicate orderId in request

application/json

500

Internal Server Error

application/json

get

HTTPcURLJavaScriptPython

GET /read-partner/api/v1/orders/operator-signature HTTP/1.1
Host: limit-order.kyberswap.com
Accept: */*

{
  "value": {
    "code": 0,
    "message": "Successfully",
    "data": {
      "id": 22452,
      "chainId": "137",
      "operatorSignature": "10cde325b99d3616c4d1e0557b8d45c86137e854af12515b4167a72a817c101d64c75a365dbeef6b50f2a6694f0692fe85abfa827af278ac00f56ba942b91b0f1b",
      "operatorSignatureExpiredAt": 1697708112
    }
  }
}

Fill Order(s)

Generate Encoded Data To Fill Order

post

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

Body

orderIdintegerRequired

The ID of the order to be filled.

takingAmountstringRequired

The amount of takerAsset in wei. String representation of uint256 value.

thresholdAmountstringRequired

If thresholdAmount != 0, the order will be filled if and only if (actualTakingAmount / actualMakingAmount) <= (thresholdAmount / requestedMakingAmount).

targetstringRequired

The Taker wallet address which will receive the makerAsset.

operatorSignaturestringRequired

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

OK

application/json

400

Bad Request - Missing required fields - orderId is invalid format - takingAmount, thresholdAmount is not uint256 - target is not ETH address

application/json

404

Not Found - Not found orderId

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /read-ks/api/v1/encode/fill-order-to HTTP/1.1
Host: limit-order.kyberswap.com
Content-Type: application/json
Accept: */*
Content-Length: 281

{
  "orderId": 22456,
  "takingAmount": "10000000000000000",
  "thresholdAmount": "0",
  "target": "0x2bfc3A4Ef52Fe6cD2c5236dA08005C59EaFB43a7",
  "operatorSignature": "8e7a0176b55cb6af042c837114ab98cba45a083a8a0facece2096ff200c060ed4d162fffa88047eb1f040f1fe0eddb27be712d38021795e3b6b5681c27914cd81c"
}

{
  "value": {
    "code": 0,
    "message": "Succeeded",
    "data": {
      "encodedData": "0xd2f1d95600000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002386f26fc100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000006530fdc60000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a7000000000000000000000000000000000000000000000000000000000000074000000000000000000000000000000000aef7e6a8082647289728e7d3ca198b9a0000000000000000000000002791bca1f2de4661ed88a30c99a7a9449aa841740000000000000000000000001c954e8fe737f99f68fa1ccda3e51ebdb291948c0000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a70000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a70000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a7000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df8200000000000000000000000000324f82e73edb06d29ff62c91ec8f5ff06571bdeb2900000000000000000000000000000000000000000000000000000000000001e00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000022000000000000000000000000000000000000000000000000000000000000002a000000000000000000000000000000000000000000000000000000000000003200000000000000000000000000000000000000000000000000000000000000540000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000044f4a215c3000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df820000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000044296637bf000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df8200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001e4961d5b1e000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000cab2fa2eeab7065b45cbcf6e3936dde2506b4f6c000000000000000000000000cab2fa2eeab7065b45cbcf6e3936dde2506b4f6c0000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000044cf6fc6e30000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a7000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002463592c2b000000000000000000000000000000000000000000000000000000006531054900000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000000417d01d984f71c81e9413a9b8ffababca76101c36259a84416cf579ce1d00d36b161a5fc1fa3e8366021ae470cac537133f7e8b9c6f06a2cd2d6a0b81534501ead1c0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000418e7a0176b55cb6af042c837114ab98cba45a083a8a0facece2096ff200c060ed4d162fffa88047eb1f040f1fe0eddb27be712d38021795e3b6b5681c27914cd81c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
    }
  }
}

Generate Encoded Data To Fill Batch Order

post

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

Body

orderIdsinteger[]Required

The order IDs to be filled in the batch order.

takingAmountstringRequired

The amount of takerAsset in wei. String representation of uint256 value.

thresholdAmountstringRequired

If thresholdAmount != 0, the order will be filled if and only if (actualTakingAmount / actualMakingAmount) <= (thresholdAmount / requestedMakingAmount).

targetstringRequired

The Taker wallet address which will receive the makerAsset.

operatorSignaturesstring[]Required

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.

Responses

200

OK

application/json

400

Bad Request - Missing required fields - takingAmount, thresholdAmount is not uint256 - target is not ETH address

application/json

404

Not Found - Not found order

application/json

409

Conflict - Duplicate order ids in request

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /read-ks/api/v1/encode/fill-batch-orders-to HTTP/1.1
Host: limit-order.kyberswap.com
Content-Type: application/json
Accept: */*
Content-Length: 297

{
  "value": {
    "orderIds": [
      22452
    ],
    "takingAmount": "10000000000000000",
    "thresholdAmount": "0",
    "target": "0x2bfc3A4Ef52Fe6cD2c5236dA08005C59EaFB43a7",
    "operatorSignatures": [
      "23eaa3c40c5f5440a099adcd010505a5e7a6445c52be45481f19bf53fa8721d03a6bcb7ca7242941662c3083bc3a2bea55f5259f72f471cff3b48033ecb747fd1b"
    ]
  }
}

{
  "code": 0,
  "message": "Succeeded",
  "data": {
    "encodedData": "0x6fbd13d0000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000000000066000000000000000000000000000000000000000000000000000000000000007e00000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a7000000000000000000000000000000000000000000000000002386f26fc10000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000004ab283f00b764bfb9f4d237bd2d9fe670000000000000000000000002791bca1f2de4661ed88a30c99a7a9449aa841740000000000000000000000001c954e8fe737f99f68fa1ccda3e51ebdb291948c0000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a70000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a70000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a7000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df8200000000000000000000000000324f82e73edb06d29ff62c91ec8f5ff06571bdeb2900000000000000000000000000000000000000000000000000000000000001e00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000022000000000000000000000000000000000000000000000000000000000000002a000000000000000000000000000000000000000000000000000000000000003200000000000000000000000000000000000000000000000000000000000000540000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000044f4a215c3000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df820000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000044296637bf000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df8200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001e4961d5b1e000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000cab2fa2eeab7065b45cbcf6e3936dde2506b4f6c000000000000000000000000cab2fa2eeab7065b45cbcf6e3936dde2506b4f6c0000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000044cf6fc6e30000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a7000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002463592c2b00000000000000000000000000000000000000000000000000000000653105410000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000041ce462832d07c5490f5aca639027dd7f95c682ce5e6ce6a8093f4374f3824acba1107271a51a61fc3fc395b72c61ea22df29dee27f9534342df6e9f44ffcd7d351c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004123eaa3c40c5f5440a099adcd010505a5e7a6445c52be45481f19bf53fa8721d03a6bcb7ca7242941662c3083bc3a2bea55f5259f72f471cff3b48033ecb747fd1b000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000006530ffd1"
  }
}