HidingBook HTTP API

The HidingBook HTTP API is used by market makers, users, and partners to access the Rook ecosystem.
Introduction
HTTP endpoint
The base endpoint URL for the Hiding Book API is:
https://hidingbook.rook.finance/api/v1/
Here is an example API call: https://hidingbook.rook.finance/api/v1/info​
Headers
{
    'content-type': 'application/json',
}
Response format
All endpoints return JSON. Examples of response format is given below.
Success
{"result": [{.......}, {......}], "message": "Ok"}
Failure
{"error": "......", "code": "......"}
Error codes
{
    -1000: "Unknown error while processing request",
    -1001: "Down for maintenance. Check back soon",
    -1002: "Invalid Api Key",
    -2000: "Invalid request",
    -2001: "Insufficient maker balance",
    -2002: "Insufficient maker allowance",
    -2003: "Order expired",
    -2004: "orderHash not valid",
    -2005: "No order matching orderHash",
    -2006: "Failed to cancel order",
    -2007: "Order signer and cancel signer mismatch",
    -2008: "Order has already been soft canceled",
    -2009: "Price temporarily unavailable",
    -2010: "Invalid param",
    -2011: "Order duration is too short",
    -2012: "Order hash mismatch",
    -2013: "Invalid order signature",
    -2014: "Order is not fillable",
    -2015: "Too many orders",
}
HTTP Methods
GET /info
Returns all general information needed to populate the user interface.
URL
​https://hidingbook.rook.finance/api/v1/info​
Method:
GET
Success Response:
{
  "result": {
    "rateLimitDict": {
      "per": 32.0,
      "apiRateLimitDict": {
        "helloWorld": 25.0, 
        "get.tokenList": 25.0, 
        "get.partnerList": 25.0, 
        "get.info": 25.0, 
        "post.orders": 14.0, 
        "get.orders": 14.0, 
        "delete.order": 25.0, 
        "get.suggestedReturn": 14.0, 
        "get.balances": 8.0, 
        "get.partner": 25.0
      }
    },
    "orderDetails": {
      "verifyingContract": "0xdef1c0ded9bec7f1a1670819833240f027b25eff",
      "chainId": 1,
      "txOrigin": "0xbd49a97300e10325c78d6b4ec864af31623bb5dd",
      "taker": "0x0000000000000000000000000000000000000000",
      "pool": "0x0000000000000000000000000000000000000000000000000000000000000017"
    },
    "tokenList": {
      "name": "Hiding Game",
      "timestamp": "2020-12-07T10:35:15+00:00",
      "version": {
        "major": 1,
        "minor": 0,
        "patch": 0
      },
      "keywords": [
        "keeperdao",
        "rook",
        "list"
      ],
      "tokens": [
        {
          "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          "chainId": 1,
          "name": "USDCoin",
          "symbol": "USDC",
          "decimals": 6,
          "logoURI": "https://tokens.1inch.exchange/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.png"
        },
        {
          "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
          "chainId": 1,
          "name": "WrappedEther",
          "symbol": "WETH",
          "decimals": 18,
          "logoURI": "https://tokens.1inch.exchange/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2.png"
        },
        {
          "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
          "chainId": 1,
          "name": "DaiStablecoin",
          "symbol": "DAI",
          "decimals": 18,
          "logoURI": "https://tokens.1inch.exchange/0x6b175474e89094c44da98b954eedeac495271d0f.png"
        },
        {
          "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
          "chainId": 1,
          "name": "TetherUSD",
          "symbol": "USDT",
          "decimals": 6,
          "logoURI": "https://tokens.1inch.exchange/0xdac17f958d2ee523a2206206994597c13d831ec7.png"
        }
      ],
      "logoURI": "https://miro.medium.com/fit/c/96/96/1*WXMtamzK0_QHWP6dJqFdtA.jpeg"
    },
    "recommendedMinTradeAmounts": {
      "TODO": 1337
    }
  },
  "message": "Ok"
}
GET /tokenList
Returns list of supported tokens.
URL
​https://hidingbook.rook.finance/api/v1/tokenList​
​
Method:
GET
Success Response:
{
  "result": {
    "name": "Hiding Game",
    "timestamp": "2020-12-07T10:35:15+00:00",
    "version": {
      "major": 1,
      "minor": 0,
      "patch": 0
    },
    "keywords": [
      "keeperdao",
      "rook",
      "list"
    ],
    "tokens": [
      {
        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "chainId": 1,
        "name": "USDCoin",
        "symbol": "USDC",
        "decimals": 6,
        "logoURI": "https://tokens.1inch.exchange/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.png"
      },
      {
        "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "chainId": 1,
        "name": "WrappedEther",
        "symbol": "WETH",
        "decimals": 18,
        "logoURI": "https://tokens.1inch.exchange/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2.png"
      },
      {
        "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
        "chainId": 1,
        "name": "DaiStablecoin",
        "symbol": "DAI",
        "decimals": 18,
        "logoURI": "https://tokens.1inch.exchange/0x6b175474e89094c44da98b954eedeac495271d0f.png"
      },
      {
        "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
        "chainId": 1,
        "name": "TetherUSD",
        "symbol": "USDT",
        "decimals": 6,
        "logoURI": "https://tokens.1inch.exchange/0xdac17f958d2ee523a2206206994597c13d831ec7.png"
      }
    ],
    "logoURI": "https://miro.medium.com/fit/c/96/96/1*WXMtamzK0_QHWP6dJqFdtA.jpeg"
  },
  "message": "Ok"
}
POST /orders
Post an array of 0x orders to the order book.
This is how you will place new orders on the Hiding Book. The order format is identical to the 0x v4 RFQ
URL
​https://hidingbook.rook.finance/api/v1/orders​
Method:
POST
Data Params
[
  {
    'maker': '0xca77dc47eec9e1c46c9f541ba0f222e741d6236b',
    'taker': '0x0000000000000000000000000000000000000000',
    'makerAmount': '93981000000000000',
    'takerAmount': '50000000',
    'makerToken': '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
    'takerToken': '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
    'salt': '1611073656000',
    'expiry': '1611074656',
    'chainId': 1,
    'txOrigin': '0xbd49a97300e10325c78d6b4ec864af31623bb5dd',
    'pool': '0x0000000000000000000000000000000000000000000000000000000000000017',
    'verifyingContract': '0xdef1c0ded9bec7f1a1670819833240f027b25eff',
    'signature': {
      'signatureType': 3,
      'v': 28,
      'r': '0x6a3182de881d03f216bdcbbc5d78c3c1b86b19c880eef7b1f5cde26cc202a142',
      's': '0x7c68df85de87098c97110515a64f27b9c0ff918abfeed375700d7df653f88ee7'
    }
  },
  {
    'maker': '0xca77dc47eec9e1c46c9f541ba0f222e741d6236b',
    'taker': '0x0000000000000000000000000000000000000000',
    'makerAmount': '50000000',
    'takerAmount': '93981000000000000',
    'makerToken': '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
    'takerToken': '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
    'salt': '1611073656000',
    'expiry': '1611074656',
    'chainId': 1,
    'txOrigin': '0xbd49a97300e10325c78d6b4ec864af31623bb5dd',
    'pool': '0x0000000000000000000000000000000000000000000000000000000000000017',
    'verifyingContract': '0xdef1c0ded9bec7f1a1670819833240f027b25eff',
    'signature': {
      'signatureType': 3,
      'v': 28,
      'r': '0x21dc310bff19f899781a70b52940aee98eaa4dcfaee89274de3e300ca716f9f8',
      's': '0x40967fc8ba28e0eff8c707521e9a81ab396a8b55bda88c3f07aad4ae5da584dd'
    }
  }
]
Success Response with Multiple Valid Orders:
{
  'result': [{
	'orderHash': '0x40efabc8916b25e6584c5b3bc06f15035abc91c7c1fd405bc3beaa6e248ea734',
	'code': 201,
	'message': 'Order creation succeeded'
  }, {
	'orderHash': '0xf4a1ea59b3b79a64bc5d7a0050d94a9f09b33607e4b21b5a41dccf9ef13ef095',
	'code': 201,
	'message': 'Order creation succeeded'
  }],
  'message': 'Ok'
}
Success Response with Valid and Invalid Orders:
{
  'result': [{
	'orderHash': '0x32cc742dea5cee1f3703379c51bca9da68d2b2e0fd8587944fde59ad2c9bf2d9',
	'code': 201,
	'message': 'Order creation succeeded'
  }, {
	'orderHash': '0xfe136dfc8c9437a2b2d3eba60a9ca5b900b8b48a552a85fa6c4d547447217372',
	'error': 'Insufficient maker balance',
	'code': -2001
  }],
  'message': 'Ok'
}
Success Response with Multiple Invalid Orders:
{
  'result': [{
	'orderHash': '0x1ba51662eaa7fdb89417c57caa23976ed93ad200fbe68801aab910dc342f600f',
	'error': 'Insufficient maker balance',
	'code': -2001
  }, {
	'orderHash': '0x7f2ae02dbef6e465abc5c37947ecc112c039d75b4f6b932320616f645536d41b',
	'error': 'Insufficient maker balance',
	'code': -2001
  }],
  'message': 'Ok'
}
Failure Response:
{
  'error': 'PostOrder API call failed due to internal error. Payload: Unknown Exception: ',
  'code': -1000
}
​
GET /orders
Get orders from the order book.
URL
​https://hidingbook.rook.finance/api/v1/orders​
Method:
GET
URL Params
Option 1: open=True
Option 2: maker=[address]
Sample Call:
/orders?open=True
/orders?maker=0xca77dc47eec9e1c46c9f541ba0f222e741d6236b
Success Response:
{
  "orders": [
    {
      "order": {
        "maker": "0xca77dc47eec9e1c46c9f541ba0f222e741d6236b",
        "taker": "0x0000000000000000000000000000000000000000",
        "makerAmount": "25000000",
        "takerAmount": "46990500000000000",
        "makerToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "takerToken": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "salt": "1611000201000",
        "expiry": "1611001201",
        "chainId": 1,
        "txOrigin": "0xbd49a97300e10325c78d6b4ec864af31623bb5dd",
        "pool": "0x0000000000000000000000000000000000000000000000000000000000000017",
        "verifyingContract": "0xdef1c0ded9bec7f1a1670819833240f027b25eff",
        "signature": {
          "signatureType": 3,
          "v": 28,
          "r": "0xc6e19b108ca4d059d2999e8011237f7a73a4b034993bc4256ab9bc8e6dddf220",
          "s": "0x1f2fd0d9ccb5e022b1f51dd0ad76695ebabdcfbb276aa3b2d306dd1952ca9531"
        }
      },
      "metaData": {
        "orderHash": "0xd505bf04b6cd3efe0c71568441b639cc1767af04480040933fa67b73a4e317f5",
        "makerBalance_makerToken": 1047850867,
        "makerAllowance_makerToken": 115792089237316195423570985008687907853269984665640564039457584007913129634083,
        "status": 4,
        "filledAmount_takerToken": 0,
        "remainingFillableAmount_takerToken": 0
      }
    },
    {
      "order": {
        "maker": "0xca77dc47eec9e1c46c9f541ba0f222e741d6236b",
        "taker": "0x0000000000000000000000000000000000000000",
        "makerAmount": "50000000",
        "takerAmount": "93981000000000000",
        "makerToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "takerToken": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "salt": "1611073656000",
        "expiry": "1611074656",
        "chainId": 1,
        "txOrigin": "0xbd49a97300e10325c78d6b4ec864af31623bb5dd",
        "pool": "0x0000000000000000000000000000000000000000000000000000000000000017",
        "verifyingContract": "0xdef1c0ded9bec7f1a1670819833240f027b25eff",
        "signature": {
          "signatureType": 3,
          "v": 28,
          "r": "0x21dc310bff19f899781a70b52940aee98eaa4dcfaee89274de3e300ca716f9f8",
          "s": "0x40967fc8ba28e0eff8c707521e9a81ab396a8b55bda88c3f07aad4ae5da584dd"
        }
      },
      "metaData": {
        "orderHash": "0xeb49fb338838615720dd8423650df146db7b1e6408f747733ff01b11383a91a8",
        "makerBalance_makerToken": 1121680797,
        "makerAllowance_makerToken": 115792089237316195423570985008687907853269984665640564039457584007913129634083,
        "status": 1,
        "filledAmount_takerToken": 0,
        "remainingFillableAmount_takerToken": 93981000000000000
      }
    },
    {
      "order": {
        "maker": "0xca77dc47eec9e1c46c9f541ba0f222e741d6236b",
        "taker": "0x0000000000000000000000000000000000000000",
        "makerAmount": "25000000",
        "takerAmount": "46990500000000000",
        "makerToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "takerToken": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "salt": "1610994465000",
        "expiry": "1610995465",
        "chainId": 1,
        "txOrigin": "0xbd49a97300e10325c78d6b4ec864af31623bb5dd",
        "pool": "0x0000000000000000000000000000000000000000000000000000000000000017",
        "verifyingContract": "0xdef1c0ded9bec7f1a1670819833240f027b25eff",
        "signature": {
          "signatureType": 3,
          "v": 27,
          "r": "0x5ba37acf248a3b210d52fb89602e27e3ab0020d4ccba3ed131f9ed8db9292884",
          "s": "0x684a65e09e1edf2347d7a34837c4b85d0df49be415159c71c2ad07252113c08c"
        }
      },
      "metaData": {
        "orderHash": "0x62521dcb7c3dc153e9ef7fb2d1ae4df955cacf369f381c4547578b8e316030dc",
        "makerBalance_makerToken": 1047850867,
        "makerAllowance_makerToken": 115792089237316195423570985008687907853269984665640564039457584007913129634083,
        "status": 4,
        "filledAmount_takerToken": 0,
        "remainingFillableAmount_takerToken": 0
      }
    }
  ],
  "message": "Ok"
}  
DELETE /orders
Cancel an array of 0x orders without paying gas. 
This API informs all keepers of your wish for this order to not be filled. Keepers will be disincentivized to fill a soft canceled order via the Reputation system. It will be technically possible for the order to be filled even after being soft canceled, but the Keeper will be punished. 
We recommend use of the soft cancel API for low to medium priority cancels. 
For emergency high-priority cancels, or if you suspect that a keeper is already attempting to fill your soft-cancelled order, you must make a hard cancel: an on-chain cancel, to guarantee that the order cannot be filled.
Calling this API sets the softCancel property in the order's metaData property. The order is considered soft canceled when the softCancel property is less than the current Unix epoch time in seconds.
The caller must sign a message hash with the private key whose address is the maker of the order to be cancelled.
1.Build the message text
message_text = 'soft cancel order: ' + str(orderHash.lower())
message_text = 'soft cancel order: 0xf98099dbfb5e9c9b3e79c9f66ae0a97f8a6bdb264780bd4480e0616a00d626bf''
2. Hash the message text
3. Sign the hashed message with your private key
4. Call this API with the signature and orderHash
URL
​https://hidingbook.rook.finance/api/v1/orders​
Method:
DELETE
Data Params
[
  {
    'orderHash': '0x26368e875790de2513d451c71bb12e5b83b1f897322ee24cd5c246a64628e294',
    'signature': {
      'v': 27,
      'r': '0xf2342382c6f830699955d3b6e357073b5195016c08b8a8c67828ea9d05812214',
      's': '0x12672adc8cb27639785ff4cc3349a6162a66faac6c6c268bad9e96b8d7a8da2f'
    }
  }
]
Success Response with Multiple Valid Orders:
{
  'result': [{
  	'orderHash': '0x40efabc8916b25e6584c5b3bc06f15035abc91c7c1fd405bc3beaa6e248ea734',
	'message': 'Soft order cancel succeeded',
	'code': 201
  }, {
	'orderHash': '0xf4a1ea59b3b79a64bc5d7a0050d94a9f09b33607e4b21b5a41dccf9ef13ef095',
	'message': 'Soft order cancel succeeded',
	'code': 201
  }],
  'message': 'Ok'
}
Success Response with Valid and Invalid Orders:
{
  'result': [{
	'orderHash': '0x32cc742dea5cee1f3703379c51bca9da68d2b2e0fd8587944fde59ad2c9bf2d9',
	'message': 'Soft order cancel succeeded',
	'code': 201
  }, {
	'orderHash': '0xfe136dfc8c9437a2b2d3eba60a9ca5b900b8b48a552a85fa6c4d547447217372',
	'error': 'Failed to cancel order',
	'code': -2006,
	'message': 'Either the signature is incorrect, the order does not exist, or you are trying to cancel an order you did not sign.'
  }],
  'message': 'Ok'
}
Success Response with Multiple Invalid Orders:
{
  'result': [{
	'orderHash': '0x1ba51662eaa7fdb89417c57caa23976ed93ad200fbe68801aab910dc342f600f',
	'error': 'Failed to cancel order',
	'code': -2006,
	'message': 'Either the signature is incorrect, the order does not exist, or you are trying to cancel an order you did not sign.'
  }, {
	'orderHash': '0x7f2ae02dbef6e465abc5c37947ecc112c039d75b4f6b932320616f645536d41b',
	'error': 'Failed to cancel order',
	'code': -2006,
	'message': 'Either the signature is incorrect, the order does not exist, or you are trying to cancel an order you did not sign.'
  }],
  'message': 'Ok'
}
Failure Response:
{
  'error': 'PostOrder API call failed due to internal error. Payload: Unknown Exception: ',
  'code': -1000
}
GET /suggestedReturn
Get suggested trade return based on current DEX prices.
URL
​https://hidingbook.rook.finance/api/v1/suggestedReturn​
Method:
GET
URL Params
type=[market]
tokenIn=[address]
tokenOut=[address]
amountIn=[amount]
Sample Call:
/suggestedReturn?type=market&tokenIn=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&tokenOut=0x6b175474e89094c44da98b954eedeac495271d0f&amountIn=134548728591769453840
Success Response:
{"result": 174879564424376618057728, "message": "Ok"}
GET /balances
Get token and ether balances.
URL
​https://hidingbook.rook.finance/api/v1/balances​
Method:
GET
URL Params
user=[address]
Sample Call:
/balances?address=0xcA77Dc47eec9E1C46c9F541ba0f222E741d6236b
Success Response:
{
  "result": {
    "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee": {
      "balance": 9511349808089782810,
      "decimals": 18
    },
    "0x6b175474e89094c44da98b954eedeac495271d0f": {
      "balance": 0,
      "decimals": 18
    },
    "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359": {
      "balance": 0,
      "decimals": 18
    }
  },
  "message": "Ok"
}
​
Block.timestamp vs order.expiry
Next - Integration guides
HidingBook WS API
Last modified 9mo ago
HidingBook HTTP API

Introduction

HTTP endpoint

Headers

Response format

Error codes

HTTP Methods

GET /info

GET /tokenList

POST /orders

GET /orders

DELETE /orders

GET /suggestedReturn

GET /balances

​
