├── .gitignore ├── LICENSE ├── README.md ├── http ├── v0.md ├── v2.md └── v3.md └── ws ├── v0.md ├── v2.md └── v3.md /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | 8 | # Runtime data 9 | pids 10 | *.pid 11 | *.seed 12 | *.pid.lock 13 | 14 | # Directory for instrumented libs generated by jscoverage/JSCover 15 | lib-cov 16 | 17 | # Coverage directory used by tools like istanbul 18 | coverage 19 | 20 | # nyc test coverage 21 | .nyc_output 22 | 23 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 24 | .grunt 25 | 26 | # Bower dependency directory (https://bower.io/) 27 | bower_components 28 | 29 | # node-waf configuration 30 | .lock-wscript 31 | 32 | # Compiled binary addons (http://nodejs.org/api/addons.html) 33 | build/Release 34 | 35 | # Dependency directories 36 | node_modules/ 37 | jspm_packages/ 38 | 39 | # Typescript v1 declaration files 40 | typings/ 41 | 42 | # Optional npm cache directory 43 | .npm 44 | 45 | # Optional eslint cache 46 | .eslintcache 47 | 48 | # Optional REPL history 49 | .node_repl_history 50 | 51 | # Output of 'npm pack' 52 | *.tgz 53 | 54 | # Yarn Integrity file 55 | .yarn-integrity 56 | 57 | # dotenv environment variables file 58 | .env 59 | 60 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "{}" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright {yyyy} {name of copyright owner} 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Standard Relayer API 2 | 3 | 0x Protocol is an open standard. Because of this, we expect many independent applications to be built that will want to use the protocol. In order to make it easier for anyone to source liquidity that conforms to the 0x order format, relayers can opt-in to implementing a set of standard relayer API endpoints. In doing so, they allow clients of the standard relayer API to access the orders on their orderbook. 4 | 5 | ## Specification Versions 6 | 7 | ### SRA v3 8 | 9 | Made to match [0x Protocol v3](https://github.com/0xProject/0x-protocol-specification/blob/master/v3/v3-specification.md). See [changes](https://github.com/0xProject/standard-relayer-api/releases/tag/v3.0.0) from v2. 10 | 11 | - [HTTP](https://github.com/0xProject/standard-relayer-api/blob/master/http/v3.md) 12 | - [WebSocket](https://github.com/0xProject/standard-relayer-api/blob/master/ws/v3.md) 13 | - OpenAPI Spec ([Docs](http://sra3-spec.s3-website-us-east-1.amazonaws.com/), [Package](https://github.com/0xProject/0x-monorepo/tree/development/packages/sra-spec)) 14 | 15 | ### SRA v2 16 | 17 | Made to match [0x Protocol v2](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md) 18 | 19 | - [HTTP](https://github.com/0xProject/standard-relayer-api/blob/master/http/v2.md) 20 | - [WebSocket](https://github.com/0xProject/standard-relayer-api/blob/master/ws/v2.md) 21 | - OpenAPI Spec ([Docs](http://sra-spec.s3-website-us-east-1.amazonaws.com/), [Package](https://github.com/0xProject/0x-monorepo/tree/development/packages/sra-spec)) 22 | 23 | ### SRA v1 24 | 25 | Skipped for naming convention and convenience reasons. 26 | 27 | ### SRA v0 28 | 29 | Made to match [0x Protocol v1](https://github.com/0xProject/0x-protocol-specification/blob/master/v1/v1-whitepaper.pdf) 30 | 31 | - [HTTP](https://github.com/0xProject/standard-relayer-api/blob/master/http/v0.md) 32 | - [WebSocket](https://github.com/0xProject/standard-relayer-api/blob/master/ws/v0.md) 33 | 34 | ## General Info 35 | 36 | ### Versioning 37 | 38 | The URL that specifies the SRA API endpoint should end in the version. Here are some examples: 39 | 40 | **HTTP**: `https://api.relayer.com/sra/v0/`, `https://api.relayer.com/sra/v2/` 41 | 42 | **Websocket**: `wss://api.relayer.com/sra/v0/`, `wss://api.relayer.com/sra/v2/` 43 | 44 | ### Schemas 45 | 46 | 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). 47 | 48 | ``` 49 | npm install @0xproject/json-schemas --save 50 | ``` 51 | 52 | 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: 53 | 54 | ``` 55 | import {SchemaValidator, ValidatorResult, schemas} from '@0xproject/json-schemas'; 56 | 57 | const {relayerApiTokenPairsResponseSchema} = schemas; 58 | const validator = new SchemaValidator(); 59 | 60 | const tokenPairsResponse = { 61 | ... 62 | }; 63 | const validatorResult: ValidatorResult = validator.validate(tokenPairsResponse, relayerApiTokenPairsResponseSchema); 64 | ``` 65 | 66 | ### Asset Data Encoding 67 | 68 | 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). 69 | 70 | The identifier for the Proxy uses a similar scheme to [ABI function selectors](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#function-selector). 71 | 72 | ``` 73 | // ERC20 Proxy ID 0xf47261b0 74 | bytes4(keccak256("ERC20Token(address)")) 75 | // ERC721 Proxy ID 0x02571792 76 | bytes4(keccak256("ERC721Token(address,uint256)")) 77 | ``` 78 | 79 | Asset data is encoded using [ABI encoding](https://solidity.readthedocs.io/en/develop/abi-spec.html). 80 | 81 | For example, encoding the ERC20 token contract (address: 0x1dc4c1cefef38a777b15aa20260a54e584b16c48) using the ERC20 Transfer Proxy (id: 0xf47261b0) would be: 82 | 83 | ``` 84 | 0xf47261b00000000000000000000000001dc4c1cefef38a777b15aa20260a54e584b16c48 85 | ``` 86 | 87 | Encoding the ERC721 token contract (address: `0x371b13d97f4bf77d724e78c16b7dc74099f40e84`), token id (id: `99`, which hex encoded is `0x63`) and the ERC721 Transfer Proxy (id: `0x02571792`) would be: 88 | 89 | ``` 90 | 0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063 91 | ``` 92 | 93 | 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). 94 | 95 | ### Meta Data in Order Responses 96 | 97 | 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. 98 | 99 | 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). 100 | -------------------------------------------------------------------------------- /http/v0.md: -------------------------------------------------------------------------------- 1 | # HTTP REST API Specification v0 2 | 3 | ## Table of Contents 4 | 5 | * [General](#general) 6 | * [Pagination](#pagination) 7 | * [Rate Limits](#rate-limits) 8 | * [Errors](#errors) 9 | * [Misc](#misc) 10 | * [REST API](#rest-api) 11 | * [GET token_pairs](#get-v0token_pairs) 12 | * [GET orders](#get-v0orders) 13 | * [GET order](#get-v0orderorderhash) 14 | * [GET orderbook](#get-v0orderbook) 15 | * [POST fees](#post-v0fees) 16 | * [POST order](#post-v0order) 17 | 18 | ## General 19 | 20 | ### Pagination 21 | 22 | Requests that return multiple items should respond to the **?page** and **?per_page** parameters. For example: 23 | 24 | ``` 25 | curl https://api.example-relayer.com/v0/token_pairs?page=3&per_page=20 26 | ``` 27 | Page numbering should be 1-indexed, not 0-indexed. Maximum page size should be 100. 28 | 29 | These requests include the `token_pairs`, `orders`, and `orderbook` endpoints. 30 | 31 | ### Link Header 32 | 33 | A [Link Header](https://tools.ietf.org/html/rfc5988) can be included in a response to provide clients with more context about paging 34 | For example: 35 | 36 | ``` 37 | Link: ; rel="next", 38 | ; rel="last" 39 | ``` 40 | 41 | This `Link` response header contains one or more Hypermedia link relations. 42 | 43 | The possible `rel` values are: 44 | 45 | 46 | | Name | Description 47 | | ------| ------------------------------------------------------------- | 48 | | next | The link relation for the immediate next page of results. | 49 | | last | The link relation for the last page of results. | 50 | | first | The link relation for the first page of results. | 51 | | prev | The link relation for the immediate previous page of results. | 52 | 53 | ### Rate Limits 54 | 55 | Rate limit guidance for clients can be optionally returned in the response headers: 56 | 57 | | Header Name | Description 58 | | --------------------- | ---------------------------------------------------------------------------- | 59 | | X-RateLimit-Limit | The maximum number of requests you're permitted to make per hour. | 60 | | X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. | 61 | | X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. | 62 | 63 | For example: 64 | 65 | ``` 66 | curl -i https://api.example-relayer.com/v0/token_pairs 67 | HTTP/1.1 200 OK 68 | Date: Mon, 20 Oct 2017 12:30:06 GMT 69 | Status: 200 OK 70 | X-RateLimit-Limit: 60 71 | X-RateLimit-Remaining: 56 72 | X-RateLimit-Reset: 1372700873 73 | ``` 74 | 75 | When a rate limit is exceeded, a status of **429 Too Many Requests** should be returned. 76 | 77 | ### Errors 78 | 79 | Unless the spec defines otherwise, errors to bad requests should respond with HTTP 4xx or status codes. 80 | 81 | #### Common error codes 82 | 83 | | Code | Reason 84 | | ---- | --------------------------------------- | 85 | | 400 | Bad Request – Invalid request format | 86 | | 404 | Not found | 87 | | 429 | Too many requests - Rate limit exceeded | 88 | | 500 | Internal Server Error | 89 | | 501 | Not Implemented | 90 | 91 | 92 | ### Misc. 93 | 94 | - All requests and responses should be of **application/json** content type 95 | - 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). 96 | - All addresses are sent as lower-case (non-checksummed) Ethereum addresses with the `0x` prefix. 97 | 98 | ## REST API 99 | 100 | ### GET /v0/token_pairs 101 | 102 | Retrieves a list of available token pairs and the information required to trade them. This endpoint should be paginated. 103 | 104 | #### Parameters 105 | 106 | * 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) 107 | 108 | #### Response 109 | 110 | [See response schema](https://github.com/0xProject/0x.js/blob/v1-protocol/packages/json-schemas/schemas/relayer_api_token_pairs_response_schema.ts#L1) 111 | 112 | ``` 113 | [ 114 | { 115 | "tokenA": { 116 | "address": "0x323b5d4c32345ced77393b3530b1eed0f346429d", 117 | "minAmount": "0", 118 | "maxAmount": "10000000000000000000", 119 | "precision": 5 120 | }, 121 | "tokenB": { 122 | "address": "0xef7fff64389b814a946f3e92105513705ca6b990", 123 | "minAmount": "0", 124 | "maxAmount": "50000000000000000000", 125 | "precision": 5 126 | } 127 | }, 128 | ... 129 | ] 130 | ``` 131 | 132 | - `address` - address of the token 133 | - `minAmount` - the minimum trade amount the relayer will accept 134 | - `maxAmount` - the maximum trade amount the relayer will accept 135 | - `precision` - the desired price precision a relayer would like to support within their orderbook 136 | 137 | ### GET /v0/orders 138 | 139 | Retrieves a list of orders given query parameters. This endpoint should be paginated. For querying an entire orderbook snapshot, the [orderbook endpoint](#get-v0orderbook) is recommended. 140 | 141 | #### Parameters 142 | 143 | * exchangeContractAddress [string]: returns orders created for this exchange address 144 | * tokenAddress [string]: returns orders where makerTokenAddress or takerTokenAddress is token address 145 | * makerTokenAddress [string]: returns orders with specified makerTokenAddress 146 | * takerTokenAddress [string]: returns orders with specified makerTokenAddress 147 | * maker [string]: returns orders where maker is maker address 148 | * taker [string]: returns orders where taker is taker address 149 | * trader [string]: returns orders where maker or taker is trader address 150 | * feeRecipient [string]: returns orders where feeRecipient is feeRecipient address 151 | 152 | All parameters are optional. 153 | 154 | 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. 155 | 156 | #### Response 157 | 158 | [See response schema](https://github.com/0xProject/0x.js/blob/v1-protocol/packages/json-schemas/schemas/signed_orders_schema.ts#L1) 159 | 160 | ``` 161 | [ 162 | { 163 | "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093", 164 | "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 165 | "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 166 | "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d", 167 | "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990", 168 | "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da", 169 | "makerTokenAmount": "10000000000000000", 170 | "takerTokenAmount": "20000000000000000", 171 | "makerFee": "100000000000000", 172 | "takerFee": "200000000000000", 173 | "expirationUnixTimestampSec": "42", 174 | "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500", 175 | "ecSignature": { 176 | "v": 27, 177 | "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33", 178 | "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254" 179 | } 180 | }, 181 | ... 182 | ] 183 | ``` 184 | 185 | ### GET /v0/order/[orderHash] 186 | 187 | Retrieves a specific order by orderHash. 188 | 189 | #### Response 190 | 191 | [See response schema](https://github.com/0xProject/0x.js/blob/v1-protocol/packages/json-schemas/schemas/order_schemas.ts#L24) 192 | 193 | 194 | ``` 195 | { 196 | "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093", 197 | "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 198 | "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 199 | "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d", 200 | "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990", 201 | "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da", 202 | "makerTokenAmount": "10000000000000000", 203 | "takerTokenAmount": "20000000000000000", 204 | "makerFee": "100000000000000", 205 | "takerFee": "200000000000000", 206 | "expirationUnixTimestampSec": "42", 207 | "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500", 208 | "ecSignature": { 209 | "v": 27, 210 | "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33", 211 | "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254" 212 | } 213 | } 214 | ``` 215 | 216 | Returns HTTP 404 if no order with specified orderHash was found. 217 | 218 | ### GET /v0/orderbook 219 | 220 | Retrieves the orderbook for a given token pair. 221 | 222 | #### Parameters 223 | 224 | * baseTokenAddress [string]: address of token designated as the baseToken in the [currency pair calculation](https://en.wikipedia.org/wiki/Currency_pair) of price (required) 225 | * quoteTokenAddress [string]: address of token designated as the quoteToken in the currency pair calculation of price (required) 226 | 227 | #### Response 228 | 229 | [See response schema](https://github.com/0xProject/0x.js/blob/v1-protocol/packages/json-schemas/schemas/relayer_api_orderbook_response_schema.ts#L1) 230 | 231 | ``` 232 | { 233 | "bids": [ 234 | { 235 | "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093", 236 | "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 237 | "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 238 | "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d", 239 | "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990", 240 | "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da", 241 | "makerTokenAmount": "10000000000000000", 242 | "takerTokenAmount": "20000000000000000", 243 | "makerFee": "100000000000000", 244 | "takerFee": "200000000000000", 245 | "expirationUnixTimestampSec": "42", 246 | "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500", 247 | "ecSignature": { 248 | "v": 27, 249 | "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33", 250 | "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254" 251 | } 252 | }, 253 | ... 254 | ], 255 | "asks": [ 256 | { 257 | "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093", 258 | "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 259 | "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 260 | "makerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990", 261 | "takerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d", 262 | "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da", 263 | "makerTokenAmount": "22000000000000000", 264 | "takerTokenAmount": "10000000000000000", 265 | "makerFee": "100000000000000", 266 | "takerFee": "200000000000000", 267 | "expirationUnixTimestampSec": "632", 268 | "salt": "54515451557974875123697849345751275676157243756715784155226239582178", 269 | "ecSignature": { 270 | "v": 27, 271 | "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33", 272 | "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254" 273 | } 274 | }, 275 | ... 276 | ] 277 | } 278 | ``` 279 | 280 | - `bids` - array of signed orders where `takerTokenAddress` is equal to `baseTokenAddress` 281 | - `asks` - array of signed orders where `makerTokenAddress` is equal to `baseTokenAddress` 282 | 283 | 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. 284 | 285 | ### POST /v0/fees 286 | 287 | Given an unsigned order without the fee-related properties, returns the required `feeRecipient`, `makerFee`, and `takerFee` of that order. 288 | 289 | #### Payload 290 | 291 | [See payload schema](https://github.com/0xProject/0x.js/blob/v1-protocol/packages/json-schemas/schemas/relayer_api_fees_payload_schema.ts#L1) 292 | 293 | ``` 294 | { 295 | "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093", 296 | "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 297 | "taker": "0x0000000000000000000000000000000000000000", 298 | "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d", 299 | "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990", 300 | "makerTokenAmount": "10000000000000000", 301 | "takerTokenAmount": "20000000000000000", 302 | "expirationUnixTimestampSec": "42", 303 | "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500" 304 | } 305 | ``` 306 | 307 | #### Response 308 | 309 | [See response schema](https://github.com/0xProject/0x.js/blob/v1-protocol/packages/json-schemas/schemas/relayer_api_fees_response_schema.ts#L1) 310 | 311 | ``` 312 | { 313 | "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da", 314 | "makerFee": "100000000000000", 315 | "takerFee": "200000000000000" 316 | } 317 | ``` 318 | 319 | ### POST /v0/order 320 | 321 | Submit a signed order to the relayer. 322 | 323 | #### Payload 324 | 325 | [See payload schema](https://github.com/0xProject/0x.js/blob/v1-protocol/packages/json-schemas/schemas/order_schemas.ts#L24) 326 | 327 | ``` 328 | { 329 | "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093", 330 | "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 331 | "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 332 | "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d", 333 | "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990", 334 | "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da", 335 | "makerTokenAmount": "10000000000000000", 336 | "takerTokenAmount": "20000000000000000", 337 | "makerFee": "100000000000000", 338 | "takerFee": "200000000000000", 339 | "expirationUnixTimestampSec": "42", 340 | "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500", 341 | "ecSignature": { 342 | "v": 27, 343 | "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33", 344 | "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254" 345 | } 346 | } 347 | ``` 348 | 349 | #### Response 350 | 351 | ###### Success Response 352 | 353 | Returns HTTP 201 upon success. 354 | 355 | ###### Error Response 356 | 357 | Error response will be sent with a non-2xx HTTP status code 358 | 359 | [See error response schema](https://github.com/0xProject/0x.js/blob/v1-protocol/packages/json-schemas/schemas/relayer_api_error_response_schema.ts#L1) 360 | 361 | ``` 362 | { 363 | "code": 101, 364 | "reason": "Validation failed", 365 | "validationErrors": [ 366 | { 367 | "field": "maker", 368 | "code": 1002, 369 | "reason": "Invalid address" 370 | } 371 | ] 372 | } 373 | ``` 374 | 375 | General error codes: 376 | 377 | ``` 378 | 100 - Validation Failed 379 | 101 - Malformed JSON 380 | 102 - Order submission disabled 381 | 103 - Throttled 382 | ``` 383 | 384 | Validation error codes: 385 | 386 | ``` 387 | 1000 - Required field 388 | 1001 - Incorrect format 389 | 1002 - Invalid address 390 | 1003 - Address not supported 391 | 1004 - Value out of range 392 | 1005 - Invalid ECDSA or Hash 393 | 1006 - Unsupported option 394 | ``` 395 | -------------------------------------------------------------------------------- /http/v2.md: -------------------------------------------------------------------------------- 1 | # HTTP REST API Specification v2 2 | 3 | ## Table of Contents 4 | 5 | * [General](#general) 6 | * [Pagination](#pagination) 7 | * [Network Id](#network-id) 8 | * [Link Header](#link-header) 9 | * [Rate Limits](#rate-limits) 10 | * [Errors](#errors) 11 | * [Misc](#misc) 12 | * [REST API](#rest-api) 13 | * [GET asset_pairs](#get-v2asset_pairs) 14 | * [GET orders](#get-v2orders) 15 | * [GET order](#get-v2orderorderhash) 16 | * [GET orderbook](#get-v2orderbook) 17 | * [POST order_config](#post-v2order_config) 18 | * [GET fee_recipients](#get-v2fee_recipients) 19 | * [POST order](#post-v2order) 20 | 21 | ## General 22 | 23 | ### Pagination 24 | 25 | Requests that return potentially large collections should respond to the **?page** and **?perPage** parameters. For example: 26 | 27 | ``` 28 | curl https://api.example-relayer.com/v2/token_pairs?page=3&perPage=20 29 | ``` 30 | 31 | Page numbering should be 1-indexed, not 0-indexed. If a query provides an unreasonable (ie. too high) **perPage** value, the response can return a validation error as specified in the [errors 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. 32 | 33 | 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. 34 | 35 | These requests include the [`asset_pairs`](#get-v2-asset-pairs), [`orders`](#get-v2-orders), and [`orderbook`](#get-v2-orderbook) endpoints. 36 | 37 | ### Network Id 38 | All requests should be able to specify a **?networkId** query param for all supported networks. For example: 39 | ``` 40 | curl https://api.example-relayer.com/v2/token_pairs?networkId=1 41 | ``` 42 | If the query param is not provided, it should default to **1** (mainnet). 43 | 44 | Networks and their Ids: 45 | 46 | | Network Id| Network Name | 47 | | ----------| ------------ | 48 | | 1 | Mainnet | 49 | | 42 | Kovan | 50 | | 3 | Ropsten | 51 | | 4 | Rinkeby | 52 | 53 | If a certain network is not supported, the response should **400** as specified in the [error response](#error-response) section. For example: 54 | 55 | ``` 56 | { 57 | "code": 100, 58 | "reason": "Validation failed", 59 | "validationErrors": [ 60 | { 61 | "field": "networkId", 62 | "code": 1006, 63 | "reason": "Network id 42 is not supported", 64 | } 65 | ] 66 | } 67 | ``` 68 | 69 | ### Link Header 70 | 71 | A [Link Header](https://tools.ietf.org/html/rfc5988) can be included in a response to provide clients with more context about paging 72 | For example: 73 | 74 | ``` 75 | Link: ; rel="next", 76 | ; rel="last" 77 | ``` 78 | 79 | This `Link` response header contains one or more Hypermedia link relations. 80 | 81 | The possible `rel` values are: 82 | 83 | | Name | Description | 84 | | ----- | ------------------------------------------------------------- | 85 | | next | The link relation for the immediate next page of results. | 86 | | last | The link relation for the last page of results. | 87 | | first | The link relation for the first page of results. | 88 | | prev | The link relation for the immediate previous page of results. | 89 | 90 | ### Rate Limits 91 | 92 | Rate limit guidance for clients can be optionally returned in the response headers: 93 | 94 | | Header Name | Description | 95 | | --------------------- | ---------------------------------------------------------------------------- | 96 | | X-RateLimit-Limit | The maximum number of requests you're permitted to make per hour. | 97 | | X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. | 98 | | X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. | 99 | 100 | For example: 101 | 102 | ``` 103 | curl -i https://api.example-relayer.com/v2/token_pairs 104 | HTTP/1.1 200 OK 105 | Date: Mon, 20 Oct 2017 12:30:06 GMT 106 | Status: 200 OK 107 | X-RateLimit-Limit: 60 108 | X-RateLimit-Remaining: 56 109 | X-RateLimit-Reset: 1372700873 110 | ``` 111 | When a rate limit is exceeded, a status of **429 Too Many Requests** should be returned. 112 | 113 | ### Errors 114 | 115 | Unless the spec defines otherwise, errors to bad requests should respond with HTTP 4xx or status codes. 116 | 117 | #### Common error codes 118 | 119 | | Code | Reason | 120 | | ---- | --------------------------------------- | 121 | | 400 | Bad Request – Invalid request format | 122 | | 404 | Not found | 123 | | 429 | Too many requests - Rate limit exceeded | 124 | | 500 | Internal Server Error | 125 | | 501 | Not Implemented | 126 | 127 | #### Error reporting format 128 | 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.json#L1). 129 | 130 | ``` 131 | { 132 | "code": 101, 133 | "reason": "Validation failed", 134 | "validationErrors": [ 135 | { 136 | "field": "maker", 137 | "code": 1002, 138 | "reason": "Invalid address" 139 | } 140 | ] 141 | } 142 | ``` 143 | 144 | General error codes: 145 | 146 | ``` 147 | 100 - Validation Failed 148 | 101 - Malformed JSON 149 | 102 - Order submission disabled 150 | 103 - Throttled 151 | ``` 152 | 153 | Validation error codes: 154 | 155 | ``` 156 | 1000 - Required field 157 | 1001 - Incorrect format 158 | 1002 - Invalid address 159 | 1003 - Address not supported 160 | 1004 - Value out of range 161 | 1005 - Invalid signature or hash 162 | 1006 - Unsupported option 163 | ``` 164 | 165 | 166 | ### Misc. 167 | 168 | * All requests and responses should be of **application/json** content type 169 | * 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). 170 | * All addresses are sent as lower-case (non-checksummed) Ethereum addresses with the `0x` prefix. 171 | * All parameters should use `lowerCamelCase`. 172 | 173 | ## REST API 174 | 175 | ### GET /v2/asset_pairs 176 | 177 | Retrieves a list of available asset pairs and the information required to trade them. This endpoint should be [paginated](#pagination). 178 | 179 | #### Parameters 180 | 181 | * assetDataA=&assetDataB [string]: these are assetData fields. Returns asset pairs that contain assetDataA and assetDataB (in any order). Setting only assetDataA or assetDataB returns pairs filtered by that asset only (optional) 182 | 183 | #### Response 184 | 185 | [See response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_asset_data_pairs_response_schema.json#L1) 186 | 187 | ``` 188 | { 189 | "total": 43, 190 | "page": 1, 191 | "perPage": 100, 192 | "records": [ 193 | { 194 | "assetDataA": { 195 | "minAmount": "0", 196 | "maxAmount": "10000000000000000000", 197 | "precision": 5, 198 | "assetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498" 199 | }, 200 | "assetDataB": { 201 | "minAmount": "0", 202 | "maxAmount": "50000000000000000000", 203 | "precision": 5, 204 | "assetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063" 205 | } 206 | }, 207 | ... 208 | ] 209 | } 210 | ``` 211 | 212 | * `minAmount` - the minimum trade amount the relayer will accept 213 | * `maxAmount` - the maximum trade amount the relayer will accept 214 | * `precision` - the desired price precision a relayer would like to support within their orderbook 215 | * `assetData` - the assetData representing that token 216 | 217 | ### GET /v2/orders 218 | 219 | Retrieves a list of orders given query parameters. This endpoint should be [paginated](#pagination). For querying an entire orderbook snapshot, the [orderbook endpoint](#get-v2orderbook) is recommended. 220 | 221 | #### Parameters 222 | 223 | Filter parameters: 224 | * makerAssetProxyId [string]: returns orders where the maker asset is of certain [asset proxy id](https://0xproject.com/docs/0x.js#types-AssetProxyId) (example: `0xf47261b0` for `ERC20`, `0x02571792` for `ERC721`) 225 | * takerAssetProxyId [string]: returns orders where the taker asset is of certain [asset proxy id](https://0xproject.com/docs/0x.js#types-AssetProxyId)(example: `0xf47261b0` for `ERC20`, `0x02571792` for `ERC721`) 226 | * makerAssetAddress [string] returns orders where the contract address for the maker asset matches the value specified 227 | * takerAssetAddress [string] returns orders where the contract address for the taker asset matches the value specified 228 | 229 | Order specific parameters: 230 | * exchangeAddress [string]: returns orders created for this exchange address 231 | * senderAddress [string]: returns orders with the specified senderAddress 232 | * makerAssetData [string]: returns orders with the specified makerAssetData 233 | * takerAssetData [string]: returns orders with the specified takerAssetData 234 | * traderAssetData [string]: returns orders where either makerAssetData or takerAssetData has the value specified 235 | * makerAddress [string]: returns orders with the specified makerAddress 236 | * takerAddress [string]: returns orders with the specified takerAddress 237 | * traderAddress [string]: returns orders where either makerAddress or takerAddress has the value specified 238 | * feeRecipientAddress [string]: returns orders where feeRecipientAddress is feeRecipient address 239 | 240 | All parameters are optional. 241 | 242 | If both makerAssetData and takerAssetData are specified, returned orders will be sorted by price determined by (takerAssetAmount/makerAssetAmount) in ascending order. By default, orders returned by this endpoint are unsorted. 243 | 244 | While there is some redundancy in supporting maker/takerAssetType, maker/takerAssetAddress, and maker/takerAssetData, they are actually all needed. For example, you cannot query "all ERC712 orders", or "all Cryptokitties orders", or "all ERC20 orders" with just maker/takerAssetData and need the other query params to do so. 245 | 246 | #### Response 247 | 248 | [See response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_orders_response_schema.json#L1) 249 | 250 | 251 | ``` 252 | { 253 | "total": 984, 254 | "page": 1, 255 | "perPage": 100, 256 | "records": [ 257 | { 258 | "order": { 259 | "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 260 | "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 261 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 262 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 263 | "makerAssetAmount": "10000000000000000", 264 | "takerAssetAmount": "20000000000000000", 265 | "makerFee": "100000000000000", 266 | "takerFee": "200000000000000", 267 | "expirationTimeSeconds": "1532560590", 268 | "salt": "1532559225", 269 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 270 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 271 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 272 | "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33" 273 | }, 274 | "metaData": {} 275 | } 276 | ... 277 | ] 278 | } 279 | ``` 280 | 281 | ### GET /v2/order/[orderHash] 282 | 283 | Retrieves a specific order by orderHash. 284 | 285 | #### Response 286 | 287 | [See response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/signed_order_schema.json#L1) 288 | 289 | ``` 290 | { 291 | "order": { 292 | "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 293 | "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 294 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 295 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 296 | "makerAssetAmount": "10000000000000000", 297 | "takerAssetAmount": "20000000000000000", 298 | "makerFee": "100000000000000", 299 | "takerFee": "200000000000000", 300 | "expirationTimeSeconds": "1532560590", 301 | "salt": "1532559225", 302 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 303 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 304 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 305 | "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33" 306 | }, 307 | "metaData": {} 308 | } 309 | ``` 310 | 311 | Returns HTTP 404 if no order with specified orderHash was found. 312 | 313 | ### GET /v2/orderbook 314 | 315 | Retrieves the orderbook for a given asset pair. This endpoint should be [paginated](#pagination). 316 | 317 | #### Parameters 318 | 319 | * baseAssetData [string]: assetData (makerAssetData or takerAssetData) designated as the base currency in the [currency pair calculation](https://en.wikipedia.org/wiki/Currency_pair) of price (required) 320 | * quoteAssetData [string]: assetData (makerAssetData or takerAssetData) designated as the quote currency in the currency pair calculation of price (required) 321 | 322 | #### Response 323 | 324 | [See response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_orderbook_response_schema.json#L1) 325 | 326 | ``` 327 | { 328 | "bids": { 329 | "total": 325, 330 | "page": 2, 331 | "perPage": 100, 332 | "records": [ 333 | { 334 | "order": { 335 | "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 336 | "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 337 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 338 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 339 | "makerAssetAmount": "10000000000000000", 340 | "takerAssetAmount": "20000000000000000", 341 | "makerFee": "100000000000000", 342 | "takerFee": "200000000000000", 343 | "expirationTimeSeconds": "1532560590", 344 | "salt": "1532559225", 345 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 346 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 347 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 348 | "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33" 349 | } 350 | "metaData": {} 351 | }, 352 | ... 353 | ] 354 | } 355 | "asks": { 356 | "total": 500, 357 | "page": 2, 358 | "perPage": 100, 359 | "records": [ 360 | { 361 | "order": { 362 | "makerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 363 | "takerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 364 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 365 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 366 | "makerAssetAmount": "20000000000000000", 367 | "takerAssetAmount": "10000000000000000", 368 | "makerFee": "200000000000000", 369 | "takerFee": "100000000000000", 370 | "expirationTimeSeconds": "1532560590", 371 | "salt": "1532559225", 372 | "makerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 373 | "takerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 374 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 375 | "signature": "0x013842a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b3518891" 376 | }, 377 | "metaData": {} 378 | }, 379 | ... 380 | ] 381 | } 382 | } 383 | ``` 384 | 385 | * `bids` - array of signed orders where `takerAssetData` is equal to `baseAssetData` 386 | * `asks` - array of signed orders where `makerAssetData` is equal to `baseAssetData` 387 | 388 | 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 by _taker fee price_ which is defined as the **takerFee** divided by **takerTokenAmount**. After _taker fee price_, orders are to be sorted by expiration in ascending order. 389 | 390 | The way pagination works for this endpoint is that the **page** and **perPage** query params apply to both `bids` and `asks` collections, and if `page` * `perPage` > `total` for a certain collection, the `records` for that collection should just be empty. 391 | 392 | ### POST /v2/order_config 393 | 394 | Relayers have full discretion over the orders that they are willing to host on their orderbooks (e.g what fees they charge, etc...). In order for traders to discover their requirements programmatically, they can send an incomplete order to this endpoint and receive the missing fields, specifc to that order. This gives relayers a large amount of flexibility to tailor fees to unique traders, trading pairs and volume amounts. Submit a partial order and receive information required to complete the order: `senderAddress`, `feeRecipientAddress`, `makerFee`, `takerFee`. 395 | 396 | #### Payload 397 | 398 | [See payload schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_order_config_payload_schema.json#L1) 399 | 400 | ``` 401 | { 402 | "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 403 | "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 404 | "makerAssetAmount": "10000000000000000", 405 | "takerAssetAmount": "20000000000000000", 406 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 407 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 408 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 409 | "expirationTimeSeconds": "1532560590" 410 | } 411 | ``` 412 | 413 | #### Response 414 | 415 | [See response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_order_config_response_schema.json#L1) 416 | 417 | ###### Success Response 418 | 419 | Returns a HTTP 201 response with the following payload: 420 | ``` 421 | { 422 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 423 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 424 | "makerFee": "100000000000000", 425 | "takerFee": "200000000000000" 426 | } 427 | ``` 428 | 429 | ###### Error Response 430 | 431 | Error response will be sent with a non-2xx HTTP status code. See the [Errors](#errors) section for more information. 432 | 433 | ### GET /v2/fee_recipients 434 | 435 | Retrieves a list of all fee recipient addresses for a relayer. This endpoint should be [paginated](#pagination). 436 | 437 | #### Parameters 438 | 439 | No custom parameters, just pagination parameters. 440 | 441 | #### Response 442 | 443 | [See response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_fee_recipients_response_schema.json#L1) 444 | 445 | ``` 446 | { 447 | "total": 3, 448 | "page": 1, 449 | "perPage": 10, 450 | "records": [ 451 | "0x6eC92694ea172ebC430C30fa31De87620967A082", 452 | "0x9e56625509c2f60af937f23b7b532600390e8c8b", 453 | "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32" 454 | ] 455 | } 456 | ``` 457 | 458 | 459 | ### POST /v2/order 460 | 461 | Submit a signed order to the relayer. 462 | 463 | #### Payload 464 | 465 | [See payload schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/signed_order_schema.json#L1) 466 | 467 | ``` 468 | { 469 | "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 470 | "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 471 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 472 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 473 | "makerAssetAmount": "10000000000000000", 474 | "takerAssetAmount": "20000000000000000", 475 | "makerFee": "100000000000000", 476 | "takerFee": "200000000000000", 477 | "expirationTimeSeconds": "1532560590", 478 | "salt": "1532559225", 479 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 480 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 481 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 482 | "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33" 483 | } 484 | ``` 485 | 486 | #### Response 487 | 488 | ###### Success Response 489 | 490 | Returns HTTP 201 upon success. 491 | 492 | ###### Error Response 493 | 494 | Error response will be sent with a non-2xx HTTP status code. See the [Errors](#errors) section for more information. 495 | -------------------------------------------------------------------------------- /http/v3.md: -------------------------------------------------------------------------------- 1 | # HTTP REST API Specification v3 2 | 3 | ## Table of Contents 4 | 5 | * [General](#general) 6 | * [Pagination](#pagination) 7 | * [Chain Id](#chain-id) 8 | * [Link Header](#link-header) 9 | * [Rate Limits](#rate-limits) 10 | * [Errors](#errors) 11 | * [Misc](#misc) 12 | * [REST API](#rest-api) 13 | * [GET asset_pairs](#get-asset_pairs) 14 | * [GET orders](#get-orders) 15 | * [GET order](#get-orderorderhash) 16 | * [GET orderbook](#get-orderbook) 17 | * [POST order_config](#post-order_config) 18 | * [GET fee_recipients](#get-fee_recipients) 19 | * [POST order](#post-order) 20 | 21 | ## General 22 | 23 | ### Pagination 24 | 25 | Requests that return potentially large collections should respond to the **?page** and **?perPage** parameters. For example: 26 | 27 | ``` 28 | curl https://api.0x.org/sra/orders?page=3&perPage=20 29 | ``` 30 | 31 | Page numbering should be 1-indexed, not 0-indexed. If a query provides an unreasonable (ie. too high) **perPage** value, the response can return a validation error as specified in the [errors 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. 32 | 33 | 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. 34 | 35 | These requests include the [`asset_pairs`](#get-asset_pairs), [`orders`](#get-orders), and [`orderbook`](#get-orderbook) endpoints. 36 | 37 | ### Chain Id 38 | The Standard Relayer API V3 does not specify how to deal with different chain ids (formerly called network ids). The recommendation is to provide a different SRA URL for every chain id that you support. For example, if your mainnet SRA endpoint is hosted at `https://api.0x.org/sra` then the Kovan endpoint could be hosted at `https://kovan.api.0x.org/sra`. 39 | 40 | ### Link Header 41 | 42 | A [Link Header](https://tools.ietf.org/html/rfc5988) can be included in a response to provide clients with more context about paging 43 | For example: 44 | 45 | ``` 46 | Link: ; rel="next", 47 | ; rel="last" 48 | ``` 49 | 50 | This `Link` response header contains one or more Hypermedia link relations. 51 | 52 | The possible `rel` values are: 53 | 54 | | Name | Description | 55 | | ----- | ------------------------------------------------------------- | 56 | | next | The link relation for the immediate next page of results. | 57 | | last | The link relation for the last page of results. | 58 | | first | The link relation for the first page of results. | 59 | | prev | The link relation for the immediate previous page of results. | 60 | 61 | ### Rate Limits 62 | 63 | Rate limit guidance for clients can be optionally returned in the response headers: 64 | 65 | | Header Name | Description | 66 | | --------------------- | ---------------------------------------------------------------------------- | 67 | | X-RateLimit-Limit | The maximum number of requests you're permitted to make per hour. | 68 | | X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. | 69 | | X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. | 70 | 71 | For example: 72 | 73 | ``` 74 | curl -i https://api.0x.org/sra/token_pairs 75 | HTTP/1.1 200 OK 76 | Date: Mon, 20 Oct 2017 12:30:06 GMT 77 | Status: 200 OK 78 | X-RateLimit-Limit: 60 79 | X-RateLimit-Remaining: 56 80 | X-RateLimit-Reset: 1372700873 81 | ``` 82 | When a rate limit is exceeded, a status of **429 Too Many Requests** should be returned. 83 | 84 | ### Errors 85 | 86 | Unless the spec defines otherwise, errors to bad requests should respond with HTTP 4xx or status codes. 87 | 88 | #### Common error codes 89 | 90 | | Code | Reason | 91 | | ---- | --------------------------------------- | 92 | | 400 | Bad Request – Invalid request format | 93 | | 404 | Not found | 94 | | 429 | Too many requests - Rate limit exceeded | 95 | | 500 | Internal Server Error | 96 | | 501 | Not Implemented | 97 | 98 | #### Error reporting format 99 | 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.json#L1). 100 | 101 | ``` 102 | { 103 | "code": 101, 104 | "reason": "Validation failed", 105 | "validationErrors": [ 106 | { 107 | "field": "maker", 108 | "code": 1002, 109 | "reason": "Invalid address" 110 | } 111 | ] 112 | } 113 | ``` 114 | 115 | General error codes: 116 | 117 | ``` 118 | 100 - Validation Failed 119 | 101 - Malformed JSON 120 | 102 - Order submission disabled 121 | 103 - Throttled 122 | ``` 123 | 124 | Validation error codes: 125 | 126 | ``` 127 | 1000 - Required field 128 | 1001 - Incorrect format 129 | 1002 - Invalid address 130 | 1003 - Address not supported 131 | 1004 - Value out of range 132 | 1005 - Invalid signature or hash 133 | 1006 - Unsupported option 134 | ``` 135 | 136 | ### Misc. 137 | 138 | * All requests and responses should be of **application/json** content type 139 | * 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). 140 | * All addresses are sent as lower-case (non-checksummed) Ethereum addresses with the `0x` prefix. 141 | * All parameters should use `lowerCamelCase`. 142 | 143 | ## REST API 144 | 145 | ### GET /asset_pairs 146 | 147 | Retrieves a list of available asset pairs and the information required to trade them. This endpoint should be [paginated](#pagination). 148 | 149 | #### Parameters 150 | 151 | * assetDataA=&assetDataB [string]: these are assetData fields. Returns asset pairs that contain assetDataA and assetDataB (in any order). Setting only assetDataA or assetDataB returns pairs filtered by that asset only (optional) 152 | 153 | #### Response 154 | 155 | [See response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_asset_data_pairs_response_schema.json#L1) 156 | 157 | ``` 158 | { 159 | "total": 43, 160 | "page": 1, 161 | "perPage": 100, 162 | "records": [ 163 | { 164 | "assetDataA": { 165 | "minAmount": "0", 166 | "maxAmount": "10000000000000000000", 167 | "precision": 5, 168 | "assetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498" 169 | }, 170 | "assetDataB": { 171 | "minAmount": "0", 172 | "maxAmount": "50000000000000000000", 173 | "precision": 5, 174 | "assetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063" 175 | } 176 | }, 177 | ... 178 | ] 179 | } 180 | ``` 181 | 182 | * `minAmount` - the minimum trade amount the relayer will accept 183 | * `maxAmount` - the maximum trade amount the relayer will accept 184 | * `precision` - the desired price precision a relayer would like to support within their orderbook 185 | * `assetData` - the assetData representing that token 186 | 187 | ### GET /orders 188 | 189 | Retrieves a list of orders given query parameters. This endpoint should be [paginated](#pagination). For querying an entire orderbook snapshot, the [orderbook endpoint](#get-orderbook) is recommended. 190 | 191 | #### Parameters 192 | 193 | Filter parameters: 194 | * makerAssetProxyId [string]: returns orders where the maker asset is of certain [asset proxy id](https://0xproject.com/docs/0x.js#types-AssetProxyId) (example: `0xf47261b0` for `ERC20`, `0x02571792` for `ERC721`) 195 | * takerAssetProxyId [string]: returns orders where the taker asset is of certain [asset proxy id](https://0xproject.com/docs/0x.js#types-AssetProxyId)(example: `0xf47261b0` for `ERC20`, `0x02571792` for `ERC721`) 196 | * makerAssetAddress [string] returns orders where the contract address for the maker asset matches the value specified 197 | * takerAssetAddress [string] returns orders where the contract address for the taker asset matches the value specified 198 | 199 | Order specific parameters: 200 | * senderAddress [string]: returns orders with the specified senderAddress 201 | * makerAssetData [string]: returns orders with the specified makerAssetData 202 | * takerAssetData [string]: returns orders with the specified takerAssetData 203 | * traderAssetData [string]: returns orders where either makerAssetData or takerAssetData has the value specified 204 | * makerAddress [string]: returns orders with the specified makerAddress 205 | * takerAddress [string]: returns orders with the specified takerAddress 206 | * traderAddress [string]: returns orders where either makerAddress or takerAddress has the value specified 207 | * feeRecipientAddress [string]: returns orders where feeRecipientAddress is feeRecipient address 208 | * makerFeeAssetData [string]: returns orders with the specified makerFeeAssetData 209 | * takerFeeAssetData [string]: returns orders with the specified takerFeeAssetData 210 | 211 | All parameters are optional. 212 | 213 | If both makerAssetData and takerAssetData are specified, returned orders will be sorted by price determined by (takerAssetAmount/makerAssetAmount) in ascending order. By default, orders returned by this endpoint are unsorted. 214 | 215 | While there is some redundancy in supporting maker/takerAssetType, maker/takerAssetAddress, and maker/takerAssetData, they are actually all needed. For example, you cannot query "all ERC712 orders", or "all Cryptokitties orders", or "all ERC20 orders" with just maker/takerAssetData and need the other query params to do so. 216 | 217 | #### Response 218 | 219 | [See response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_orders_response_schema.json#L1) 220 | 221 | 222 | ``` 223 | { 224 | "total": 984, 225 | "page": 1, 226 | "perPage": 100, 227 | "records": [ 228 | { 229 | "order": { 230 | "chainId": 1, 231 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 232 | "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 233 | "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 234 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 235 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 236 | "makerAssetAmount": "10000000000000000", 237 | "takerAssetAmount": "20000000000000000", 238 | "makerFee": "100000000000000", 239 | "takerFee": "200000000000000", 240 | "expirationTimeSeconds": "1532560590", 241 | "salt": "1532559225", 242 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 243 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 244 | "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 245 | "takerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 246 | "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33" 247 | }, 248 | "metaData": {} 249 | } 250 | ... 251 | ] 252 | } 253 | ``` 254 | 255 | ### GET /order/[orderHash] 256 | 257 | Retrieves a specific order by orderHash. 258 | 259 | #### Response 260 | 261 | [See response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/signed_order_schema.json#L1) 262 | 263 | ``` 264 | { 265 | "order": { 266 | "chainId": 1, 267 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 268 | "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 269 | "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 270 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 271 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 272 | "makerAssetAmount": "10000000000000000", 273 | "takerAssetAmount": "20000000000000000", 274 | "makerFee": "100000000000000", 275 | "takerFee": "200000000000000", 276 | "expirationTimeSeconds": "1532560590", 277 | "salt": "1532559225", 278 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 279 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 280 | "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 281 | "takerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 282 | "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33" 283 | }, 284 | "metaData": {} 285 | } 286 | ``` 287 | 288 | Returns HTTP 404 if no order with specified orderHash was found. 289 | 290 | ### GET /orderbook 291 | 292 | Retrieves the orderbook for a given asset pair. This endpoint should be [paginated](#pagination). 293 | 294 | #### Parameters 295 | 296 | * baseAssetData [string]: assetData (makerAssetData or takerAssetData) designated as the base currency in the [currency pair calculation](https://en.wikipedia.org/wiki/Currency_pair) of price (required) 297 | * quoteAssetData [string]: assetData (makerAssetData or takerAssetData) designated as the quote currency in the currency pair calculation of price (required) 298 | 299 | #### Response 300 | 301 | [See response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_orderbook_response_schema.json#L1) 302 | 303 | ``` 304 | { 305 | "bids": { 306 | "total": 325, 307 | "page": 2, 308 | "perPage": 100, 309 | "records": [ 310 | { 311 | "order": { 312 | "chainId": 1, 313 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 314 | "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 315 | "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 316 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 317 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 318 | "makerAssetAmount": "10000000000000000", 319 | "takerAssetAmount": "20000000000000000", 320 | "makerFee": "100000000000000", 321 | "takerFee": "200000000000000", 322 | "expirationTimeSeconds": "1532560590", 323 | "salt": "1532559225", 324 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 325 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 326 | "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 327 | "takerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 328 | "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33" 329 | } 330 | "metaData": {} 331 | }, 332 | ... 333 | ] 334 | } 335 | "asks": { 336 | "total": 500, 337 | "page": 2, 338 | "perPage": 100, 339 | "records": [ 340 | { 341 | "order": { 342 | "chainId": 1, 343 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 344 | "makerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 345 | "takerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 346 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 347 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 348 | "makerAssetAmount": "20000000000000000", 349 | "takerAssetAmount": "10000000000000000", 350 | "makerFee": "200000000000000", 351 | "takerFee": "100000000000000", 352 | "expirationTimeSeconds": "1532560590", 353 | "salt": "1532559225", 354 | "makerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 355 | "takerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 356 | "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 357 | "takerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 358 | "signature": "0x013842a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b3518891" 359 | }, 360 | "metaData": {} 361 | }, 362 | ... 363 | ] 364 | } 365 | } 366 | ``` 367 | 368 | * `bids` - array of signed orders where `takerAssetData` is equal to `baseAssetData` 369 | * `asks` - array of signed orders where `makerAssetData` is equal to `baseAssetData` 370 | 371 | 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 by _taker fee price_ which is defined as the **takerFee** divided by **takerTokenAmount**. After _taker fee price_, orders are to be sorted by expiration in ascending order. 372 | 373 | The way pagination works for this endpoint is that the **page** and **perPage** query params apply to both `bids` and `asks` collections, and if `page` * `perPage` > `total` for a certain collection, the `records` for that collection should just be empty. 374 | 375 | ### POST /order_config 376 | 377 | Relayers have full discretion over the orders that they are willing to host on their orderbooks (e.g what fees they charge, etc...). In order for traders to discover their requirements programmatically, they can send an incomplete order to this endpoint and receive the missing fields, specifc to that order. This gives relayers a large amount of flexibility to tailor fees to unique traders, trading pairs and volume amounts. Submit a partial order and receive information required to complete the order: `senderAddress`, `feeRecipientAddress`, `makerFee`, `takerFee`. 378 | 379 | #### Payload 380 | 381 | [See payload schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_order_config_payload_schema.json#L1) 382 | 383 | ``` 384 | { 385 | "chainId": 1, 386 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 387 | "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 388 | "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 389 | "makerAssetAmount": "10000000000000000", 390 | "takerAssetAmount": "20000000000000000", 391 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 392 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 393 | "expirationTimeSeconds": "1532560590" 394 | } 395 | ``` 396 | 397 | #### Response 398 | 399 | [See response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_order_config_response_schema.json#L1) 400 | 401 | ###### Success Response 402 | 403 | Returns a HTTP 201 response with the following payload: 404 | ``` 405 | { 406 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 407 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 408 | "makerFee": "100000000000000", 409 | "takerFee": "200000000000000", 410 | "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 411 | "takerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498" 412 | } 413 | ``` 414 | 415 | ###### Error Response 416 | 417 | Error response will be sent with a non-2xx HTTP status code. See the [Errors](#errors) section for more information. 418 | 419 | ### GET /fee_recipients 420 | 421 | Retrieves a list of all fee recipient addresses for a relayer. This endpoint should be [paginated](#pagination). 422 | 423 | #### Parameters 424 | 425 | No custom parameters, just pagination parameters. 426 | 427 | #### Response 428 | 429 | [See response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_fee_recipients_response_schema.json#L1) 430 | 431 | ``` 432 | { 433 | "total": 3, 434 | "page": 1, 435 | "perPage": 10, 436 | "records": [ 437 | "0x6eC92694ea172ebC430C30fa31De87620967A082", 438 | "0x9e56625509c2f60af937f23b7b532600390e8c8b", 439 | "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32" 440 | ] 441 | } 442 | ``` 443 | 444 | 445 | ### POST /order 446 | 447 | Submit a signed order to the relayer. 448 | 449 | #### Payload 450 | 451 | [See payload schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/signed_order_schema.json#L1) 452 | 453 | ``` 454 | { 455 | "chainId": 1, 456 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 457 | "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 458 | "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 459 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 460 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 461 | "makerAssetAmount": "10000000000000000", 462 | "takerAssetAmount": "20000000000000000", 463 | "makerFee": "100000000000000", 464 | "takerFee": "200000000000000", 465 | "expirationTimeSeconds": "1532560590", 466 | "salt": "1532559225", 467 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 468 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 469 | "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 470 | "takerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 471 | "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33" 472 | } 473 | ``` 474 | 475 | #### Response 476 | 477 | ###### Success Response 478 | 479 | Returns HTTP 201 upon success. 480 | 481 | ###### Error Response 482 | 483 | Error response will be sent with a non-2xx HTTP status code. See the [Errors](#errors) section for more information. 484 | -------------------------------------------------------------------------------- /ws/v0.md: -------------------------------------------------------------------------------- 1 | # WebSocket API Specification v0 2 | 3 | ## Table of Contents 4 | 5 | * [Websocket API](#websocket-api) 6 | * [Orderbook channel](#orderbook-channel) 7 | * [Request messages](#request-messages) 8 | * [Subscribe](#subscribe) 9 | * [Response messages](#response-messages) 10 | * [Snapshot](#snapshot) 11 | * [Update](#update) 12 | 13 | 14 | ## Websocket API 15 | 16 | ### Orderbook Channel 17 | 18 | #### Request messages 19 | 20 | ##### Subscribe 21 | 22 | [See payload schema](https://github.com/0xProject/0x.js/blob/v1-protocol/packages/json-schemas/schemas/relayer_api_orberbook_channel_subscribe_schema.ts#L1) 23 | 24 | ``` 25 | { 26 | "type": "subscribe", 27 | "channel": "orderbook", 28 | "requestId": 1, 29 | "payload": { 30 | "baseTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d", 31 | "quoteTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990", 32 | "snapshot": true, 33 | "limit": 100 34 | } 35 | } 36 | ``` 37 | 38 | - `requestId` - an integer that will be sent back by the server in response messages so the client can appropriately respond when multiple subscriptions are made 39 | - `baseTokenAddress` - address of token designated as the baseToken in the currency pair calculation of price (required) 40 | - `quoteTokenAddress` - address of token designated as the quoteToken in the currency pair calculation of price (required) 41 | - `snapshot` - if `true`, a snapshot of the orderbook will be sent before any updates to the orderbook 42 | - `limit` - maximum number of bids and asks in orderbook snapshot 43 | 44 | #### Response messages 45 | 46 | ##### Snapshot 47 | 48 | This message is sent in response to a subscribe message with the `payload/snapshot` property set to `true` detailed above. It should be the first message received in response to a subscribe message. 49 | 50 | [See payload schema](https://github.com/0xProject/0x.js/blob/v1-protocol/packages/json-schemas/schemas/relayer_api_orderbook_channel_snapshot_schema.ts#L1) 51 | 52 | ``` 53 | { 54 | "type": "snapshot", 55 | "channel": "orderbook", 56 | "requestId": 1, 57 | "payload": { 58 | "bids": [ 59 | { 60 | "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093", 61 | "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 62 | "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 63 | "makerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990", 64 | "takerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d", 65 | "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da", 66 | "makerTokenAmount": "22000000000000000", 67 | "takerTokenAmount": "10000000000000000", 68 | "makerFee": "100000000000000", 69 | "takerFee": "200000000000000", 70 | "expirationUnixTimestampSec": "632", 71 | "salt": "54515451557974875123697849345751275676157243756715784155226239582178", 72 | "ecSignature": { 73 | "v": 27, 74 | "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33", 75 | "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254" 76 | } 77 | }, 78 | ... 79 | ], 80 | "asks": [ 81 | { 82 | "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093", 83 | "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 84 | "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 85 | "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d", 86 | "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990", 87 | "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da", 88 | "makerTokenAmount": "10000000000000000", 89 | "takerTokenAmount": "20000000000000000", 90 | "makerFee": "100000000000000", 91 | "takerFee": "200000000000000", 92 | "expirationUnixTimestampSec": "42", 93 | "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500", 94 | "ecSignature": { 95 | "v": 27, 96 | "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33", 97 | "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254" 98 | } 99 | }, 100 | ... 101 | ] 102 | } 103 | 104 | } 105 | ``` 106 | 107 | - `requestId` - an integer that corresponds to the requestId sent by the client in the `subscribe` message 108 | - `bids` - array of signed orders where `takerTokenAddress` is equal to `baseTokenAddress` 109 | - `asks` - array of signed orders where `makerTokenAddress` is equal to `baseTokenAddress` 110 | 111 | 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. 112 | 113 | ##### Update 114 | 115 | This message is sent whenever the relayer receives or hears about a new order. 116 | 117 | [See payload schema](https://github.com/0xProject/0x.js/blob/v1-protocol/packages/json-schemas/schemas/relayer_api_orderbook_channel_update_response_schema.ts#L1) 118 | 119 | ``` 120 | { 121 | "type": "update", 122 | "channel": "orderbook", 123 | "requestId": 1, 124 | "payload": { 125 | "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093", 126 | "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 127 | "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 128 | "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d", 129 | "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990", 130 | "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da", 131 | "makerTokenAmount": "10000000000000000", 132 | "takerTokenAmount": "20000000000000000", 133 | "makerFee": "100000000000000", 134 | "takerFee": "200000000000000", 135 | "expirationUnixTimestampSec": "42", 136 | "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500", 137 | "ecSignature": { 138 | "v": 27, 139 | "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33", 140 | "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254" 141 | } 142 | } 143 | } 144 | ``` 145 | 146 | - `requestId` - an integer that corresponds to the requestId sent by the client in the `subscribe` message 147 | -------------------------------------------------------------------------------- /ws/v2.md: -------------------------------------------------------------------------------- 1 | # WebSocket API Specification v2 2 | 3 | ## Table of Contents 4 | 5 | - [WebSocket API Specification v2](#websocket-api-specification-v2) 6 | - [Table of Contents](#table-of-contents) 7 | - [Websocket API](#websocket-api) 8 | - [Orders Channel](#orders-channel) 9 | - [Request messages](#request-messages) 10 | - [Subscribe](#subscribe) 11 | - [Response messages](#response-messages) 12 | - [Update](#update) 13 | 14 | ## Websocket API 15 | 16 | The SRA Websocket API is meant to supplement the [REST API](https://github.com/0xProject/standard-relayer-api/blob/master/http/v2.md) by providing updates without resorting to polling. 17 | 18 | ### Orders Channel 19 | 20 | #### Request messages 21 | 22 | ##### Subscribe 23 | 24 | [See payload schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_orders_channel_subscribe_schema.json#L1) 25 | 26 | Minimum request: 27 | ``` 28 | { 29 | "type": "subscribe", 30 | "channel": "orders", 31 | "requestId": "123e4567-e89b-12d3-a456-426655440000" 32 | } 33 | ``` 34 | This will subscribe to all new orders and order state changes in the orderbook. 35 | 36 | Filtered request: 37 | ``` 38 | { 39 | "type": "subscribe", 40 | "channel": "orders", 41 | "requestId": "123e4567-e89b-12d3-a456-426655440000", 42 | "payload": { 43 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 44 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 45 | "networkId": 42, 46 | } 47 | } 48 | ``` 49 | This will subscribe to all new Kovan orders and Kovan order state changes in the orderbook with `makerAssetData` and `takerAssetData` equal to the values specified in the subscribe request. 50 | 51 | **Parameters** 52 | 53 | General: 54 | * `requestId`: a string uuid that will be sent back by the server in response messages so the client can appropriately respond when multiple subscriptions are made 55 | * `networkId`: the Ethereum network id to which you'd like to subscribe. Default is 1 (mainnet). (optional) 56 | 57 | Networks and their Ids: 58 | 59 | | Network Id| Network Name | 60 | | ----------| ------------ | 61 | | 1 | Mainnet | 62 | | 42 | Kovan | 63 | | 3 | Ropsten | 64 | | 4 | Rinkeby | 65 | 66 | Filter parameters (optional): 67 | * `makerAssetProxyId` : returns orders where the maker asset is of certain [asset proxy id](https://0xproject.com/docs/0x.js#types-AssetProxyId) (example: `0xf47261b0` for `ERC20`, `0x02571792` for `ERC721`) 68 | * `takerAssetProxyId`: returns orders where the taker asset is of certain [asset proxy id](https://0xproject.com/docs/0x.js#types-AssetProxyId)(example: `0xf47261b0` for `ERC20`, `0x02571792` for `ERC721`) 69 | * `makerAssetAddress`: subscribes to new orders where the contract address for the maker asset matches the value specified 70 | * `takerAssetAddress`: subscribes to new orders where the contract address for the taker asset matches the value specified 71 | 72 | Order specific parameters (optional): 73 | * `makerAssetData`: subscribes to new orders with the specified makerAssetData 74 | * `takerAssetData`: subscribes to new orders with the specified takerAssetData 75 | * `traderAssetData`: subscribes to new orders where either makerAssetData or takerAssetData has the value specified 76 | 77 | While there is some redundancy in supporting maker/takerAssetType, maker/takerAssetAddress, and maker/takerAssetData, they are actually all needed. For example, you cannot query "all ERC712 orders", or "all Cryptokitties orders", or "all ERC20 orders" with just maker/takerAssetData and need the other query params to do so. 78 | 79 | #### Response messages 80 | 81 | ##### Update 82 | 83 | This message is sent whenever the relayer receives a new order, or when the relayer deems an update necessary (such as when the state of the order changes). For example, some relayers may implement the `remainingTakerAssetAmount` field. If this is the case, the scenarios where an update may occur include: 84 | * The relayer received a new order. 85 | * An order was fully or partially filled, so `remainingTakerAssetAmount` has changed. 86 | * The order is cancelled. 87 | 88 | An update is not necessary for order expiration, as that information can be derived from the `expirationTimeSeconds` field in the order. 89 | 90 | Updates can be sent in bulk since the payload of the message specifies a collection of updated or new orders. 91 | 92 | [See payload schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_orders_channel_update_response_schema.json#L1) 93 | 94 | ``` 95 | { 96 | "type": "update", 97 | "channel": "orders", 98 | "requestId": "123e4567-e89b-12d3-a456-426655440000", 99 | "payload": [ 100 | { 101 | "order": { 102 | "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 103 | "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 104 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 105 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 106 | "makerAssetAmount": "10000000000000000", 107 | "takerAssetAmount": "20000000000000000", 108 | "makerFee": "100000000000000", 109 | "takerFee": "200000000000000", 110 | "expirationTimeSeconds": "1532560590", 111 | "salt": "1532559225", 112 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 113 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 114 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 115 | "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33" 116 | }, 117 | "metaData": { 118 | "remainingTakerAssetAmount": "500000000" 119 | } 120 | }, 121 | ... 122 | ] 123 | } 124 | ``` 125 | 126 | * `requestId` - a string uuid that corresponds to the requestId sent by the client in the `subscribe` message 127 | -------------------------------------------------------------------------------- /ws/v3.md: -------------------------------------------------------------------------------- 1 | # WebSocket API Specification v3 2 | 3 | ## Table of Contents 4 | 5 | - [WebSocket API Specification v3](#websocket-api-specification-v3) 6 | 7 | - [Websocket API](#websocket-api) 8 | - [Orders Channel](#orders-channel) 9 | - [Request messages](#request-messages) 10 | - [Subscribe](#subscribe) 11 | - [Response messages](#response-messages) 12 | - [Update](#update) 13 | 14 | ## Chain Id 15 | 16 | The Standard Relayer API V3 does not specify how to deal with different chain ids (formerly called network ids). The recommendation is to provide a different SRA URL for every chain id that you support. For example, if your mainnet SRA websocket endpoint is hosted at `ws://api.relayer.com/sra/v3/` then the Kovan endpoint could be hosted at `ws://kovan.api.relayer.com/sra/v3/`. 17 | 18 | ## Websocket API 19 | 20 | The SRA Websocket API is meant to supplement the [REST API](https://github.com/0xProject/standard-relayer-api/blob/master/http/v3.md) by providing updates without resorting to polling. 21 | 22 | ### Orders Channel 23 | 24 | #### Request messages 25 | 26 | ##### Subscribe 27 | 28 | [See payload schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_orders_channel_subscribe_schema.json#L1) 29 | 30 | Minimum request: 31 | ``` 32 | { 33 | "type": "subscribe", 34 | "channel": "orders", 35 | "requestId": "123e4567-e89b-12d3-a456-426655440000" 36 | } 37 | ``` 38 | This will subscribe to all new orders and order state changes in the orderbook. 39 | 40 | Filtered request: 41 | ``` 42 | { 43 | "type": "subscribe", 44 | "channel": "orders", 45 | "requestId": "123e4567-e89b-12d3-a456-426655440000", 46 | "payload": { 47 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 48 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063" 49 | } 50 | } 51 | ``` 52 | This will subscribe to all new Kovan orders and Kovan order state changes in the orderbook with `makerAssetData` and `takerAssetData` equal to the values specified in the subscribe request. 53 | 54 | **Parameters** 55 | 56 | General: 57 | * `requestId`: a string uuid that will be sent back by the server in response messages so the client can appropriately respond when multiple subscriptions are made 58 | 59 | Filter parameters (optional): 60 | * `makerAssetProxyId` : returns orders where the maker asset is of certain [asset proxy id](https://0xproject.com/docs/0x.js#types-AssetProxyId) (example: `0xf47261b0` for `ERC20`, `0x02571792` for `ERC721`) 61 | * `takerAssetProxyId`: returns orders where the taker asset is of certain [asset proxy id](https://0xproject.com/docs/0x.js#types-AssetProxyId)(example: `0xf47261b0` for `ERC20`, `0x02571792` for `ERC721`) 62 | * `makerAssetAddress`: subscribes to new orders where the contract address for the maker asset matches the value specified 63 | * `takerAssetAddress`: subscribes to new orders where the contract address for the taker asset matches the value specified 64 | 65 | Order specific parameters (optional): 66 | * `makerAssetData`: subscribes to new orders with the specified makerAssetData 67 | * `takerAssetData`: subscribes to new orders with the specified takerAssetData 68 | * `traderAssetData`: subscribes to new orders where either makerAssetData or takerAssetData has the value specified 69 | 70 | While there is some redundancy in supporting maker/takerAssetType, maker/takerAssetAddress, and maker/takerAssetData, they are actually all needed. For example, you cannot query "all ERC712 orders", or "all Cryptokitties orders", or "all ERC20 orders" with just maker/takerAssetData and need the other query params to do so. 71 | 72 | #### Response messages 73 | 74 | ##### Update 75 | 76 | This message is sent whenever the relayer receives a new order, or when the relayer deems an update necessary (such as when the state of the order changes). For example, some relayers may implement the `remainingTakerAssetAmount` field. If this is the case, the scenarios where an update may occur include: 77 | * The relayer received a new order. 78 | * An order was fully or partially filled, so `remainingTakerAssetAmount` has changed. 79 | * The order is cancelled. 80 | 81 | An update is not necessary for order expiration, as that information can be derived from the `expirationTimeSeconds` field in the order. 82 | 83 | Updates can be sent in bulk since the payload of the message specifies a collection of updated or new orders. 84 | 85 | [See payload schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_orders_channel_update_response_schema.json#L1) 86 | 87 | ``` 88 | { 89 | "type": "update", 90 | "channel": "orders", 91 | "requestId": "123e4567-e89b-12d3-a456-426655440000", 92 | "payload": [ 93 | { 94 | "order": { 95 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 96 | "domainHash" "0x78772b297e1b0b31089589a6608930cceba855af9d3ccf7b92cf47fa881e21f7", 97 | "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b", 98 | "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 99 | "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da", 100 | "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32", 101 | "makerAssetAmount": "10000000000000000", 102 | "takerAssetAmount": "20000000000000000", 103 | "makerFee": "100000000000000", 104 | "takerFee": "200000000000000", 105 | "expirationTimeSeconds": "1532560590", 106 | "salt": "1532559225", 107 | "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 108 | "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063", 109 | "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093", 110 | "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 111 | "takerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", 112 | "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33" 113 | }, 114 | "metaData": { 115 | "remainingTakerAssetAmount": "500000000" 116 | } 117 | }, 118 | ... 119 | ] 120 | } 121 | ``` 122 | 123 | * `requestId` - a string uuid that corresponds to the requestId sent by the client in the `subscribe` message 124 | --------------------------------------------------------------------------------