Maker APIs

KyberSwap Limit Order Maker APIs

Download OpenAPI specification:

99KB

LimitOrderAPIs_v1.2.1.yaml

Maker 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.

Latest

Create Order(s)

Developer Guide

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

Get Unsigned Create Order Message

post

Get EIP712 create order message to be signed. The response of this API will need to be signed with Sign Typed Data v4 before submitting create order request to KyberSwap via /write/api/v1/orders.

Body

chainIdstringRequired

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

makerAssetstringRequired

The token address of the asset which the Maker is selling.

takerAssetstringRequired

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

makerstringRequired

The address of the Maker.

receiverstringOptional

Defines who will receive the takerAsset when the order is filled. Default: maker.

allowedSendersstring[] · max: 1Optional

Defines the addresses who are allowed to fill the order.

makingAmountstringRequired

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

takingAmountstringRequired

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

feeRecipientstringOptional

The address to receive the fees, if any. Fees are configured in makerTokenFeePercent.

makerTokenFeePercentstringOptional

Amount of makerToken paid by the taker to the feeRecipient. For example, 20% = 0.2 -> makerTokenFeePercent = 0.2 * 10000 = 2000 Format: uint32

expiredAtintegerRequired

The unix timestamp upon which the order will automatically lapse (i.e. expire).

Responses

200

OK

application/json

400

Bad Request - Missing required fields - chainId is not supported - makerAsset, takerAsset, maker, receiver, allowedSenders, feeRecipient are not ETH address - makerAsset or takerAsset are native tokens - makingAmount, takingAmount are less than or equal to 0 - makerTokenFeePercent is less than 0 - makingAmount, takingAmount, takerTokenFeeAmount are not uint128 - expiredAt is in the past

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /write/api/v1/orders/sign-message HTTP/1.1
Host: limit-order.kyberswap.com
Content-Type: application/json
Accept: */*
Content-Length: 331

{
  "chainId": "137",
  "makerAsset": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
  "takerAsset": "0x1c954e8fe737f99f68fa1ccda3e51ebdb291948c",
  "maker": "0x2bfc3A4Ef52Fe6cD2c5236dA08005C59EaFB43a7",
  "allowedSenders": [
    "0x2bfc3A4Ef52Fe6cD2c5236dA08005C59EaFB43a7"
  ],
  "makingAmount": "10000",
  "takingAmount": "20000000000000000",
  "expiredAt": 1697690051
}

{
  "value": {
    "code": 0,
    "message": "Successfully",
    "data": {
      "types": {
        "DSOrder": [
          {
            "name": "orderHash",
            "type": "bytes32"
          },
          {
            "name": "opExpireTime",
            "type": "uint32"
          }
        ],
        "EIP712Domain": [
          {
            "name": "name",
            "type": "string"
          },
          {
            "name": "version",
            "type": "string"
          },
          {
            "name": "chainId",
            "type": "uint256"
          },
          {
            "name": "verifyingContract",
            "type": "address"
          }
        ],
        "Order": [
          {
            "name": "salt",
            "type": "uint256"
          },
          {
            "name": "makerAsset",
            "type": "address"
          },
          {
            "name": "takerAsset",
            "type": "address"
          },
          {
            "name": "maker",
            "type": "address"
          },
          {
            "name": "receiver",
            "type": "address"
          },
          {
            "name": "allowedSender",
            "type": "address"
          },
          {
            "name": "makingAmount",
            "type": "uint256"
          },
          {
            "name": "takingAmount",
            "type": "uint256"
          },
          {
            "name": "feeConfig",
            "type": "uint256"
          },
          {
            "name": "makerAssetData",
            "type": "bytes"
          },
          {
            "name": "takerAssetData",
            "type": "bytes"
          },
          {
            "name": "getMakerAmount",
            "type": "bytes"
          },
          {
            "name": "getTakerAmount",
            "type": "bytes"
          },
          {
            "name": "predicate",
            "type": "bytes"
          },
          {
            "name": "interaction",
            "type": "bytes"
          }
        ]
      },
      "domain": {
        "name": "Kyber Limit Order Protocol",
        "version": "2",
        "chainId": "5",
        "verifyingContract": "0x973B1847407C579a58E610e5f12003996C5a4f16"
      },
      "primaryType": "Order",
      "message": {
        "allowedSender": "0x2bfc3a4ef52fe6cd2c5236da08005c59eafb43a7",
        "feeConfig": "73529011378642731556159749336395186902652258478889",
        "getMakerAmount": "0xf4a215c3000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df820000",
        "getTakerAmount": "0x296637bf000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df820000",
        "interaction": "0x",
        "maker": "0x2bfc3a4ef52fe6cd2c5236da08005c59eafb43a7",
        "makerAsset": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
        "makerAssetData": "0x",
        "makingAmount": "10000",
        "predicate": "0x961d5b1e000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000cab2fa2eeab7065b45cbcf6e3936dde2506b4f6c000000000000000000000000cab2fa2eeab7065b45cbcf6e3936dde2506b4f6c0000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000044cf6fc6e30000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a7000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002463592c2b0000000000000000000000000000000000000000000000000000000065308b6d00000000000000000000000000000000000000000000000000000000",
        "receiver": "0x2bfc3a4ef52fe6cd2c5236da08005c59eafb43a7",
        "salt": "108360087403015833110619993432889154326",
        "takerAsset": "0x1c954e8fe737f99f68fa1ccda3e51ebdb291948c",
        "takerAssetData": "0x",
        "takingAmount": "20000000000000000"
      }
    }
  }
}

Create New Order

post

API for Makers to create new orders by sending in order params which includes the signed EIP712 message returned in /write/api/v1/orders/sign-message.

Body

chainIdstringRequired

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

makerAssetstringRequired

The token address of the asset which the Maker is selling.

takerAssetstringRequired

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

makerstringRequired

The address of the Maker.

receiverstringOptional

Defines who will receive the takerAsset when the order is filled. Default: maker.

allowedSendersstring[]Optional

Defines the addresses who are allowed to fill the order.

makingAmountstringRequired

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

takingAmountstringRequired

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

feeRecipientstringOptional

The address to receive the fees, if any. Fees are configured in makerTokenFeePercent.

makerTokenFeePercentstringOptional

Amount of makerToken paid by the taker to the feeRecipient. For example, 20% = 0.2 -> makerTokenFeePercent = 0.2 * 10000 = 2000 Format: uint32

expiredAtintegerRequired

The unix timestamp upon which the order will automatically lapse (i.e. expire).

saltstringRequired

The randomized data fed as an additional input to the hashing function. Returned in /write/api/v1/orders/sign-message.

signaturestringRequired

The signed(signDataTyped) EIP712 creation order returned in /write/api/v1/orders/sign-message.

Responses

200

OK

application/json

400

Bad Request - Missing required fields - chainId is not supported - makerAsset, takerAsset, maker, receiver, allowedSenders, feeRecipient are not ETH address - makerAsset, takerAsset are native token - makingAmount, takingAmount are less than or equal 0 - makerTokenFeePercent is less than 0 - makingAmount, takingAmount, salt are not uint256 - makerTokenFeePercent is not uint32 - makerAsset is equal to takerAsset - expiredAt is in the past - signature is incorrect - maker's balance is not enough - maker's allowance amount is not enough

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /write/api/v1/orders HTTP/1.1
Host: limit-order.kyberswap.com
Content-Type: application/json
Accept: */*
Content-Length: 527

