NAV Navbar
  • 0x HTTP REST API Specification v2
  • REST API
  • 0x WebSocket API Specification v2
  • 0x HTTP REST API Specification v2

    Endpoint

    The Bamboo Relay 0x Standard Relayer API implements the 0x v2 standard relayer specification.

    https://sra.bamboorelay.com/0x/v2/
    

    Pagination

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

    curl https://sra.bamboorelay.com/0x/v2/asset_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://sra.bamboorelay.com/0x/v2/asset_pairs?networkId=1
    

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

    Networks and their Ids:

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

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

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

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

    Link: <https://sra.bamboorelay.com/0x/v2/asset_pairs?page=3&perPage=20>; rel="next",
    <https://sra.bamboorelay.com/0x/v2/asset_pairs?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://sra.bamboorelay.com/0x/v2/asset_pairs
    HTTP/1.1 200 OK
    Date: Mon, 20 Oct 2017 12:30:06 GMT
    Status: 200 OK
    X-RateLimit-Limit: 60
    X-RateLimit-Remaining: 56
    X-RateLimit-Reset: 1372700873
    

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

    Errors

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

    Common error codes

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

    Error reporting format

    For all 400 responses, see the error response schema.

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

    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

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

    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:

    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

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

    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 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.

    0x WebSocket API Specification v2

    The SRA Websocket API is meant to supplement the REST API by providing updates without resorting to polling.

    Endpoint

    wss://sra.bamboorelay.com/0x/v2/ws
    

    Orders Channel

    Request messages

    Subscribe

    See payload schema

    Minimum request:

    {
        "type": "subscribe",
        "channel": "orders",
        "requestId": "123e4567-e89b-12d3-a456-426655440000"
    }
    

    This will subscribe to all new orders and order state changes in the orderbook.

    Filtered request:

    {
        "type": "subscribe",
        "channel": "orders",
        "requestId": "123e4567-e89b-12d3-a456-426655440000",
        "payload": {
            "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
            "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063",
            "networkId": 42,
        }
    }
    

    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.

    Parameters

    General:

    Networks and their Ids:

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

    Filter parameters (optional):

    Order specific parameters (optional):

    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 messages

    Update

    This message is sent whenever Bamboo Relay receives a new order. API consumers are encouraged to watch the Ethereum network for event logs that pertain to 0x order updates.

    Updates are sent sequentially as recieved by Bamboo Relay.

    See payload schema

    {
        "type": "update",
        "channel": "orders",
        "requestId": "123e4567-e89b-12d3-a456-426655440000",
        "payload":  [
            {
              "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": {
                  "remainingTakerAssetAmount": "500000000"
                }
            },
            ...
        ]
    }