1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
# Testing
Use the [sra-report](https://github.com/0xProject/0x-monorepo/tree/development/packages/sra-report) command line tool to test your API for SRA compliance.
# Schemas
The [JSON schemas](http://json-schema.org/) for the API payloads and responses can be found in [@0xproject/json-schemas](https://github.com/0xProject/0x.js/tree/development/packages/json-schemas). Examples of each payload and response can be found in the library's [test suite](https://github.com/0xProject/0x.js/blob/development/packages/json-schemas/test/schema_test.ts#L1).
```bash
npm install @0xproject/json-schemas --save
```
You can easily validate your API's payloads and responses using the [@0xproject/json-schemas](https://github.com/0xProject/0x.js/tree/development/packages/json-schemas) package:
```js
import {SchemaValidator, ValidatorResult, schemas} from '@0xproject/json-schemas';
const {relayerApiTokenPairsResponseSchema} = schemas;
const validator = new SchemaValidator();
const tokenPairsResponse = {
...
};
const validatorResult: ValidatorResult = validator.validate(tokenPairsResponse, relayerApiTokenPairsResponseSchema);
```
# Pagination
Requests that return potentially large collections should respond to the **?page** and **?per_page** parameters. For example:
```bash
$ curl https://api.example-relayer.com/v2/asset_pairs?page=3&per_page=20
```
Page numbering should be 1-indexed, not 0-indexed. If a query provides an unreasonable (ie. too high) `per_page` value, the response can return a validation error as specified in the [errors section](#section/Errors). If the query specifies a `page` that does not exist (ie. there are not enough `records`), the response should just return an empty `records` array.
All endpoints that are paginated should return a `total`, `page`, `perPage` and a `records` value in the top level of the collection. The value of `total` should be the total number of records for a given query, whereas `records` should be an array representing the response to the query for that page. `page` and `perPage`, are the same values that were specified in the request. See the note in [miscellaneous](#section/Misc.) about formatting `snake_case` vs. `lowerCamelCase`.
These requests include the [`/v2/asset_pairs`](#operation/getAssetPairs), [`/v2/orders`](#operation/getOrders), [`/v2/fee_recipients`](#operation/getFeeRecipients) and [`/v2/orderbook`](#operation/getOrderbook) endpoints.
# Network Id
All requests should be able to specify a **?networkId** query param for all supported networks. For example:
```bash
$ curl https://api.example-relayer.com/v2/asset_pairs?networkId=1
```
If the query param is not provided, it should default to **1** (mainnet).
Networks and their Ids:
| Network Id | Network Name |
| ---------- | ------------ |
| 1 | Mainnet |
| 42 | Kovan |
| 3 | Ropsten |
| 4 | Rinkeby |
If a certain network is not supported, the response should **400** as specified in the [error response](#section/Errors) section. For example:
```
{
"code": 100,
"reason": "Validation failed",
"validationErrors": [
{
"field": "networkId",
"code": 1006,
"reason": "Network id 42 is not supported",
}
]
}
```
# Link Header
A [Link Header](https://tools.ietf.org/html/rfc5988) can be included in a response to provide clients with more context about paging
For example:
```
Link: <https://api.example-relayer.com/v2/asset_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 Limits
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/v2/asset_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.
# Errors
Unless the spec defines otherwise, errors to bad requests should respond with HTTP 4xx or status codes.
## Common error 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 |
## Error reporting format
For all **400** responses, see the [error response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_error_response_schema.ts#L1).
```
{
"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 signature or hash
1006 - Unsupported option
```
# Asset Data Encoding
As we now support multiple [token transfer proxies](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#assetproxy), the identifier of which proxy to use for the token transfer must be encoded, along with the token information. Each proxy in 0x v2 has a unique identifier. If you're using 0x.js there will be helper methods for this [encoding](https://0xproject.com/docs/0x.js#zeroEx-encodeERC20AssetData) and [decoding](https://0xproject.com/docs/0x.js#zeroEx-decodeAssetProxyId).
The identifier for the Proxy uses a similar scheme to [ABI function selectors](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#function-selector).
```
// ERC20 Proxy ID 0xf47261b0
bytes4(keccak256("ERC20Token(address)"))
// ERC721 Proxy ID 0x08e937fa
bytes4(keccak256("ERC721Token(address,uint256)"))
```
Asset data is encoded using [ABI encoding](https://solidity.readthedocs.io/en/develop/abi-spec.html).
For example, encoding the ERC20 token contract (address: 0x1dc4c1cefef38a777b15aa20260a54e584b16c48) using the ERC20 Transfer Proxy (id: 0xf47261b0) would be:
```
0xf47261b00000000000000000000000001dc4c1cefef38a777b15aa20260a54e584b16c48
```
Encoding the ERC721 token contract (address: `0x371b13d97f4bf77d724e78c16b7dc74099f40e84`), token id (id: `99`, which hex encoded is `0x63`) and the ERC721 Transfer Proxy (id: 0x08e937fa) would be:
```
0x08e937fa000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063
```
For more information see [the Asset Proxy](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#erc20proxy) section of the v2 spec and the [Ethereum ABI Spec](https://solidity.readthedocs.io/en/develop/abi-spec.html).
# Meta Data in Order Responses
In v2 of the standard relayer API we added the `metaData` field. It is meant to provide a standard place for relayers to put optional, custom or non-standard fields that may of interest to the consumer of the API.
A good example of such a field is `remainingTakerAssetAmount`, which is a convenience field that communicates how much of a 0x order is potentially left to be filled. Unlike the other fields in a 0x order, it is not guaranteed to be correct as it is derived from whatever mechanism the implementer (ie. the relayer) is using. While convenient for prototyping and low stakes situations, we recommend validating the value of the field by checking the state of the blockchain yourself, such as by using [Order Watcher](https://0xproject.com/wiki#0x-OrderWatcher).
# Misc.
* 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.
* All URL query parameters are to be written in `snake_case` and all queries and responses specified in JSON should use `lowerCamelCase`.
|