{
  "chainId": "137",
  "makerAsset": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
  "takerAsset": "0x1c954e8fe737f99f68fa1ccda3e51ebdb291948c",
  "maker": "0x2bfc3A4Ef52Fe6cD2c5236dA08005C59EaFB43a7",
  "allowedSenders": [
    "0x2bfc3A4Ef52Fe6cD2c5236dA08005C59EaFB43a7"
  ],
  "makingAmount": "10000",
  "takingAmount": "20000000000000000",
  "expiredAt": 1697683411,
  "salt": "235124343165545613944116882191476069603",
  "signature": "0xff25fe292d922e7a28b4b84919d2709b8b01a4d2cd4d5ee2335b227dbaa13e1f789d861e1cbb1153e251d839651490276bae2324266f3107c1ade2137c6b4c301b"
}

{
  "value": {
    "code": 0,
    "message": "Successfully",
    "data": {
      "id": 1
    }
  }
}

Query Maker Order(s)

Get List Of Orders By Maker

get

Get all orders created by a Maker address filtered by the order status.

Query parameters

chainIdstringRequired

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

makerstringRequired

The address of the Maker.

statusstring · enumRequired

The status of the order to filter for:

• active: Order is active (both open and has been partially filled).
• open: Order is open and has yet to be filled.
• partially_filled: Order has been partially filled.
• closed: Order has been closed and can no longer be filled.
• filled: Order has been filled with no remaining assets to be filled.
• cancelled: Order was cancelled by the Maker and can no longer be filled.
• expired: Order can no longer be filled as the expiry set by the Maker is in the past.

