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 24 hours. 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
generateSignedIntegers
(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:
apiKey
n
min
max
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:
random
random
object contains the
following properties.
method
hashedApiKey
random
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.
data
base
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.
license
data
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.
userData
userData
object. If the request
did not contain a value for
userData
, it will be included in the response with
the value null
.
completionTime
serialNumber
apiKey
(and, consequently, within the corresponding hashedApiKey
).
signature
random
object, signed with RANDOM.ORG's private key.
bitsUsed
bitsLeft
requestsLeft
advisoryDelay
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. No replacement
parameter is given, which
means the service will use the default value of true
and 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
generateIntegerSequences
. 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:
apiKey
n
length
length
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.
min
min
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.
max
max
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.
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 generateIntegers
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:
random
random
object contains the
following properties.
method
hashedApiKey
random
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.
data
license
data
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.
userData
userData
object. If the request
did not contain a value for
userData
, it will be included in the response with
the value null
.
completionTime
serialNumber
apiKey
(and, consequently, within the corresponding hashedApiKey
).
signature
random
object, signed with RANDOM.ORG's private key.
bitsUsed
bitsLeft
requestsLeft
advisoryDelay
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 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 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, "userData": null }, "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 }
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:
apiKey
n
decimalPlaces
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:
random
random
object contains the
following properties.
method
hashedApiKey
random
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
, 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.
data
license
data
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.
userData
userData
object. If the request
did not contain a value for
userData
, it will be included in the response with
the value null
.
completionTime
serialNumber
apiKey
(and, consequently, within the corresponding hashedApiKey
).
signature
random
object, signed with RANDOM.ORG's private key.
bitsUsed
bitsLeft
requestsLeft
advisoryDelay
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
, replacement
and userData
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 form
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:
apiKey
n
mean
standardDeviation
significantDigits
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:
random
random
contains the following properties.
method
hashedApiKey
random
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.
data
license
data
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.
userData
userData
object. If the request
did not contain a value for
userData
, it will be included in the response with
the value null
.
completionTime
serialNumber
apiKey
(and, consequently, within the corresponding hashedApiKey
).
signature
random
object, signed with RANDOM.ORG's private key.
bitsUsed
bitsLeft
requestsLeft
advisoryDelay
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:
apiKey
n
length
characters
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:
random
random
object contains the
following properties.
method
hashedApiKey
random
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.
data
license
data
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.
userData
userData
object. If the request
did not contain a value for
userData
, it will be included in the response with
the value null
.
completionTime
serialNumber
apiKey
(and, consequently, within the corresponding hashedApiKey
).
signature
random
object, signed with RANDOM.ORG's private key.
bitsUsed
bitsLeft
requestsLeft
advisoryDelay
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 strings will be picked with replacement, i.e., can
contain duplicate values.
{ "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
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
, 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:
apiKey
n
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:
random
random
object contains the
following properties.
method
hashedApiKey
random
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
params
object. The reason it is included in the response
is to allow it to be signed by RANDOM.ORG.
data
license
data
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.
userData
userData
object. If the request
did not contain a value for
userData
, it will be included in the response with
the value null
.
completionTime
serialNumber
apiKey
(and, consequently, within the corresponding hashedApiKey
).
signature
random
object, signed with RANDOM.ORG's private key.
bitsUsed
bitsLeft
requestsLeft
advisoryDelay
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:
apiKey
n
size
The 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:
random
random
object contains the
following properties.
method
hashedApiKey
random
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
, format
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.
data
format
specified in the request.
license
data
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.
userData
userData
object. If the request
did not contain a value for
userData
, it will be included in the response with
the value null
.
completionTime
serialNumber
apiKey
(and, consequently, within the corresponding hashedApiKey
).
signature
random
object, signed with RANDOM.ORG's private key.
bitsUsed
bitsLeft
requestsLeft
advisoryDelay
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 null
value that the client passed in the userData
parameter is included unchanged in the response.
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 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:
apiKey
This 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:
status
stopped
or running
. An API key must
be running
for it to be able to serve
requests.
creationTime
bitsLeft
requestsLeft
totalBits
totalRequests
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 24 hours, 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:
apiKey
serialNumber
No 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 above.
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:
random
random
field from a response returned by RANDOM.ORG through one of the Signed API methods.
signature
signature
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:
authenticity
true
if the random numbers were authentic RANDOM.ORG numbers 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 above.
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.