API

KeeperDAO's Hiding Game RESTful API makes it easy to integrate into your dApp.

The base endpoint is: https://hidingbook.keeperdao.com/api/v1/

  • Limit order protocol: 0xv4 RFQ orders

  • All endpoints return JSON

  • Response format

    • success

      • {"orders": [], "message": "Ok"}

      • {"orders": [{"order": ....... ], "message": "Ok"}

    • error

      • {"error": "Insufficient maker balance", "code": -2001}

      • {"error": "Invalid param", "code": -2010, "message": "txOrigin failed validation"}

GET /info

Returns all general information needed to populate the user interface.

  • URL

    /info

  • Method:

    GET

  • Success Response:

    {
    "result": {
    "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

    /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.

  • URL

    /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:

    {
    'result': {
    'hashList': [
    '0x345cfe65093ee90aec8824be4b7c24070cf56240e04b6fb6e5b1e003f24527f9',
    '0xeb49fb338838615720dd8423650df146db7b1e6408f747733ff01b11383a91a8'
    ]
    },
    'message': 'Order creation succeeded'
    }

GET /orders

Get orders from the order book.

  • URL

    /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 [Soft Cancel]

Cancel an array of 0x orders without paying gas. This API informs all keepers that you wish for this order to not be filled. Keepers will be disincentivize to fill a soft canceled order via the Coordination Game. Do note that it will be technically possible for the order to be filled on chain by any whitelisted keeper even after being soft canceled. But a keeper who fills a soft canceled order will be punished, so keepers are incentivized to be on their best behavior. We recommend that you use this soft cancel API for low to medium priority cancels. If you wish to make an emergency high priority cancel, or if you suspect that a keeper is already attempting to fill your order, please make an on chain cancel to the blockchain to guarantee that the order cannot be filled.

In order to make a soft cancel, you must sign a message hash with the private key who's address is the maker of the order you wish to cancel.

Calling this API sets the softCancel property in the order's metaData. The order is considered soft canceled when the softCancel property is less than the current unix epoch time in seconds.

Steps:

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

    /orders

  • Method:

    DELETE

  • Data Params

    [
    {
    'orderHash': '0x26368e875790de2513d451c71bb12e5b83b1f897322ee24cd5c246a64628e294',
    'signature': {
    'v': 27,
    'r': '0xf2342382c6f830699955d3b6e357073b5195016c08b8a8c67828ea9d05812214',
    's': '0x12672adc8cb27639785ff4cc3349a6162a66faac6c6c268bad9e96b8d7a8da2f'
    }
    }
    ]
  • Success Response:

    {
    'result': {
    'hashList': [
    '0x26368e875790de2513d451c71bb12e5b83b1f897322ee24cd5c246a64628e294'
    ]
    },
    'message': 'Soft order cancel succeeded'
    }

GET /suggestedReturn

Get suggested trade return based on current DEX prices.

  • URL

    /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

    /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"
    }

Note: The Hiding Book API is under continuous development and is subject to change.

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",
}