NAV Navbar
javascript

Introduction

Welcome to the Bank of Hodlers Enterprise API documentation!

You can use our API to access secure endpoints, which can help you create wallets for your users with immediate access to our platform's lending features.

We have language bindings in JavaScript. You can view relevant code samples over to the right in the dedicated dark section as shown. You can switch the programming language of the examples shown with tabs displayed on the top-left corner of the region.

Boh

Getting Started

The base URL for our API: https://apis.bankofhodlers.com

With this URL, access is limited to the corresponding cryptocurrency's testnet, a simultion of the blockchain, as opposed to the mainnet where the currency holds value. To interact, or just play around with, some test crypto, there are 'faucets' that drip test cryptocurrency to be used with the testnets. The testnet we will be using here is Kovan.

For more reading on mainnets and testnets: Ethereum 101: Mainnet and testnets

Alright, if that's all good, let's get started!

Wallets and Testnets

A wallet and some test cryptocurrency is required

Metamask is a wallet provider: Metamask

For the Bitcoin Kovan faucet: Bitcoin Kovan Faucet

For the Ethereum Kovan faucet: Ethereum Kovan Faucet

After you have completed implementing your wallet structure with the testnet, Sign Up for a Mainnet Access Key

Authentication

To authenticate, use this format:

# You can use any hmac library that supports SHA256 algorithm
# Illustrative code generate hmac for a payload

const CryptoJS = require('CryptoJS');

const jsonToURI = async (jsonObj) => {
    var output = '';
    var keys = Object.keys(jsonObj);
    keys.forEach(function(key) {
        output = output + key + '=' + jsonObj[key] + '&';
    });
    return output.slice(0, -1);
}

const payload = '_Request_inJSON_';
const secret = '_your_APIKey_' // make this your secret!!

let URIencodedPayload = jsonToURI(JSON.parse(payload));
let hmac = CryptoJS.HmacSHA256(URIencodedPayload, secret);
let hash = hmac.toString(CryptoJS.enc.Hex);

pm.request.headers.add({
  key: 'hmac',
  value: hash
});    

Here at BOH, We use HMAC based authentication, for further reading on the protocol: HMAC documentation

To authenticate the APIs, we create an HMAC hash for the payload (in URI format) using the SHA-256 hashing algorithm using the provided APIKey as the seed. The HMAC hash generated is converted to it's Hex notation and is passed to the response body in the format mentioned below, with the headers set to Content-Type: application/json.

hmac: _HMAC_Hash_asHex_

Boh

Users Module

Create New User

JSON response object format:

{
    "success": true,
    "data": {
        "message": "User account created.",
        "userDetails": {
            "userID": "5daaf3d38566f255e33ceff7",
            "walletsCreated": true,
            "BTCAddress": "2MzB28k9NUH3FBxasQKdPVqbBHK8aZabuvy",
            "ETHAddress": "0x8E22D85F2dBc5191b4250379190277E4B71f99c3",
            "DAIAddress": "0x8E22D85F2dBc5191b4250379190277E4B71f99c3",
            "TUSDAddress": "0x8E22D85F2dBc5191b4250379190277E4B71f99c3"
        }
    }
}

This endpoint creates a new user account for your organisation. This also creates a cryptocurrency wallet for each currecy on our platform for the user.

HTTP Request

POST {{url}}/api/v1/users/create

Query Parameters

Parameter Required Description
orgID yes Your OrganisationID
name yes Name of the user
email yes Email of the user

Response Details

Key Description
success true or false, depending on the processing of the request
data Contains details of the request
message Descriptive response
userDetails Details of the new user created
userID Unique identifier of the user, all interaction with our platform for the user will be via this ID
walletsCreated Boolean, true if wallets for the user were created for the user, false otherwise
BTCAddress Receiving Address for the user on the Bitcoin network
ETHAddress Receiving Address for the user on the Ethereum network
DAIAddress Receiving Address for the user on the DAI network
TUSDAddress Receiving Address for the user on the TrueUSD network

Get User Details

JSON response object format:

{
  "success": true,
  "data": {
      "userDetails": {
          "userID": "5da859e3d8ed65974e4ea837",
          "email": "email_of_the_registered_user",
          "txns": "5da859e3d8ed65974e4ea836"
      }
  }
}

This endpoint retrieves details of a specific registered user.

HTTP Request

POST {{url}}/api/v1/users/profile

URL Parameters

Parameter Required Description
orgID yes Your OrganisationID
username yes Email address of the registered user.

Wallets Module

User Wallet Details

JSON response object format:

