NAV Navbar

Lake Connect

TLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTL
TLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTL
TLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTL
TLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTL
TLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTL
TLPTLPTLPTL               TLPTLPTLPTLPTLPTLPTLPTLP
TLPTLPTLPTL               TLPTLPTLPTLPTLPTLPTLPTLP
TLPTLPTLPTLP              TLPTLPTLPTLPTLPTLPTLPTLP
TLPTLPTLPTLPT             TLPTLPTLPTLPTLPTLPTLPTLP
TLPTLPTLPTLPTLP           TLPTLPTLPTLPTLPTLPTLPTLP
TLPTLPTLPTLPTLPTL         TLPTLPTLPTLPTLPTLPTLPTLP
TLPTLPTLPTLPTLPTLPTLP     TLPTLPTLPTLPTLPTLPTLPTLP
TLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTL
TLPTLPTLPTLPTLPTLPTLPTLPTLP               TLPTLPTL
TLPTLPTLPTLPTLPTLPTLPTLPTLP               TLPTLPTL
TLPTLPTLPTLPTLPTLPTLPTLPTLP              TLPTLPTLP
TLPTLPTLPTLPTLPTLPTLPTLPTLP             TLPTLPTLPT
TLPTLPTLPTLPTLPTLPTLPTLPTLP           TLPTLPTLPTLP
TLPTLPTLPTLPTLPTLPTLPTLPTLP         TLPTLPTLPTLPTL
TLPTLPTLPTLPTLPTLPTLPTLPTLP     TLPTLPTLPTLPTLPTLP
TLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTL
TLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTL
TLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTL
TLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTL
TLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTLPTL

Lake Connect is a trading API compliant with 0xProject's SRA standards (Standard Relayer API). As a relayer, TheLakeProject is a part of a network that helps to distribute trade liquidity amongst other relayers.

Before proceeding!

Please take the time to get acquainted with the following documentation

@0x-connect

This repository contains a Javascript library that makes it easy to interact with Relayers such as TheLakeProject, whom conform to the Standard Relayer API

@0x-standard-relayer-api

A specification detailing SRA standards for compliance

Network Id

Networks and their Ids:

Example of specifying a networkId

$ curl https://api.lakeproject.co/v2/<ENDPOINT_HERE>?networkId=1

All requests should be able to specify a networkId query parameter for all supported networks.

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

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

Response when providing an invalid networkId

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

If a certain network is not supported, the response should 400 as specified in the Errors section.

Pagination

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

Sample request using pagination

$ curl https://api.lakeproject.co/v2/<ENDPOINT_HERE>?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.

Headers

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

Example of using link headers

Link:
<https://api.lakeproject.co/v2/<ENDPOINT_HERE>?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:

For example

$ curl -i https://api.lakeproject.co/v2/<ENDPOINT_HERE>
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
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.

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

REST API Endpoints

GET /v2/asset_pairs

Sample response

{
  "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"
      }
    },
    ...
  ]
}

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

Parameters

Response

See response schema

GET /v2/orders

Sample response

{
  "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": {
        ...
      }
    }
    ...
  ]
}

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:

Order specific parameters:

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

GET /v2/order/[orderHash]

Sample response

{
  "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": {
    ...
  }
}

Retrieves a specific order by orderHash.

Response

See response schema

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

GET /v2/orderbook

Sample response

{
  "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": {
          ...
        }
      },
      ...
    ]
  }
}

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

Parameters

Response

See response schema

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

Sample payload

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

Success response returns a HTTP 201 response with the following payload

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

Error response - returns HTTP non-2xx status code. See the Errors section for more information.

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

Response

See response schema

GET /v2/fee_recipients

Sample response

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

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

POST /v2/order

Sample payload

{
    "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"
}

Submit a signed order to the relayer.

Payload

See payload schema

Success response - returns HTTP 201 upon success.

Error response - returns HTTP non-2xx status code. See the Errors section for more information.

Response

Does not conform to any response schema

Errors

Common error codes

For all 400 responses, see the error response schema.

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

Sample error response

{
    "code": 101,
    "reason": "Validation failed",
    "validationErrors": [
        {
            "field": "maker",
            "code": 1002,
            "reason": "Invalid address"
        }
    ]
}
General error codes: Reason
100 Validation Failed
101 Malformed JSON
102 Order submission disabled
103 Throttled
Validation error codes: Reason
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