Hodlberg ]-[ Financial - Tokenized Holdings
HODLBERG'S CONTRACTS ARE CONNECTED TO RINKEBY TESTNET (click me!)

API Documentation

In order to use the Hodlberg API to retrieve private token data, as authorized by a token holder, one will need to follow these steps.

1. Account Creation

Create a free account

Multi-Factor Authentication with Google Authenticator or like app is required to complete account setup.

2. Account Management

Add A Site

A pair of API keys will be generated for you. Keep the API Secret a secret, and do not disclose or expose to publicly accessible systems. These keys will be used in making requests to the Hodlberg API.

Webhook URLs are necessary to receive notifications from Hodlberg when a token holder authorizes or revokes access to your site/application.

The Site Key should be made public so token holders can authorize your site to access their tokens without going through an on-site authentication process.

3. Hodlberg API Calls

All requests to Hodlberg require the addition of three HTTP Headers:

  • x-api-key - Your public API Key
  • x-hodlberg-signature - Base64 encoded string of a SHA256 hashed TIMESTAMP + REQUEST METHOD + PATH, encoded with your API Secret
  • x-hodlberg-timestamp - Current TIMESTAMP, used in signature formation

TIMESTAMP should be Coordinated Universal Time (UTC) and contain milliseconds

PATH parameters (if any) should be lexically ordered when generating x-hodlberg-signature. Example: ?apple=1&banana=2

All requests from Hodlberg include the following HTTP Headers:

  • x-api-key - Your public API Key
  • x-hodlberg-signature - Base64 encoded string of a SHA256 hashed TIMESTAMP + REQUEST METHOD + PATH, encoded with your API Secret
  • x-hodlberg-timestamp - Current TIMESTAMP, used in signature formation
  • x-hodlberg-network - "mainnet" or "testnet"
  • x-hodlberg-method - HTTP method used in the call and for signature generation
  • A site owner should verify the signature in any request from Hodlberg to make sure it is authentic.

    4. Authorize a Token Holder

    5. Token API Endpoint Discovery

    Once you have authenticated a user's wallet address, several calls to the Hodlberg NFT Smart Contract will lead you to the NFT metadata and Hodlberg Token API endpoint.

    The contract exposes several useful methods:

    • balanceOf(WALLET_ADDRESS <ADDRESS>) - Return the amount of Hodlberg NFTs held by this wallet
    • tokenOfOwnerByIndex(WALLET_ADDRESS <ADDRESS>, INDEX <UINT256>) - Return the TOKENID of a given WALLET_ADDRESS, based on its INDEX (INDEX range can be determined from the previous balanceOf() call)
    • tokenURI(TOKENID <UINT256>) - Return the <STRING> Token API Endpoint where the live metadata resides

    If a user has already authenticated an Ethereum wallet address on your site, one could query the balanceOf() method to auto-discover if the user holds a Hodlberg NFT, and then ask for private access if warranted.

    Smart Contract Addresses

    6. Webhooks

    Webhooks are configured on the account page. When a Hodlberg token holder changes site access permissions, Hodlberg will make a POST request to the designated webhook URL with the following JSON payload: { address: HOLDER_PUBLIC_ADDRESS, tokenIDs: [ ARRAY_OF_TOKEN_IDS_AFFECTED ], action: ALLOW_OR_DENY }

    If a Hodlberg token holder revokes access to your site, you may still retreive public information from the endpoint.