NAV Navbar
  • bZx HTTP REST API Specification v1
  • REST API
  • WebSocket API Specification v1
  • bZx HTTP REST API Specification v1

    Endpoint

    The Bamboo Relay bZx Standard Relayer API implements the bZx v1 standard relayer specification.

    https://sra.bamboorelay.com/bzx/v1/
    

    Pagination

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

    curl https://sra.bamboorelay.com/bzx/v1/tokens?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/bzx/v1/tokens?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/bzx/v1/tokens?page=3&perPage=20>; rel="next",
    <https://sra.bamboorelay.com/bzx/v1/tokens?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/bzx/v1/tokens
    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 /v1/tokens

    Retrieves a list of available tokens and the information required to loan them. This endpoint should be paginated.

    Response

    {
        "total": 43,
        "page": 1,
        "perPage": 100,
        "records": [
            {
                "minAmount": "0",
                "maxAmount": "10000000000000000000",
                "precision": 5,
                "address": "0xe41d2489571d322189246dafa5ebde1f4699f498"
            },
            ...
        ]
    }
    

    GET /v1/orders

    Retrieves a list of loan 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.

    By default, orders returned by this endpoint are unsorted.

    Response

    {
        "total": 984,
        "page": 1,
        "perPage": 100,
        "records": [
            {
                "order": {
                    "bZxAddress" :"0xaa86dda78e9434aca114b6676fc742a18d15a1cc",
                    "makerAddress": "0x5409ed021d9299bf6814279a6a1411a7e866a631",
                    "loanTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
                    "interestTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
                    "collateralTokenAddress": "0x0000000000000000000000000000000000000000",
                    "feeRecipientAddress": "0x5dd835a893734b8d556eccf87800b76dda5aedc5",
                    "oracleAddress": "0xe704967449b57b2382b7fa482718748c13c63190",
                    "loanTokenAmount": "5000000000000000000",
                    "interestAmount": "1000000000000000000",
                    "initialMarginAmount": "50",
                    "maintenanceMarginAmount": "25",
                    "lenderRelayFee": "0",
                    "traderRelayFee": "0",
                    "maxDurationUnixTimestampSec": "604800",
                    "expirationUnixTimestampSec": "1540786678",
                    "makerRole": "0",
                    "salt": "59940742713651368663364744180266918345412120379624374896164725450574161449117",
                    "ecSignature": "0x6420ffffe4a1849e4946d535119454aaae0b89cc09a002c097272a6dee977c3706628289f6a2981ae6b82449f17b284e3ca41086815eabcccb0c375f3a43cfd70103",
                    "oracleData": ""
                },
                "metaData": {}
            }
            ...
        ]
    }
    

    GET /v1/order/[orderHash]

    Retrieves a specific order by orderHash.

    Response

    {
        "order": {
            "bZxAddress" :"0xaa86dda78e9434aca114b6676fc742a18d15a1cc",
            "makerAddress": "0x5409ed021d9299bf6814279a6a1411a7e866a631",
            "loanTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
            "interestTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
            "collateralTokenAddress": "0x0000000000000000000000000000000000000000",
            "feeRecipientAddress": "0x5dd835a893734b8d556eccf87800b76dda5aedc5",
            "oracleAddress": "0xe704967449b57b2382b7fa482718748c13c63190",
            "loanTokenAmount": "5000000000000000000",
            "interestAmount": "1000000000000000000",
            "initialMarginAmount": "50",
            "maintenanceMarginAmount": "25",
            "lenderRelayFee": "0",
            "traderRelayFee": "0",
            "maxDurationUnixTimestampSec": "604800",
            "expirationUnixTimestampSec": "1540786678",
            "makerRole": "0",
            "salt": "59940742713651368663364744180266918345412120379624374896164725450574161449117",
            "ecSignature": "0x6420ffffe4a1849e4946d535119454aaae0b89cc09a002c097272a6dee977c3706628289f6a2981ae6b82449f17b284e3ca41086815eabcccb0c375f3a43cfd70103",
            "oracleData": ""
        },
        "metaData": {}
    }
    

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

    GET /v1/orderbook

    Retrieves the orderbook for a given loan token. This endpoint should be paginated.

    Parameters

    Response

    {
        "bids": {
            "total": 325,
            "page": 2,
            "perPage": 100,
            "records": [
                {
                    "order": {
                        "bZxAddress" :"0xaa86dda78e9434aca114b6676fc742a18d15a1cc",
                        "makerAddress": "0x5409ed021d9299bf6814279a6a1411a7e866a631",
                        "loanTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
                        "interestTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
                        "collateralTokenAddress": "0x0000000000000000000000000000000000000000",
                        "feeRecipientAddress": "0x5dd835a893734b8d556eccf87800b76dda5aedc5",
                        "oracleAddress": "0xe704967449b57b2382b7fa482718748c13c63190",
                        "loanTokenAmount": "5000000000000000000",
                        "interestAmount": "1000000000000000000",
                        "initialMarginAmount": "50",
                        "maintenanceMarginAmount": "25",
                        "lenderRelayFee": "0",
                        "traderRelayFee": "0",
                        "maxDurationUnixTimestampSec": "604800",
                        "expirationUnixTimestampSec": "1540786678",
                        "makerRole": "0",
                        "salt": "59940742713651368663364744180266918345412120379624374896164725450574161449117",
                        "ecSignature": "0x6420ffffe4a1849e4946d535119454aaae0b89cc09a002c097272a6dee977c3706628289f6a2981ae6b82449f17b284e3ca41086815eabcccb0c375f3a43cfd70103",
                        "oracleData": ""
                    }
                    "metaData": {}
              },
              ...
            ]
        }
        "asks": {
            "total": 500,
            "page": 2,
            "perPage": 100,
            "records": [
                {
                    "order":  {
                        "bZxAddress" :"0xaa86dda78e9434aca114b6676fc742a18d15a1cc",
                        "makerAddress": "0x5409ed021d9299bf6814279a6a1411a7e866a631",
                        "loanTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
                        "interestTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
                        "collateralTokenAddress": "0x0000000000000000000000000000000000000000",
                        "feeRecipientAddress": "0x5dd835a893734b8d556eccf87800b76dda5aedc5",
                        "oracleAddress": "0xe704967449b57b2382b7fa482718748c13c63190",
                        "loanTokenAmount": "5000000000000000000",
                        "interestAmount": "1000000000000000000",
                        "initialMarginAmount": "50",
                        "maintenanceMarginAmount": "25",
                        "lenderRelayFee": "0",
                        "traderRelayFee": "0",
                        "maxDurationUnixTimestampSec": "604800",
                        "expirationUnixTimestampSec": "1540786678",
                        "makerRole": "0",
                        "salt": "59940742713651368663364744180266918345412120379624374896164725450574161449117",
                        "ecSignature": "0x6420ffffe4a1849e4946d535119454aaae0b89cc09a002c097272a6dee977c3706628289f6a2981ae6b82449f17b284e3ca41086815eabcccb0c375f3a43cfd70103",
                        "oracleData": ""
                    },
                    "metaData": {}
                },
              ...
            ]  
        }
    }
    

    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 /v1/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: feeRecipientAddress, lenderRelayFee, traderRelayFee.

    Payload

    See payload schema

    {
        "bZxAddress" :"0xaa86dda78e9434aca114b6676fc742a18d15a1cc",
        "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
        "loanTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
        "interestTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
        "loanTokenAmount": "10000000000000000",
        "interestAmount": "20000000000000000",
        "maxDurationUnixTimestampSec": "604800"
    }
    

    Response

    Success Response

    Returns a HTTP 201 response with the following payload:

    {
        "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
        "lenderRelayFee": "100000000000000",
        "traderRelayFee": "200000000000000"
    }
    

    Error Response

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

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

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

    POST /v1/order

    Submit a signed order to the relayer.

    Payload

    {
        "bZxAddress" :"0xaa86dda78e9434aca114b6676fc742a18d15a1cc",
        "makerAddress": "0x5409ed021d9299bf6814279a6a1411a7e866a631",
        "loanTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
        "interestTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
        "collateralTokenAddress": "0x0000000000000000000000000000000000000000",
        "feeRecipientAddress": "0x5dd835a893734b8d556eccf87800b76dda5aedc5",
        "oracleAddress": "0xe704967449b57b2382b7fa482718748c13c63190",
        "loanTokenAmount": "5000000000000000000",
        "interestAmount": "1000000000000000000",
        "initialMarginAmount": "50",
        "maintenanceMarginAmount": "25",
        "lenderRelayFee": "0",
        "traderRelayFee": "0",
        "maxDurationUnixTimestampSec": "604800",
        "expirationUnixTimestampSec": "1540786678",
        "makerRole": "0",
        "salt": "59940742713651368663364744180266918345412120379624374896164725450574161449117",
        "ecSignature": "0x6420ffffe4a1849e4946d535119454aaae0b89cc09a002c097272a6dee977c3706628289f6a2981ae6b82449f17b284e3ca41086815eabcccb0c375f3a43cfd70103",
        "oracleData": ""
    }
    

    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.

    WebSocket API Specification v1

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

    Endpoint

    wss://sra.bamboorelay.com/bzx/v1/ws
    

    Orders Channel

    Request messages

    Subscribe

    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": {
            "loanTokenAddress": "0x8dc114d77e857558aefbe8e1a50b460ff9578f1a",
            "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

    Response messages

    Update

    This message is sent whenever the relayer receives a new order. Bamboo Relay advises that API consumers watch the ethereum blockchain logs for updates and cancellations of existing orders.

    {
        "type": "update",
        "channel": "orders",
        "requestId": "123e4567-e89b-12d3-a456-426655440000",
        "payload":  [
            {
              "order": {
                  "bZxAddress" :"0xaa86dda78e9434aca114b6676fc742a18d15a1cc",
                  "makerAddress": "0x5409ed021d9299bf6814279a6a1411a7e866a631",
                  "loanTokenAddress": "0x8dc114d77e857558aefbe8e1a50b460ff9578f1a",
                  "interestTokenAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
                  "collateralTokenAddress": "0x0000000000000000000000000000000000000000",
                  "feeRecipientAddress": "0x5dd835a893734b8d556eccf87800b76dda5aedc5",
                  "oracleAddress": "0xe704967449b57b2382b7fa482718748c13c63190",
                  "loanTokenAmount": "5000000000000000000",
                  "interestAmount": "1000000000000000000",
                  "initialMarginAmount": "50",
                  "maintenanceMarginAmount": "25",
                  "lenderRelayFee": "0",
                  "traderRelayFee": "0",
                  "maxDurationUnixTimestampSec": "604800",
                  "expirationUnixTimestampSec": "1540786678",
                  "makerRole": "0",
                  "salt": "59940742713651368663364744180266918345412120379624374896164725450574161449117",
                  "ecSignature": "0x6420ffffe4a1849e4946d535119454aaae0b89cc09a002c097272a6dee977c3706628289f6a2981ae6b82449f17b284e3ca41086815eabcccb0c375f3a43cfd70103",
                  "oracleData": ""
                },
                "metaData": {
                }
            },
            ...
        ]
    }