Skip to content

Latest commit

 

History

History
494 lines (390 loc) · 20.6 KB

v2.md

File metadata and controls

494 lines (390 loc) · 20.6 KB
Raw

HTTP REST API Specification v2

Table of Contents

General

Pagination

Requests that return potentially large collections should respond to the ?page and ?perPage parameters. For example:

curl https://api.example-relayer.com/v2/token_pairs?page=3&perPage=20

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. If the query specifies a page that does not exist (ie. there are not enough records), the response should just return an empty records array.

All endpoints that are paginated should return a total, page, perPage and a records value in the top level of the collection. The value of total should be the total number of records for a given query, whereas records should be an array representing the response to the query for that page. page and perPage, are the same values that were specified in the request.

These requests include the asset_pairs, orders, and orderbook endpoints.

Network Id

All requests should be able to specify a ?networkId query param for all supported networks. For example:

curl https://api.example-relayer.com/v2/token_pairs?networkId=1

If the query param is not provided, it should default to 1 (mainnet).

Networks and their Ids:

Network Id Network Name
1 Mainnet
42 Kovan
3 Ropsten
4 Rinkeby

If a certain network is not supported, the response should 400 as specified in the error response section. For example:

{
    "code": 100,
    "reason": "Validation failed",
    "validationErrors": [
        {
            "field": "networkId",
            "code": 1006,
            "reason": "Network id 42 is not supported",
        }
    ]
}

Link Header

A Link Header can be included in a response to provide clients with more context about paging For example:

Link: <https://api.example-relayer.com/v2/token_pairs?page=3&perPage=20>; rel="next",
<https://api.github.com/user/repos?page=10&perPage=20>; rel="last"

This Link response header contains one or more Hypermedia link relations.

The possible rel values are:

Name Description
next The link relation for the immediate next page of results.
last The link relation for the last page of results.
first The link relation for the first page of results.
prev The link relation for the immediate previous page of results.

Rate Limits

Rate limit guidance for clients can be optionally returned in the response headers:

Header Name Description
X-RateLimit-Limit The maximum number of requests you're permitted to make per hour.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

For example:

curl -i https://api.example-relayer.com/v2/token_pairs
HTTP/1.1 200 OK
Date: Mon, 20 Oct 2017 12:30:06 GMT
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 56
X-RateLimit-Reset: 1372700873

When a rate limit is exceeded, a status of 429 Too Many Requests should be returned.

Errors

Unless the spec defines otherwise, errors to bad requests should respond with HTTP 4xx or status codes.

Common error codes

Code Reason
400 Bad Request – Invalid request format
404 Not found
429 Too many requests - Rate limit exceeded
500 Internal Server Error
501 Not Implemented

Error reporting format

For all 400 responses, see the error response schema.

{
    "code": 101,
    "reason": "Validation failed",
    "validationErrors": [
        {
            "field": "maker",
            "code": 1002,
            "reason": "Invalid address"
        }
    ]
}

General error codes:

100 - Validation Failed
101 - Malformed JSON
102 - Order submission disabled
103 - Throttled

Validation error codes:

1000 - Required field
1001 - Incorrect format
1002 - Invalid address
1003 - Address not supported
1004 - Value out of range
1005 - Invalid signature or hash
1006 - Unsupported option

Misc.

  • All requests and responses should be of application/json content type
  • All token amounts are sent in amounts of the smallest level of precision (base units). (e.g if a token has 18 decimal places, selling 1 token would show up as selling '1000000000000000000' units by this API).
  • All addresses are sent as lower-case (non-checksummed) Ethereum addresses with the 0x prefix.
  • All parameters should use lowerCamelCase.

REST API

GET /v2/asset_pairs

Retrieves a list of available asset pairs and the information required to trade them. This endpoint should be paginated.

Parameters

  • 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)

Response

See response schema

{
    "total": 43,
    "page": 1,
    "perPage": 100,
    "records": [
        {
            "assetDataA": {
                "minAmount": "0",
                "maxAmount": "10000000000000000000",
                "precision": 5,
                "assetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498"
            },
            "assetDataB": {
                "minAmount": "0",
                "maxAmount": "50000000000000000000",
                "precision": 5,
                "assetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063"
            }
        },
        ...
    ]
}
  • minAmount - the minimum trade amount the relayer will accept
  • maxAmount - the maximum trade amount the relayer will accept
  • precision - the desired price precision a relayer would like to support within their orderbook
  • assetData - the assetData representing that token

GET /v2/orders

Retrieves a list of orders given query parameters. This endpoint should be paginated. For querying an entire orderbook snapshot, the orderbook endpoint is recommended.

Parameters

Filter parameters:

  • makerAssetProxyId [string]: returns orders where the maker asset is of certain asset proxy id (example: 0xf47261b0 for ERC20, 0x02571792 for ERC721)
  • takerAssetProxyId [string]: returns orders where the taker asset is of certain asset proxy id(example: 0xf47261b0 for ERC20, 0x02571792 for ERC721)
  • makerAssetAddress [string] returns orders where the contract address for the maker asset matches the value specified
  • takerAssetAddress [string] returns orders where the contract address for the taker asset matches the value specified