{
    "success": true,
    "data": {
        "btc": {
            "WLP": 87740,
            "interest_earned": 0,
            "as_collateral": 0,
            "networkBalance": 0,
            "balance": 0,
            "address": "2N7RzJHbhQXDsLAUh2xCEhnSkAoVA1K6R8g"
        },
        "eth": {
            "WLP": 0,
            "interest_earned": 0,
            "as_collateral": 0,
            "networkBalance": 0,
            "balance": 0,
            "address": "0x055600D252835fCb4d4561ac2DD7Ab68442925C4"
        },
        "tusd": {
            "WLP": 0,
            "interest_earned": 0,
            "as_collateral": 0,
            "networkBalance": 0,
            "balance": 0,
            "address": "0x055600D252835fCb4d4561ac2DD7Ab68442925C4"
        },
        "dai": {
            "WLP": 0,
            "interest_earned": 0,
            "as_collateral": 0,
            "networkBalance": 0,
            "balance": 0,
            "address": "0x055600D252835fCb4d4561ac2DD7Ab68442925C4"
        }
    }
}

This endpoint retrieves wallet details of a specific registered user.

HTTP Request

POST {{url}}/api/v1/wallets/userBalanceDetails

URL Parameters

Parameter Required Description
orgID yes Your OrganisationID
userID yes Unique identifier of the user, received while creating a new user

Response Details

Key Description
success true or false, depending on the processing of the request
data Contains details of coin specific details
btc Bitcoin token specific details
eth Ethereum token specific details
tusd TrueUSD token specific details
dai DAI token specific details
WLP Withdrawable Lending Pool Balance, It reflects the amount that was sweeped from the user wallet to Organisation wallet ( If Organisation has opted for Lending Service)
interest_earned Interest earned for desposit in wallet ( If Organisation has opted for Lending Service )
as_collateral Users pledged amount for the loan ( If Organisation has opted for Borrowing Service)
networkBalance Balance avaialible on this wallet on the respective token, can be cross verified with token specific blockchain
balance Total Balance of the User ( WLP + as_collateral + networkBalance )
address Blockchain address assigned to the user

Transfer

JSON response object format:

{
    "success": true,
    "data": {
        "btc": {
            "WLP": 87740,
            "interest_earned": 0,
            "as_collateral": 0,
            "networkBalance": 0,
            "balance": 0,
            "address": "2N7RzJHbhQXDsLAUh2xCEhnSkAoVA1K6R8g"
        },
        "eth": {
            "WLP": 0,
            "interest_earned": 0,
            "as_collateral": 0,
            "networkBalance": 0,
            "balance": 0,
            "address": "0x055600D252835fCb4d4561ac2DD7Ab68442925C4"
        },
        "tusd": {
            "WLP": 0,
            "interest_earned": 0,
            "as_collateral": 0,
            "networkBalance": 0,
            "balance": 0,
            "address": "0x055600D252835fCb4d4561ac2DD7Ab68442925C4"
        },
        "dai": {
            "WLP": 0,
            "interest_earned": 0,
            "as_collateral": 0,
            "networkBalance": 0,
            "balance": 0,
            "address": "0x055600D252835fCb4d4561ac2DD7Ab68442925C4"
        }
    }
}

This endpoint transfers tokens from one wallet to another

HTTP Request

POST {{url}}/api/v1/wallets/transfer

URL Parameters

Parameter Required Description
token yes token ticker
walletAddr yes sender's wallet address
orgID yes Your OrganisationID
amount yes Amount to be sent
receiver yes Receiver wallet address
userID yes Unique identifier of the user, received while creating a new user

Response Details

Key Description
success true or false
data Contains coin specific details
btc Bitcoin token specific details
eth Ethereum token specific details
tusd TrueUSD token specific details
dai DAI token specific details
WLP Withdrawable Lending Pool Balance, It reflects the amount that was sweeped from the user wallet to Organisation wallet ( If Organisation has opted for Lending Service)
interest_earned Interest earned for desposit in wallet ( If Organisation has opted for Lending Service )
as_collateral Users pledged amount for the loan ( If Organisation has opted for Borrowing Service)
networkBalance Balance avaialible on this wallet on the respective token, can be cross verified with token specific blockchain
balance Total Balance of the User ( WLP + as_collateral + networkBalance )
address Blockchain address assigned to the user

Transaction Cost

JSON response object format:

{
    "success": true,
    "fee": "sample fee",
    "coin": "btc"
}

This endpoint gets the cost of a transaction, if it were to be broadcast at that moment. This is amount agnostic!

HTTP Request

POST {{url}}/api/v1/wallets/getTxnFees

URL Parameters

Parameter Required Description
token yes token ticker
orgID yes Your OrganisationID
amount yes Amount to be sent
receiver yes Receiver wallet address

Response Details

Key Description
success true or false
data Contains coin specific details
fee the fee to be charged for the transaction
coin The cryptocurrency for which the transaction details have been returned