Possible values:

querystringOptional

Token symbol or token address. Search prefix for symbol, search exact for address.

pageinteger · min: 1Optional

Number of pages to return. Minimum and default is set at 1.

Default: 1

pageSizeinteger · min: 1 · max: 50Optional

Number of results to display per page. Minimum is 1 and maximum is 50. Default is 10.

Default: 10

Responses

200

OK

application/json

400

Bad Request - Missing required fields - status is not part of accepted values - page, pageSize are in invalid formats - page, pageSize are greater than/less than max/min value

application/json

500

Internal Server Error

application/json

get

HTTPcURLJavaScriptPython

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

{
  "code": 0,
  "message": "Successfully",
  "data": {
    "orders": [
      {
        "id": "22385,",
        "chainId": "137",
        "nonce": "3,",
        "makerAsset": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
        "takerAsset": "0x1c954e8fe737f99f68fa1ccda3e51ebdb291948c",
        "contractAddress": "0xcab2fa2eeab7065b45cbcf6e3936dde2506b4f6c",
        "orderHash": "57e2bec735db51269aff31b60f4a02f8bd2ef2e554c1433bbd0aea914c378f3a",
        "makerAssetSymbol": "USDC.e",
        "takerAssetSymbol": "KNC",
        "makerAssetLogoURL": "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
        "takerAssetLogoURL": "https://storage.googleapis.com/ks-setting-1d682dca/9e796f57-482a-426d-904d-007a6adf22fb.png",
        "makerAssetDecimals": 6,
        "takerAssetDecimals": 18,
        "makingAmount": "10000",
        "takingAmount": "20000000000000000",
        "filledMakingAmount": "0",
        "filledTakingAmount": "0",
        "status": "open",
        "createdAt": 1697679812,
        "expiredAt": 1697683411,
        "operatorSignatureExpiredAt": 0,
        "transactions": []
      }
    ],
    "pagination": {
      "totalItems": 1
    }
  }
}

Get Maker Active Making Amount

get

Get the Maker's total making amount for a specified token.

Query parameters

chainIdstringRequired

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

makerAssetstringRequired

The token address of the asset which the Maker is selling.

makerstringRequired

The address of the Maker.

Responses

200

OK

application/json

400

Bad Request - Missing required fields

application/json

500

Internal Server Error

application/json

get

HTTPcURLJavaScriptPython

