NAV Navbar
  • Standard Coordinator API
  • Standard Coordinator API

    The Bamboo Relay 0x Standard Coordinator API implements the 0x v2 coordinator specification.

    See the 0x specification for more information on how to encode transactions.

    Endpoint

    https://coordinator.bamboorelay.com/
    

    Fee Address

    In order for the coordinator to be able to sign off on valid transactions, each order must have its feeRecipient field set to the Bamboo Relay fee address.

    0xc898fbee1cc94c0ff077faa5449915a506eff384
    

    Current Configuration

    The current server configuration can be queried via the /v1/configuration endpoint.

    {
        "expirationDurationSeconds": 60,
        "selectiveDelayMs": 1000,
        "supportedNetworkIds": [
            1,
            3,
            4,
            42
        ]
    }
    

    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
    500 Internal Server Error

    Error reporting format

    {
        "code": 101,
        "reason": "Validation failed",
        "validationErrors": [
            {
                "field": "networkId",
                "code": 1003,
                "reason": "Requested networkId not supported by this coordinator"
            }
        ]
    }
    

    General error codes:

    100 - Validation Failed
    101 - Malformed JSON
    102 - Request blocked
    

    Validation error codes:

    1000 - Required field
    1001 - Incorrect format
    1004 - Value out of range
    1003 - Unsupported option
    1004 - Included order already soft-cancelled
    1005 - 0x transaction decoding failed
    1006 - No coordinator orders included
    1007 - Invalid 0x transaction signature
    1008 - Only maker can cancel orders
    1009 - Function call unsupported
    1010 - Fill requests exceeded takerAssetAmount
    1011 - 0x transaction already used
    

    Rest API

    Network Id

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

    
    curl https://coordinator.bamboorelay.com/v1/request_transaction?networkId=1
    
    

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

    Some 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"
        }
      ]
    }
    

    GET /v1/configuration

    This endpoint returns the specific configurations chosen by this Coordinator server.

    Response

    {
      "expirationDurationSeconds": 60,
      "selectiveDelayMs": 1000,
      "supportedNetworkIds": [1, 42]
    }
    

    POST /v1/request_transaction

    Submit a signed 0x transaction encoding either a 0x fill or cancellation. If the 0x transaction encodes a fill, the sender is requesting a coordinator signature required to fill the order(s) on-chain. If the 0x transaction encodes an order(s) cancellation request, the sender is requesting the included order(s) to be soft-cancelled by the coordinator.

    Payload

    {
      "signedTransaction": {
        "salt": "62799490869714002130337144204631467715674661702713158022807378407578488540214",
        "signerAddress": "0xe834ec434daba538cd1b9fe1582052b880bd7e63",
        "data": "0xb4be83d500000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000056bc75e2d6310000000000000000000000000000000000000000000000000000000000000000002a0000000000000000000000000e36ea790bc9d7ab70c55260c66d52b1eca985f84000000000000000000000000000000000000000000000000000000000000000000000000000000000000000078dc5d2d739606d31509c31d654056a45185ecb60000000000000000000000006ecbe1db9ef729cbe972c83fb886247691fb6beb0000000000000000000000000000000000000000000000056bc75e2d6310000000000000000000000000000000000000000000000000000ad78ebc5ac62000000000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000000000000000000000000000000de0b6b3a7640000000000000000000000000000000000000000000000000000000000005c879733d9cbe51a7e6b6c5e1f057d3d3ba3c1b57c8734fe0f523afa6250aff64aa9db37000000000000000000000000000000000000000000000000000000000000018000000000000000000000000000000000000000000000000000000000000001e00000000000000000000000000000000000000000000000000000000000000024f47261b000000000000000000000000034d402f14d58e001d8efbe6585051bf9706aa064000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000024f47261b000000000000000000000000025b8fe1de9daf8ba351890744ff28cf7dfa8f5e30000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000421c9e99c16367e608d75d943549b49fbeedcf58c84897b69daf0646e6184086a44107dda6e675826189c4bf509061880b5fe3e4707f449203249b98a39480bbee4803000000000000000000000000000000000000000000000000000000000000",
        "verifyingContractAddress": "0x48bacb9266a570d521063ef5dd96e61686dbe788",
        "signature": "0x1b36fca95c03d4e28b0ffb7796194841612005f0913e60f9da36f477a432e478240af81e8be55368b1a43f21266c6964e2b3d6c55b9d11dd5318ab76e63ff0c6f903"
      },
      "txOrigin": "0xe834ec434daba538cd1b9fe1582052b880bd7e63"
    }
    

    Response

    Fill request response:

    {
      "signatures": [
        "0x1cc07d7ae39679690a91418d46491520f058e4fb14debdf2e98f2376b3970de8512ace44af0be6d1c65617f7aae8c2364ff63f241515ee1559c3eeecb0f671d9e903"
      ],
      "expirationTimeSeconds": "1552390014"
    }
    

    Usually a single signature will be returned. Only when someone requests to batchFill multiple orders from the coordinator that were created with different supported feeRecipientAddresses, will this return a signature per feeRecipientAddress involved.

    Cancellation request response:

    {
      "outstandingFillSignatures": [
        {
          "orderHash": "0xd1dc61f3e7e5f41d72beae7863487beea108971de678ca00d903756f842ef3ce",
          "approvalSignatures": [
            "0x1c7383ca8ebd6de8b5b20b1c2d49bea166df7dfe4af1932c9c52ec07334e859cf2176901da35f4480ceb3ab63d8d0339d851c31929c40d88752689b9a8a535671303"
          ],
          "expirationTimeSeconds": "1552390380",
          "takerAssetFillAmount": "100000000000000000000"
        }
      ],
      "cancellationSignatures": [
        "0x2ea3117a8ebd6de8b5b20b1c2d49bea166df7dfe4af1932c9c52ec07334e859cf2176901da35f4480ceb3ab63d8d0339d851c31929c40d88752689b9a855b5a7b401"
      ]
    }
    

    POST /v1/soft_cancels

    Within the coordinator model, the Coordinator server is the source-of-truth when it comes to determining whether an order has been soft-cancelled. This endpoint can be used to query whether a set of orders have been soft-cancelled. The response returns the subset of orders that have been soft-cancelled.

    Payload

    {
      "orderHashes": [
        "0xd1dc61f3e7e5f41d72beae7863487beea108971de678ca00d903756f842ef3ce", "0xabcc372e3812bba31a35958dc32d0beadf27595d51fb953709944559404e1b61"
      ]
    }
    

    Response

    {
      "orderHashes": [
        "0xabcc372e3812bba31a35958dc32d0beadf27595d51fb953709944559404e1b61"
      ]
    }
    

    WebSocket API

    Ping / Pong Frames

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

    Transaction request notifications

    Endpoint: /v1/requests

    The WebSocket endpoint allows a client to subscribe to the following events:

    FILL_REQUEST_RECEIVED

    A fill request was received and is valid. The request has not yet been granted a coordinator signature. Depending on the server implementation, the request might need to wait for a selective delay before being issued a signature.

    {
      "type": "FILL_REQUEST_RECEIVED",
      "data": {
        "transactionHash": "0xef5c67ee7812fba2da35958dc32d0beadf27595d51fb953709944559404e1b6b"
      }
    }
    

    FILL_REQUEST_ACCEPTED

    The fill request has been accepted and a signature issued. The corresponding 0x transaction can now be executed on-chain.

    {
      "type": "FILL_REQUEST_ACCEPTED",
      "data": {
        "functionName": "fillOrder",
        "orders": [
          {
            "makerAddress": "0xe36ea790bc9d7ab70c55260c66d52b1eca985f84",
            "takerAddress": "0x0000000000000000000000000000000000000000",
            "feeRecipientAddress": "0x78dc5d2d739606d31509c31d654056a45185ecb6",
            "senderAddress": "0x6ecbe1db9ef729cbe972c83fb886247691fb6beb",
            "makerAssetAmount": "100000000000000000000",
            "takerAssetAmount": "200000000000000000000",
            "makerFee": "1000000000000000000",
            "takerFee": "1000000000000000000",
            "expirationTimeSeconds": "1552396423",
            "salt": "66097384406870180066678463045003379626790660770396923976862707230261946348951",
            "makerAssetData": "0xf47261b000000000000000000000000034d402f14d58e001d8efbe6585051bf9706aa064",
            "takerAssetData": "0xf47261b000000000000000000000000025b8fe1de9daf8ba351890744ff28cf7dfa8f5e3",
            "exchangeAddress": "0x4f833a24e1f95d70f028921e27040ca56e09ab0b"
          }
        ],
        "txOrigin": "0x2ebac44a8b1218cabe972c83fb886247691fb6beb",
        "signedTransaction": {
          "salt": "1495510454898017617137906367124143312199249786920467590762356946976468764317",
          "signerAddress": "0xe834ec434daba538cd1b9fe1582052b880bd7e63",
          "data": "0xb4be83d500000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000056bc75e2d6310000000000000000000000000000000000000000000000000000000000000000002a0000000000000000000000000e36ea790bc9d7ab70c55260c66d52b1eca985f84000000000000000000000000000000000000000000000000000000000000000000000000000000000000000078dc5d2d739606d31509c31d654056a45185ecb60000000000000000000000006ecbe1db9ef729cbe972c83fb886247691fb6beb0000000000000000000000000000000000000000000000056bc75e2d6310000000000000000000000000000000000000000000000000000ad78ebc5ac62000000000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000000000000000000000000000000de0b6b3a7640000000000000000000000000000000000000000000000000000000000005c87b0879221cb37dcf690e02b0f9aecf44fcaa5ed9ce99697e86743795fa132596ff597000000000000000000000000000000000000000000000000000000000000018000000000000000000000000000000000000000000000000000000000000001e00000000000000000000000000000000000000000000000000000000000000024f47261b000000000000000000000000034d402f14d58e001d8efbe6585051bf9706aa064000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000024f47261b000000000000000000000000025b8fe1de9daf8ba351890744ff28cf7dfa8f5e30000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000421ce8e3c600d933423172b5021158a6be2e818613ff8e762d70ef490c752fd98a626a215f09f169668990414de75a53da221c294a3002f796d004827258b641876e03000000000000000000000000000000000000000000000000000000000000",
          "verifyingContractAddress": "0x48bacb9266a570d521063ef5dd96e61686dbe788",
          "signature": "0x1b36fca95c03d4e28b0ffb7796194841612005f0913e60f9da36f477a432e478240af81e8be55368b1a43f21266c6964e2b3d6c55b9d11dd5318ab76e63ff0c6f903"
        },
        "approvalSignatures": [
          "0x1b98e8b81249e49de6a76ae515108215621a2ad85909580de16a960280c97830eb2b417c7675775dc1ccaeca596deee5c8a0613058a48649e9b0ee2696b0cb975703"
        ],
        "approvalExpirationTimeSeconds": "1552395894"
      }
    }
    

    CANCEL_REQUEST_ACCEPTED

    A cancellation request has been recevied and processed. The 0x orders included in the request have been soft-cancelled, and not additional fill signatures will be issued by the coordinator.

    {
      "type": "CANCEL_REQUEST_ACCEPTED",
      "data": {
        "orders": [
          {
            "makerAddress": "0xe36ea790bc9d7ab70c55260c66d52b1eca985f84",
            "takerAddress": "0x0000000000000000000000000000000000000000",
            "feeRecipientAddress": "0x78dc5d2d739606d31509c31d654056a45185ecb6",
            "senderAddress": "0x6ecbe1db9ef729cbe972c83fb886247691fb6beb",
            "makerAssetAmount": "100000000000000000000",
            "takerAssetAmount": "200000000000000000000",
            "makerFee": "1000000000000000000",
            "takerFee": "1000000000000000000",
            "expirationTimeSeconds": "1552396423",
            "salt": "77312126688742331532122416049113540452139616608135326468253415920865328290216",
            "makerAssetData": "0xf47261b000000000000000000000000034d402f14d58e001d8efbe6585051bf9706aa064",
            "takerAssetData": "0xf47261b000000000000000000000000025b8fe1de9daf8ba351890744ff28cf7dfa8f5e3",
            "exchangeAddress": "0x4f833a24e1f95d70f028921e27040ca56e09ab0b"
          }
        ],
        "transaction": {
          "salt": "30502121252152069340049118328369905364578815501441646224439039476012324011326",
          "signerAddress": "0xe36ea790bc9d7ab70c55260c66d52b1eca985f84",
          "data": "0xd46b02c30000000000000000000000000000000000000000000000000000000000000020000000000000000000000000e36ea790bc9d7ab70c55260c66d52b1eca985f84000000000000000000000000000000000000000000000000000000000000000000000000000000000000000078dc5d2d739606d31509c31d654056a45185ecb60000000000000000000000006ecbe1db9ef729cbe972c83fb886247691fb6beb0000000000000000000000000000000000000000000000056bc75e2d6310000000000000000000000000000000000000000000000000000ad78ebc5ac62000000000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000000000000000000000000000000de0b6b3a7640000000000000000000000000000000000000000000000000000000000005c87b087aaed1cee5db78cfae5b9be5a1a30c67fc3515aacfa536bea1aa33deb90e4d9a8000000000000000000000000000000000000000000000000000000000000018000000000000000000000000000000000000000000000000000000000000001e00000000000000000000000000000000000000000000000000000000000000024f47261b000000000000000000000000034d402f14d58e001d8efbe6585051bf9706aa064000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000024f47261b000000000000000000000000025b8fe1de9daf8ba351890744ff28cf7dfa8f5e300000000000000000000000000000000000000000000000000000000",
          "verifyingContractAddress": "0x48bacb9266a570d521063ef5dd96e61686dbe788"
        }
      }
    }