NAV Navbar
  • SRA API Reference
  • REST API
  • REST API Extensions
  • Websocket API
  • SRA API Reference

    Endpoint

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

    Bamboo Relay currently supports Ethereum Mainnet and Ropsten, Rinkeby, Kovan testnets.

    https://sra.bamboorelay.com/main/v0/
    
    https://sra.bamboorelay.com/ropsten/v0/
    
    https://sra.bamboorelay.com/rinkeby/v0/
    
    https://sra.bamboorelay.com/kovan/v0/
    

    Pagination

    Requests that return multiple items should respond to the ?page and ?per_page parameters.

    curl "https://sra.bamboorelay.com/main/v0/orders?page=3&per_page=20"
    

    Page numbering should be 1-indexed, not 0-indexed.

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

    Bamboo Relay reserves the right to automatically paginate large result sets if no parameters are provided.

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

    Link: <https://sra.bamboorelay.com/main/v0/token_pairs?page=3&per_page=20>; rel="next",
    <https://sra.bamboorelay.com/main/v0/token_pairs?page=10&per_page=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/main/v0/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

    Misc.

    REST API

    GET /v0/token_pairs

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

    Parameters

    Response

    See response schema

    [
        {
            "tokenA": {
                "address": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
                "minAmount": "0",
                "maxAmount": "10000000000000000000",
                "precision": 5
            },
            "tokenB": {
                "address": "0xef7fff64389b814a946f3e92105513705ca6b990",
                "minAmount": "0",
                "maxAmount": "50000000000000000000",
                "precision": 5
            }
        },
        ...
    ]
    

    GET /v0/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

    All parameters are optional.

    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.

    Response

    See response schema

    [
        {
            "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
            "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
            "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
            "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
            "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
            "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
            "makerTokenAmount": "10000000000000000",
            "takerTokenAmount": "20000000000000000",
            "makerFee": "100000000000000",
            "takerFee": "200000000000000",
            "expirationUnixTimestampSec": "42",
            "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
            "ecSignature": {
                "v": 27,
                "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
                "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
            }
        },
        ...
    ]
    

    GET /v0/order/[orderHash]

    Retrieves a specific order by orderHash.

    Response

    See response schema

    {
        "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
        "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
        "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
        "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
        "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
        "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
        "makerTokenAmount": "10000000000000000",
        "takerTokenAmount": "20000000000000000",
        "makerFee": "100000000000000",
        "takerFee": "200000000000000",
        "expirationUnixTimestampSec": "42",
        "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
        "ecSignature": {
            "v": 27,
            "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
            "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
        }
    }
    

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

    GET /v0/orderbook

    Retrieves the orderbook for a given token pair.

    Parameters

    Response

    See response schema

    {
        "bids": [
            {
                "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
                "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
                "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
                "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
                "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
                "makerTokenAmount": "10000000000000000",
                "takerTokenAmount": "20000000000000000",
                "makerFee": "100000000000000",
                "takerFee": "200000000000000",
                "expirationUnixTimestampSec": "42",
                "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
                "ecSignature": {
                    "v": 27,
                    "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
                    "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
                }
            },
            ...
        ],
        "asks": [
            {
                "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
                "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
                "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                "makerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
                "takerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
                "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
                "makerTokenAmount": "22000000000000000",
                "takerTokenAmount": "10000000000000000",
                "makerFee": "100000000000000",
                "takerFee": "200000000000000",
                "expirationUnixTimestampSec": "632",
                "salt": "54515451557974875123697849345751275676157243756715784155226239582178",
                "ecSignature": {
                    "v": 27,
                    "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
                    "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
                }
            },
            ...
        ]
    }
    

    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.

    POST /v0/fees

    Given an unsigned order without the fee-related properties, returns the required feeRecipient, makerFee, and takerFee of that order.

    Payload

    See payload schema

    {
        "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
        "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
        "taker": "0x0000000000000000000000000000000000000000",
        "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
        "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
        "makerTokenAmount": "10000000000000000",
        "takerTokenAmount": "20000000000000000",
        "expirationUnixTimestampSec": "42",
        "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500"
    }
    

    Response

    See response schema

    {
        "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
        "makerFee": "100000000000000",
        "takerFee": "200000000000000"
    }
    

    POST /v0/order

    Submit a signed order to the relayer.

    Payload

    See payload schema

    {
        "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
        "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
        "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
        "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
        "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
        "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
        "makerTokenAmount": "10000000000000000",
        "takerTokenAmount": "20000000000000000",
        "makerFee": "100000000000000",
        "takerFee": "200000000000000",
        "expirationUnixTimestampSec": "42",
        "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
        "ecSignature": {
            "v": 27,
            "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
            "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
        }
    }
    

    Response

    Success Response

    Returns HTTP 201 upon success.

    Error Response

    Error response will be sent with a non-2xx HTTP status code

    See 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 ECDSA or Hash
    1006 - Unsupported option
    

    REST API Extensions

    DELETE /v0/cancelOrders

    Cancels orders and removes them from the order book and API.

    Payload

    The challenge must be signed with the Ethereum Signed Message prefix and by the same private key as address

    {
        "address": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
        "ecSignature": {
           "v": 27,
           "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
           "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
        },
        "orderHash": [
          "0xc9032156213c565108f32e6f0e9000c564297bf7636fd646dbd4f33d04c3ec76",
          "0x8b9d14ba0e8e5c1b7c5e13aa39148665e3102b8756301141fa68297814f0e7fc"
          ...
        ]
    }
    

    Response

    Success Response

    Returns HTTP 200 upon success.

    Error Response

    Error response will be sent with a non-2xx HTTP status code

    PUT /v0/fillOrders

    Notifies Bamboo Relay of your intent to fill an order, reduces latency on updating the order book and re-broadcasts your transaction to our backbone Parity nodes.

    It is in your best interest to notify this end point as it will reduce the chance that an order is double filled and gas wasted.

    Payload

    The payload is a JSON representation of a signed Ethereum Transaction.

    { 
      "nonce": "0x0109",
      "gasPrice": "0x01",
      "gasLimit": "0x030d40",
      "to": "0xb69e673309512a9d726f87304c6984054f87a93b",
      "value": "0x",
      "data": "0x363349be000000000000000000000000000000000000...",
      "v": "0x1c",
      "r": "0x5539615eb293e82b4a99d9eb095ac40cea733e854f6064c4140459dedbf569e7",
      "s": "0x64aab2b6b5fc12813429a4c23791f4ff5d139a85bdcd325aa3c6ffccce6d6532" 
    }
    

    Response

    Success Response

    Returns HTTP 200 upon success.

    Error Response

    Error response will be sent with a non-2xx HTTP status code

    Websocket API

    Endpoint

    Websocket endpoints are available for Ethereum Mainnet and Ropsten, Rinkeby, Kovan testnets.

    wss://sra.bamboorelay.com/main/v0/websocket
    
    wss://sra.bamboorelay.com/ropsten/v0/websocket
    
    wss://sra.bamboorelay.com/rinkeby/v0/websocket
    
    wss://sra.bamboorelay.com/kovan/v0/websocket
    

    Orderbook Channel

    Request messages

    Subscribe

    See payload schema

    {
        "type": "subscribe",
        "channel": "orderbook",
        "requestId": 1,
        "payload": {
            "baseTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
            "quoteTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
            "snapshot": true,
            "limit": 100
        }
    }
    

    Response messages

    Snapshot

    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.

    See payload schema

    {
        "type": "snapshot",
        "channel": "orderbook",
        "requestId": 1,
        "payload": {
            "bids": [
                {
                    "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
                    "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
                    "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                    "makerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
                    "takerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
                    "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
                    "makerTokenAmount": "22000000000000000",
                    "takerTokenAmount": "10000000000000000",
                    "makerFee": "100000000000000",
                    "takerFee": "200000000000000",
                    "expirationUnixTimestampSec": "632",
                    "salt": "54515451557974875123697849345751275676157243756715784155226239582178",
                    "ecSignature": {
                        "v": 27,
                        "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
                        "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
                    }
                },
                ...
            ],
            "asks": [
                {
                    "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
                    "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
                    "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                    "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
                    "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
                    "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
                    "makerTokenAmount": "10000000000000000",
                    "takerTokenAmount": "20000000000000000",
                    "makerFee": "100000000000000",
                    "takerFee": "200000000000000",
                    "expirationUnixTimestampSec": "42",
                    "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
                    "ecSignature": {
                        "v": 27,
                        "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
                        "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
                    }
                },
                ...
            ]
        }
    
    }
    

    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.

    Update

    This message is sent whenever the relayer receives or hears about a new order.

    See payload schema

    {
        "type": "update",
        "channel": "orderbook",
        "requestId": 1,
        "payload": {
            "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
            "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
            "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
            "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
            "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
            "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
            "makerTokenAmount": "10000000000000000",
            "takerTokenAmount": "20000000000000000",
            "makerFee": "100000000000000",
            "takerFee": "200000000000000",
            "expirationUnixTimestampSec": "42",
            "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
            "ecSignature": {
                "v": 27,
                "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
                "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
            }
        }
    }