Requests that return multiple items should respond to the ?page and ?per_page parameters. For example:
curl https://api.example-relayer.com/v0/token_pairs?page=3&per_page=20
Page numbering should be 1-indexed, not 0-indexed. Maximum page size should be 100.
These requests include the token_pairs
, orders
, and orderbook
endpoints.
A Link Header can be included in a response to provide clients with more context about paging For example:
Link: <https://api.example-relayer.com/v0/token_pairs?page=3&per_page=20>; rel="next",
<https://api.github.com/user/repos?page=10&per_page=20>; rel="last"
This Link
response header contains one or more Hypermedia link relations.
The possible rel
values are:
Name | Description |
---|---|
next | The link relation for the immediate next page of results. |
last | The link relation for the last page of results. |
first | The link relation for the first page of results. |
prev | The link relation for the immediate previous page of results. |
Rate limit guidance for clients can be optionally returned in the response headers:
Header Name | Description |
---|---|
X-RateLimit-Limit | The maximum number of requests you're permitted to make per hour. |
X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. |
X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. |
For example:
curl -i https://api.example-relayer.com/v0/token_pairs
HTTP/1.1 200 OK
Date: Mon, 20 Oct 2017 12:30:06 GMT
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 56
X-RateLimit-Reset: 1372700873
When a rate limit is exceeded, a status of 429 Too Many Requests should be returned.
Unless the spec defines otherwise, errors to bad requests should respond with HTTP 4xx or status codes.
Code | Reason |
---|---|
400 | Bad Request – Invalid request format |
404 | Not found |
429 | Too many requests - Rate limit exceeded |
500 | Internal Server Error |
501 | Not Implemented |
- All requests and responses should be of application/json content type
- All token amounts are sent in amounts of the smallest level of precision (base units). (e.g if a token has 18 decimal places, selling 1 token would show up as selling
'1000000000000000000'
units by this API). - All addresses are sent as lower-case (non-checksummed) Ethereum addresses with the
0x
prefix.
Retrieves a list of available token pairs and the information required to trade them. This endpoint should be paginated.
- tokenA=&tokenB [string]: these are token addresses. returns token pairs that contain tokenA and tokenB (in any order). Setting only tokenA or tokenB returns pairs filtered by that token only (optional)
[
{
"tokenA": {
"address": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
"minAmount": "0",
"maxAmount": "10000000000000000000",
"precision": 5
},
"tokenB": {
"address": "0xef7fff64389b814a946f3e92105513705ca6b990",
"minAmount": "0",
"maxAmount": "50000000000000000000",
"precision": 5
}
},
...
]
address
- address of the tokenminAmount
- the minimum trade amount the relayer will acceptmaxAmount
- the maximum trade amount the relayer will acceptprecision
- the desired price precision a relayer would like to support within their orderbook
Retrieves a list of orders given query parameters. This endpoint should be paginated. For querying an entire orderbook snapshot, the orderbook endpoint is recommended.
- exchangeContractAddress [string]: returns orders created for this exchange address
- tokenAddress [string]: returns orders where makerTokenAddress or takerTokenAddress is token address
- makerTokenAddress [string]: returns orders with specified makerTokenAddress
- takerTokenAddress [string]: returns orders with specified makerTokenAddress
- maker [string]: returns orders where maker is maker address
- taker [string]: returns orders where taker is taker address
- trader [string]: returns orders where maker or taker is trader address
- feeRecipient [string]: returns orders where feeRecipient is feeRecipient address
All parameters are optional.
If both makerTokenAddress and takerTokenAddress are specified, returned orders will be sorted by price determined by (takerTokenAmount/makerTokenAmount) in ascending order. By default, orders returned by this endpoint are unsorted.
[
{
"exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
"maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
"taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
"makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
"takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
"feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
"makerTokenAmount": "10000000000000000",
"takerTokenAmount": "20000000000000000",
"makerFee": "100000000000000",
"takerFee": "200000000000000",
"expirationUnixTimestampSec": "42",
"salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
"ecSignature": {
"v": 27,
"r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
"s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
}
},
...
]
Retrieves a specific order by orderHash.
{
"exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
"maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
"taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
"makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
"takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
"feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
"makerTokenAmount": "10000000000000000",
"takerTokenAmount": "20000000000000000",
"makerFee": "100000000000000",
"takerFee": "200000000000000",
"expirationUnixTimestampSec": "42",
"salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
"ecSignature": {
"v": 27,
"r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
"s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
}
}
Returns HTTP 404 if no order with specified orderHash was found.
Retrieves the orderbook for a given token pair.
- baseTokenAddress [string]: address of token designated as the baseToken in the currency pair calculation of price (required)
- quoteTokenAddress [string]: address of token designated as the quoteToken in the currency pair calculation of price (required)
{
"bids": [
{
"exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
"maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
"taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
"makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
"takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
"feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
"makerTokenAmount": "10000000000000000",
"takerTokenAmount": "20000000000000000",
"makerFee": "100000000000000",
"takerFee": "200000000000000",
"expirationUnixTimestampSec": "42",
"salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
"ecSignature": {
"v": 27,
"r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
"s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
}
},
...
],
"asks": [
{
"exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
"maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
"taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
"makerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
"takerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
"feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
"makerTokenAmount": "22000000000000000",
"takerTokenAmount": "10000000000000000",
"makerFee": "100000000000000",
"takerFee": "200000000000000",
"expirationUnixTimestampSec": "632",
"salt": "54515451557974875123697849345751275676157243756715784155226239582178",
"ecSignature": {
"v": 27,
"r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
"s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
}
},
...
]
}
bids
- array of signed orders wheretakerTokenAddress
is equal tobaseTokenAddress
asks
- array of signed orders wheremakerTokenAddress
is equal tobaseTokenAddress
Bids will be sorted in descending order by price, and asks will be sorted in ascending order by price. Within the price sorted orders, the orders are further sorted first by total fees, then by expiration in ascending order.
Given an unsigned order without the fee-related properties, returns the required feeRecipient
, makerFee
, and takerFee
of that order.
{
"exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
"maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
"taker": "0x0000000000000000000000000000000000000000",
"makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
"takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
"makerTokenAmount": "10000000000000000",
"takerTokenAmount": "20000000000000000",
"expirationUnixTimestampSec": "42",
"salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500"
}
{
"feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
"makerFee": "100000000000000",
"takerFee": "200000000000000"
}
Submit a signed order to the relayer.
{
"exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
"maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
"taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
"makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
"takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
"feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
"makerTokenAmount": "10000000000000000",
"takerTokenAmount": "20000000000000000",
"makerFee": "100000000000000",
"takerFee": "200000000000000",
"expirationUnixTimestampSec": "42",
"salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
"ecSignature": {
"v": 27,
"r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
"s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
}
}
Returns HTTP 201 upon success.
Error response will be sent with a non-2xx HTTP status code
{
"code": 101,
"reason": "Validation failed",
"validationErrors": [
{
"field": "maker",
"code": 1002,
"reason": "Invalid address"
}
]
}
General error codes:
100 - Validation Failed
101 - Malformed JSON
102 - Order submission disabled
103 - Throttled
Validation error codes:
1000 - Required field
1001 - Incorrect format
1002 - Invalid address
1003 - Address not supported
1004 - Value out of range
1005 - Invalid ECDSA or Hash
1006 - Unsupported option