Order specific parameters:

  • exchangeAddress [string]: returns orders created for this exchange address
  • senderAddress [string]: returns orders with the specified senderAddress
  • makerAssetData [string]: returns orders with the specified makerAssetData
  • takerAssetData [string]: returns orders with the specified takerAssetData
  • traderAssetData [string]: returns orders where either makerAssetData or takerAssetData has the value specified
  • makerAddress [string]: returns orders with the specified makerAddress
  • takerAddress [string]: returns orders with the specified takerAddress
  • traderAddress [string]: returns orders where either makerAddress or takerAddress has the value specified
  • feeRecipientAddress [string]: returns orders where feeRecipientAddress is feeRecipient address

All parameters are optional.

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.

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.

Response

See response schema

{
    "total": 984,
    "page": 1,
    "perPage": 100,
    "records": [
        {
          "order": {
              "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
              "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
              "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
              "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
              "makerAssetAmount": "10000000000000000",
              "takerAssetAmount": "20000000000000000",
              "makerFee": "100000000000000",
              "takerFee": "200000000000000",
              "expirationTimeSeconds": "1532560590",
              "salt": "1532559225",
              "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
              "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063",
              "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093",
              "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33"
            },
            "metaData": {}
        }
        ...
    ]
}

GET /v2/order/[orderHash]

Retrieves a specific order by orderHash.

Response

See response schema

{
      "order": {
          "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
          "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
          "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
          "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
          "makerAssetAmount": "10000000000000000",
          "takerAssetAmount": "20000000000000000",
          "makerFee": "100000000000000",
          "takerFee": "200000000000000",
          "expirationTimeSeconds": "1532560590",
          "salt": "1532559225",
          "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
          "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063",
          "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093",
          "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33"
      },
      "metaData": {}
}

Returns HTTP 404 if no order with specified orderHash was found.

GET /v2/orderbook

Retrieves the orderbook for a given asset pair. This endpoint should be paginated.

Parameters

  • baseAssetData [string]: assetData (makerAssetData or takerAssetData) designated as the base currency in the currency pair calculation of price (required)
  • quoteAssetData [string]: assetData (makerAssetData or takerAssetData) designated as the quote currency in the currency pair calculation of price (required)

Response

See response schema

{
    "bids": {
        "total": 325,
        "page": 2,
        "perPage": 100,
        "records": [
            {
                "order": {
                    "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
                    "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                    "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
                    "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                    "makerAssetAmount": "10000000000000000",
                    "takerAssetAmount": "20000000000000000",
                    "makerFee": "100000000000000",
                    "takerFee": "200000000000000",
                    "expirationTimeSeconds": "1532560590",
                    "salt": "1532559225",
                    "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
                    "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063",
                    "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093",
                    "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33"
                }
                "metaData": {}
          },
          ...
        ]
    }
    "asks": {
        "total": 500,
        "page": 2,
        "perPage": 100,
        "records": [
            {
                "order":  {
                    "makerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                    "takerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
                    "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
                    "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                    "makerAssetAmount": "20000000000000000",
                    "takerAssetAmount": "10000000000000000",
                    "makerFee": "200000000000000",
                    "takerFee": "100000000000000",
                    "expirationTimeSeconds": "1532560590",
                    "salt": "1532559225",
                    "makerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063",
                    "takerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
                    "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093",
                    "signature": "0x013842a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b3518891"
                },
                "metaData": {}
            },
          ...
        ]  
    }
}
  • bids - array of signed orders where takerAssetData is equal to baseAssetData
  • asks - array of signed orders where makerAssetData is equal to baseAssetData

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.

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.

POST /v2/order_config

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.

Payload

See payload schema

{
    "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
    "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
    "makerAssetAmount": "10000000000000000",
    "takerAssetAmount": "20000000000000000",
    "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
    "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063",
    "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093",
    "expirationTimeSeconds": "1532560590"
}

Response

See response schema

Success Response

Returns a HTTP 201 response with the following payload:

{
    "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
    "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
    "makerFee": "100000000000000",
    "takerFee": "200000000000000"
}
Error Response

Error response will be sent with a non-2xx HTTP status code. See the Errors section for more information.

GET /v2/fee_recipients

Retrieves a list of all fee recipient addresses for a relayer. This endpoint should be paginated.

Parameters

No custom parameters, just pagination parameters.

Response

See response schema

{
    "total": 3,
    "page": 1,
    "perPage": 10,
    "records": [
        "0x6eC92694ea172ebC430C30fa31De87620967A082", 
        "0x9e56625509c2f60af937f23b7b532600390e8c8b", 
        "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32"
    ]
}

POST /v2/order

Submit a signed order to the relayer.

Payload

See payload schema

{
    "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
    "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
    "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
    "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
    "makerAssetAmount": "10000000000000000",
    "takerAssetAmount": "20000000000000000",
    "makerFee": "100000000000000",
    "takerFee": "200000000000000",
    "expirationTimeSeconds": "1532560590",
    "salt": "1532559225",
    "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
    "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063",
    "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093",
    "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33"
}

Response

Success Response

Returns HTTP 201 upon success.

Error Response

Error response will be sent with a non-2xx HTTP status code. See the Errors section for more information.