GET /read-ks/api/v1/orders/active-making-amount HTTP/1.1
Host: limit-order.kyberswap.com
Accept: */*

{
  "value": {
    "code": 0,
    "message": "Successfully",
    "data": {
      "activeMakingAmount": "1000000000000000000"
    }
  }
}

Gasless Cancel Order(s)

Developer Guide

Please refer to Gasless Cancel for the relevant sequence diagram as well as a TypeScript example.

Get Unsigned Cancel Order(s) Message

post

Get EIP712 cancel order message to be signed (i.e. 'Gasless Cancel'). The response of this API will need to be signed with Sign Typed Data v4 before submitting create order request to KyberSwap via /write/api/v1/orders/cancel.

Body

chainIdstringRequired

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

makerstringRequired

The address of the Maker that created the order.

orderIdsinteger[]Required

The order IDs to be cancelled gaslessly.

Responses

200

OK

application/json

400

Bad Request - Missing required fields - chainId is not supported - makerAsset, takerAsset, maker, receiver, allowedSenders, feeRecipient are not ETH address - makerAsset or takerAsset are native tokens - makingAmount, takingAmount are less than or equal to 0 - makerTokenFeePercent is less than 0 - makingAmount, takingAmount, takerTokenFeeAmount are not uint128 - expiredAt is in the past

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /write/api/v1/orders/cancel-sign HTTP/1.1
Host: limit-order.kyberswap.com
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "chainId": "137",
  "maker": "0x2bfc3A4Ef52Fe6cD2c5236dA08005C59EaFB43a7",
  "orderIds": [
    22393
  ]
}

{
  "value": {
    "code": 0,
    "message": "Successfully",
    "data": {
      "types": {
        "EIP712Domain": [
          {
            "name": "name",
            "type": "string"
          },
          {
            "name": "version",
            "type": "string"
          },
          {
            "name": "chainId",
            "type": "uint256"
          },
          {
            "name": "verifyingContract",
            "type": "address"
          }
        ],
        "CancelOrder": [
          {
            "name": "chainId",
            "type": "string"
          },
          {
            "name": "maker",
            "type": "address"
          },
          {
            "name": "orderIds",
            "type": "uint64[]"
          }
        ]
      },
      "domain": {
        "name": "Kyber Limit Order Protocol",
        "version": "1",
        "chainId": "137"
      },
      "primaryType": "CancelOrder",
      "message": {
        "chainId": "137",
        "maker": "0x2bfc3a4ef52fe6cd2c5236da08005c59eafb43a7",
        "orderIds": [
          22393
        ]
      }
    }
  }
}

Submit Gasless Cancel Order(s)

post

API for Makers to gaslessly cancel orders by sending in order params which includes the signed EIP712 message returned in /write/api/v1/orders/cancel-sign.

Header parameters

OriginstringRequired

Required to include 'https://kyberswap.com' to authenticate the POST call.

Body

chainIdstringRequired

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

makerstringRequired

The address of the Maker that created the order.

orderIdsinteger[]Required

The order IDs to be cancelled gaslessly.

signaturestringRequired

The signed(signDataTyped) EIP712 cancellation order returned in /write/api/v1/orders/cancel-sign.

Responses

200

OK

application/json

400

Bad Request - Missing required fields - chainId is not supported - makerAsset, takerAsset, maker, receiver, allowedSenders, feeRecipient are not ETH addresses - makerAsset, takerAsset are native tokens - makingAmount, takingAmount are less than or equal 0 - makerTokenFeePercent is less than 0 - makingAmount, takingAmount, salt are not uint256 - makerTokenFeePercent is not uint32 - makerAsset is equal to takerAsset - expiredAt is in the past - signature is incorrect - maker's balance is not enough - maker's allowance amount is not enough

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /write/api/v1/orders/cancel HTTP/1.1
Host: limit-order.kyberswap.com
Origin: text
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "chainId": "137",
  "maker": "0x2bfc3A4Ef52Fe6cD2c5236dA08005C59EaFB43a7",
  "orderIds": [
    22405
  ],
  "signature": "0xc888d70ebd240e95dc2af556c8002bb8ad92c3e34f6c037e496779d06e778ede53b76399fdacdb812fc0bc3eb7a429ae0b1bdfeabf052f212f732daea628beaa1c"
}

{
  "value": {
    "code": 0,
    "message": "Successfully",
    "data": {
      "orders": [
        {
          "id": 22404,
          "chainId": "137",
          "operatorSignatureExpiredAt": 0
        }
      ]
    }
  }
}

Hard Cancel Order(s)

Developer Guide

Please refer to Hard Cancel for the relevant sequence diagram as well as a TypeScript example.

Generate Encoded Data For Batch Cancellation

post

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

Body

orderIdsinteger[]Required

The order IDs to be cancelled on-chain.

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

post

HTTPcURLJavaScriptPython

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

{
  "value": {
    "orderIds": [
      22393,
      22394
    ]
  }
}

{
  "value": {
    "code": 0,
    "message": "Successfully",
    "data": {
      "encodedData": "0xf7da270200000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000bf887decc94b42c183580ae17ef2f93d0000000000000000000000002791bca1f2de4661ed88a30c99a7a9449aa841740000000000000000000000001c954e8fe737f99f68fa1ccda3e51ebdb291948c0000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a70000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a70000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a7000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df8200000000000000000000000000324f82e73edb06d29ff62c91ec8f5ff06571bdeb2900000000000000000000000000000000000000000000000000000000000001e00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000022000000000000000000000000000000000000000000000000000000000000002a000000000000000000000000000000000000000000000000000000000000003200000000000000000000000000000000000000000000000000000000000000540000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000044f4a215c3000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df820000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000044296637bf000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000470de4df8200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001e4961d5b1e000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000cab2fa2eeab7065b45cbcf6e3936dde2506b4f6c000000000000000000000000cab2fa2eeab7065b45cbcf6e3936dde2506b4f6c0000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000044cf6fc6e30000000000000000000000002bfc3a4ef52fe6cd2c5236da08005c59eafb43a7000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002463592c2b000000000000000000000000000000000000000000000000000000006530ac2500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
    }
  }
}

Generate Encoded Data For Cancel All

post

Request for the cancel all encoded data from KyberSwap. By increasing the LO contract nonce tied to the Maker, the LO contract is able to nullify all existing orders. This data can then be executed on-chain from the Maker's wallet.

Responses

200

OK

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /read-ks/api/v1/encode/increase-nonce HTTP/1.1
Host: limit-order.kyberswap.com
Accept: */*

{
  "value": {
    "code": 0,
    "message": "Successfully",
    "data": {
      "encodedData": "0xc53a0292"
    }
  }
}