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

    Endpoint

    The Bamboo Relay 0x Standard Relayer API implements and extends the 0x v3 standard relayer specification.

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

    Pagination

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

    curl https://sra.bamboorelay.com/0x/v3/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.

    Chain Id

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

    curl https://sra.bamboorelay.com/0x/v3/asset_pairs?chainId=1
    

    Alternatively a chain may be addressed in the path:

    curl https://sra.bamboorelay.com/mainnet/0x/v3/asset_pairs
    curl https://sra.bamboorelay.com/kovan/0x/v3/asset_pairs
    curl https://sra.bamboorelay.com/ropsten/0x/v3/asset_pairs
    curl https://sra.bamboorelay.com/rinkeby/0x/v3/asset_pairs
    

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

    Chains and their Ids:

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

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

    {
        "code": 100,
        "reason": "Validation failed",
        "validationErrors": [
            {
                "field": "chainId",
                "code": 1006,
                "reason": "Chain 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/v3/asset_pairs?page=3&perPage=20>; rel="next",
    <https://sra.bamboorelay.com/0x/v3/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/v3/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 /v3/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",
                    "symbol": "ZRX",
                    "decimals": 18
                },
                "assetDataB": {
                    "minAmount": "0",
                    "maxAmount": "50000000000000000000",
                    "precision": 5,
                    "assetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                    "symbol": "WETH",
                    "decimals": 18
                }
            },
            ...
        ]
    }
    

    GET /v3/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": {
                  "chainId": 1,
                  "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
                  "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                  "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
                  "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                  "makerAssetAmount": "10000000000000000",
                  "takerAssetAmount": "20000000000000000",
                  "makerFee": "100000000000000",
                  "takerFee": "200000000000000",
                  "expirationTimeSeconds": "1532560590",
                  "salt": "1532559225",
                  "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
                  "takerAssetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                  "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
                  "takerFeeAssetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                  "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093",
                  "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33"
                },
                "metaData": {}
            }
            ...
        ]
    }
    

    GET /v3/order/[orderHash]

    Retrieves a specific order by orderHash.

    Response

    See response schema

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

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

    GET /v3/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": {
                        "chainId": 1,
                        "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
                        "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                        "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
                        "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                        "makerAssetAmount": "10000000000000000",
                        "takerAssetAmount": "20000000000000000",
                        "makerFee": "100000000000000",
                        "takerFee": "200000000000000",
                        "expirationTimeSeconds": "1532560590",
                        "salt": "1532559225",
                        "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
                        "takerAssetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                        "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
                        "takerFeeAssetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                        "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093",
                        "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33"
                    }
                    "metaData": {}
              },
              ...
            ]
        }
        "asks": {
            "total": 500,
            "page": 2,
            "perPage": 100,
            "records": [
                {
                    "order":  {
                        "chainId": 1,
                        "makerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                        "takerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
                        "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
                        "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                        "makerAssetAmount": "20000000000000000",
                        "takerAssetAmount": "10000000000000000",
                        "makerFee": "200000000000000",
                        "takerFee": "100000000000000",
                        "expirationTimeSeconds": "1532560590",
                        "salt": "1532559225",
                        "makerAssetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                        "takerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
                        "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
                        "takerFeeAssetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                        "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 /v3/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

    {
        "chainId": 1,
        "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
        "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
        "makerAssetAmount": "10000000000000000",
        "takerAssetAmount": "20000000000000000",
        "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
        "takerAssetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
        "takerFeeAssetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "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 /v3/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 /v3/order

    Submit a signed order to the relayer.

    Payload

    See payload schema

    {
        "chainId": 1,
        "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
        "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
        "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
        "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
        "makerAssetAmount": "10000000000000000",
        "takerAssetAmount": "20000000000000000",
        "makerFee": "100000000000000",
        "takerFee": "200000000000000",
        "expirationTimeSeconds": "1532560590",
        "salt": "1532559225",
        "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
        "takerAssetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
        "takerFeeAssetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "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 v3

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

    Ping / Pong Frames

    The server will send Ping frames once every 30 seconds over a WebSocket connection. It is expected the client connection will respond with a Pong frame, otherwise the connection will be terminated.

    It is advised that the client WebSocket connection also sends periodic Ping frames in order to keep the connection open.

    Endpoint

    wss://sra.bamboorelay.com/0x/v3/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": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "chainId": 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:

    Chains and their Ids:

    Chain Id Chain 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, orders are filled or orders are cancelled.

    Updates may be sent sequentially in the case of new orders, or in a batch of multiple in the case of order expiries.

    See payload schema

    {
        "type": "update",
        "channel": "orders",
        "requestId": "123e4567-e89b-12d3-a456-426655440000",
        "payload":  [
            {
              "order": {
                  "chainId": 1,
                  "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
                  "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                  "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
                  "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                  "makerAssetAmount": "10000000000000000",
                  "takerAssetAmount": "20000000000000000",
                  "makerFee": "100000000000000",
                  "takerFee": "200000000000000",
                  "expirationTimeSeconds": "1532560590",
                  "salt": "1532559225",
                  "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
                  "takerAssetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                  "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
                  "takerFeeAssetData": "0xf47261b0000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                  "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093",
                  "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33"
                },
                "metaData": {
                  "action": "REMOVED",
                  "orderHash": "0x653a64f3a1c9f62c93de63dc0d0c416c5fe8754418cb32e0d8c29c725037252c",
                  "remainingTakerAssetAmount": "500000000",
                  "isCoordinated": true,
                  "assetPair": "WETH/DAI",
                  "type": "BID",
                  "bridgedMarket": "Eth2Dai"
                }
            },
            ...
        ]
    }
    

    action values correspond to: