Creating Limit Orders

💡

This API is currently in alpha, and can be changed or removed without notice. Also, the maker needs to be whitelisted to use it. Please reach out to us via email for more information.

💡

There will be a limit on the number of limit orders that can be opened at the same time. This limit will be determined later.

Maker can submit a limit order to Swapscanner API. Since the order does not need to be submitted to the blockchain as a transaction, the order can be created without paying any gas fee.

Limit orders submitted to Swapscanner API will be stored on our database. They will be filled by many other swap requests routed by Navigator.

Endpoint

POST https://api.swapscanner.io/v0alpha/limit-orders
Content-Type: application/json

Request Body

[
  {
    "order": {
      "salt": "0xa432632382fce00d4b8c3f68a55043ef74a560c44480919e37e7eb890b0ea9c3",
      "nonce": "0x0",
      // 2023-11-16T03:00:00.000Z
      "expiresAt": "0x655585b0",
      "making": {
        // 1,000,000 oUSDC
        "token": "0x754288077d0ff82af7a5317c7cb8c444d421d103",
        "amount": "0xe8d4a51000"
      },
      "taking": {
        // 1,000,000 wKLAY
        "token": "0x19aac5f612f524b754ca7e7c41cbfa2e981a4432",
        "amount": "0xd3c21bcecceda1000000"
      },
      "maker": "0x6115b85a7aa4c4e5f03B93FD4A279dc2Bdf7f430",
      "permittedTaker": "0x0000000000000000000000000000000000000000"
    },
    "signature": "0xa8a3bbe9240e9fa578d48df575464f4980786dc93e88d2758c3ab5eae8b98c0f6b07cb4cb19ef8860696603341d9e15e034bec485a9517513c092ccfd9ab94fc1c"
  }
]

order - The order to create.
- salt - A random number to disambiguate orders with identical parameters, and to prevent replay attacks.
- nonce - A number that is incremented when maker cancels all of their orders. See Nonce for more information.
- expiresAt - The timestamp (seconds) when the order expires. The order will be permanently invalid after this time. Thus, expired orders will be considered same as cancelled order. See Order Expiration for more information.
  
  Navigator will only include orders that have enough time until expiration. This is to prevent the order from trying to be filled after it has expired. This grace period is currently set to 60 seconds.
- making - The amount of tokens the maker is selling.
  - token - The address of the token.
  - amount - The amount of tokens.
- taking - The amount of tokens the maker is buying.
  - token - The address of the token.
  - amount - The amount of tokens.
- maker - The address of the maker.
- permittedTaker - The address of the permitted taker. Setting this to zero address allows anyone to fill the order. For now this must be set to zero address.
signature - The signature of the order. See Schema for Signing for more information.

Order Validations

ERC20 Allowance

The maker must have approved the LimitOrderProtocol contract to transfer the making.token token.

Otherwise the order will stay in INVALID state until the allowance is set.

The order can be executed at any time after the allowance is set.

ERC20 Balance

The maker must have enough making.token token balance to cover the making.amount.

Otherwise the order will stay in INVALID state until the balance is sufficient.

The order can be executed at any time after the balance is sufficient.

Order Expiration

The order will be considered expired if the expiresAt timestamp is in the past.

Since the time does not go backwards, the order will never be considered valid again.

Nonce

The nonce is a number that is incremented when the maker cancels all of their orders.

If the order's nonce is different than the maker's current nonce, the order will be considered cancelled.

The current nonce can be found by calling the nonce method on the LimitOrderProtocol contract.

ABI and contract address to be disclosed.

Since the nonce only increments, the order will never be considered valid again.

See Bulk Explicit Cancellation for more information.

Cancelled Order

The order will be considered cancelled if the maker has cancelled a order.

Since the cancellation is irreversible, the order will never be considered valid again.

See Cancelling Limit Orders for more information.

Schema for Signing

{
  "domain": {
    "name": "Swapscanner Limit Order Protocol",
    "version": "v0",
    "chainId": "8217",
    "verifyingContract": "TBD"
  },
  "primaryType": "Order",
  "message": {
    "salt": "0xa432632382fce00d4b8c3f68a55043ef74a560c44480919e37e7eb890b0ea9c3",
    "nonce": "0x0",
    "expiresAt": "0x655585b0",
    "making": {
      "token": "0x754288077d0ff82af7a5317c7cb8c444d421d103",
      "amount": "0xe8d4a51000"
    },
    "taking": {
      "token": "0x19aac5f612f524b754ca7e7c41cbfa2e981a4432",
      "amount": "0xd3c21bcecceda1000000"
    },
    "maker": "0x6115b85a7aa4c4e5f03B93FD4A279dc2Bdf7f430",
    "permittedTaker": "0x0000000000000000000000000000000000000000"
  },
  "types": {
    "EIP712Domain": [
      { "name": "name", "type": "string" },
      { "name": "version", "type": "string" },
      { "name": "chainId", "type": "uint256" },
      { "name": "verifyingContract", "type": "address" }
    ],
    "Order": [
      { "name": "salt", "type": "uint256" },
      { "name": "nonce", "type": "uint256" },
      { "name": "expiresAt", "type": "uint256" },
      { "name": "making", "type": "TokenAmount" },
      { "name": "taking", "type": "TokenAmount" },
      { "name": "maker", "type": "address" },
      { "name": "permittedTaker", "type": "address" }
    ],
    "TokenAmount": [
      { "name": "token", "type": "address" },
      { "name": "amount", "type": "uint256" }
    ]
  }
}

