CSRNG Pro documentation

CSRNG Pro is the subscription-based, full-featured cryptographically secure random number generator. It returns a standard JSON response containing random numbers, and a lot of useful information regarding your request.

How to call the API

The URL to call is https://csrng.net/csrng/csrng.php?key=[your_API_secure_key]. Calling it with no other 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

The following parameters can be called to change the behavior of the API:

  • key [hexadecimal] (mandatory)
    In order to use the CSRNG Pro API, you need to obtain an API key that uniquely identifies you.
  • min and max [numeric] (optional)
    Set the scope between the min and max values to pick the random numbers. If not specified, min will default to 0 and max will default to 9,007,199,254,740,991.
  • num [numeric] (optional)
    The number of random numbers to pick within the selected range. If not specified, a single random number is generated.
    If you wish to generate unique numbers, “num” can range from 1 to 100,000, meaning the API will generate up to 100,000 unique random number per batch. The num value while generating a batch of unique random numbers will have to be at most 75% of the scope (75% of the difference between min and max)
    If you generate non-unique numbers, “num” can range from 1 to 1,000,000.
  • unique [0 | 1] (optional)
    Set the value to 1 if you want the random numbers selected to be unique within the selected range.
  • store [yes] (optional)
    Only for use with CSRNG.net Pro with storage subscription. When set to “yes”, the requested numbers can be stored and queried later using the request ID with the csrng_query.php API.

The following call includes all parameters and would ask the API for 5 unique random numbers between 1 and 100:

https://csrng.net/csrng/csrng.php?key=abcd1234&min=1&max=100&unique=1&num=5

JSON Response content

If the call is successful:

  • status: success
  • parameters:
    • request_id: [number]
      This value is set to 0 (zero), except if you have requested that the query be stored for later user (CSRNG.net Pro with storage only). Using this request ID, you can use our csrng_query.php API to retrieve the results specific to this request.
    • 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,999,999,999,999,999.
    • num: [number]
      This is the number of random numbers you requested. If you did not specify it in the request, the value will be 1.
    • unique: [0 | 1]
      If you specified that the numbers should be unique, the return value will be 1. If you did not specify it, or set it to a value other than 1, will return 0.
  • values: [number1, number2… numberN]
    These are the random numbers generated according to the specified parameters, separated by a comma (,).

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

[{
  "status":"success"
},{
  "parameters":[{
    "request_id":0,
    "min":1,
    "max":100,
    "num":5,
    "unique":1
  }]
},{
  "values":[
    93,
    51,
    78,
    84,
    23
  ]
}]

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 1, which is specific to CSRNG Pro:

[{
  "status":"error",
  "code":"1",
  "reason":"The number of random numbers requested should not be greater than 75% of the random scope"
}]

Error handling

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

  • Error 9: You are trying to query the API without having a valid subscription, with a subscription that has expired, or that is not active yet.
  • 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 3: You have requested more than 1,000,000 non-unique random numbers. 1 million is the maximum we can provide in a single request in a timely manner.
  • Error 2: You have requested more than 100,000 unique random numbers. 100,000 is the maximum we can provide in a single request in a timely manner.
  • Error 1: You have requested unique random numbers, but the number of random numbers requested is more than 75% of the scope. This limitation is for performance purposes, since asking for more than that impairs performance.
  • 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.net Query API documentation

For those who subscribe for the CSRNG Pro with storage plan, you can later query all your stored random numbers requests. First, you need to have queried the csrng.php API with the “store=yes” GET parameter. Once the call is completed, the request is stored for later use.

How to list all numbers requests

The URL to call is https://csrng.net/csrng/csrng_query.php?key=[your_API_secure_key]&list_requests=all. The JSON response will look like this:

[{"3230":{"min":"0","max":"100","num":"1","unique":"0","timestamp":"2017-02-05 10:19:07"}},{"3231":{"min":"0","max":"1000","num":"750","unique":"1","timestamp":"2017-02-05 10:19:41"}}]

The fields returned in the JSON response are:

  • [request_id]: This is the ID of the request that you can use later to get the list of random numbers generated in this request.
    • min:[number]: This is the min value of the request
    • max:[number]: This is the max value of the request
    • num:[number]: This is the number of random numbers that were generated by this request
    • unique:[ 0 | 1 ]: Whether the numbers generated are unique or not (1 for unique)
    • timestamp:[date]: The date and time the random numbers request was generated

In the above JSON response example, 2 requests were listed, request ID 3230 and 3231, with the above listed parameters for each.

How to get the numbers of a specific request

The URL to call is https://csrng.net/csrng/csrng_query.php?key=[your_API_secure_key]&request_id=[request_id].

For the following request:

https://csrng.net/csrng/csrng_query.php?key=abcd1234abcd1234&request_id=3230

The JSON response will look like this:

[{"status":"success"},{"parameters":[{"request_id":3230,"min":0,"max":100,"num":1,"unique":0}]},{"values":[94]}]

The fields returned in the JSON response are exactly the same as those returned on the initial request, as described -> here <-