API and Downloads | Integrations

The API

The Entropy on Tap API is simple, efficient, and environment-agnostic. You can use it equally easy from Javascript or C++, Windows or mac.

You will only ever need one URL to trigger – the one of your tap – which you can find on your My Taps page:

Next to the tap URL you will see your access key (press the View button to disclose it).

The 0fhszmf2 piece is a unique identifier of your tap. It never changes.

You work with your tap by sending GET and POST request to its address. You use GET to retrieve random data from the tap. You use POST to seed the tap with your own entropy, should you want to do so (which is good, but in no way required).

With each request, you need to provide the following parameters in the query string:

  • q (required) – the quantity of random data that you would like to receive, in bytes
  • f – the format that you would like to receive the data in. This can be “json” or “binary”. The default is JSON.
  • n (required) – a nonce. Each request you send must be accompanied by a unique nonce. This is to protect your tap from replay attacks and prevent abuse. Generate the nonce as a 4-8 character random string, or simply as current time in Unix epoch format.
  • m – setting it to “test” lets you try out the tap without incurring charges. The output in this case will be always the same, pre-defined data string.
  • auth (required) – a signature over the request made with your tap access key. Read on to find out how to calculate it.

It is advised to build the parameters string (except for auth) in alphabetical order, as it simplifies further calculation of the request signature.

Here’s an example of a request for 255 bytes in JSON format:

GET /taps/0fhszmf2?f=json&n=a31c&q=255&auth=ea024cd23eb11bf7e1edc46fc8d21..77ed7994de934e3e5f6fc4a6dd

Calculating the signature

The signature that is included with your request ensures its integrity and authenticity. Only the person/code that knows the access key can use your tap and stay confident that the exchange is not tampered with.

Use the following algorithm to calculate the signature when preparing the request.

1. Form the request imprint:

method ” ” resource “?” parameters

Note: make sure your parameters come in alphabetical order (e.g. f, m, n, q; or n, q).

for example:

GET /taps/0fhszmf2?f=json&n=a0b1c2d3&q=255

2. Initialize mix as a concatenation of the request imprint and your tap access key:

mix = imprint | access_key

for example:

GET /taps/0fhszmf2?f=json&n=a0b1c2d3&q=255hfunt7o3a7glzcp2vvxly66lj36a2wvp

3. Initialize vector to equal mix:

vector = mix

4. Send vector through 1000 iterations of hash calls:

for (int i = 0; i < 1000; i++)
{
    // Prepare the hash input as a concatenation of 
    // - i, encoded as 8-byte big-endian number (e.g. [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0xBC] for i of 444)
    // - the current value of vector
    // - mix
    input = GetBigEndianInt64Bytes(i) | vector | mix;
    
    // Update the value of vector by sending input to SHA256 function:
    vector = SHA256(input);    
}

5. The value of vector after the completion of the loop is your raw signature. As it is comprised of binary data, it needs to be formatted before using in an ASCII-friendly REST request. Encode it in hex (base16) and prepend with a “ea02” prefix:

signature = “ea02” | base16(vector)

6. Finally, append the signature to the query as an auth parameter:

GET /taps/0fhszmf2?f=json&n=a0b1c2d3&q=255&auth=ea02a032c377b6…21a6

Example in Javascript

Below you will find an example code of making a data request to Entropy on Tap API in Javascript. Copy the code to an HTML file, upload the file to your web server, and open it from your browser. 

<html>
<head>
<script>

    const BuildNonce = size => [...Array(size)].map(() => Math.floor(Math.random() * 16).toString(16)).join('');

    async function fetchAsync (url) {
      let response = await fetch(url);
      let data = await response.json();
      return data;
    }

    async function GetTrulyRandomBytes(tapUrl, accessKey)
    {
        alert("We are about to make a test request to tap " + tapUrl + ". Note: In test mode, the tap always returns the same pre-defined string. Hit OK (or Close) to continue.");

        // --- Forming the parameters array (in alphabetic order) ---
        //
        // - f: "json"
        // - m: "test" (for test mode onlt)
        // - n: nonce (8 hex chars)
        // - q: the amount 

        var pars = "f=json&n=" + BuildNonce(8) + "&q=32";


        // --- Composing the Request Imprint ---
        //
        // RequestImprint = HTTPMethod [SPACE] resource [QUESTIONMARK] QueryString
        
        // - cutting out the host from tapUrl
        var idx = tapUrl.indexOf("/taps/");
        var resource = tapUrl.substring(idx);

        //  - concatenating the elements
        var imprint = "GET" + " " + resource + "?" + pars;


        // --- Composing the mix as imprint | accessKey ---
        //
        // Note: we will need mix as a byte array, so using TextEncoder to convert it
        var mix = new TextEncoder("utf-8").encode(imprint + accessKey);


        // --- Running 1000 rounds of hashing ---
        var vector = mix;
        for (var i = 0; i < 1000; i++)
        {
            // allocating a byte array for the concatenation
            var len = 8 + vector.byteLength + mix.byteLength;
            var input = new Uint8Array(len);

            // first eight bytes comprise the big-endian encoding of i
            input[0] = 0; 
            input[1] = 0; 
            input[2] = 0; 
            input[3] = 0; 
            input[4] = 0; 
            input[5] = 0;
            input[6] = (i >> 8); 
            input[7] = i & 0xff;

            // then goes the current value of vector
            input.set(vector, 8);

            // and, finally, the mix
            input.set(mix, 8 + vector.byteLength);

            // hashing the input using SHA256
            var hashbuf = await crypto.subtle.digest('SHA-256', input);

            // updating the vector with the hashing result
            vector = new Uint8Array(hashbuf);
        }

        var sig = "ea02" + Array.from(vector).map(b => b.toString(16).padStart(2, '0')).join('');

        // Appending the auth tag to the query
        pars = pars + "&auth=" + sig;

        // ...and the query to the tap URL
        var callUrl = tapUrl + "?" + pars;

        // Making a request
        let json = await fetchAsync(callUrl);

        alert('A chunk of random data was received: ' + json.Data);
    }
    
</script>
</head>
<body>
  <button onclick="GetTrulyRandomBytes('https://api.entropyontap.com/taps/0fhszmf2', 'hfunt7o3a7glzcp2vvxly66lj3');">Request random data</button>
</body>
</html>

Try it yourself

Use tap parameters from your My Taps panel to make a test request to your tap.

Tap URL:


Access key:


Quantity:


Test mode:


Libraries and SDKs

The integration libraries for other SDKs and development frameworks are currently on the private testing stage. If you would like to participate in the evaluation, please contact us at contact@entropyontap.com, and we will be happy to help.

Scroll to Top