CSRNG Lite documentation

CSRNG Lite is a free API you can call to generate random numbers. It returns a standard JSON response containing a random number in a certain range.

How to call the API

The URL to call is https://csrng.net/csrng/csrng.php. Calling it without any parameters will return a single random number ranging between 0 and 9,007,199,254,740,991 inside a JSON response

The call has to be made using the GET method. (ex: https://csrng.net/csrng/csrng.php?parameter1=value1&parameter2=value2)

Configurable request parameters

Configurable parameters are “min” and “max”, in any order, that you append at the end of the URL using the standard GET method to pass parameters. You can call the API using only the “max” parameter (the API will assume 0 as the “min” value), or using the “min” AND “max” parameters. If you call the API using only the “min” parameter, you will get an error code in the JSON response.

The following call includes both parameters and would ask the API for a random number between 1 and 100:

https://csrng.net/csrng/csrng.php?min=1&max=100

JSON Response content

If the call is successful:

  • status: success
  • min: [number]
    If you set this parameter in the request, will have the value you requested. If not, value will default to 0.
  • max: [number]
    If you set this parameter in the request, will have the value you requested. If not, value will default to 9,007,199,254,740,991.

The JSON response would look like this for the above call:

[{"status":"success","min":1,"max":100,"random":38}]

If the call is in error:

  • status: error
  • code: [number]
    An error code corresponding to one of the errors listed below
  • reason: [textual reason]
    A textual reason describing the reason of the failure.

Here is an example of error message 5, which is the most likely to occur:

[{"status":"error","code":"5","reason":"Reached maximum queries in the last second. To remove limitation, please get our PRO service at https:\/\/www.csrng.net"}]

Error handling

The following list describes all the errors you may encounter while using CSRNG Lite:

  • Error 8: Invalid request method. For example, if you are trying to use the POST method instead of the GET method.
  • Error 7: Cannot connect to our database. This is a technical issue that only us can solve. Service should come back shortly
  • Error 6: Some of the parameters have invalid values. Please see API documentation.
  • Error 5: You have reached the maximum number of queries in the last second.
  • Error 4: You are trying to use an invalid Pro API key. You have up to 5 attempts before your IP address is banned for an hour.
  • Error 0: Your IP address has been banned for an hour. This can be because you have unsuccessfully tried to use a Pro version API key that is invalid.

CSRNG Lite limitations

The free CSRNG Lite API is limited to generating single random numbers, one at a time, with a limit of a single request per second per client IP address. You can call as many times as you wish, but a second request within the same second will generate an error. When this second is over, you may request a new random number.

Also, the Lite version is less configurable than the Pro version, in that the Pro version lets you generate batches of random numbers (up to 1 million non-unique random numbers or 100,000 unique random numbers at a time). The Pro version also lets you access an history of all the requests that have been made, all through the same API