Response Codes

200: OK
400: Bad Request
- duplicate: the computed orderHash already exists on our database.
- too_many_orders: the number of orders in the request exceeds the limit.
403: Forbidden
- invalid_signature: the referrer address does not match with the recovered one.
429: Too Many Requests
- rate_limited: the request is rejected due to rate limiting.

Response Body

[
  {
    "order": {
      "salt": "0xa432632382fce00d4b8c3f68a55043ef74a560c44480919e37e7eb890b0ea9c3",
      "nonce": "0x0",
      // 2023-11-16T03:00:00.000Z
      "expiresAt": "0x655585b0",
      "making": {
        // 1,000,000 oUSDC
        "token": "0x754288077d0ff82af7a5317c7cb8c444d421d103",
        "amount": "0xe8d4a51000"
      },
      "taking": {
        // 1,000,000 wKLAY
        "token": "0x19aac5f612f524b754ca7e7c41cbfa2e981a4432",
        "amount": "0xd3c21bcecceda1000000"
      },
      "maker": "0x6115b85a7aa4c4e5f03B93FD4A279dc2Bdf7f430",
      "permittedTaker": "0x0000000000000000000000000000000000000000"
    },
    "orderHash": "0xf1d82a6887bdc01a73609d52fdcf0a8cab436e02d29ef26cb324faaf9ac1cc60",
    "signature": "0xa8a3bbe9240e9fa578d48df575464f4980786dc93e88d2758c3ab5eae8b98c0f6b07cb4cb19ef8860696603341d9e15e034bec485a9517513c092ccfd9ab94fc1c",
    "status": "VALIDATING"
  },
  {
    "order": {
      "salt": "0x37827693dfcb822ea0ef42341c81f7757cfe056c925ac8a53404e0899eea2883",
      "nonce": "0x0",
      // 2023-11-16T03:00:00.000Z
      "expiresAt": "0x655585b0",
      "making": {
        // 1,000,000 oUSDC
        "token": "0x754288077d0ff82af7a5317c7cb8c444d421d103",
        "amount": "0xe8d4a51000"
      },
      "taking": {
        // 1,000,000 wKLAY
        "token": "0x19aac5f612f524b754ca7e7c41cbfa2e981a4432",
        "amount": "0xd3c21bcecceda1000000"
      },
      "maker": "0xdcbb62c5127e7af18de57b426ace12b773c7c6c8",
      "permittedTaker": "0x0000000000000000000000000000000000000000"
    },
    "orderHash": "0xd0056e57b2192cfa1832ac0b4730ad11264f84e10ddbc015f3cf9b35e4756299",
    "signature": "0x00af393bfa32cf78f4b340b189a6ec4bf4169d524994bddd8ebf1f263f49bf2ab6fa7c8103b9147305c298aa3b64fd1eeede0fbd0c55ed22cff32b91664df5eabb",
    "status": "VALIDATING"
  },
  {
    "order": {
      "salt": "0x519fd8023344a3dc7ac5c731b76d804037804902d9bf3f7a6b0ffa7739131555",
      "nonce": "0x0",
      // 2023-11-16T03:00:00.000Z
      "expiresAt": "0x655585b0",
      "making": {
        // 1,000,000 oUSDC
        "token": "0x754288077d0ff82af7a5317c7cb8c444d421d103",
        "amount": "0xe8d4a51000"
      },
      "taking": {
        // 1,000,000 wKLAY
        "token": "0x19aac5f612f524b754ca7e7c41cbfa2e981a4432",
        "amount": "0xd3c21bcecceda1000000"
      },
      "maker": "0x06f2b7eb919258bc25634a65d4baa72172cbbc5d",
      "permittedTaker": "0x0000000000000000000000000000000000000000"
    },
    "orderHash": "0x9cab6a3756a1a346dcc080b40bb43f0354c3106800a9b5fb3d0fcbf0613bcfc0",
    "signature": "0xb5d932b11f3a203069c868280cddf209a757f2e2ebc13bf70ef419e7b792a93e415e6147d5e540f2cd1f65f0c99c1e1f2447bb32312de20ce123037556ced5d0b1",
    "status": "VALIDATING"
  }
]