This section describes RANDOM.ORG's Signed API, which together with the Basic API constitutes the Core API. The Signed API is intended for applications that need to support non-repudiation, and its methods produce digitally signed series of true random values, generated specifically for your client. The digital signatures mean that the values can be proved to originate from RANDOM.ORG.
In the Signed API, a signature is a SHA-512 digest
of the JSON representation of a random object, which
has been signed with RANDOM.ORG's private key.
Given a random object and its signature,
anyone can verify the signature against RANDOM.ORG's
public key to confirm that the numbers
are authentic. To do this, the client should JSON-encode the
random object, then compute the SHA-512 digest and
verify the signature against it. While a client is free to use
its own signature verification algorithm, it can also use the
verifySignature method described here.
The Signed API also stores the values generated with the methods
for a minimum of one year. This allows you to retrieve values that
were generated but may not have been delivered to your client due
to network failures, etc. The getResult method is
used for this purpose.
The URL for invoking the Signed API is:
https://api.random.org/json-rpc/2/invoke
application/json.
application/json. In particular,
application/json-rpc and
application/jsonrequest are no longer allowed.
generateSignedIntegerSequencesgetResultuserData was added to the
following methods:
generateSignedIntegersgenerateSignedDecimalFractionsgenerateSignedGaussiansgenerateSignedStringsgenerateSignedUUIDsgenerateSignedBlobslicense and userData
were added to random objects returned by the following
methods:
generateSignedIntegersgenerateSignedDecimalFractionsgenerateSignedGaussiansgenerateSignedStringsgenerateSignedUUIDsgenerateSignedBlobsgenerateSignedIntegers (method)
This method generates true random integers within a user-defined
range. Your client must set the method property of
its JSON-RPC request object to generateSignedIntegers.
The request must also contain an id member, which
will be returned in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynminmax
The following parameters are optional and can be included in
the params object of your JSON-RPC request if you
want functionality that is different from the default:
replacement (default value true)true) will cause the
numbers to be picked with replacement, i.e., the resulting
numbers may contain duplicate values (like a series of dice
rolls). If you want the numbers picked to be unique (like
raffle tickets drawn from a container), set this value to
false.
base (default value 10)2, 8,
10 and 16. This affects the JSON
types of the data property included in the response,
as discussed below.
userData (default value null)
If the numbers were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property
containing an object with the following named values:
randomrandom object contains the
following properties.
methodhashedApiKeyrandom object
to a third party and allow that third party to associate the
response with a given apiKey, without requiring
the client to disclose the actual apiKey.
n, min, max,
replacement, base
params
object. Values that are optional and did not appear in the
request will appear in the response with the default values.
The reason these are included in the response is to allow them
to be signed by RANDOM.ORG.
database 10 (or did
not specify a base and therefore defaults to 10),
the elements in the array will be integers. Because JSON (according
to RFC4627)
only allows numbers to be written as decimal, the numbers will
be typed as strings if a different base than
10 was specified in the request. Numbers in any
base other than 10 will be padded with leading zeros up to
the width required to display the chosen range.
licensedata can be used. The API
key owner selects a license for each API key created, which
affects this field in the responses generated for this API
key. For example, an API key could be licensed for non-profit
use only, or for commercial gambling up to a certain prize
value per month.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response
with the value null.
completionTimeserialNumberapiKey (and, consequently, within the corresponding
hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
bitsUsedbitsLeftrequestsLeftadvisoryDelay
For a successful response, the error property is
absent.
A client that stores the results to show non-repudiation or
implements code to satisfy other auditing requirements should
store the random and signature properties,
such that they can be shared publically or with auditors.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result property is
absent and the error property contains an error
object as described in Error Codes and
Messages.
The following requests ten numbers in the [1,6] range. The
replacement parameter is set to true,
which means the numbers will be picked with replacement, i.e., can
contain duplicate values. This makes them suitable for use as dice
rolls.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegers",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 10,
"min": 1,
"max": 6,
"replacement": true
},
"id": 10720
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 10,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"data": [
3, 2, 6, 6, 2, 2, 1, 3, 1, 5
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": null,
"completionTime": "2017-02-12 10:47:15Z",
"serialNumber": 4
},
"signature": "dPXrMbLTr9Bq7pFyghExeI09n92H9Q1Mj6CDD2ABHtDwHDAzN3Tq3el6mS+xkmLyZpkBrWm+ficdLGS8BI8dq8f+GTuzDJCQ0Ah6FnAaXn7TX32xdZ9rqAp0S1IcR7GVMa8Wbcb5u70+evtVSUciotYqQNLkPPB6xx5+TFkY2L24TkfxHGXqG53D5MZDha7kSR7w2cuTRhabRmGmRA7dXgw4swJwAfvKXs63fCzZVbK1pfjZbm7IkmimhP7SRox9t5rAQkFSYfNKeGDrIlFgONb9+5OUEMO+9860nzUBIYsahO+VIHZWYbxSDB4chfmy/bNeBAeexx7tvV8Df2sQ3+soF3fQ/3ca5YFWdWceE+clkI7/8zlPaNYlWQiFDo/0QnySQxLf09O/2Ct3HBoIxBixEj+4FtYbpUi7OmE6IOL/Jhk+RRBfdXxHZUieOykJynTdbXchXCVGY9w5ZkgT8b5w6nDRxTid0RXfepY+sdOucZp7Few4/IYNQmGxB1jMFnUbw5l2TQD2f65P0FojwXpSkJfUnXsRy6m72XCUwo8PwTvrpfdHykWxwWyzhw+jLz/Pte3DrpD/xvwjtOi5OnZAO8SXYdjR8lH6ZUrvQZZI9qT0O3OBMPEgspYDNEx3IGbmwW2/wxaujW6xbxkFS+i0n4gjjdtOhAQHYstTE+o=",
"bitsUsed": 26,
"bitsLeft": 4999948,
"requestsLeft": 19998,
"advisoryDelay": 1090
},
"id": 10720
}
The method shows which part of the
RANDOM.ORG API was used to generate the
true random numbers. The hashedApiKey allows the
client to share the full contents of the random
and signature objects with third parties without
disclosing its apiKey. The n,
min, max and replacement
parameters from the request are included too. The base
and userData properties have been added, even though
they did not appear in the request. The data array
within the result contains the true random numbers
produced, and the license describes how the numbers
can be used. The completionTime specifies UTC time
zone (‘Zulu time’) by the letter ‘Z’ after
the clock time. The serialNumber indicates that this
is the 4th request to have been completed with the apiKey
in question.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. Through the other
fields in the result, RANDOM.ORG also advises how many true random bits were used to satisfy the
request and how many bits and requests are left in the client's
quota. The service advises the client when it can issue the next
request, after a short delay.
The following requests 52 numbers in the [1,52] range. The
replacement parameter is set to false,
meaning the numbers will be picked without replacement, i.e.,
duplicates will not occur. This makes them suitable to shuffle a
deck of cards. The client also includes an object in the
userData property. The service does not perform any
operations on this object, but simply includes it along with
the signed random data that is returned to the client in the
response.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegers",
"params": {
"apiKey": "b9529387-e0f8-4cc9-a5ad-c5b32b394d1c",
"n": 52,
"min": 1,
"max": 52,
"replacement": false,
"base": 10,
"userData": {
"myHashType": "md5",
"myHashValue": "c4ec4ba28cbe8390c2f846bf589e538a"
}
},
"id": 3448
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "rAkSMsx6PBe0w/l2OEssiIZZDC7/4wJCYjSmrLMDgkVM9KhslJ65wsOaZxgJn44kbUtBT5dSSyBBnQ+CFtdj4A==",
"n": 52,
"min": 1,
"max": 52,
"replacement": false,
"base": 10,
"data": [
5, 3, 18, 35, 47, 43, 4, 49, 51, 28, 36, 12, 8, 41, 16, 19, 46, 39, 23, 6, 32, 17, 15, 50, 30, 45, 42, 11, 48, 26, 20, 40, 22, 7, 31, 13, 21, 37, 29, 38, 34, 44, 2, 1, 52, 14, 24, 33, 25, 10, 27, 9
],
"license": {
"type": "gambling-1m",
"text": "These values are licensed for gambling up to a total monthly prize value of $1 million USD",
"infoUrl": "https://api.random.org/licenses/gambling-1m"
},
"userData": {
"myHashType": "md5",
"myHashValue": "c4ec4ba28cbe8390c2f846bf589e538a"
},
"completionTime": "2017-02-12 11:03:42Z",
"serialNumber": 1
},
"signature": "eafA7oDQ+fKM4mjuulkku88svdwyogfWQ5EyWTaMbljLPQXmkEJeMr0ydShEHyEp3h0ZHa0qu84zyzpMBu7nyc8Vx79PlNyfEoIfUTNedTNyO6lHHBay+8Lbbj3SAyDJnNdxQPp16e23VoYEFpnvBiacEtiuwhTlEK4z0F4ORSzAR0gdnuPnyL+NG3oCMAunahmnnkJz5jyD/ckOC9vZLlW1K64jb5f86q2zxSqs2wLO5GY9Rv2IJX85wYS8r22/XVuqmrFwtAJJhdvjW24MJJlOP/l8nKrkbg6GnpheVMGj2DchB3CMLfZ2DJBBKY3+002LClcEivF2NARF8HwJVA29Gf53XoVr0Yv8X9Xn/nZN0Bt9MYtJ50k6uVDBLunKIvlH5qQornG9/dTiNxQJboCzx3bV16lBwdTmzUTUuKZ1DqQ91nBNYdhK4gyWM3AaSCkYbeytEWkDSx62QlxzCrZGVwfeaZhlYgjWLi3nqCH0wZeQepjxl6Ym6h8pYKyR2UVng4CccStUEbqXlWF2G4G8iLGyVxQzBSfshKesS4IS97h+njRVXJHpBgalys25ZfVErA6fTshgcMCcbt3MM3QUIbVLAOcV1xMPrhhHnXyEpM+ZobjwfrH3TIhzh2GuBQaVDaXeCoIRGfpPyw4T/IFfrw/dYoIqccR5/iAHa6g=",
"bitsUsed": 296,
"bitsLeft": 499704,
"requestsLeft": 4999,
"advisoryDelay": 1260
},
"id": 3448
}
The method, n, min,
max, replacement and base
parameters are the same that appeared in the request. The
hashedApiKey allows the client to share the full
contents of the random and signature
objects with third parties without disclosing its apiKey.
The random object contains the true random numbers
(in the data array) produced. The service advises
exactly when the request was completed, and that the values are
licensed for commercial gambling up to a certain monthly prize
value. The object that the client passed in the userData
parameter is included unchanged in the response. The serial number
indicates that this is the very first request to be completed with
this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits
and requests are left in the client's quota. The service advises
the client when it can issue the next request, after a short delay.
The following requests 512 bytes, i.e., numbers in the [0,255]
range. The replacement parameter is set to
true, which means the numbers will be picked with
replacement, i.e., duplicates are allowed. The optional
base parameter is used to indicate that the client
wishes the numbers to be returned in hexadecimal form. The numbers
could be used as seed material for a pseudo-random number generator.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegers",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 512,
"min": 0,
"max": 255,
"replacement": true,
"base": 16,
"userData": "I promise these values will be used for something very special."
},
"id": 31658
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 512,
"min": 0,
"max": 255,
"replacement": true,
"base": 16,
"data": [
"fe", "6f", "f7", "9a", "27", "00", "c2", "a6", "78", "c0", "0c", "6b", "95", "92", "85", "dc", "a5", "ab", "b7", "7c", "b6", "d7", "41", "88", "5a", "8e", "2a", "ab", "b6", "ea", "33", "a7", "f5", "90", "13", "e6", "cf", "f5", "a4", "4a", "03", "f6", "83", "4b", "43", "0d", "a2", "e5", "ce", "80", "59", "47", "d3", "ea", "b0", "3c", "a1", "00", "5e", "8a", "91", "4f", "da", "22", "65", "f8", "1b", "3d", "6d", "c4", "02", "0c", "12", "14", "91", "f9", "62", "97", "dc", "89", "73", "37", "ce", "cd", "65", "32", "57", "11", "6f", "cd", "f5", "f3", "ba", "4f", "fd", "96", "e2", "39", "9b", "2d", "da", "32", "f6", "b2", "08", "f8", "c1", "2c", "2d", "ba", "e5", "6e", "7e", "38", "f6", "3a", "c8", "0f", "cd", "03", "0c", "68", "05", "98", "be", "cf", "cd", "4d", "7c", "5c", "74", "23", "e3", "a3", "41", "89", "d0", "9a", "e9", "b8", "3a", "a1", "8f", "55", "60", "d3", "42", "4b", "db", "08", "23", "9a", "1a", "eb", "80", "9c", "65", "d6", "da", "af", "0f", "5e", "b8", "66", "75", "62", "85", "d9", "f8", "ba", "a9", "d1", "39", "a7", "35", "d7", "af", "df", "de", "5f", "dd", "ec", "0d", "26", "31", "c4", "a7", "95", "a8", "c2", "71", "72", "0d", "db", "e1", "c7", "f3", "03", "f5", "91", "b8", "0f", "4a", "72", "d4", "fa", "06", "97", "c4", "b5", "61", "cd", "5d", "87", "f9", "d5", "5b", "77", "63", "1d", "a0", "d3", "07", "bb", "83", "be", "44", "a1", "a1", "c9", "44", "49", "a0", "4b", "63", "a6", "4f", "c7", "20", "3a", "c7", "17", "86", "da", "8d", "0c", "15", "35", "26", "8a", "2f", "d3", "a2", "b6", "1b", "bf", "ce", "21", "0d", "cd", "a1", "d0", "57", "b5", "24", "63", "06", "ab", "ff", "12", "31", "71", "e5", "e8", "81", "99", "ac", "c7", "c5", "12", "7e", "af", "44", "22", "b3", "16", "bc", "60", "ea", "7b", "f1", "57", "6f", "3c", "ac", "5d", "75", "d5", "7a", "8b", "13", "da", "26", "79", "28", "22", "c9", "a2", "be", "7d", "47", "f0", "3d", "8c", "45", "4d", "30", "21", "c5", "12", "7b", "b7", "1c", "3c", "67", "00", "30", "36", "f0", "78", "85", "b4", "bf", "09", "dc", "e8", "76", "65", "cc", "71", "7a", "c6", "3e", "17", "fc", "26", "38", "4a", "58", "8b", "bf", "d1", "49", "39", "86", "42", "d3", "b0", "f8", "d1", "1f", "c2", "00", "dc", "de", "8f", "75", "e3", "91", "4e", "7e", "a3", "7d", "1c", "20", "f2", "31", "ed", "e3", "fe", "1d", "87", "ec", "f3", "31", "5f", "46", "2f", "ca", "0b", "7d", "bc", "cd", "5a", "d7", "21", "5b", "a1", "57", "7f", "a2", "42", "e8", "c7", "ae", "c0", "5c", "b8", "43", "a1", "33", "1c", "0d", "ce", "47", "a7", "49", "47", "6d", "bb", "e5", "26", "e4", "ea", "bf", "7e", "6f", "12", "c4", "da", "3a", "a3", "a3", "cc", "da", "89", "a5", "44", "d2", "06", "0e", "b2", "cf", "f5", "a0", "81", "c3", "4e", "3e", "1f", "17", "f0", "d3", "45", "43", "95", "fc", "94", "ca", "86", "78", "c4", "fc", "46", "55", "84", "ae", "95", "ed", "f3", "d4", "39", "2c", "81", "e9", "a1", "7e", "6e", "7b", "0f", "11", "f6", "75", "6b", "61", "b0", "65", "64", "2c", "df", "46", "b9", "a2", "6a", "7c", "70", "8e", "7a", "2f", "ec", "19", "48", "53", "87", "0f", "42", "91", "97", "08", "a4", "02", "cd"
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": "I promise these values will be used for something very special.",
"completionTime": "2017-02-12 11:12:38Z",
"serialNumber": 5
},
"signature": "AXEdtYkivVoxIo+9mapwQ/imsYp6LmtLkIZNXVc/CA+9bn00U8ewyQ2XYhzj4EXiV086liNzCj86dgKxqeEwOfScEXZoYVpmWNxOMTynEOIzT1F9d0RTI30YcMVbYIaTHIMI1jnDCqPWUXyXB5KA5iDA2ojE/bfPYyaoRSTFEV/MxLiVwNCfi5BkPlXQvZb/wW33XCuvoHq6BhaXLPKqzDUjofoX1+yTRaE+LKQhApPye9QDV8G9EMaH9kQff76ej7er9QwDWm1L+ki3N6wrLT6Orq/dF45Ejxgng2CZHq164NDTlEW/lT4/gqD8yl5lpzYbVO0FLZJmz7FH/d7XkgzOupcdkveNskV/E1uluCLYn5J8z/fnlB5uKlkXRRirvI1n4Z4r8xFaURJyIiLI53gmRMsBtgbg0Ml3HaYnWFfxTSqXAuEXvDJ8g0VhS9SWHvnf/mLDuSpCsB2eokmIMWBXmuvchlJAaX6mhn3MdHQTUWvbItD7jAmAppK4LPq0frLGnoEx04WJCi9XCBDmhRf5X30e9fFE2DumreZQ7nMF0C2xqgwm/Dql4JpR0vlBi6g/hUCO+wECA2ZZrSgoYpboHKd00+yvEfTmDrbC61xZoVkIsnVOX45UaIVyMbmSvmv+GqlEDGf5V3p6ReZSGLhhmZqRrK4eHUuheDY89gc=",
"bitsUsed": 4096,
"bitsLeft": 4995852,
"requestsLeft": 19997,
"advisoryDelay": 1070
},
"id": 31658
}
The method, n, min,
max, replacement, base
and userData parameters are the same that appeared
in the request. The hashedApiKey allows the client
to share the full contents of the random and
signature objects with third parties without disclosing
its apiKey. The random object contains
the true random numbers (in the data array) produced.
The data array contains strings rather than integers,
because the numbers are formatted in base 16. The license
shows that the values are licensed for general commercial use, but
not for gambling. The completionTime specifies UTC
time zone (‘Zulu time’) by the letter ‘Z’
after the clock time. The service advises that this is the 5th request
to be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
generateSignedIntegerSequences (method)
This method generates uniform or multiform sequences of true
random integers within user-defined ranges. Uniform sequences
all have the same general form (length, range, replacement and
base) whereas these characteristics can vary for multiform
sequences. Your client must set the method
property of its JSON-RPC request object to
generateSignedIntegerSequences. The request must
also contain an id member, which will be returned
in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynlengthlength must be an integer in
the [1,
10000]
range. For multiform sequences, length can be an array
with n integers, each specifying the length of the
sequence identified by its index. In this case, each value in
length must be within the
[1,
10000]
range and the total sum of all the lengths must be in the
[1,
10000] range.
minmin must be an
integer in the [-1000000000,
1000000000] range. For
multiform sequences, min can be an array with
n integers, each specifying the lower boundary
of the sequence identified by its index. In this case, each
value in min must be within the
[-1000000000,
1000000000] range.
maxmax must be an
integer in the [-1000000000,
1000000000] range. For
multiform sequences, max can be an array with
n integers, each specifying the upper boundary
of the sequence identified by its index. In this case, each
value in max must be within the
[-1000000000,
1000000000] range.
The following parameters are optional and can be included in
the params object of your JSON-RPC request if you
want functionality that is different from the default:
replacement (default value true)replacement
must be a Boolean value where true indicates the
sequences will be picked with replacement and false
indicates that they will not. For multiform sequences,
replacement can be an array with n
Boolean values, each specifying whether the sequence identified by
its index will be created with (true) or without
(false) replacement.
base (default value 10)base
must be an integer with with one of the values 2,
8, 10 or 16. For multiform
sequences, base can be an array with n
integer values taken from the same set, each specifying the base
that will be used to display the sequence identified by its index.
Use of the base parameter affects the JSON types and
formatting of the resulting data as discussed in the documentation
for the generateSignedIntegers method.
userData (default value null)
If the numbers were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property
containing an object with the following named values:
randomrandom object contains the
following properties.
methodhashedApiKeyrandom object
to a third party and allow that third party to associate the
response with a given apiKey, without requiring
the client to disclose the actual apiKey.
n, length, min,
max, replacement, base
params
object. Values that are optional and did not appear in the request
will appear in the response with the default values. The reason
these are included in the response is to allow them to be signed
by RANDOM.ORG.
datalicensedata can be used.
The API key owner selects a license for each API key created,
which affects this field in the responses generated for this
API key. For example, an API key could be licensed for
non-profit use only, or for commercial gambling up to a
certain prize value per month.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response
with the value null.
completionTimeserialNumberapiKey (and, consequently, within the
corresponding hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
bitsUsedbitsLeftrequestsLeftadvisoryDelay
For a successful response, the error property is
absent.
A client that stores the results to show non-repudiation or
implements code to satisfy other auditing requirements should
store the random and signature
properties, such that they can be shared publically or with auditors.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result property is
absent and the error property contains an error
object as described in Error Codes and
Messages.
The following requests six numbers, five from the [1,69] range
and one from [1,26]. While the two sequences are multiform (they
have different lengths and ranges), the request only uses the
array format for the parameters where the values are different.
The replacement parameter is set to the simple
Boolean value false (rather than an array of Boolean
values), which means both sequences be picked without replacement,
i.e., will not contain duplicate values. This makes them suitable
for use as winning lottery numbers, for example for a US Powerball
type lottery.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegerSequences",
"params": {
"apiKey": "00000000-0000-0000-0000-000000000000",
"n": 2,
"length": [5, 1],
"min": 1,
"max": [69, 26],
"replacement": false,
"base": 10,
"userData": "Winning lottery numbers for Week 5"
},
"id": 6447
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegerSequences",
"hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
"n": 2,
"length": [5, 1],
"min": 1,
"max": [69, 26],
"replacement": false,
"base": 10,
"data": [
[63, 3, 67, 26, 38],
[8]
],
"license": {
"type": "beta",
"text": "These values are licensed for non-profit, commercial (non-gambling), and for gambling purposes with no prize value limitations.",
"infoUrl": "https://api.random.org/licenses/beta"
},
"userData": "Winning lottery numbers for Week 5",
"completionTime": "2018-01-30 17:35:40Z",
"serialNumber": 2940255
},
"signature": "j35QUCHnsnSnGt85qLom8YVobRrE91FGEuvpmeHSrIyLM3By2VaeZJZx2R0KSTcF7F2kdPCqElWDfihmdiYWbGqWGNnPwwqF0LSBszYTZZmwvKC6qwIy+ch9xrpU+T8dnSAPiD1mel2ZxznblTxB0Jf9UX8ppy9vP6v3RfZNH192mV2yirjZcExhX3JNUg9gV5tJGDjpTFnZANz28pW8S+9fTCElb+Mj9jM/PosQDzyRuRrwtX05l77tqtz65GHQ+Z7jhZPYyWX8ZIL5a9vY3qjUHlR0mtkHfExv5ljXQKbCJBc8twTHgsrgmQloM/+su1j6yc9ikKe+qaqvc597V/AEBmK2w3EFCwoFBUL6yWGM/mC/UhK7JgoBtrVWmMnqDRULvkA7fEwZWzwh4N7Q90Dkowk0YcdNiPxCPu9ukASbKABnnGZqOA8ZJldHl9ZUnWryGwWIAZaEz6ENGtTdxBaoZ8U0q8G/s60SXzqWdUS2w4nNmTiSDFs1NYjq6vuMh79scxFJnvAiffj8Fjo8FWLEiA7+g3Z8nEnYR7SZuA5cVhOOD/RLaRQsuXYc0f/p2DS5O8M8hgG+DcxBp63kS9TCtw+yWMAuZq1e2VKizap0rvzwH9GoYAORdNx18DCcsUAFJshAEXnm67B04EKkKPKZjXQH33sz6VvMSJzqUrY=",
"bitsUsed": 36,
"bitsLeft": 580938,
"requestsLeft": 199490,
"advisoryDelay": 300
},
"id": 6447
}
The method, n, length,
min, max, replacement
and base parameters are the same that appeared
in the request. The hashedApiKey allows the client
to share the full contents of the random and
signature objects with third parties without disclosing
its apiKey. The random object contains the
true random numbers (in the data array) produced. The
service advises exactly when the request was completed, and that the
values are licensed for non-profit, commercial and gambling purposes
with no prize value limitations. The object that the client passed in
the userData parameter is included unchanged in the
response. The serial number indicates that this is the 2,940,255th
request to be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
The following requests eight uniform randomizations of the [1,52]
range. The replacement parameter is set to
false, meaning the numbers will be picked without
replacement, i.e., duplicates will not occur. This makes them
suitable to shuffle decks of cards.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegerSequences",
"params": {
"apiKey": "00000000-0000-0000-0000-000000000000",
"n": 8,
"length": 52,
"min": 1,
"max": 52,
"replacement": false,
"base": 10,
"userData": {
"description": "Shuffled Cards",
"player": "joe69",
"gameStart": "2018-01-30 18:00:00Z"
}
},
"id": 28490
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegerSequences",
"hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
"n": 8,
"length": 52,
"min": 1,
"max": 52,
"replacement": false,
"base": 10,
"data": [
[28, 15, 3, 11, 10, 16, 18, 48, 4, 49, 50, 42, 6, 22, 34, 31, 45, 20, 14, 24, 29, 23, 25, 2, 8, 52, 17, 44, 32, 37, 26, 1, 43, 27, 12, 38, 46, 41, 5, 36, 33, 39, 21, 40, 13, 47, 9, 19, 7, 30, 51, 35],
[18, 26, 43, 17, 6, 7, 28, 36, 47, 51, 3, 29, 19, 49, 33, 32, 34, 1, 39, 48, 24, 9, 41, 25, 42, 10, 5, 27, 4, 11, 38, 50, 30, 23, 46, 15, 40, 20, 12, 22, 8, 13, 52, 2, 35, 14, 21, 16, 37, 31, 45, 44],
[9, 15, 14, 10, 52, 25, 39, 7, 34, 43, 50, 30, 27, 20, 49, 42, 11, 48, 6, 26, 45, 28, 47, 41, 13, 3, 17, 5, 23, 32, 44, 46, 35, 12, 40, 16, 2, 4, 33, 29, 24, 31, 18, 51, 1, 37, 36, 19, 8, 22, 21, 38],
[6, 51, 35, 12, 40, 15, 5, 23, 34, 33, 22, 27, 2, 3, 43, 21, 50, 31, 9, 37, 18, 25, 26, 46, 49, 1, 19, 39, 45, 16, 8, 29, 13, 52, 20, 14, 41, 11, 7, 44, 4, 38, 47, 48, 17, 36, 42, 28, 10, 24, 30, 32],
[44, 37, 2, 41, 11, 25, 22, 19, 36, 47, 16, 1, 21, 48, 40, 8, 5, 38, 50, 28, 46, 42, 24, 32, 4, 13, 33, 49, 18, 27, 7, 20, 10, 9, 35, 23, 6, 12, 3, 39, 30, 52, 51, 45, 14, 26, 29, 34, 31, 43, 15, 17],
[7, 36, 11, 17, 22, 28, 50, 47, 45, 31, 27, 51, 20, 33, 23, 43, 19, 25, 48, 41, 5, 30, 37, 8, 52, 2, 14, 26, 34, 44, 13, 18, 24, 6, 38, 3, 10, 29, 12, 1, 4, 32, 40, 49, 39, 15, 16, 21, 46, 42, 35, 9],
[10, 8, 17, 28, 49, 38, 45, 22, 3, 21, 12, 20, 42, 40, 14, 9, 52, 27, 25, 39, 36, 1, 23, 7, 19, 37, 46, 11, 33, 2, 26, 30, 44, 31, 24, 48, 51, 29, 18, 43, 5, 15, 6, 35, 4, 16, 13, 34, 50, 41, 47, 32],
[20, 39, 35, 41, 30, 38, 48, 31, 12, 19, 21, 50, 7, 28, 17, 45, 6, 40, 14, 51, 5, 32, 22, 25, 29, 37, 34, 13, 47, 24, 9, 43, 4, 8, 52, 46, 26, 2, 49, 44, 10, 42, 16, 18, 1, 27, 23, 3, 33, 36, 15, 11]
],
"license": {
"type": "beta",
"text": "These values are licensed for non-profit, commercial (non-gambling), and for gambling purposes with no prize value limitations.",
"infoUrl": "https://api.random.org/licenses/beta"
},
"userData": {
"description": "Shuffled Cards",
"player": "joe69",
"gameStart": "2018-01-30 18:00:00Z"
},
"completionTime": "2018-01-30 17:37:52Z",
"serialNumber": 2940257
},
"signature": "4uIV7janwXoqjj9MME/0SMDWYblVujNbPwAogiHU4FJ/HoqSeggOQm5wbrccGlJZy4XadZZlf9mUqm4EFDNL9PMttNavxihnMzVePCEJNwbw23lE6zBGQOLiywpEH99cbUf7E/e4tLlnd5kKCJTdAKeVH8v7de4RT94hw9BmjJuu2SfRZaIF7H/MIVY6y4J+vDipnLMH/Oq5DTUhPVhIq30mfOmnYlyXArJwzwiZYLrbhyEw3Q+yL0TsrTGaV6LmbcNZbLtHmMyRiVimeOpBXzUQndR74/7z+PlPf/BLWUWvZvIVaU1IOGo3XNk0hUoUjR0ZKg81fy+MfiqYzB6Y/dNnybZvADNzPtmN5K/sQ5nEE5v4UsqzeWRV7LrbmrJlQXxcd9XVGhoEa0Gn9lZAvHeREXpWZYoPBN822coED5oBVM0w96iu+xxsqzexQdLXu03izJC2/C3qyIvTLzSv3jqmlJmnA0AGYEbB+qcoo6L0yt1ntDWkjMQYuG3OnmWpojTJ8dYZMY76PwqbgtB8N4gT11rYvQb62iMFBiJ8ELSdBHhaarozXHItw79CaL8U6PEHfdlLacqWtfZMPfWxNBbmLas1TIq8CCjs7XnvWkA4HzFYgp9OISAkQFh9c4wrdwYcrsL00+NoQ+MNVyGWft8r7vxk/ArCZS3JdGErv+4=",
"bitsUsed": 2368,
"bitsLeft": 578541,
"requestsLeft": 199488,
"advisoryDelay": 240
},
"id": 28490
}
The response here is very similar to that in Example 1. The
method, n, length,
min, max, replacement and
base parameters are the same that appeared in the
request. The hashedApiKey allows the client to share
the full contents of the random and signature
objects with third parties without disclosing its apiKey.
The random object contains the true random numbers (in
the data array) produced. The service advises exactly
when the request was completed, and that the values are licensed for
non-profit, commercial and gambling purposes with no prize value
limitations. The object that the client passed in the
userData parameter is included unchanged in the
response. The serial number indicates that this is the 2,940,257th
request to be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
The following requests one random number from the [1,8] range and
three from the [1,6]. Both sequences are generated with replacement.
The numbers could be used as a 1d8+3d6 dice roll. In some fields
(min and replacement), the caller gives
an array of identical values and in another (base) a
single value that will apply for all sequences. The two approaches
are equivalent, and both are allowed by the API. The caller does not
specify a value for userData, so it will receive a
default value of null.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegerSequences",
"params": {
"apiKey": "00000000-0000-0000-0000-000000000000",
"n": 2,
"length": [1, 3],
"min": [1, 1],
"max": [8, 6],
"replacement": [true, true],
"base": 10
},
"id": 873
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegerSequences",
"hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
"n": 2,
"length": [1, 3],
"min": [1, 1],
"max": [8, 6],
"replacement": [true, true],
"base": 10,
"data": [
[2],
[5, 2, 1]
],
"license": {
"type": "beta",
"text": "These values are licensed for non-profit, commercial (non-gambling), and for gambling purposes with no prize value limitations.",
"infoUrl": "https://api.random.org/licenses/beta"
},
"userData": null,
"completionTime": "2018-01-30 17:42:14Z",
"serialNumber": 2940260
},
"signature": "lDuZdhApcURQf1KIIRVz0R2A0azTDcFsw/1H/tq4AJvcGJcjR/a7iVhJQzvLti34GVRz5G1d5cOrY/XrJKPbdS1PA+j8rxwjBy2H9UZhfcR8DRNQeIszQrlrvx+w7RId4T2aduJv5EOhc7A4y/Sr+HahFZNhM7FwxKTVhapAwqTV0qt6vjzzUe20pS+p4Y+//5F/lVQH2V49PnLJZoU+HE+uGMkOilUBWB+uvcFntFk3JwfUWpnMfNwIH9NPfrsFCo3PBGcx3hq52QXJINPoP1H4BrhwJs1eWvH2xuaHMBCPqQF9aOf3BOWUZd9rNwyE+gG3jvsdOvlqKETP3adLvS+qY81FbF77JFCaow7ESekidrrVcQDwqRpqg+by8vKjAgvO/9uuyShAExAUwIhv7dCZiob7L2MwDHsajhT6GMlFZb8oiXeh39er2AEGcn9iEWlcJkGt5KKrin5Jsal0MV+5DxRWJMOIyHLUpaEIeOuom8SkzzbNksVhj8shZ7vZRb4EgHwf/4wBxddYlCyIP5HcWn2q+j/EgHmgxqvi2O4dT++LkKK4B79TCSVq6kF/ofZ69JvZjS/AhvlfXBkmH+HvIxes2oQijTmByvaYMyWvIEE5LFa5gufCpEYfQM1oKs9QFrMM1Xi7KfazvfGZbU1UHfjwpWFT1zhWdI6kBu4=",
"bitsUsed": 11,
"bitsLeft": 578490,
"requestsLeft": 199485,
"advisoryDelay": 280
},
"id": 873
}
The method, n, length,
min, max, replacement
and base parameters are the same that appeared
in the request. The hashedApiKey allows the client
to share the full contents of the random and
signature objects with third parties without
disclosing its apiKey. The random
object contains the true random numbers (in the data
array) produced. The service advises exactly when the request
was completed, and that the values are licensed for non-profit,
commercial and gambling purposes with no prize value limitations.
The userData property is included with its default
value of null, despite not appearing in the request.
The serial number indicates that this is the 2,940,260th request
to be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits
and requests are left in the client's quota. The service advises
the client when it can issue the next request, after a short delay.
generateSignedDecimalFractions (method)
This method generates true random
decimal fractions from a uniform distribution across the [0,1)
interval with a user-defined number of
decimal
places. Your client must set the method property of
its JSON-RPC request object to generateSignedDecimalFractions.
The request must also contain an id member, which will
be returned in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeyndecimalPlaces
The following parameters are optional and can be included in
the params object of your JSON-RPC request if you
want functionality that is different from the default:
replacement (default value true)true) will cause the
numbers to be picked with replacement, i.e., the resulting
numbers may contain duplicate values (like a series of dice
rolls). If you want the numbers picked to be unique (like
raffle tickets drawn from a container), set this value to
false.
userData (default value null)
If the numbers were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property
containing an object with the following named values:
randomrandom object contains the
following properties.
methodhashedApiKeyrandom object
to a third party and allow that third party to associate the
response with a given apiKey, without requiring
the client to disclose the actual apiKey.
n, decimalPlaces, replacementparams
object. Values that are optional and did not appear in the
request will appear in the response with the default values.
The reason these are included in the response is to allow
them to be signed by RANDOM.ORG.
datalicensedata can be used.
The API key owner selects a license for each API key
created, which affects this field in the responses generated
for this API key. For example, an API key could be licensed
for non-profit use only, or for commercial gambling up to
a certain prize value per month.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response
with the value null.
completionTimeserialNumberapiKey (and, consequently, within the
corresponding hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
bitsUsedbitsLeftrequestsLeftadvisoryDelay
For a successful response, the error property is
absent.
A client that stores the results to show non-repudiation or
implements code to satisfy other auditing requirements should
store the random and signature
properties, such that they can be shared publically or with
auditors.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result property is
absent and the error property contains an error
object as described in Error Codes and
Messages.
The following requests ten random decimal fractions with eight
decimal places. The replacement parameter is absent,
but will default to true, which means the numbers
will be picked with replacement, i.e., can contain duplicate
values.
{
"jsonrpc": "2.0",
"method": "generateSignedDecimalFractions",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 10,
"decimalPlaces": 8
},
"id": 17624
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedDecimalFractions",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 10,
"decimalPlaces": 8,
"replacement": true,
"data": [
0.74744505, 0.42197001, 0.34411193, 0.0483503, 0.14961319, 0.5368158, 0.56901306, 0.60690888, 0.55509952, 0.15932251
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": null,
"completionTime": "2017-02-12 12:33:43Z",
"serialNumber": 10
},
"signature": "ltsKR+9V6/HlZLutqJmnpBzL7/r+i7gGJEs4kFfpu5xfjvmaZ4vQ4jWKB1V8LbtovojewX1DPWK39Y+BYYhvOHTZIIwYHpAo3vpe7c3+HcruNVUaXmIOZD/lrPCFO/BWTvRi7R/gp+MAicQUXfxfwrs6ZHI4KHLakiOVVNUy7S0aUMihQIAeSSEeECHeALXzpQmBoalFfn5giubBB5eSmkm5at5CNcYtLcy8sxlCgi8Y7P9bEkuao0Luw5DqOVNM2h9gYVUsN5ez2A+IA9rHLfYyaUhhAG1tEdvsv7URLBQp0N6dh6U62qzOmihO6zklBJFXVN7+y7E+ikMHXuz31Xj7FoUxgXhlAomRJAMYIvI4Eg9HEacHi6HpY/dcvdTtOVLrwYeYo4A2g2wspQ8qq6lIwMtxPK7Zjo4TSKTAvlGy3u3QE1+3D3brmIPvLu7J40134ljr8mpnzd+iqf4/sU0vRl4lHXwRuI3olxyqXfyZOUtuqWlceoccF0pG2oaxdwJsmSTEuW4L5KolhmQkJs6HVcVZHSa8WWSDlJ7dk++DLwvrzO4lIZufmS/KCLe0pKkM/fC5JYFCXTbzCZ4Z4DAO5FPLHhK7MEfwRvQkHK0NE2CpM2vhPkvAtey2eD+3kO1/0SK0QtBWWgAB1Fjgn2CRpsEzlsimqlGYZpdWeI0=",
"bitsUsed": 266,
"bitsLeft": 4995454,
"requestsLeft": 19992,
"advisoryDelay": 1190
},
"id": 17624
}
The method shows which part of the
RANDOM.ORG API was used to generate the true
random values. The hashedApiKey allows the client
to share the full contents of the random and
signature objects with third parties without
disclosing its apiKey. The n and
decimalPlaces parameters from the request are
included too. The replacement and userData
properties have been added with default values, even though
they did not appear in the request. The data
array within the result contains the true random
values produced. While eight decimal places are used, final
zeroes are not shown, making the fourth and sixth values appear
to have fewer decimal places. The license shows
that the values are licensed for general commercial use, but not
for gambling. The completionTime specifies UTC time
zone (‘Zulu time’) by the letter ‘Z’ after
the clock time. The value of the serialNumber field
indicates this was the 10th request to be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
The following requests four decimal fractions with two decimal
places. The replacement parameter is set to
false, meaning the numbers will be picked without
replacement, i.e., duplicates will not occur. The client also
specifies how it intends to use the values by passing a string
in the userData parameter.
{
"jsonrpc": "2.0",
"method": "generateSignedDecimalFractions",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 4,
"decimalPlaces": 2,
"replacement": false,
"userData": "Sample values for Experiment X."
},
"id": 32398
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedDecimalFractions",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 4,
"decimalPlaces": 2,
"replacement": false,
"data": [
0.79, 0.71, 0.65, 0.59
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": "Sample values for Experiment X.",
"completionTime": "2017-02-12 12:40:53Z",
"serialNumber": 12
},
"signature": "h3c5PKxurppejE/YDJPLmtHXDDNORNejnkhjGxDFRIk0WA5mBeeGWryL9J67hhR1kbAd7+go4s5NWKawQjeBd78t5YhxWN3E2re/PP4lG4V/6nz3sob2Xf4Lp0BOMgSrmxRQRjzlrqQe/Zbqq6vKJfzVpAEKhNdKgDy020fXk2SaYcCKwYY4Oi9OpjlazeaOZOsXIc17qjkxjDWm9Lh60uX/pqyfbhXgZRPZiv4YmW3rogO5HM+VsIaU7rn9Um62LS0KL1F1XEek6OU3DYRUjlAqd3OrSNOUSLtFMcoHOyiL6blkGiheykjKR3gnQv1kmHsI7keRDJw4PA2KRBKWnKWOAln31qjjVNn8yDC8FUY4/4zrYzKLMkAXzzaHOW9Zn9ZS+LrKTFtdfnlsdhDITKEyeUyRuSPxqsmmZGL09pM7PTkLSJv4PVCEWE7RYLGGscBZzXyfF0Cz1rMau+ex9v5iXOu3mKz/B+frMiz0gfl1BYdw0mG95wZKsVeT5VyeGwoDekzAToDMEv2JWIHIOdqm3obJcxi+0kXR/AWFsN/rcs97/SR2Vu3M1oTaOLxCsEiEbB4VL40DqqyCsnK3rrPojgcE7deOYOhJpfizfQoJDJXSejJ8LqX7dD7fm05G9c4AiAoBLwuM19bBraBAYTJYBuMyiUmUX4nyFxlw++A=",
"bitsUsed": 27,
"bitsLeft": 4995400,
"requestsLeft": 19990,
"advisoryDelay": 1460
},
"id": 32398
}
The method, n, decimalPlaces,
and replacement parameters are the same that appeared
in the request. The hashedApiKey allows the client to
share the full contents of the random and
signature objects with third parties without disclosing
its apiKey. The random object contains the
true random numbers (in the data array) produced. The
license shows that the values are licensed for general
commercial use, but not for gambling. The object that the client
passed in the userData parameter is included unchanged
in the response. The completion time is also included.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits
and requests are left in the client's quota. The service advises
the client when it can issue the next request, after a short delay.
The following requests 100 decimal fractions with 14 decimal places
picked with replacement, meaning that duplicates are allowed.
The caller uses the userData parameter to add a comment
about what the purpose of the numbers is.
{
"jsonrpc": "2.0",
"method": "generateSignedDecimalFractions",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 100,
"decimalPlaces": 14,
"replacement": true,
"userData": "Values for simulation #42"
},
"id": 4382
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedDecimalFractions",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 100,
"decimalPlaces": 14,
"replacement": true,
"data": [
0.4067510307335, 0.49498113191822, 0.96960783219835, 0.77940791846587, 0.37867866849969, 0.43640599001835, 0.81430101831017, 0.69796365463651, 0.0942566653479, 0.25085002911158, 0.83004825433361, 0.79620697134977, 0.720055648638, 0.41350446256046, 0.28231841331453, 0.23953329445949, 0.1961463107723, 0.03906840253952, 0.73616063596467, 0.92496353352522, 0.26195236044893, 0.29378308228826, 0.11832176836192, 0.9989525459118, 0.23135714044692, 0.80966955787489, 0.61670274372882, 0.36431684412347, 0.65726095223665, 0.26382156309141, 0.72046065977158, 0.33279821097059, 0.41401283668207, 0.76009322515673, 0.86241590893612, 0.88434814101742, 0.62091919729814, 0.32724013073814, 0.52582231304218, 0.83984703256043, 0.70238844695876, 0.23085296348294, 0.17342914794024, 0.55133072331219, 0.03647590678838, 0.39565921998995, 0.74001473763128, 0.37293325275437, 0.78479087118939, 0.6554376034658, 0.21180818800494, 0.45222314930199, 0.03138205026346, 0.73634438997669, 0.60848835285306, 0.48525414928505, 0.40695826110508, 0.08755699985925, 0.1327404895991, 0.45012795160046, 0.35679395898872, 0.02816896189466, 0.34692364515903, 0.71748606916851, 0.99168150164265, 0.70112591391798, 0.54362811975613, 0.86629274274412, 0.034614332813, 0.9462347774718, 0.05429400861552, 0.01842902514169, 0.71956053899195, 0.28770029742542, 0.57277901975847, 0.80525270205962, 0.187468583738, 0.55817462425694, 0.62882296718066, 0.57761266071113, 0.21314298068171, 0.40536490694956, 0.15837603138236, 0.0771418283278, 0.35466264894526, 0.60012682678243, 0.62622128957065, 0.80395923825592, 0.60537756977515, 0.9056463993078, 0.8793539662833, 0.81086626012268, 0.61590072433323, 0.53359745363757, 0.58583208622114, 0.50608772933066, 0.21082597082672, 0.85210734571782, 0.36234261780001, 0.01670513943516
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": "Values for simulation #42",
"completionTime": "2017-02-12 12:53:20Z",
"serialNumber": 13
},
"signature": "2jmGDjzKDQjWoqxVp63JJny1sdUHtpIX0kDz+0XgNltFWNgygmCqWUxBuIOl5j1c3iOmu6sQ5WvcX0gf1RVHVD8t+kPL+6/Sj2e3TUF+Htv8hT+DEH+tkJSzvRKAKoUNRBdoAVHnQnQzwSbJdxTysuwOC8AFiJ/M+XNaZIXkkewNC8UoX+pP6Rkf+NnmkpEonqHg/+K18Lceg/NwzmAdSEbPqs9Ah5tJR4TvpsLNLHFzhe0yKLonhyQVKmOMi453zyU+LhzDp+rtOJim2mmWDCj+bA+04LnKuFE5N0qHRUfQbMR9FwugHHOZQ9F/JIumoKYnkY1vHnm/YadHUcX2XaIyo8FwMv2U6FYfEvb3ti7H4vuds+R0ksU5vlDCJMMVDIaM497V1YJ1SbqzoXUQJp4ncmE/OmCXfjSIcwSNB4N81eYOmawMsBdW/pKc2bKpv9QmNqaCtnU8999+7aRTElIsspL3MrjHyaz9fJjph8fNznfAGou3ZqSO55mZhQy9wzvTPFQrQPbEu1wf7as7qteqwfwel+1MY1KxmX/+ZeHXni4W63szbEdLKN4fALgrlGde6ds0Rw9IsNphaJX4vnrhDDLf1T5/vJ8IAxAjcFt9llH1Vf1o4P1p5fMGDRz9atcsyrbq7E56nNc9osZl6FUZQdxqS/kRm9r3zWzckdo=",
"bitsUsed": 4651,
"bitsLeft": 4990749,
"requestsLeft": 19989,
"advisoryDelay": 1310
},
"id": 4382
}
The method, n, decimalPlaces
and replacement properties are the same that appeared
in the request. The hashedApiKey allows the client to
share the full contents of the random and
signature objects with third parties without disclosing
its apiKey. The random object contains the
true random numbers (in the data array) produced. The
license shows that the values are licensed for general
commercial use, but not for gambling. The object that the client passed
in the userData parameter is included unchanged in the
response. The completion time is also included.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
generateSignedGaussians (method)
This method generates true random numbers from a
Gaussian
distribution (also known as a normal distribution). The method
uses a
Box-Muller Transform to generate the Gaussian distribution from
uniformly distributed numbers. Your client must set the
method property of its JSON-RPC request object to
generateSignedGaussians. The request must also contain
an id member, which will be returned in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynmeanstandardDeviationsignificantDigits
The following parameter is optional and can be included in
the params object of your JSON-RPC request if you
want functionality that is different from the default:
userData (default value null)
If the numbers were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property
containing an object with the following named values:
randomrandom contains the following properties.
methodhashedApiKeyrandom object to a third
party and allow that third party to associate the response with
a given apiKey, without requiring the client
to disclose the actual apiKey.
n, mean, standardDeviation,
significantDigits
params
object. The reason these are included in the response is to
allow them to be signed by RANDOM.ORG.
datalicensedata can be used.
The API key owner selects a license for each API key created,
which affects this field in the responses generated for this
API key. For example, an API key could be licensed for
non-profit use only, or for commercial gambling up to a
certain prize value per month.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response
with the value null.
completionTimeserialNumberapiKey (and, consequently, within the corresponding
hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
bitsUsedbitsLeftrequestsLeftadvisoryDelay
For a successful response, the error property is
absent.
A client that stores the results to show non-repudiation or
implements code to satisfy other auditing requirements should
store the random and signature properties,
such that they can be shared publically or with auditors.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result property is
absent and the error property contains an error
object as described in Error Codes and
Messages.
The following requests four random numbers from a Gaussian distribution with mean 0.0 and standard deviation 1.0, accurate up to eight significant digits.
{
"jsonrpc": "2.0",
"method": "generateSignedGaussians",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 4,
"mean": 0,
"standardDeviation": 1,
"significantDigits": 8,
"userData": null
},
"id": 32559
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedGaussians",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 4,
"mean": 0,
"standardDeviation": 1,
"significantDigits": 8,
"data": [
1.1158169, 1.4592766, -0.13000855, -2.4014567
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": null,
"completionTime": "2017-02-12 13:08:07Z",
"serialNumber": 14
},
"signature": "ZdPJHoxP6h/fB80puc91ZyUD/JqV/iz4agCZsqUvk59DPyvS/1VW1VyBSdPKqKGEXXK1fZtGZ45elQFpXl7faxeXI29gVC9bKpQ76Ilt+/X1jGdvgO9u76fbtPpqipjentpQhMuEWYqKrSakcicwv7U9AVQNdjqIlF/CB8mixukWOek02fsykmEMQCPZPXADlF8HkI35GzjSJWox1BwvsFBUxqe0bQKPgTwv2vLgsfbq56ozR2epa4jG8f49TtHRDywsx42bKk2w9xikMVy2J0aWGBk8sTsith9LxUHQPBbhEz6luUftUz03qH5v0wzsxQAQ07RdhV/JnHyF/E0VxyrGiuqXrGNTmQdezWvGywWIq8vuijBimhaLStkSWrGa4kSjHN9Oepx+COCJAJLrFGkINegIjO47V1nIotK8+VIdl2jWY1OzMnNs3fxvsMfIhVC+LSvWAepEa5qcRGpei3FBRoCiC1d8bdTZlRGkTzknqIoa1Zd6r3b0C29HWZqcYQ9OIv3rIfdA8IqJJKuvoLeJDUDJL3mjEqMpj6RPIb/EbJ8m2inN2yCid7Z7lL3WAE8+9r4zuc/UFLmXzePm7m2zhB50HN36N502Yl3I9/YVVgIKnK45HpPWM3Eda4BoxYZKeKclFQkOLmoLymcWcFqyrGaAp8zlk2ivOESEW7A=",
"bitsUsed": 106,
"bitsLeft": 4990643,
"requestsLeft": 19988,
"advisoryDelay": 1210
},
"id": 32559
}
The method, n, mean,
standardDeviation, significantDigits
and userData parameters are the same that appeared
in the request. The hashedApiKey allows the client
to share the full contents of the random and
signature objects with third parties without disclosing
its apiKey. The data array within the
result contains the true random numbers produced.
The license shows that the values are licensed for
general commercial use, but not for gambling. The
completionTime specifies UTC time zone (‘Zulu
time’) by the letter ‘Z’ after the clock time.
The value of the serialNumber field indicates that
this was the 14th request to be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
The following requests 2,000 random numbers from a Gaussian
distribution with mean of 1,100 and standard deviation of 100,
accurate up to four decimal places. This could be used to
simulate the lifetimes of lightbulbs (measured in hours), as in
example 10.3.5 of
Handbook of Statistical Distributions with Applications.
The example includes this as a note in the userData
property.
{
"jsonrpc": "2.0",
"method": "generateSignedGaussians",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 2000,
"mean": 1100,
"standardDeviation": 100,
"significantDigits": 4,
"userData": {
"simulation": "Lightbulb Lifetimes",
"dataSetNumber": 42
}
},
"id": 6380
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedGaussians",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 2000,
"mean": 1100,
"standardDeviation": 100,
"significantDigits": 4,
"data": [
999.4, 1146, 1011, 1117, 970.1, 1115, 1209, 887.1, 1102, 1159, 1178, 1155, 1072, 1115, 991.6, 1163, 1105, 1450, 1144, 1163, 938.9, 1027, 1024, 1118, 1118, 955.9, 1086, 1083, 995.4, 1039, 1047, 1039, 1209, 994.1, 1032, 1147, 927.1, 1149, 1097, 1136, 1155, 973.5, 1139, 929, 1202, 1039, 1236, 893, 1131, 1075, 876.6, 1265, 1075, 995.2, 1103, 1180, 1072, 1179, 1217, 1177, 1131, 1163, 1295, 932.2, 1069, 1275, 946.6, 1185, 1080, 907.9, 1067, 1208, 1133, 1117, 1261, 770.4, 1116, 1254, 998.9, 1069, 1184, 1018, 1079, 1346, 1202, 1157, 987.5, 1136, 1168, 1125, 1033, 1138, 1050, 1060, 1134, 1124, 1185, 1197, 975.8, 1021, 1161, 1227, 990.9, 1022, 1161, 1133, 1038, 926.5, 1206, 1181, 1043, 1112, 1101, 1065, 1041, 1157, 1208, 1168, 950.5, 1007, 1079, 1036, 1134, 808.5, 1005, 1145, 1109, 1123, 1154, 959.4, 1068, 1205, 1044, 1152, 1198, 949.6, 1133, 1206, 1142, 1147, 1065, 1180, 946.7, 1274, 901.1, 925.7, 1197, 1139, 1120, 1110, 1074, 1260, 1266, 1223, 984.3, 997.6, 1033, 1114, 1237, 993, 934.5, 1078, 1043, 1009, 1085, 1191, 997.1, 1104, 777.7, 1130, 896.2, 1162, 1224, 1077, 1153, 1167, 1144, 1026, 1182, 964.3, 1144, 1019, 995.4, 1280, 1318, 1201, 1221, 1076, 1055, 1153, 1050, 1052, 1016, 1166, 977.5, 1184, 1026, 1071, 1107, 1089, 1052, 1084, 913.4, 1070, 1016, 1360, 1025, 1009, 1246, 1079, 1169, 1034, 1004, 1051, 1082, 1276, 960.9, 1129, 1093, 1229, 1146, 898.3, 1153, 1102, 1059, 1058, 1106, 958.4, 1220, 1234, 1209, 1136, 1278, 1179, 1008, 1128, 1242, 1089, 1048, 976.4, 1076, 1061, 1089, 1214, 950.3, 1090, 1001, 1014, 1149, 1134, 1104, 1120, 1194, 1060, 1115, 1089, 1200, 1178, 926.6, 1154, 1091, 1084, 1086, 1105, 1001, 1070, 937.5, 1091, 1064, 865.5, 1068, 1127, 1023, 1198, 1020, 969.7, 1106, 988, 1176, 1093, 1182, 1254, 1148, 1125, 1169, 1210, 1117, 1145, 1071, 1144, 1068, 985.9, 1170, 1010, 915, 1014, 1296, 994.5, 1112, 962.3, 1199, 992.9, 1080, 990.3, 1063, 1052, 1024, 1161, 1213, 1127, 1092, 1102, 992.9, 1111, 1192, 1097, 1065, 1008, 1123, 1025, 1064, 1100, 1122, 1206, 1206, 1139, 1044, 1148, 940.8, 944.3, 1051, 1194, 1281, 1154, 1254, 1131, 1008, 1066, 1092, 1266, 1015, 1242, 1167, 976.1, 1264, 1125, 1165, 1173, 957.4, 1171, 1065, 1196, 890.1, 1062, 1200, 1147, 1146, 1225, 1201, 1044, 1217, 1063, 1177, 1055, 1083, 1010, 1110, 1123, 1223, 994.6, 904.2, 1235, 916.5, 1040, 1118, 1192, 1095, 1079, 1084, 990.5, 1101, 1306, 1122, 932, 1076, 1269, 1370, 1412, 1227, 1070, 1076, 922.2, 1164, 1067, 959.1, 1007, 1201, 1357, 1111, 1396, 1271, 1195, 1228, 1123, 1051, 1123, 1161, 1087, 1131, 1038, 1201, 1203, 994.8, 992.5, 1078, 1304, 1208, 934.3, 1131, 1074, 1094, 1123, 1040, 1241, 1131, 975.6, 1208, 1223, 1103, 1319, 1023, 1088, 1224, 1098, 1068, 1059, 1020, 880.8, 1030, 1149, 1180, 1074, 1035, 990.7, 1184, 1285, 1077, 915.9, 1134, 954.8, 1005, 1121, 1148, 1144, 1088, 924.9, 1094, 889.7, 1203, 1152, 1149, 1105, 1066, 977.5, 1323, 1085, 889.7, 1163, 986.5, 1204, 1055, 1215, 1134, 956.6, 1024, 964, 1024, 1149, 1085, 1123, 1059, 1045, 966.9, 1069, 1210, 1275, 952.1, 999.6, 1137, 1135, 959.6, 1126, 1110, 1088, 972.2, 1187, 1074, 997.4, 1121, 1035, 1034, 1014, 1239, 1328, 1055, 939.2, 1004, 1084, 1101, 1175, 1184, 994.4, 1083, 1227, 988.4, 1216, 1106, 1059, 1064, 1118, 1361, 831.4, 1116, 1115, 965, 1080, 1229, 1074, 1119, 1066, 1011, 1305, 1047, 1114, 1203, 1031, 1265, 1164, 1100, 1222, 1123, 957.4, 1067, 1052, 1308, 939.7, 1050, 1063, 935.6, 1240, 1121, 1004, 1033, 1249, 1131, 1138, 1273, 1186, 1075, 1073, 1187, 1092, 1164, 1122, 1166, 959.8, 1163, 1328, 941.6, 1077, 1157, 1043, 1029, 1062, 911.2, 1165, 1294, 1072, 821.8, 1198, 1002, 1184, 1029, 938.9, 1153, 964, 1040, 1073, 1280, 1393, 1138, 1092, 1133, 1042, 1187, 942.5, 1043, 1079, 1161, 990.7, 1103, 1049, 885.1, 1012, 1055, 955.6, 1065, 1268, 1174, 1187, 1177, 1084, 1157, 1185, 1088, 1043, 1094, 1159, 1016, 1001, 1021, 1143, 993.3, 1023, 1152, 1172, 1081, 1197, 1194, 1041, 1050, 1041, 1140, 1053, 1138, 921.2, 988.2, 1270, 1012, 1015, 1177, 1074, 1340, 986.2, 1290, 1079, 1093, 1269, 1255, 1070, 1063, 1089, 1116, 1139, 1127, 1112, 1063, 1056, 1012, 1305, 1192, 1107, 1095, 1230, 990.7, 988.6, 706.9, 1144, 1283, 979.9, 1006, 970, 1135, 1119, 1221, 1030, 999.7, 1070, 1233, 1140, 1176, 909.6, 1157, 1027, 1048, 1126, 1185, 1204, 1124, 1273, 1083, 1089, 1086, 1024, 982, 1027, 1155, 1039, 882.8, 1048, 1146, 1185, 1093, 1166, 1091, 1289, 1121, 986.6, 1094, 1184, 1142, 1281, 1191, 1092, 1056, 1065, 1157, 996.1, 1165, 1051, 1154, 966.1, 1192, 1234, 1019, 1133, 1052, 1110, 896.4, 1072, 1018, 1139, 1125, 1239, 1153, 1034, 1243, 916.5, 1165, 1310, 1148, 1022, 1222, 1129, 1181, 1285, 1091, 1250, 1013, 1013, 1076, 1100, 1144, 1169, 1078, 1114, 974.3, 1029, 1089, 1095, 1077, 1151, 1010, 984.9, 1174, 1049, 1095, 990.7, 1176, 1112, 1300, 944.9, 1292, 1007, 1167, 1181, 939.7, 1229, 1086, 1086, 1118, 1102, 934.9, 1097, 1182, 998.7, 1167, 1272, 1199, 1159, 904.3, 1149, 998.3, 1013, 1036, 978, 994.9, 1089, 943.6, 1090, 992.3, 1097, 1072, 917.7, 1254, 1312, 1049, 1103, 1201, 773.3, 1107, 1029, 1186, 1170, 1182, 1100, 1075, 968.8, 917.7, 1188, 1097, 1176, 1311, 1204, 924, 1182, 1080, 1025, 1215, 1102, 1077, 1003, 1097, 1074, 1279, 1122, 1270, 1237, 1132, 1183, 1002, 1107, 1119, 916.4, 1103, 1116, 1046, 1132, 938.5, 1191, 1147, 1132, 1154, 1173, 1068, 1100, 1082, 921.3, 1038, 1060, 1038, 1089, 1256, 1070, 1010, 1233, 1005, 1204, 1233, 1109, 1102, 1100, 1108, 856.5, 1094, 1030, 886.9, 1191, 1190, 1107, 1090, 1127, 1020, 1058, 959.8, 1125, 969.8, 1168, 1205, 934.7, 1264, 1030, 1007, 1109, 1111, 1127, 1015, 1101, 1006, 966.1, 1157, 1172, 1047, 1191, 1078, 1277, 998.1, 1064, 1015, 1199, 1086, 1116, 960.9, 1075, 1286, 1086, 1101, 1085, 1042, 1104, 1351, 1153, 1064, 1106, 1125, 1268, 1075, 1021, 1203, 1089, 1140, 972.1, 1057, 1124, 1141, 1100, 1176, 999.3, 1096, 1128, 1038, 1152, 1119, 984.3, 1167, 1184, 1191, 1099, 1123, 1172, 1177, 1014, 1181, 1042, 741.2, 1102, 946.4, 1130, 1221, 1084, 1072, 869, 1218, 990.1, 1194, 1281, 1162, 1223, 1021, 1187, 1045, 946.1, 1312, 1038, 1154, 1205, 823.3, 1269, 1080, 1044, 1040, 1086, 898.2, 1065, 959.6, 1423, 1191, 1187, 1128, 1050, 1007, 952.7, 1090, 1093, 1230, 1124, 990.2, 1290, 1199, 895.8, 1195, 1226, 1129, 1148, 1096, 1068, 1062, 1169, 1046, 1107, 869.2, 1151, 950.2, 1016, 1108, 1139, 1047, 1281, 1060, 1028, 914.8, 1280, 1015, 1048, 1063, 1056, 1037, 1111, 1132, 1160, 1137, 1075, 1017, 1103, 1041, 948.9, 1203, 1181, 1071, 974.5, 1000, 1114, 1003, 1235, 1035, 938.4, 1018, 1010, 939.7, 1036, 1115, 1102, 1060, 1085, 1218, 969.8, 989.9, 1138, 989.8, 1095, 1126, 1170, 1245, 1219, 974, 1200, 1035, 1152, 1036, 1062, 1098, 1110, 1008, 1259, 1031, 1300, 1172, 1066, 1061, 1142, 1183, 1040, 1267, 1199, 1069, 1094, 1036, 895.4, 1271, 1043, 1159, 926.6, 1263, 981.1, 951.5, 1115, 1111, 1116, 1018, 1142, 1103, 1123, 1042, 1015, 1204, 1198, 1115, 1115, 1150, 1213, 1133, 913.1, 1310, 1056, 1159, 1037, 989.6, 1133, 1184, 1067, 1143, 1186, 918.8, 1032, 1150, 1120, 1180, 1231, 1054, 1008, 1139, 1104, 1001, 1139, 1260, 1036, 1055, 1095, 1094, 1243, 1044, 1088, 1033, 1260, 1193, 1149, 1026, 1012, 962.6, 1064, 1279, 1198, 1026, 1092, 1037, 1172, 1042, 989.8, 1076, 1182, 1056, 1010, 1226, 1131, 1180, 1154, 1036, 1181, 1082, 1066, 1063, 1167, 1145, 988.6, 1004, 1115, 999.2, 1066, 1010, 1193, 1127, 1095, 1056, 927.4, 1083, 1037, 1134, 1235, 1166, 934.8, 989.2, 1204, 1137, 1010, 978.9, 1039, 1324, 1104, 1065, 1006, 976.9, 1155, 1095, 1120, 1069, 1156, 1081, 1203, 1090, 1015, 1047, 1095, 1106, 1053, 1010, 1001, 1042, 1212, 1199, 991.9, 978.8, 1094, 1113, 973.2, 988.1, 1008, 1166, 1039, 1219, 1000, 1115, 1300, 1197, 1013, 1209, 1030, 1280, 1027, 986.7, 1064, 1109, 1093, 1158, 1049, 1036, 1150, 1021, 1022, 1213, 1214, 1225, 933.5, 1313, 966.4, 1172, 1213, 1105, 851.7, 1191, 1146, 1043, 1063, 1136, 1180, 1082, 1010, 1088, 1070, 1265, 1153, 1117, 1177, 1002, 1014, 1138, 1059, 1045, 1104, 983.5, 1014, 1140, 1046, 1104, 1094, 1144, 971.3, 1045, 1092, 1113, 1244, 1039, 1051, 961.8, 1212, 1131, 1125, 812.8, 1045, 1188, 1151, 1105, 1160, 1260, 930.7, 963.3, 1029, 1244, 1192, 1093, 1163, 1154, 1196, 1015, 1129, 919.6, 1346, 1244, 962.7, 931.6, 1106, 1211, 1214, 1170, 1074, 1158, 1054, 1106, 1233, 1055, 1244, 1218, 1076, 1055, 1176, 1072, 1250, 1097, 1004, 1080, 1173, 1071, 1197, 1090, 1122, 1126, 991.7, 959.8, 1085, 1022, 1122, 1252, 1096, 1128, 1097, 1085, 1155, 1158, 1300, 1186, 1033, 1175, 1119, 1031, 1238, 1048, 1125, 1289, 1036, 1238, 1090, 1142, 1020, 1061, 802.6, 1170, 994, 1079, 1017, 1197, 1092, 1084, 1184, 1120, 1219, 856.7, 1040, 1123, 1009, 1108, 1088, 1167, 974.5, 1318, 1011, 1088, 1134, 1027, 1117, 1073, 1022, 1355, 1201, 1117, 1031, 1059, 1357, 1117, 1158, 1063, 1024, 1089, 978.6, 1294, 1144, 1015, 1127, 1120, 1127, 1074, 1045, 949.5, 1044, 1090, 1153, 1017, 1154, 1164, 1082, 1084, 1070, 1190, 1063, 1161, 1079, 1133, 1232, 941, 1113, 1183, 944.3, 1113, 1215, 1317, 1052, 895.6, 903.3, 1074, 917, 1257, 937.5, 995.3, 1249, 1057, 990.3, 1225, 993.8, 1093, 1180, 1184, 957.5, 1032, 1026, 964, 915.6, 1017, 1249, 1027, 1187, 1104, 975.1, 1117, 1113, 1189, 985.4, 1039, 1101, 952.7, 1345, 973, 1045, 849.3, 1052, 1295, 1200, 971.9, 1198, 1065, 1091, 1053, 1050, 1130, 1066, 1170, 1095, 1219, 1111, 1138, 1073, 1232, 1072, 1207, 1379, 1048, 982, 1033, 1075, 1150, 1204, 960.3, 1069, 1162, 907.3, 1070, 1184, 1080, 1126, 1117, 1092, 1201, 933.7, 981.9, 1121, 934.1, 1036, 1032, 1268, 1121, 1009, 1060, 1242, 1053, 999.6, 1023, 1099, 1197, 1041, 976.4, 904.3, 1200, 959.3, 1134, 853.6, 1028, 1032, 1327, 1044, 1181, 1146, 1239, 1194, 1132, 1167, 986.1, 970.4, 1162, 1182, 1035, 1316, 1103, 1170, 973.3, 1033, 992.2, 1084, 1230, 945.4, 1259, 1005, 1172, 1342, 1172, 997.2, 1242, 982.6, 1087, 1151, 1066, 1276, 1206, 1078, 989.9, 1079, 1156, 1228, 1123, 939.2, 1090, 1037, 1006, 1088, 1076, 1037, 1031, 1211, 1184, 1019, 1075, 1158, 1113, 1009, 1147, 1100, 1233, 1101, 1276, 1096, 1070, 1121, 853.1, 932.6, 953, 1173, 1110, 1104, 979.9, 1098, 1200, 1052, 1201, 1100, 1094, 1169, 968.3, 1145, 1174, 998.6, 981.2, 1171, 1134, 1031, 1056, 1036, 1146, 1128, 933.7, 1042, 949, 993.8, 1081, 1161, 1162, 1074, 1123, 942.2, 1265, 1310, 1198, 1004, 1172, 964.1, 1017, 1205, 1151, 1224, 1174, 1339, 1114, 1182, 1115, 1062, 1107, 1138, 1125, 1045, 1080, 1023, 943.8, 1065, 957.4, 1198, 1065, 1104, 1125, 1259, 986.9, 950.9, 957.3, 1070, 1021, 1025, 1056, 998.4, 1176, 1050, 1020, 1083, 1169, 1318, 1175, 1050, 1066, 993.9, 1018, 1146, 1167, 904.4, 985.9, 1053, 1139, 1081, 1136, 947.6, 952.9, 1162, 1071, 1226, 944.1, 1101, 1157, 1026, 1215, 1238, 1105, 1152, 1083, 931.6, 891.9, 926.2, 1038, 957.3, 1172, 1153, 1009, 1109, 1290, 1074, 1185, 1122, 904.4, 1096, 1091, 1019, 1136, 1256, 1121, 1102, 970.4, 1028, 1131, 1080, 1092, 1158, 1118, 1107, 998.3, 1031, 1063, 930.5, 1278, 1086, 1033, 1176, 1186, 970.4, 1148, 984, 1355, 1143, 1039, 1003, 1255, 1234, 1334, 1010, 1145, 997, 1063, 1033, 1058, 849.2, 1062, 1126, 1144, 988.5, 1026, 1107, 1064, 1194, 933.2, 1037, 956, 877.6, 1064, 1080, 1148, 1048, 1199, 1083, 1100, 1208, 1123, 963.6, 1059, 1005, 1019, 1055, 1059, 936.2, 1108, 1199, 1019, 1098, 951.7, 1282, 1075, 1170, 1048, 1181, 1117, 1145, 1094, 981.5, 1341, 1202, 1172, 1138, 1219, 1159, 1178, 1125, 1145, 1147, 1236, 1103, 1108, 1038, 1157, 1178, 1072, 1097, 1070, 1095, 1130, 971.1, 1160, 1046, 1109, 1266, 1286, 814.1, 1120, 1107, 1136, 1191, 1135, 1162, 967.1, 1081, 1093, 1114, 1016, 1230, 1170, 1238, 909.5, 1088, 1065, 976.7, 1120, 1235, 991.5, 1055, 1105, 1184, 984.5, 1031, 1276, 1149, 1069, 993.4, 1159, 1015, 969.5, 1098, 1126, 1164, 1213, 885.9, 1067, 972.6, 1227, 1022, 954.8, 1111, 1121, 1277, 1107, 836.3, 892.8, 1080, 1124, 1200, 1053, 1078, 953.9, 1259, 967, 1179, 1133, 1093, 1201, 980.6, 904, 1144, 941.7, 1014, 1213, 1255, 1074, 1111, 981.4, 998.3, 1135, 988.3, 1116, 1005, 1037, 1041, 1121, 973.8, 1232, 1108, 1112, 1199, 1011, 1134, 944.2, 1097, 1045, 1053, 1085, 903.5, 1238, 1102, 1001, 1133, 1084, 938.4, 890.3, 1126, 1153, 991.6, 1052, 1128, 1161, 1167, 996.7, 1153, 1172, 1091, 1050, 1202, 1199, 1086, 1287, 1256, 1128, 1280, 1187, 1138, 961.1, 1214, 938.9, 1140, 1192, 1231, 1271, 1219, 1145, 1172, 1023, 1166, 1088, 1172, 1094, 1101, 948.3, 946.3, 1135, 943.4, 981.8, 1229, 1177, 1102, 1054, 1023, 1112, 1225, 1043, 1098, 1120, 1284, 1123, 1141, 1171, 1234, 1062, 1250, 1216, 1317
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": {
"simulation": "Lightbulb Lifetimes",
"dataSetNumber": 42
},
"completionTime": "2017-02-12 13:13:58Z",
"serialNumber": 15
},
"signature": "k9iU+3bz9HwByNPQ+cUoToooi32EeDN0FI284izlZYq2u2Ej6Fjn1dCbgmvqo/oCS9B3DHZrhnghwlGTBwmuGLmpITb2xXypLXevv5WzHvNcm0iDalUHDlLWwyuphPiPcW2hB4nRTHsHRm8f9oNYLqgUOP0oLYU6H1phQhqAYoZHzLrRYGpfbRUAy5YkAk0Y8LGX60h+veLw+3wpyoNlmWo9yuYGXqnG5FcmYK7c/LS+ALHCm8pWisQAK1aXZf/UaU+oi7G+ZEPoBfmtn3O1e2ftWe4OHRzb3Rf17PmE20ZsxkRWQafukmQdXfVStMZX1BForscRaTsd6Temje6e0LVGu2Gw6utLJVSnD/+ixIeQsnCeEQZsXlHCg9moKGirDBU/qjaCSJCI6biumzCFfsXh1eH+gn3hJWGCjW814iJI4Kh9hADktIX8GWIDz9PvdcGp3AbVIPpLiLnuPsAzOqf1SYqtmdex3Bl9n2kgFCepxoLU+8cb4/JvoEtsK+dzikQiNCyspKJjccSx3hYeqfANJriYOc/cuo2vNnZgWGVPPesyPpMbzGAukcXpZ3Gn7U4w1cfBGHQrR0gajWPgAfE5RT26F5mtwgxhEG7b3GqhlYMrjmAwMwQuS+mnrTFVsoKGqaJGeeeC7RvIl9ez3Vl0Alto/UDddjOS8UCzMnk=",
"bitsUsed": 26575,
"bitsLeft": 4964068,
"requestsLeft": 19987,
"advisoryDelay": 1420
},
"id": 6380
}
The method, n, min,
max, replacement, base
and userData parameters are the same that appeared
in the request. The hashedApiKey allows the client
to share the full contents of the random and
signature objects with third parties without disclosing
its apiKey. The random object contains
the true random numbers (in the data array) produced.
The license shows that the values are licensed for
general commercial use, but not for gambling. The
completionTime specifies UTC time zone (‘Zulu
time’) by the letter ‘Z’ after the clock time.
The value of the serialNumber field indicates this
was the 15th request to be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
generateSignedStrings (method)
This method generates true random strings. Your client must
set the method property of its JSON-RPC request
object to generateSignedStrings. The request must
also contain an id member, which will be returned
in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynlengthcharacters
The following parameters are optional and can be included in
the params object of your JSON-RPC request if you
want functionality that is different from the default:
replacement (default value true)true) will cause the
strings to be picked with replacement, i.e., the resulting
list of strings may contain duplicates (like a series of dice
rolls). If you want the strings to be unique (like raffle
tickets drawn from a container), set this value to
false.
userData (default value null)
If the strings were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property
containing an object with the following named values:
randomrandom object contains the
following properties.
methodhashedApiKeyrandom object
to a third party and allow that third party to associate the
response with a given apiKey, without requiring
the client to disclose the actual apiKey.
n, length, characters,
replacement
params
object. Values that are optional and did not appear in the
request will appear in the response with the default values.
The reason these are included in the response is to allow them
to be signed by RANDOM.ORG.
datalicensedata can be used.
The API key owner selects a license for each API key created,
which affects this field in the responses generated for this
API key. For example, an API key could be licensed for
non-profit use only, or for commercial gambling up to a
certain prize value per month.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response
with the value null.
completionTimeserialNumberapiKey (and, consequently, within the corresponding
hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
bitsUsedbitsLeftrequestsLeftadvisoryDelay
For a successful response, the error property is
absent.
A client that stores the results to show non-repudiation or
implements code to satisfy other auditing requirements should
store the random and signature properties,
such that they can be shared publically or with auditors.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result property is
absent and the error property contains an error
object as described in Error Codes and
Messages.
The following requests eight strings of ten characters in
length. Only lowercase characters from the
English
alphabet are allowed. The replacement parameter
is set to true, which means the response will be picked
with replacement, i.e., can contain duplicate strings.
{
"jsonrpc": "2.0",
"method": "generateSignedStrings",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 8,
"length": 10,
"characters": "abcdefghijklmnopqrstuvwxyz",
"replacement": true,
"userData": null
},
"id": 5750
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedStrings",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 8,
"length": 10,
"characters": "abcdefghijklmnopqrstuvwxyz",
"replacement": true,
"data": [
"dmrfwmcclb", "fdztgetgzf", "mbfjfgvhvp", "qfllbtnwlh", "wcepppjgkl", "bdoismmnky", "lyxxbfasgm", "swmsyolhar"
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": null,
"completionTime": "2017-02-12 13:41:22Z",
"serialNumber": 16
},
"signature": "uxNedFTWcAhFyGzrPFFEGGa81QKaepcemBFSfcLczUXXUWGgdjH6P/xE+1kR7jLIt/VLw/xOu/g1vPHyawtnvkPBle6HmQCnJ+nPRjNLUyEpAcZKiOCpvMRtsiUV9IBAwSefWgqaA+IdE457IwSG+LHXAn//0tiISn7hFdSF51cSsbvbM8aLH12vXc9AUuaqGlp6KpTgyfQAX1IciHrPiowdgmJ5hqJvXGj40h1C/NtHPazx6tvEE3ZHHgRubUUlAFJiP3hYcOZq1f+hdyk5d8pHKRFJsZee8aqiszidLPIeWGP4ce+8/g9NSAVUW3uqyxhSfnWM/CIo6ajR+VmzvjTdQO9ThcmkwXIgFauKaOkXmHi/kAzP9X2bLrxu3fIORtno/AO0Asu0mvC8QEcXk2iUWNqfU8FD0DcYeK44qpzKz+Rd1NSyGYVcU7katKSXZghEGQexXd0LHq5IQQeyUIJkA515l+sppebQpScRiUip2AmM2EJTxVuXDRL857R1zyorHZb5GHAUXb5jYUvRrxhavC73G8ppKv7z3aVSVZJ0fqam7zKQyQaWY4wrTG4HjJuHX0Elvtxp49HB4dkHs9nPGw+ETJRiNPZm9Fguf/z4RWuCAuvdarPSINK2N4Fmv2ww5tKWj/veFmHc52oRHFq/cv+90hpPFDaIc6beJ+Y=",
"bitsUsed": 376,
"bitsLeft": 4963692,
"requestsLeft": 19986,
"advisoryDelay": 1100
},
"id": 5750
}
The method shows which part of the
RANDOM.ORG API was used to generate the
true random strings. The hashedApiKey allows the
client to share the full contents of the random and
signature objects with third parties without disclosing
its apiKey. The n, length,
characters, replacement and
userData parameters from the request are included
too. The data array within the result
contains the true random strings produced. The license
shows that the values are licensed for general commercial use, but
not for gambling. The completionTime specifies UTC
time zone (‘Zulu time’) by the letter ‘Z’
after the clock time. The value of serialNumber shows
indicates that this was the 16th request to be completed with this
API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
The following requests ten strings of length eight. Allowable
characters are all letters from the English alphabet (uppercase
and lowercase letters are treated as separate characters) as well
as decimal digits and a few special characters. The
replacement parameter is set to false,
meaning that strings will be generated without replacement, such
that there will be no duplicates amongst them.
{
"jsonrpc": "2.0",
"method": "generateSignedStrings",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 10,
"length": 8,
"characters": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$%&*",
"replacement": false,
"userData": null
},
"id": 22888
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedStrings",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 10,
"length": 8,
"characters": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$%&*",
"replacement": false,
"data": [
"RgPsSy34", "&Vknm!on", "L2wr36U2", "wuS839Ja", "cNWFW0xd", "OV0vsV*s", "Uq25R68s", "%tGC%TQa", "jhvG!RON", "7Qe2oyvE"
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": null,
"completionTime": "2017-02-12 13:45:31Z",
"serialNumber": 17
},
"signature": "2g5O/kbSxA7dbYd5NrGOoZUyk6DFt0hiAzb5Zrp8bFxefB8vZiz2XuhjLlQGrjIsnj1fewpzlxTiPeKPUPteaEOxz6Bin4uebhpJP51fNG8VAMoOAvq4HfwziCwmxiZf1Sp7D68bOos3p71ZuCDhKTW338etYKHZhv6RDv/qjwAifRsU+vMZyCtjMulSXCN2s2LLzHweBBqLRJ1zflMS2XaXh0ZPeA2lcWqU0Nf/yqsneeTd3Wqmmp8xm6c5qa3AkifW7r0FxFC8nwla+V24AwCSnvzF0i4ZjTxXjI3zxRDxX3ce7KyNEU8JzFwUeb51g5AZ5c5ntB9srlnaccb8upqQtgDlQnzEaPOC1SGGjnp1oZPdflvJR6F0SE9jALjgdTBiffGNCSWpwb2RE69p659uDIlxfJEbfdFbHM8+ur1gqicxwIH6FibQH6yb6gvNiuGIT9y865AeLZsiElbvdCR6qjiWJ21ahFpYzZqCCqtBaDDSXR892zlsNuEOVppycxuplD5wJZfXhyj3nN+6DdaiMSIDg53lr3TCpMSHM526dUZ0WdXF/j6KiTdkp7yyj4soywwkIR2VNneJfu3OeUA5y2VBVoMAtLLxYad+gmOpOGOHAmUoDF9mTBKTOu1ncgXxbLAiULmwE6Y+BfjV536gPp0NfooPEyVg99WT/lw=",
"bitsUsed": 487,
"bitsLeft": 4963205,
"requestsLeft": 19985,
"advisoryDelay": 1210
},
"id": 22888
}
The method, n, length,
characters, replacement and
userData parameters are the same that appeared in
the request. The hashedApiKey allows the client to
share the full contents of the random and
signature objects with third parties without
disclosing its apiKey. The random
object contains the true random strings (in the data
array) produced. The license shows that the values
are licensed for general commercial use, but not for gambling.
The completionTime specifies UTC time zone (‘Zulu
time’) by the letter ‘Z’ after the clock time.
The value of the serialNumber field indicates this
was the 17th request to be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
The following requests sixteen strings of length four. All
characters from the
Danish and Norwegian alphabet are allowed. The
replacement parameter is absent, which means the
service will use the default value of true such
that the strings will be picked with replacement, i.e., duplicates
are allowed.
{
"jsonrpc": "2.0",
"method": "generateSignedStrings",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 16,
"length": 4,
"characters": "abcdefghijklmnopqrstuvwxyzæøåABCDEFGHIJKLMNOPQRSTUVWXYZÆØÅ",
"userData": null
},
"id": 21936
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedStrings",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 16,
"length": 4,
"characters": "abcdefghijklmnopqrstuvwxyzæøåABCDEFGHIJKLMNOPQRSTUVWXYZÆØÅ",
"replacement": true,
"data": [
"sLSø", "KUGC", "Æfgæ", "HævY", "CmqI", "CPcF", "RqØG", "Zset", "dvOo", "ZØUJ", "PZqH", "jaAT", "xZCz", "øaUU", "LhrF", "zbæE"
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": null,
"completionTime": "2017-02-12 13:50:21Z",
"serialNumber": 18
},
"signature": "rD1YBjD+yIWkjlwi9IFHbAf/9sxW/o9s+8aFiG13mNhD9OT7wgocNQlT+TwNwtC8IwSc+WGj3ZBlBHeRzI57wjBySGk8MpOx2fhDCOysRzK6e+bc75WJaY0VxpfbHFkaySKNpPTA1xVYJxHM8GRc4T0g3Vv7dqaF5No072Pe1geYy47usBRz2VII0FdxMCRf5gM02mDWHiWM81XRPJEC39LHesYsH3EzfBFOLDGiNf9H5EVy3cCcmHy37LvuDJ9fz4SNFd/ziXUgA+fXe4BY1/mAf53KTvWFHasq/juMARvA0EGKQ+k8Y57ED9bSE5B/ImsAorKcrjCZ5M7i5JaD7QASRVL8JwyeRlI8EQHpN7e6Znn2L5Cop9A+Y5oor8/oaB9+diKffP3OtYprmwO2vKEcsaYcXfGY4MQBTJOAFtq0NewvPuiNO6PrgBHYvMCX0PEQV/yu7oWMlnkiflWFhUp0nnMDa1KAmveQNV30Hk1YxTU8X99G07mf6aDu/GHKY6qJbL+jUNk6jAQ7OwMCbBe3ybUlWXQixIDze0MlNdWjMsUX4bFW9JZgIeUMmfnU7x4BvXXjkML1Og5ehC2xZX+h7By8xjlfFYiU3inLdlU9AiUKURpDVpc+B+nZG/C3Ze8FViT2/BiVz/AqgCZbji44ubiYx/apwe6dlbRVwg8=",
"bitsUsed": 375,
"bitsLeft": 4962830,
"requestsLeft": 19984,
"advisoryDelay": 1270
},
"id": 21936
}
The method, n, length,
characters and userData parameters are
the same that appeared in the request. The replacement
parameter was not specified in the request and has therefore been
added with the default value of true. The
hashedApiKey allows the client to share the full
contents of the random and signature
objects with third parties without disclosing its apiKey.
The random object contains the random data generated
by the server. The license shows that the values are
licensed for general commercial use, but not for gambling. The
completionTime specifies UTC time zone (‘Zulu
time’) by the letter ‘Z’ after the clock time.
The value of the serialNumber field indicates this
was the 18th request to be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
generateSignedUUIDs (method)
This method generates version 4 true random
Universally Unique IDentifiers (UUIDs) in accordance with
section 4.4 of RFC 4122.
Your client must set the method property of its
JSON-RPC request object to generateSignedUUIDs. The
request must also contain an id member, which will be
returned in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeyn
The following parameter is optional and can be included in
the params object of your JSON-RPC request if you
want functionality that is different from the default:
userData (default value null)
If the UUIDs were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property
containing an object with the following named values:
randomrandom object contains the
following properties.
methodhashedApiKeyrandom object to a third
party and allow that third party to associate the response with
a given apiKey, without requiring the client
to disclose the actual apiKey.
nparams
object. The reason it is included in the response is to allow
it to be signed by RANDOM.ORG.
datalicensedata can be used.
The API key owner selects a license for each API key created,
which affects this field in the responses generated for this
API key. For example, an API key could be licensed for
non-profit use only, or for commercial gambling up to a
certain prize value per month.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response
with the value null.
completionTimeserialNumberapiKey (and, consequently, within the corresponding
hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
bitsUsedbitsLeftrequestsLeftadvisoryDelay
For a successful response, the error property is
absent.
A client that stores the results to show non-repudiation or
implements code to satisfy other auditing requirements should
store the random and signature properties,
such that they can be shared publically or with auditors.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result property is
absent and the error property contains an error
object as described in Error Codes and
Messages.
The following requests four UUIDs. The client does not include
the optional userData parameter.
{
"jsonrpc": "2.0",
"method": "generateSignedUUIDs",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 4
},
"id": 17230
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedUUIDs",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 4,
"data": [
"8a5e74a0-8db5-4fa8-871d-79646ba0a8c0", "daf218f5-e6cf-452d-8581-ca24a826f12c", "9e951f45-f67a-4788-873e-9d18a8de4cc1", "b95136e2-a59f-4e16-a029-bf46418691be"
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": null,
"completionTime": "2017-02-12 14:08:43Z",
"serialNumber": 19
},
"signature": "cG54OCqbxmOUN0Qk2ajplZDj/9A3ms4sobt6qGHSS1/Yy4XZ0O/1Axkd/WwkxFpE+z/qaY7WBsrdbOkN3sceKNwvd63AR8rbjkGx7zxTRAyP3jaCHQUyL1qOM8E3tx//OOi/o4Y7qSQXD4QH5jPDCR+PpjBFU6lD+KUI/6RX9v7p2cV5LAtGYV35rR83Zlid6KBxJhoT189y3kbD2b63S/RuS3siHZZPa5ASm6JTpiNPkOvTGBXf/k++d8Sx6xieFId2ydGpSkG0EKFR/2rzKEw8JrjmweXWJ4kPgdemei4g0tNNTaca90Vt+Tr8XkMNtTdM4lXXP/P4VZnlacy/sNLo2FsMLN+2YW29sKaWAp1lPpJgLYd72R1NleZ++sN2HNALCBj3vxAeFplfydyReuVv3rWkpRdxbCDZ0jl6VG6eyzAtgZ+AYStq/Hhn9t/0Q9qvfdhyfQGh4nAUCCVdzJp6BA7AJS3NDyCyGyAC6ZCCr3DGGvJDdNhIkTcVJY2ikbhtlXv6TfjQh3qhElqKRgJVJUzvFqSvoIHc1I1iY+YsvuXhD4VzmmRjR3nELt9wXi8fSKLlH8VkITmirJUM6vhfLrxBAgrgNC7QQT62v6Ov5Jzn+EYQ6ncoIsU3JIC1UFX/uwfU+3iEouY3O8OnjDWABwOOdWZecB5e+KkMirc=",
"bitsUsed": 488,
"bitsLeft": 4962342,
"requestsLeft": 19983,
"advisoryDelay": 1140
},
"id": 17230
}
The method shows which part of the
RANDOM.ORG API was used to generate the
true random values. The hashedApiKey allows the
client to share the full contents of the random and
signature objects with third parties without disclosing
its apiKey. The n parameter from the
request are included too. The userData was not
specified in the request and has therefore been added with the
default value of null, even though they did not appear
in the request. The data array within the result
contains the true random values produced. The license
shows that the values are licensed for general commercial use, but
not for gambling. The completionTime specifies UTC time
zone (‘Zulu time’) by the letter ‘Z’ after
the clock time. The service advises that this is the 19th request to
be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
generateSignedBlobs (method)
This method generates
Binary
Large OBjects (BLOBs) containing true random data. Your
client must set the method property of its JSON-RPC
request object to generateSignedBlobs. The request
must also contain an id member, which will be returned
in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynsizeThe total size of all BLOBs requested must not exceed 1,048,576 bits (128 KiB).
The following parameters are optional and can be included in
the params object of your JSON-RPC request if you
want functionality that is different from the default:
format (default value base64)base64 and hex.
userData (default value null)
If the BLOBs were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property
containing an object with the following named values:
randomrandom object contains the
following properties.
methodhashedApiKeyrandom object to a third
party and allow that third party to associate the response with
a given apiKey, without requiring the client to
disclose the actual apiKey.
n, size, formatparams
object. Values that are optional and did not appear in the
request will appear in the response with the default values.
The reason these are included in the response is to allow them
to be signed by RANDOM.ORG.
dataformat
specified in the request.
licensedata can be used. The API key
owner selects a license for each API key created, which affects
this field in the responses generated for this API key. For
example, an API key could be licensed for non-profit use only,
or for commercial gambling up to a certain prize value per month.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response
with the value null.
completionTimeserialNumberapiKey (and, consequently, within the corresponding
hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
bitsUsedbitsLeftrequestsLeftadvisoryDelay
For a successful response, the error property is
absent.
A client that stores the results to show non-repudiation or
implements code to satisfy other auditing requirements should
store the random and signature properties,
such that they can be shared publically or with auditors.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result property is
absent and the error property contains an error
object as described in Error Codes and
Messages.
The following requests a single BLOB containing 1,024 true random bits (128 bytes), for example to seed a pseudo-random number generator.
{
"jsonrpc": "2.0",
"method": "generateSignedBlobs",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 1,
"size": 1024
},
"id": 6585
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedBlobs",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 1,
"size": 1024,
"format": "base64",
"data": [
"hVP+dJrpTxyHTtEfKGGOFPd5a7Bjc0873oWAFFPLZjSEAObMEoBe/M1z/lJWH7AFkJCeBEtqcd9H3ERlEyQ4Q5cFtateCgVQJ0lk7gBp7xpHtrl5fQ03st8gZPPo64JY2JYIpYSTCGAN0FK3tLSLjfHDilSq3E22GYkQIQUZzWY="
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": null,
"completionTime": "2017-02-12 17:43:43Z",
"serialNumber": 20
},
"signature": "SwpyF0bd7ue4iXrFpj/xAGIz0/cd9ginzjfBXfl4gsFPKXgxkkItgby9mafz6B1DK5UL3jexfrMTJxhsq3BV3b7W/PG5DUicIoCYFRNAHgfoVZ94ddDefIkQjPC8+tOXqVDNBKeXBFFz+A+QF3SAL1OcEXooMlSuiZaNKI7R8NS/AhxWQwPOv8/oeWQXkoyejZWmCrMNX84hYgNUi6Ri/WHs8r0CZAm9fhlgoREX8kSC9wmyFm+H0e+z5C9ZHzmO3OHGHP4nzLF1NdOL3Z5xWls1RLmwqlmpF2KpFsEs9PLqfx6AQymyR3kxNFhLSAoVkuLzHQb3nX9ncHPesKmxIajmID6OsUtt5LC9osfPxrZT+iQVX3NN93pcE3ZNQ4GzOMv2OVk72M7QbmeZT8Ra4VJOmMJVvCbvWZcmpXgvFb795NBExQlnmFCJN+B/BkeasdwL+1hJiFoi0pWgU7odnnp9MNGRtknoYOut337EqF3MTH+aZ0vlb6fXiJ4jNHwcFkCODjnRf9PXFrBMswcV6tU5EdnfJQ4OMFhk3wXE2pqDAkwBo7R6C38EVvKz39AO7rP7QIN54OzUl/x2eHLivxgszBBubA1RUgtDFhqLRMawnpfYLgb5+E9nUCBf0nwOqz1OJSo0X5TNptQy6pOElE8rSDhZjTxjxq3ldKOyCkk=",
"bitsUsed": 1024,
"bitsLeft": 4961318,
"requestsLeft": 19982,
"advisoryDelay": 1120
},
"id": 6585
}
The method shows which part of the
RANDOM.ORG API was used to generate the true
random BLOB. The hashedApiKey allows the client to
share the full contents of the random and
signature objects with third parties without disclosing
its apiKey. The n parameter from the
request is included too. The format and userData
parameters were not specified in the request, so they have been added
with default values. The data array within the
result contains the random BLOB produced. Since no
value was specified for the format parameter, the BLOB
is encoded with the default base64-encoding. The
completionTime specifies UTC time zone (‘Zulu
time’) by the letter ‘Z’ after the clock time.
The serialNumber indicates that this is the 20th request
to be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. Through the other
fields in the result, RANDOM.ORG also advises how many true random bits were used to satisfy the
request and how many bits and requests are left in the client's
quota. The service advises the client when it can issue the next
request, after a short delay.
The following requests four BLOBs, each containing 6,144 true random bits (768 bytes) encoded as hex strings.
{
"jsonrpc": "2.0",
"method": "generateSignedBlobs",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"n": 4,
"size": 6144,
"format": "hex",
"userData": null
},
"id": 5443
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedBlobs",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 4,
"size": 6144,
"format": "hex",
"data": [
"2767b57f38f77b753b6e686b45bcdb5ba7a69821e5249fb11b8ba95f6465bfd7231c48a49e18810e9db4ed42bbb3ba1efa616184774f64bcb1b2d5c29babeef361a243c9672279dce7a79f30764b2e12276aaf6731a97fc1ebe8a461831680e3ce0254aca6a282b57695f4ee988032e8f805fa1adfefcbf3a7c5c825ee1ce7ee16947d436937d165c36deb324c83b010a4e0c1f3cc60f52feac7b3419bcb6905022b88e22a31d2649f057654ab4cbbdf04d1ac0865f37f53d0d30cce7607593654974b659d7db0bfc8b3136aba4b9090ec71782506b57cd43f95fb33e3d97b2d47f126a7c4dcfb090bb0e68137553abbe7cd863183ffe9c306549ce86173901382c49c7b03c0d57f537c5ad81ac7d039a3eb88d6c68326ac7e68a8d3cfdf9c8247a2629fb147f8f5d6eeedb019b6c2254dbc45821c9257b204c52b64173feb9c6ed900d2a019e95a576caaf113f9ea8b621b8dc7371be3b938d42df816b665462ab6f1085bd7f85ee6d7bffc6f28da2dce39d8cbe116e44cee62ae1c69df03e9a2cd56528fa42ac7961505353d92d272e0f81365c62d92c2e657aeef8869fe66c833a39ae14a6b08bc99d0eabe501bbb73ae2afb884fe7f12cc71a6a29baf18cc67b8cc125b6bbb3216923b96bb055e862b4b21ff4eb990938f0245a2b8f86ffb2370f3ae5fc223fd7264adaf98df236d031938d2d81d6f9496bdc293ebb9da86cbcd1227b431d85dc9c7c26649ca81871a92ea2b653170e0111f93dd5750f41708b5b333473bf10f520ed9fb9cdb77207ef0c718ca2f8598cfc062a7d351b656b8c139597f4833c6f8c5b9985232562ae2f85312ec08803d983ab4848db2716b3f836a13c01fd1e0d554f7ebc52240c1038a6d7510270561a471bc7565b476e36aab33f566510ce6182a6e30d4caa6c3894b2dbe4b71b55687cc7c9e35f675a5bcbcc9db79648d2289d95053a4c04b6d8c4025492a6493e8eff036aef2b59b965e8e32b4b3ee3c5b4854d03efa5bf13b67f9d5639373c24b9bdf387fbad66aa059cd2ad2675a74a6ce9b1938e370169f50ab01a5a5d4bf5448f5843788f861e",
"a71d6f47fb4ce17c40bc791ca1954ce4dc96f64df4839167b98f588c1e93aceb622bf55902efe76de3f1ee3f168bf6f4851223fedd7039ebd6c8e0887fe2bf1e8b78b1f81f920621b33fb7bd949cc2a8379fa90f2122355a97fac8bf1f134ac7604f58a146117c97675b3e5346f4d9e83118298566680bd3e137d07530a59a35981733cdbbac6cdd4b706bdb02e1da58d1ee1226d821bbf13adbec16a06de595a61e676feb52abb0e591ef0790357bd969aa2d6348c19925c1a4057bb08d3b061123769ed8534dc1b67e4d7e516856f248df6b3bc254332db843b8574784e5828e8b9ef5247376dd64c58675e777e8dd87a4211552d5fdc553d4302890c7c0e20a3d6fc5cdca73a6780693a94b42cf0f45b85caccc6c54edf7c57c1b3e88f41c49d34f4d75cc6458b8ba29056992ba6323c0d54ba53988877e2948facf517bafebb33292d65a236d69401e1b8276f6951763a4cddc72305c5829fe76daf230d456fe0ba027a5783b7f8d0ac714d57f09806ed4b02cea4ed48d5030d55004867368901b048c3b763c48aeb424649834ce848183e5ebda90a2a5943cb1ecb8aa89ee656c3727273e3f1ced617c1c7d2006b0ce4054cf7fb6ddf9016bd61b537f267b7da213d001dfc316be1aecd3c903c4e87056b7864a63d1cea722f64c5cc45b9fa55e23475cbc75420cd680345bcae56d8c54d791dd61c48ea709cd65c5526ad19b290689c0b92cf7330a97a07a76f05f7b201ee84423036ec7853d20d21d4b6655d15f6cbd1f2634c87ae3a765fbc0004f55a09cbc47871d3de30b9c0ca5589c6d1b50037e02dac0ec04c2dc6952bea55374e87f90d91185d87536a72985760baf4505c4fad32ba498730c1f6f70db00ea60f89fdc9c012d261221349805b88ef1e89ecf11a975d0893e83fa96d7c79d3cbd94ba5df625eba703d234760ddc0cfcd8edfc3f0adc75eb10cbdba583a5490394614c29bd7e59bc435962b121a4765004b18c76f691c6f50807f116b708e3578254d069e20660400eb3bc29c975f4d3fe59972ed7c99e48dbcc775fe3617d9d936b7e3109d47207d220aab03c8d",
"425d24ff735eda2e1723b4b3f6efb4b6bd0bcd645e34b42fe977e0aa1dd64832b76acb3aed54b4105ba81817766c812f40f550d49a23a793d3bb60b5587bdba6e58f2c7693a884d1d901168f5f1565be1524d0a46afddf70997fa3fa14139b50a224aeee9c71357d7a1abaddbf1b9edfaba1b4f42eba034b6b7c0c841d757eed36dc589843355a999b8ad3d06ff9c42dff0c673f5675282290d074bdc7636fdbc4fd72933bdfefd107f3fe9bc78011620beeafe349f16d33a113aa2f21ac4759452638dceaa23728994ffe1ceaa99c95e495deebc69035ab18daaeba6153efeb64be10f5c9695a667d86ee88412c97e0aa43dd5dfd4a5167f5c3a0b801b99ca6268ee9cb2bce1ca55584d121551cf4e052abeb947fa46ba92209834dd88272797fdc670800b3649e84fe5bf9c0a5acae0a8e9ca6539844bc73288e6541e4fcf0c867db4bfbe6814c64317f6d47a9828768aa67ac605a9d51dceccce5dc081972196e6e8d2cd5dafca65efc3cc40f5d84773ecd9601b236e8e42e1a3199ae511e8cd5d52088af8f4bc2806717125f679f119bf6e9a0fe99bdc5659c9081b90601df7795126a17b070c3287370bdfa5744c8fe75eea3595b4efe17e1e1a9c8bbf9dc519660e972cfa3964214405bb7261a047abe5034a9017ed742ad7481875f66076f9c454e86ba432884918447b27ef592f40c92b8bfc69e1af81f37400ee4807282cd614fd86b915fc131d88ec12534940c329db6234af894f45f2f1b169899cc03f06a741ad85d8674804afff260c1ce04b526b232d877874bd9153c57c52a7892aef1a523e5edeed8d95c4abc4721148d6496dc5bdb6da3091dff1de46be653be12ef118f3aec43d6153ba06184b1101e1739820ef0db754d66df8fd941f2bd5b079272acb4f923a84ddd9c480d3290143bfa858609a905d3ca908b910e1233915be1ac9bd1abfef5f88ae2194a588c29a9c570b5dd1ea559a53f3dc7cefa77d871943bdb74f1b480c01c6e74ca388e94a200a9b1282ed5f678993dd3206d52c3b12d19d7cbbf129f978d6d2a841b40ff032ebd4807c5142d1a9882e63ebd",
"10187f1610db255c73504c92cb498f3abf2dd4192e3e77b3dcaf5fc6527e5814675296ddf818280cb88c1714f8d8a7e8a7c15537a766e11cf6ca5718921b771ab8aa6db075e368fdb98d5615ee08ea0b8e42950efa346792ac2b249ced6af265465045f0170c33c1ca1f707d1092abcc95cd479139f747cceddcb6f6eca59af3378692549a90bf4464fff6ed622b610974e4e105ddc4c51b7520dd76bc1f7a46ffdefaf0030c883e2e6c3263a88d9e81996795d17b7b3ad78e83e2d8f668f54bce50145e5d26c19738fae6a089d9814785ba190cca401f832ed3f7fe48bb953712a7a27534f53b76acf203804516e3cf5f4620c780b6d213b0f873714598a3983a75982e673b6eea255d3f2e097caf82fa8d97fd22bda9ea2eeff6fb957245f1e2498736e3d7b7701700fce2fc3a3f7894cc2d45ebaede7d2435df9cb8ca2b9b5d76e1b46488b2d50fe2180ab60869e661f9b4c758a1570ab12afdd23d4f17d4722437f822b91be9c399a15130cb2465f8241a2d88f32fbc9ee80617601fa27f4d5d48fb3271f3ee76efa98d5a9cde5c7ff64d3fbf70129775c5a77b86057f09ae288677bb019eef4c7a8299e492dda73e9b8b07a892e73a52c2d41ee5d77a116ace4441977a4c088c34dc411bbb1efd07ab0cb27a6bb5f3d368fb560b48174f21ca1a1fc29c00683caf73ef4551f45f4475b41ed349e7501901c67e26deb3c17c2f7a469bcb035e062ea423b9574ae5a21e3984bb16368ca56f2f050591bd7aa362a1d9c2e1e33d6b83b386f403e740cba463b2e7386441abf7a64eb7a97e85e35b2c4f267ec393855b53aa33e5df846b99e0c915524d6fcb02106ff8664134f3119079a8a0a5cce163696598ce1e8cd849a67505ead5d8eba8276d7f3964d2f220356c8c851c5b0213d78006815e1c417774e19f061bb4a63878975152b10c238bdc094abe3158d516ae4d1c79854c0e9397f1910202e283fa1ed09e0603a4c58d1ce7efd5f23cbedc3e9eba284034a4fadf11710aac4eb3bf6b576840dc34fc1d5ab29426979a56d502ef1aa56c5598d727f08aaca4030ca379188642dbb8"
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": null,
"completionTime": "2017-02-12 17:48:45Z",
"serialNumber": 21
},
"signature": "RAckRhXH5OB9qjOXAYMXDx4m+YcmVeOE9Uf2/5pBiInV/56q5aLbV+x0WAANdmpiY/MtyUOiMSGojrx9albwaTqzl6NmDKrGMluJBAa5Z0IzsYaAvR/mG89Ob2Rtx79qE7B8vqiE71jZEAhno3equk6U1aN9+tZ1VXDdhWO/i8SQQVLDpPrV0O1g588KnyKwk96y7juvlTip/GQsS2KNOaHiPQ6qRAUr0AQn8VZmyPC5zIzdGY+hHlrMKvasDQRXlHV0EXG62NNtdoK6vQ2MkOK5CmGQPERQrkd8YbT5PiCBLSYjVKqH3U2qhrNUHELsUJ90G40NIhjYDU4LwIhcbCDJkn23Cl79BLMOyLi03Ae37rsL4FVqBJM0/AHaCVoBWtfgev/Tz8RKWgS5cT//xTeh73mNBUgtkXWZUnlT11wxw/DG/hODChnZGZ5AYO30hxY/hfGlIKkX9w8vkz9SkK//65r8eFrQECcpe9Uaa8cdpC4E0a9WAkY1aXmIo1D70h2GD9Xf/RyoGgK2aJYu1Twat+KH6BYDE4w1u6WmbcXZjWNOOHyumkJrUGCUakJ7O5Ewd0lhHz8ERpu0unNmRZ+LaZrU55xM6RNbHUXT5ilu1stz9QZGlPXvPyYegDb2CZpgcH5M3G2TCZrhXNYjr75PqVtMqR6QyoeuksVdUCk=",
"bitsUsed": 24576,
"bitsLeft": 4936742,
"requestsLeft": 19981,
"advisoryDelay": 1390
},
"id": 5443
}
The method, n, format and
userData parameters are the same that appeared in the
request. The hashedApiKey allows the client to share
the full contents of the random and signature
objects with third parties without disclosing its apiKey.
The data array within the result contains
the random BLOBs produced, formatted as hex strings. The
license shows that the values are licensed for general
commercial use, but not for gambling. The serial number indicates that
this is the 21st request to be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
getUsage (method)
This method returns information related to the usage of a given
API key. Your client must set the method property of
its JSON-RPC request object to getUsage. The request
must also contain an id member, which will be
returned in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeyThis method has no optional parameters.
If the request succeeded, RANDOM.ORG returns
a JSON-RPC response with the result property containing
an object with the following named values:
statusstopped or running. An API key
must be running for it to be able to serve
requests.
creationTimebitsLeftrequestsLefttotalBitstotalRequests
For a successful response, the error property is
absent.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result property is
absent and the error property contains an error
object as described in Error Codes and
Messages.
The following requests usage information for an API key that exists and is running.
{
"jsonrpc": "2.0",
"method": "getUsage",
"params": {
"apiKey": "00000000-0000-0000-0000-000000000000"
},
"id": 15998
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"status": "running",
"creationTime": "2013-02-01 17:53:40Z",
"bitsLeft": 998532,
"requestsLeft": 199996,
"totalBits": 1646421,
"totalRequests": 65036
},
"id": 15998
}
RANDOM.ORG informs that the API key in question is running and advises how many bits (998,532) and requests (199,996) are left in its quota. The response also contains information about how many bits (1,646,421) and requests (65,036) have been served with this API key since it was created (on 1 February 2013 at 5.53pm UTC).
The following requests usage information for an API key that is stopped.
{
"jsonrpc": "2.0",
"method": "getUsage",
"params": {
"apiKey": "00000000-0000-0000-0000-000000000000"
},
"id": 21185
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"status": "stopped",
"creationTime": "2013-02-01 17:53:40Z",
"bitsLeft": 871365,
"requestsLeft": 199977,
"totalBits": 3519123,
"totalRequests": 69274
},
"id": 21185
}
RANDOM.ORG advises that the API key in question exists but is stopped, which means that it cannot be used to serve requests. The service also informs how many bits (871,365) and requests (199,977) are left in the quota for this API key. The response also contains information about how many bits (3,519,123) and requests (69,274) have been served with this API key since it was created (on 1 February 2013 at 5.53pm UTC).
The following requests usage information for an API key that does not exist.
{
"jsonrpc": "2.0",
"method": "getUsage",
"params": {
"apiKey": "ffffffff-ffff-ffff-ffff-ffffffffffff"
},
"id": 3677
}
The service responds with the following:
{
"jsonrpc": "2.0",
"error": {
"code": 400,
"message": "The API key you specified does not exist",
"data": null
},
"id": 3677
}
RANDOM.ORG advises that the API key in question
does not exist. More information about the error object contained
in the error property can be found in
Error Codes and Messages.
getResult (method)
When your client uses the Signed API to generate random values,
RANDOM.ORG stores the signed result for a
minimum of one year, such that you can fetch it again. The
getResult method is used to retrieve such previously
generated results. Your client must set the method
property of its JSON-RPC request object to getResult.
The request must also contain an id member, which
will be returned in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeyserialNumberNo optional parameters.
If the historical response was found, RANDOM.ORG returns a JSON-RPC response with the result property
containing the same values that were returned by the method that
was used to generate the values. They are not listed here, since
they depend on the method that was used to generate the random values.
This is illustrated by example below.
Note that all values within the result object are
historical, including not only signature, but also
bitsUsed, bitsLeft, requestsLeft
and advisoryDelay. For this reason, the client when
invoking getResult should not adapt its behavior in
response to these properties, as it normally should when generating
random values using the Signed API.
For a successful response, the error property is
absent.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result property is
absent and the error property contains an error
object as described in Error Codes
and Messages.
The following requests the result generated in Example 1 from
the generateSignedIntegers method description above.
{
"jsonrpc": "2.0",
"method": "getResult",
"params": {
"apiKey": "f138f168-fdda-4588-893a-b5f0cb65cef2",
"serialNumber": 4
},
"id": 18932
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 10,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"data": [
3, 2, 6, 6, 2, 2, 1, 3, 1, 5
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": null,
"completionTime": "2017-02-12 10:47:15Z",
"serialNumber": 4
},
"signature": "dPXrMbLTr9Bq7pFyghExeI09n92H9Q1Mj6CDD2ABHtDwHDAzN3Tq3el6mS+xkmLyZpkBrWm+ficdLGS8BI8dq8f+GTuzDJCQ0Ah6FnAaXn7TX32xdZ9rqAp0S1IcR7GVMa8Wbcb5u70+evtVSUciotYqQNLkPPB6xx5+TFkY2L24TkfxHGXqG53D5MZDha7kSR7w2cuTRhabRmGmRA7dXgw4swJwAfvKXs63fCzZVbK1pfjZbm7IkmimhP7SRox9t5rAQkFSYfNKeGDrIlFgONb9+5OUEMO+9860nzUBIYsahO+VIHZWYbxSDB4chfmy/bNeBAeexx7tvV8Df2sQ3+soF3fQ/3ca5YFWdWceE+clkI7/8zlPaNYlWQiFDo/0QnySQxLf09O/2Ct3HBoIxBixEj+4FtYbpUi7OmE6IOL/Jhk+RRBfdXxHZUieOykJynTdbXchXCVGY9w5ZkgT8b5w6nDRxTid0RXfepY+sdOucZp7Few4/IYNQmGxB1jMFnUbw5l2TQD2f65P0FojwXpSkJfUnXsRy6m72XCUwo8PwTvrpfdHykWxwWyzhw+jLz/Pte3DrpD/xvwjtOi5OnZAO8SXYdjR8lH6ZUrvQZZI9qT0O3OBMPEgspYDNEx3IGbmwW2/wxaujW6xbxkFS+i0n4gjjdtOhAQHYstTE+o=",
"bitsUsed": 26,
"bitsLeft": 4999948,
"requestsLeft": 19998,
"advisoryDelay": 1090
},
"id": 18932
}
The result object contains all the properties that
were returned when the random values were generated. Note that
the id property contains the new JSON-RPC identifier
(from the invocation of getResult) rather than the
historical one (from the invocation of getSignedIntegers).
The following requests a result generated with a nonexistent API key.
{
"jsonrpc": "2.0",
"method": "getResult",
"params": {
"apiKey": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"serialNumber": 2647656
},
"id": 13609
}
The service responds with the following:
{
"jsonrpc": "2.0",
"error": {
"code": 303,
"message": "The resource identified by 'apiKey' was not found",
"data": ["apiKey"]
},
"id": 13609
}
The following requests a result generated with an API key that exists, but where the requested result is nonexistent, for example because it has expired.
{
"jsonrpc": "2.0",
"method": "getResult",
"params": {
"apiKey": "00000000-0000-0000-0000-000000000000",
"serialNumber": 1
},
"id": 28447
}
The service responds with the following:
{
"jsonrpc": "2.0",
"error": {
"code": 303,
"message": "The resource identified by 'serialNumber' was not found",
"data": ["serialNumber"]
},
"id": 28447
}
verifySignature (method)
This method verifies the signature of a response previously
received from one of the methods in the Signed API. This is used
to examine the authenticity of numbers. Your client must set the
method property of its JSON-RPC request object to
verifySignature. The request must also contain
an id member, which will be returned in the
response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
randomrandom field from a response returned by
RANDOM.ORG through one of the Signed API
methods.
signaturesignature field from the same response that
the random field originates from.
No optional parameters.
If the signature was examined successfully, RANDOM.ORG returns a JSON-RPC response with the result property
containing an object with the following named values:
authenticitytrue if the random
values were authentic RANDOM.ORG values or
false if they were not.
For a successful response, the error property is
absent.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result property is
absent and the error property contains an error
object as described in Error Codes and
Messages.
The following requests validation of the response from Example
1 from the generateSignedIntegers method description
above.
{
"jsonrpc": "2.0",
"method": "verifySignature",
"params": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 10,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"data": [
3, 2, 6, 6, 2, 2, 1, 3, 1, 5
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": null,
"completionTime": "2017-02-12 10:47:15Z",
"serialNumber": 4
},
"signature": "dPXrMbLTr9Bq7pFyghExeI09n92H9Q1Mj6CDD2ABHtDwHDAzN3Tq3el6mS+xkmLyZpkBrWm+ficdLGS8BI8dq8f+GTuzDJCQ0Ah6FnAaXn7TX32xdZ9rqAp0S1IcR7GVMa8Wbcb5u70+evtVSUciotYqQNLkPPB6xx5+TFkY2L24TkfxHGXqG53D5MZDha7kSR7w2cuTRhabRmGmRA7dXgw4swJwAfvKXs63fCzZVbK1pfjZbm7IkmimhP7SRox9t5rAQkFSYfNKeGDrIlFgONb9+5OUEMO+9860nzUBIYsahO+VIHZWYbxSDB4chfmy/bNeBAeexx7tvV8Df2sQ3+soF3fQ/3ca5YFWdWceE+clkI7/8zlPaNYlWQiFDo/0QnySQxLf09O/2Ct3HBoIxBixEj+4FtYbpUi7OmE6IOL/Jhk+RRBfdXxHZUieOykJynTdbXchXCVGY9w5ZkgT8b5w6nDRxTid0RXfepY+sdOucZp7Few4/IYNQmGxB1jMFnUbw5l2TQD2f65P0FojwXpSkJfUnXsRy6m72XCUwo8PwTvrpfdHykWxwWyzhw+jLz/Pte3DrpD/xvwjtOi5OnZAO8SXYdjR8lH6ZUrvQZZI9qT0O3OBMPEgspYDNEx3IGbmwW2/wxaujW6xbxkFS+i0n4gjjdtOhAQHYstTE+o="
},
"id": 2020
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"authenticity": true
},
"id": 2020
}
The value of true for the authenticity
field indicates that the random value specified as
part of the request was indeed signed by RANDOM.ORG,
proving the authenticity of the numbers.
The following requests validation of the response from Example 1
above except that the first integer has been modified from a 5 to
a 6, as you might expect in a tampering attempt. The other values
in the random field have not been modified.
{
"jsonrpc": "2.0",
"method": "verifySignature",
"params": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "jRRSWJJ4kGLIQJ6FngDu2WaGnf7CAV8jqmj2K2HjaF5y++av3qB7r4oq67cnIKAEBeciqJKCXdXKE9apwtg2MA==",
"n": 10,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"data": [
6, 2, 6, 6, 2, 2, 1, 3, 1, 5
],
"license": {
"type": "commercial-2",
"text": "These values are licensed for commercial (non-gambling) use.",
"infoUrl": "https://api.random.org/licenses/commercial-2"
},
"userData": null,
"completionTime": "2017-02-12 10:47:15Z",
"serialNumber": 4
},
"signature": "dPXrMbLTr9Bq7pFyghExeI09n92H9Q1Mj6CDD2ABHtDwHDAzN3Tq3el6mS+xkmLyZpkBrWm+ficdLGS8BI8dq8f+GTuzDJCQ0Ah6FnAaXn7TX32xdZ9rqAp0S1IcR7GVMa8Wbcb5u70+evtVSUciotYqQNLkPPB6xx5+TFkY2L24TkfxHGXqG53D5MZDha7kSR7w2cuTRhabRmGmRA7dXgw4swJwAfvKXs63fCzZVbK1pfjZbm7IkmimhP7SRox9t5rAQkFSYfNKeGDrIlFgONb9+5OUEMO+9860nzUBIYsahO+VIHZWYbxSDB4chfmy/bNeBAeexx7tvV8Df2sQ3+soF3fQ/3ca5YFWdWceE+clkI7/8zlPaNYlWQiFDo/0QnySQxLf09O/2Ct3HBoIxBixEj+4FtYbpUi7OmE6IOL/Jhk+RRBfdXxHZUieOykJynTdbXchXCVGY9w5ZkgT8b5w6nDRxTid0RXfepY+sdOucZp7Few4/IYNQmGxB1jMFnUbw5l2TQD2f65P0FojwXpSkJfUnXsRy6m72XCUwo8PwTvrpfdHykWxwWyzhw+jLz/Pte3DrpD/xvwjtOi5OnZAO8SXYdjR8lH6ZUrvQZZI9qT0O3OBMPEgspYDNEx3IGbmwW2/wxaujW6xbxkFS+i0n4gjjdtOhAQHYstTE+o="
},
"id": 27423
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"authenticity": false
},
"id": 27423
}
The value of false for the authenticity
field indicates that the random value specified as part
of the request was not signed by RANDOM.ORG, i.e.,
the signature is not valid.
The following requests validation of the response from Example 2
in the section about generateSignedIntegers, except
that the MD5 digest that was specified in the original request has
been replaced with another, as might be the case if an attempt at
tampering had been made:
{
"jsonrpc": "2.0",
"method": "verifySignature",
"params": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "rAkSMsx6PBe0w/l2OEssiIZZDC7/4wJCYjSmrLMDgkVM9KhslJ65wsOaZxgJn44kbUtBT5dSSyBBnQ+CFtdj4A==",
"n": 52,
"min": 1,
"max": 52,
"replacement": false,
"base": 10,
"data": [
5, 3, 18, 35, 47, 43, 4, 49, 51, 28, 36, 12, 8, 41, 16, 19, 46, 39, 23, 6, 32, 17, 15, 50, 30, 45, 42, 11, 48, 26, 20, 40, 22, 7, 31, 13, 21, 37, 29, 38, 34, 44, 2, 1, 52, 14, 24, 33, 25, 10, 27, 9
],
"license": {
"type": "gambling-1m",
"text": "These values are licensed for gambling up to a total monthly prize value of $1 million USD",
"infoUrl": "https://api.random.org/licenses/gambling-1m"
},
"userData": {
"myHashType": "md5",
"myHashValue": "a7d8eb2cb9c55110a91e2a80b7932177"
},
"completionTime": "2017-02-12 11:03:42Z",
"serialNumber": 1
},
"signature": "eafA7oDQ+fKM4mjuulkku88svdwyogfWQ5EyWTaMbljLPQXmkEJeMr0ydShEHyEp3h0ZHa0qu84zyzpMBu7nyc8Vx79PlNyfEoIfUTNedTNyO6lHHBay+8Lbbj3SAyDJnNdxQPp16e23VoYEFpnvBiacEtiuwhTlEK4z0F4ORSzAR0gdnuPnyL+NG3oCMAunahmnnkJz5jyD/ckOC9vZLlW1K64jb5f86q2zxSqs2wLO5GY9Rv2IJX85wYS8r22/XVuqmrFwtAJJhdvjW24MJJlOP/l8nKrkbg6GnpheVMGj2DchB3CMLfZ2DJBBKY3+002LClcEivF2NARF8HwJVA29Gf53XoVr0Yv8X9Xn/nZN0Bt9MYtJ50k6uVDBLunKIvlH5qQornG9/dTiNxQJboCzx3bV16lBwdTmzUTUuKZ1DqQ91nBNYdhK4gyWM3AaSCkYbeytEWkDSx62QlxzCrZGVwfeaZhlYgjWLi3nqCH0wZeQepjxl6Ym6h8pYKyR2UVng4CccStUEbqXlWF2G4G8iLGyVxQzBSfshKesS4IS97h+njRVXJHpBgalys25ZfVErA6fTshgcMCcbt3MM3QUIbVLAOcV1xMPrhhHnXyEpM+ZobjwfrH3TIhzh2GuBQaVDaXeCoIRGfpPyw4T/IFfrw/dYoIqccR5/iAHa6g="
},
"id": 18064
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"authenticity": false
},
"id": 18064
}
The value of false for the authenticity field
indicates that the userData value specified as part of
the request was not signed by RANDOM.ORG, i.e.,
the signature is not valid.