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
: OK400
: Bad Requestduplicate
: the computedorderHash
already exists on our database.too_many_orders
: the number of orders in the request exceeds the limit.
403
: Forbiddeninvalid_signature
: the referrer address does not match with the recovered one.
429
: Too Many Requestsrate_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"
}
]