Advisory: We only operate services from the RANDOM.ORG domain. Other sites that claim to be operated by us are impostors. If in doubt, contact us.
This section describes RANDOM.ORG's Signed API, which together with the Basic API constitutes the Core API. The Signed API is intended for applications that need to support non-repudiation, and its methods produce digitally signed series of true random values, generated specifically for your client. The digital signatures mean that the values can be proved to originate from RANDOM.ORG.
In the Signed API, a signature is a SHA-512 digest
of the JSON representation of a random object, which
has been signed with RANDOM.ORG's private key.
Given a random object and its signature,
anyone can verify the signature against RANDOM.ORG's
public key to confirm that the numbers
are authentic. To do this, the client should JSON-encode the
random object, then compute the SHA-512 digest and
verify the signature against it. While a client is free to use
its own signature verification algorithm, it can also use the
verifySignature method described here.
The Signed API also stores the values generated with the methods
for a minimum of one year. This allows you to retrieve values that
were generated but may not have been delivered to your client due
to network failures, etc. The getResult method is
used for this purpose.
The URL for invoking the Signed API is:
https://api.random.org/json-rpc/4/invoke
revealTicketspregeneratedRandomization and
licenseData were added to the following methods:
generateSignedIntegersgenerateSignedIntegerSequencesgenerateSignedDecimalFractionsgenerateSignedGaussiansgenerateSignedStringsgenerateSignedUUIDsgenerateSignedBlobspregeneratedRandomization,
licenseData and costwere added to
random objects returned by the following methods:
generateSignedIntegersgenerateSignedIntegerSequencesgenerateSignedDecimalFractionsgenerateSignedGaussiansgenerateSignedStringsgenerateSignedUUIDsgenerateSignedBlobsgenerateSignedIntegers (method)
This method generates true random integers within a user-defined
range. Your client must set the method property of
its JSON-RPC request object to generateSignedIntegers.
The request must also contain an id member, which
will be returned in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynminmax
The following parameters are optional and can be included in
the params object of your JSON-RPC request if you
want functionality that is different from the default:
replacement (default value true)true) will cause the
numbers to be picked with replacement, i.e., the resulting
numbers may contain duplicate values (like a series of dice
rolls). If you want the numbers picked to be unique (like
raffle tickets drawn from a container), set this value to
false.
base (default value 10)2, 8, 10
and 16. This affects the JSON types of the
data property included in the response, as discussed
below.
pregeneratedRandomization (default value null)null value (or does not
specify a value), then RANDOM.ORG will
generate true randomness specifically for the caller and will
discard this randomness immediately after it has been used to
generate the random values requested. This is the standard way
of using a true random number generator.
{ "date": "YYYY-MM-DD" } where YYYY-MM-DD
is a date in ISO
8601 format, then RANDOM.ORG uses
historical true randomness generated on the corresponding date.
The date must be in the past or the current date in UTC time.
{ "id": "PERSISTENT-IDENTIFIER" } where
PERSISTENT-IDENTIFIER is a string, then
RANDOM.ORG uses historical true randomness
derived from the corresponding identifier in a deterministic
manner. The identifier must have a length in the
[1,
64] range.
null forms for the
pregeneratedRandomization parameter causes
RANDOM.ORG to generate the random values
based on a pregenerated randomization, i.e., historical true
randomness generated by RANDOM.ORG at some
point in the past. This makes it possible for the client to
replay a given sequence of numbers at a later stage, and also
allows multiple parties in different locations to get the same
numbers in a predictable fashion. These modes effectively turn
RANDOM.ORG into a pseudo-random number
generator.
licenseData (default value null)apiKey. This is required
for API keys with the following license types:
Flexible Gambling.
It is optional for the following: Developer. For such API keys,
the caller must specify the Maximum Payout Value (MPV) for the
game round or lottery draw for which the true random values are
used to determine the outcome. The client must do this by specifying
for the licenseData parameter an object of the form
{ "maxPayoutValue": { "currency": "XTS", "amount": 0.0 } }
where XTS is an
ISO 4217
currency code for a currency supported by RANDOM.ORG and 0.0 is an amount expressed in that currency. The
amount given is used to construct the license object
in the response, licensing the random values as requested by the
caller, and is also used for billing. Currently, the following
currencies are supported as values for
licenseData.maxPayoutValue.currency:
USD, EUR, GBP, BTC, ETH.
userData (default value null)ticketId (default value null)createTickets method. Specifying a value for
ticketId will cause RANDOM.ORG to record that the ticket was used to generate the requested
random values. Each ticket can only be used once.
If the numbers were generated successfully,
RANDOM.ORG returns a JSON-RPC response
with the result property containing an object
with the following named values:
randomrandom object contains the
following properties.
methodhashedApiKeyrandom object
to a third party and allow that third party to associate the
response with a given apiKey, without requiring
the client to disclose the actual apiKey.
n, min, max,
replacement, base,
pregeneratedRandomizaion
params
object. Values that are optional and did not appear in the
request will appear in the response with the default values.
The reason these are included in the response is to allow
them to be signed by RANDOM.ORG.
database 10 (or
did not specify a base and therefore defaults to 10),
the elements in the array will be integers. Because JSON
(according to
RFC4627) only allows numbers to be written as decimal,
the numbers will be typed as strings if a different
base than 10 was specified in the
request. Numbers in any base other than 10 will be padded with
leading zeros up to the width required to display the chosen
range.
licensedata can be used. The API
key owner selects a license for each API key created, which
affects this field in the responses generated for this API
key. For example, an API key could be licensed for non-profit
use only, or for commercial gambling up to a certain prize
value per month. If a
Flexible Gambling license is used, then the license.text property
will reflect the information given in the request's
licenseData parameter.
licenseDatalicenseData
object. If the request did not contain a value for
licenseData, it will be included in the response
with the value null.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response
with the value null.
ticketDataticketId was specified
in the request, then ticketData contains an object
with the following properties: ticketId,
previousTicketId and nextTicketId.
The value in ticketData.ticketId will contain a
copy of ticketId from the request. The value of
ticketData.previousTicketId will contain the
identifier of the ticket preceding ticketId
in the chain and will be null if ticketId
was the first ticket in its chain. The value in
ticketData.nextTicketId will contain the identifier
of the newly created ticket in the chain, which will be unused
at the time when the call returns, and which can be used in future
calls to the Signed API. If the caller did not specify a value for
ticketId (or specified null) in the request,
then the value of ticketData will be null.
completionTimeserialNumberapiKey (and, consequently, within the corresponding
hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
costbitsUsedbitsLeftrequestsLeftadvisoryDelay
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 three 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": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 3,
"min": 1,
"max": 6,
"replacement": true,
"base": 10
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"pregeneratedRandomization": null,
"data": [
1, 3, 1
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-15 13:51:32Z",
"serialNumber": 6116
},
"signature": "hprai35Zc95uAM47oVpqUTEiVla/GvF+u/8GjZCvcGKRG86fQrnVvuzn1HN5VrJoU13SDE96DmggtTYECzkk9bzfVnhHg47/Zn+7w27GedseB2F4QxNtf7aycvcdBHnSg08IaVo+ohPiqlZcxpx5TVUfmLb6LfYRPirQUHMv5vpT7ba/hDSb7bQ6wGpiV1By48nDC5p/ncZEvfAHQcrNxtrtCbwQoI9BMBxRXqV5DaG6YYPxTpQeg9dWJMhZJuBNWIf4hsCKoOGkyBI/uHPaGgTy5jmSk4cFutK3jQP+9vWkDwYQ9sgok0U9Dgp5jG2zC6JOwaEgosagY7B29r1s6aXxcZCXFtX9yBdAh6Of7Z1PeLeva14lQWdZmqYSYvD56HlYWQfeb0lY2Lgf7Yvr9W/lxUxSg9OUvXi+urR0sprXpGwOcml5dSVRXyG6oyDphwXsvJ8h9ofiCP5rkyxHNphR6s1LF5NQ91OCBDllXiwXAKvJBcBxftFVAJRqpRALuLQB2xTXlrld/XBEBc93Pve3e+B0DancFa1XHgBFLlRSmF+MpSY+8qIT2U4hHSGO38ISSX2RdHYR+talXoQ8Vj6fiibzZCUNMbXp4HcYRjmWUVCii0otGYC/fSg25ZmnpG/SMJXfDbVpzx8sC49qYpaN9GRG5QC5pHfA69nJVqo=",
"cost": 0,
"bitsUsed": 8,
"bitsLeft": 249992,
"requestsLeft": 999,
"advisoryDelay": 2310
},
"id": 6995
}
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, replacement and
base parameters from the request are included too.
The pregeneratedRandomization, licenseData,
userData and ticketData properties have
been added with their respective default values, 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 6116th
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": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 52,
"min": 1,
"max": 52,
"replacement": false,
"base": 10,
"userData": {
"myHashType": "md5",
"myHashValue": "c4ec4ba28cbe8390c2f846bf589e538a"
}
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 52,
"min": 1,
"max": 52,
"replacement": false,
"base": 10,
"pregeneratedRandomization": null,
"data": [
45, 1, 43, 18, 25, 23, 11, 50, 38, 15, 34, 9, 30, 33, 48, 20, 29, 19, 2, 47, 40, 16, 14, 3, 6, 46, 12, 10, 7, 26, 35, 41, 13, 24, 49, 42, 32, 31, 4, 51, 27, 8, 37, 52, 28, 22, 44, 39, 21, 36, 5, 17
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": {
"myHashType": "md5",
"myHashValue": "c4ec4ba28cbe8390c2f846bf589e538a"
},
"ticketData": null,
"completionTime": "2021-03-15 14:40:05Z",
"serialNumber": 6126
},
"signature": "xlmLISGNHgy0S5zBmwn3D1ogtqkpj8thJmkqZQQC1muO6nHxCUhQ5OELFlsnYVkyaJ2xX+J1wlltM6RfrfbdOUKozEHiZ7cuRt/FRbRyl7MI/JlFHi4DiPvAPIbhHWh4JgHZcC/b3r1MzjspYJ+UGIYd60oGsjxbKA4gXas5EE6JRZTi2rZeeqmwVXIWoR8lrEuvQffwUghR0wHXZStOMikyyjbrR7WYDqmEbonkQpM7S+vfdLyNYzQF2JKa1AxImKI963njWgt5D8OvsZz875c6dxkgL/uNt4OhZi4LA/kH2moDn3r67yVBLov7Iq6XDBWU+Ory3T318L3NTP7y2WEeGt94tuoVqarU574J68Whg6QPus3vEi8D0AxAmBuMdV573u9IxdKbiXiUjMjdExtMH7lVwqpmMtPU+BDyHvVh7rK/SQmKifqEmN3Dzz5vq3O61YUdERUwhDgAcfcERyJZyhqHzaB4l/nms2KMpmBbYqdvi515NEX/iF3eqdvsg0ctkzpfxJAsGymQmYRe0r46LJAj/SDZ79XrGRvRIiXGlu8YRR+rctMCrL6328BgLFWXPVzA5krhusEqvAcxIi38+d+F8CUA0/cBORVF2h0fX+/JTNi2AvHuGzTCLsHCyxaqmxWOP5aPbYToz3Wet3jIPWRjE+JUfGDGjj+80hI=",
"cost": 0,
"bitsUsed": 296,
"bitsLeft": 249262,
"requestsLeft": 989,
"advisoryDelay": 2660
},
"id": 6995
}
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 testing and development only. The object that the
client passed in the userData parameter is included
unchanged in the response, and the ticketData property
has been added with its default value of null because
ticketId did not appear in the request. The
pregeneratedRandomization and licenseData
properties were also added with their default values, as they
were not used. The serial number indicates that this is the 6126th
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 a single value in the [0,36] range, for
example to decide a spin in European roulette. The client
specifies a value of true for the replacement
parameter, but this has no effect since we're only generating a
single number. The optional base parameter is used
to indicate that the client wishes the numbers to be returned in
decimal form.
The client specifies that it wishes to use a ticket (see the
documentation for createTickets) that was created
previously. In this example, we specify a ticket that was created
with showResult set to false. This means
the random values returned in response to the request will not be
included in later responses by getTicket.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegers",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 1,
"min": 0,
"max": 36,
"replacement": true,
"base": 10,
"ticketId": "ca71d8928623cee5"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 1,
"min": 0,
"max": 36,
"replacement": true,
"base": 10,
"pregeneratedRandomization": null,
"data": [
15
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "ca71d8928623cee5",
"previousTicketId": null,
"nextTicketId": "d7563dedd09b6b80"
},
"completionTime": "2021-03-26 15:18:32Z",
"serialNumber": 6276
},
"signature": "pUqJfluUibvarPqwzblWMOMrWwVCAcJlLjaa4UdHuOpPMnG51+p4PoTYdtwzrno243uv9gzBf9GrGsAWf5KIVuU0XFIjNJsrTsk3xSZ1wfxeiJstA1/lAlW5H+67IDapIenUJ+gy9aHqDIYut8cW9fe7/6BzEDqBUKlrh7Z2j9/qs1hW0x7hanhC/KNTOoF6D5APO/zk/jL7pC5b2sP9+gDyYtdwKG8L61TjLrev7DxXw4E0CQVzSO9/uNUNQa1jgU1uXV+Nk///MTZXe/wxYIcAMTPQxZ+v9qdnrVHTrjIdpjaP1djVZAE8pLOKUrUr2PwOWT3LDynkzyrn8WUPmp2B5cLnYqcGkD+AH9Fp3sp9D27xTr+CF+AlTEzJy2M9gJYHsDd6nFdGtLov1wb5sJb+r6zyd4LFxlyeGvV2rnebyGlnbqmEzPuyJ8jlBs2a0u8ZfYBj0Ht6xxe02guk+C7+bEoJavUtsNW5esaeUK/y34KDPKny/TIgb0avVtB14xoUAvhwXPlgIyS9Iinq1Pc2+wmy85PFMcBWYkwV0IkBmgrXF7q+LiDapja6LGKnmOJr8q+XmcBZZ+1PejaUpDpVkUwwxhLeUESAvItR9LsyKMu8l3022pIpLA20v3MnEc8oCrcEF3VqPRzCIR5RsopmYdDYb7skjxGrnNadTYk=",
"cost": 0,
"bitsUsed": 5,
"bitsLeft": 249995,
"requestsLeft": 993,
"advisoryDelay": 2520
},
"id": 22746
}
The method, n, min,
max, replacement and base
properties are the same that appeared in the request. The
pregeneratedRandomization, licenseData
and userData properties were added with their
respecitive default values, as they were not included 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 number (in the data
array) produced. The data array contains the
single random number that will represent the client's
roulette spin. The license shows that the
values are licensed for development and testing only. The
completionTime specifies UTC time zone (‘Zulu
time’) by the letter ‘Z’ after the clock time.
The service advises that this is the 6276th request to be
completed with this API key.
The ticketData object contains the ticketId
from the client's request. The request has now used this ticket
identifier and it will not be possible to use it again in future
calls to the API. The ticketData object contains two
other properties. The value of previousTicketId is
null meaning that the ticket that was used for the request
is the first in a chain. The value of nextTicketId
contains a newly created ticket, which the client can use for their
next request.
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.
Like Example 3 above, The following requests a single value
in the [0,36] range, for example to decide a spin in European
roulette. The client specifies a value of true
for the replacement parameter, but this has no effect
since we're only generating a single number. The optional
base parameter is used to indicate that the client
wishes the numbers to be returned in decimal form.
The client specifies that it wishes to use a ticket (see the
documentation for createTickets) that was created
previously. However, this time, we specify a ticket that was
created with showResult set to true.
This will allow the random values returned in response to the
request also be displayed by calls to getTicket later.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegers",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 1,
"min": 0,
"max": 36,
"replacement": true,
"base": 10,
"ticketId": "992104b84ba7aed6"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 1,
"min": 0,
"max": 36,
"replacement": true,
"base": 10,
"pregeneratedRandomization": null,
"data": [
6
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "992104b84ba7aed6",
"previousTicketId": null,
"nextTicketId": "448c8e3467a07577"
},
"completionTime": "2021-03-26 15:19:59Z",
"serialNumber": 6277
},
"signature": "DNELqzKkBC78nAXPk5+TnrolPSY3mzpXYXHdmrOHjyWSDAPE2YICg+02qP5pJR2xjqv+UUl0o52GHRqAB6o75cAa8qd6b6F724M7tAzlZWHKH7Z16/HGDPf82HnMvyd4xA5n0/A4vlvoX9A63hjz30O0qaivqdYEHJOevu9l3e6Q2QVMrMkd3GxCrILOquNZAjrWorMKvHITrJh8zwVxZSDU4mjGX3GEHuFBsImJloQaDrxabgZH5Sc15F6076ULfZ7dzE0W8x3+xm4IeckOo4/Z8jMV0W6AxSmAJEK2dq4xLSyWIVR6wpiPS5v0z9aHkhu6+uXh3UyQVLq3hglCm6Gx4cRTFO+vq1I5xOCXHvQc1RtWYsLbSvLWUCnDQdDwpXIq5kpYhgbbnR1tQmlsmkQOzaHF7IYoSKcg8JGM5y1fDldE+RaUgkQmMEmAMJ9SLs/67W5OW5Gjetqlg4k1rENx7PiZQ91DxJWaIA+G3v3qABDuSNVNSkqLJS6eUvAZu8lLX57FBvwYbbMH41d4fdxnJNk1jkzxeLn3PoUZ6OEnDNCdQv37xaeP/McHwQF9yazNuc/8LyNv6amkzHM0qZooXfbFgV/q3MSDhQ97wEDUiMlEJkIwFw1HFMT8aHA7ChhLxSJtINmWCfjRKZ0p3FRiDTk+uz6doKeXRuckKWo=",
"cost": 0,
"bitsUsed": 5,
"bitsLeft": 249990,
"requestsLeft": 992,
"advisoryDelay": 2430
},
"id": 22746
}
The response is very similar to that discussed under Example 3
above. However, we will see the difference under the documentation
for getTicket where we will retrieve the two tickets.
In this example, we will issue a request that uses the same ticket as was used in Example 3 above. This is to show that tickets can be used only once.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegers",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 1,
"min": 0,
"max": 36,
"replacement": true,
"base": 10,
"pregeneratedRandomization": null,
"licenseData": null,
"userData": null,
"ticketId": "2cc535f6ceb42eda"
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"error": {
"code": 422,
"message": "The ticket you specified has already been used",
"data": null
},
"id": 6995
}
In this example, we will issue a request that uses a non-existent ticket.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegers",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 1,
"min": 0,
"max": 36,
"replacement": true,
"base": 10,
"userData": null,
"ticketId": "7777777777777777"
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"error": {
"code": 420,
"message": "The ticket you specified does not exist",
"data": null
},
"id": 6995
}
Like Example 1, the following requests three numbers in the
[1,6] range. The replacement parameter is set
to true, which means the the response can contain
duplicate values. This makes them suitable for use as dice
rolls. The client also specifies a value of type date
for the optional pregeneratedRandomization
parameter, meaning that the results will be historical true
randomness generated by RANDOM.ORG at some
point in the past.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegers",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 3,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"pregeneratedRandomization": {
"date": "2010-12-31"
},
"licenseData": null,
"userData": null,
"ticketId": null
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"pregeneratedRandomization": {
"date": "2010-12-31"
},
"data": [
4, 5, 4
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-15 15:22:18Z",
"serialNumber": 6132
},
"signature": "knHzeE/mYaQgZrgYZSG9IYCsjbe49TqrDXLtcNB2GgDWiAwFSw3OfFJA99Z2TCttyhycDLVz4imMjuLZBWxAlMd8byW5HZnJsLLK0qzd6vwfF3su/p3LHMI1D8ShqeO0XrZkSI+4k8X+iytWJJh5R7wy6p9pBJHwdCLMnS0zfnS/O1DnxA1YowU/vix++dQTSuaUht649NwRiGAY/UM/KiCegxYkFQ5HgFua81Ykd0yln8xPX767yqh9wty1lYxQZkXnHiXwW4JOE7K9ECLcjaVswV/edFYc4/l/I1VI4+/SnDQVDUvIBOg9/Tf0arPSnYdgCB/fG48SqdiT/Uf5uzlimKizezvQWm3i0PieMlvlnkF+mUWhIjDux39HwOmNHUWyNKOPSATZxC+/y6heTx61EYZiap1MeZhsuOL5QcMUuw7Vuc0DWXtN7ORgI9lD8c/U0gC5C+/F+eiQQkIpvZczvhzcycSbWeVfUvZhb+1e639s2mrfO/I8sVsJTCDi+ubfspcODEhBFt59t99hJ7JmIxWK/qlPMtT0DDzE2oocYh5Bv1gHsUEbMNR9Gqhv94EvFla4+aPCIsn4To6ZZ46adZYt8cND/B7csE0ygyfW62mvuaKkqgYrRv62kMIvpXA0e2V0omNX10sKU+PiugLQwg4g3/GqbQy1ITOLUJ8=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 249242,
"requestsLeft": 983,
"advisoryDelay": 3920
},
"id": 6995
}
The random object contains the random integers
returned by the server. By asking for pregenerated random values,
any request with the same specifications, i.e. the same values
for n, min, max,
replacement and pregneratedRandomization,
will return the same data. This also applies to the equivalent
method in the Basic API, see Example 4 of
the generateIntegers method.
The service also advises that this was the 6132nd request using this API key, and that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.
The following request differs from that in Example 7 only
in that the optional pregeneratedRandomization
parameter contains an id value instead of a
date value.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegers",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 3,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"pregeneratedRandomization": {
"id": "foobar"
}
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"pregeneratedRandomization": {
"id": "foobar"
},
"data": [
4, 6, 1
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-15 15:27:01Z",
"serialNumber": 6134
},
"signature": "3Q0pdJvoIMxeRqxsYgNZJ7ye/+gCIiGtORWqjYtye4LoPUxA/6dRNGuP8xz5vjFWo+lK/5KS3rg0QZD3VvNZ4NvkvYh0z56uWzx15NaBF5Q5ApOZ/+U5/ChFt4MCq4/eyF0F2krYLnn1XQAuyEH0kDF9A1vGIe79Ew/DUIJJWZh8pyg70Oxqwm9hR7NZjfUC6RwrofI6s99AXx4DnDhJUqLaa7PDS6Jdv4ELZfhuiXwuCF5wcw1gBt2j+fpUg34C0FLVqC3lwSeSP3Oj4jp1PN5Jn/qey8IDvI+lBAYc03Kkuw5AZeyvWVr8Qg7affMzxHp0tjVirTRNrwxdrkCOyH2UwH/CdbMwOj9gapc21qgmYtKY0qK8guQYr8953M5WSU5LHOxFVcs+JaVtU73FuEJHD3YXeJe0kPlymt7NX/vLjLY7pPwoqGXnPIpWPq22Hkg2yz8gSDxX93griRRo3QfY7qpJy6Gb3EaW+WnWRziDxrfzJpPXGr91YOs2bFDbPtFKkXpDeuoQy49OhuhCZ0RarKKz+wYWgCl5IdTXOwH/aIAfxPsyFshzMrWtpxVajULhKcyPyTtPxE0qwyRh4QDXrGDe8Phm0tG4g5aFmqhnJhjrBQ++pJXf0UTl2DA6RUUs2qOggE2s30/O1bhpUxBSQloRpzgfqc/YGUqjOfc=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 249242,
"requestsLeft": 981,
"advisoryDelay": 3790
},
"id": 6995
}
As in Example 7, the values in the data object
were generated at some point in the past and any time a request
with the same parameters is sent, the data returned will be
identical. Making a request to generateIntegers
(i.e. the basic version of this method) with the same parameters,
will also return the same values.
The following, like examples 1, 7 and 8 above, requests three
values in the [1, 6] range. The values returned could be used
to simulate dice rolls. In addition to this, as we are using an
API key with a 'Flexible Gambling' license, as opposed to the
'Developer' license used in the other examples. Because of this,
the licenseData parameter requires a valid non-null
value. Here, we indicate that the Maximum Payout Value (MPV)
for any game using these values is 99 USD.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegers",
"params": {
"apiKey": "0e8c1eb1-cf1c-4ba8-9c2e-284f78b4bd98",
"n": 3,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
}
},
"id": 28076
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "2ySfUFzaKECQS9yl99r8gdx5izVMkyCRElp8NxNEpj0KbTLIjI5C30FRqDtp0IsdLpdV9p5N+/ReyUQyxvHXPA==",
"n": 3,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"pregeneratedRandomization": null,
"data": [
3, 5, 6
],
"license": {
"type": "gambling-flexible",
"text": "Random values licensed for use in games with a payout of up to $99.00 USD",
"infoUrl": null
},
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
},
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 09:35:47Z",
"serialNumber": 2
},
"signature": "Ba4bQGOLo+FZGIoX9BuqI9nOtPqwE4kbu/vjDz7+MSyknbJBKRnXntsmEx9tOC/K7Vz932QWmG6YUwGYPcX1sPgcd48B4h2DdtzBARWY1IlPdZmRT1XN2wEloBNH87GpcdEhgIrkKz7ukgeF+TorYe7N2ij37+r+DqguuOvPdtih02sZbRui3r0oOpvXk7DCzDI8yeyf1ypZM7/yRx06SANUWPdwz6Pk5YU/wpXkb5VZZ2SS1asZQv69SIX9cJmkdmfLhUYvlRVXfiIaxlxpU5CFw/yRWUA/3n177PfvEBTCCb7f9NVXUaH0Autq8HvHhe5mRpr3/C0YJDU5WNf43bwVStfQMW84cs3/K+iZIi2E7L7REPgfILy6ebW1YUgXWVP5S+ZLcoGAQne/KXVa36m3OQwllR6VwmWID2Cvm9M56uegolXlZrBvK71VJ8/0KD0kttdNt1Uy87M05A4pOUZoB2PKJWqn7/sWZDVFlmhTYMIg5AkbHteZw2fNoABDZtZbpx5R8pqwu8mtRxxKrp3dOA5f8iAfxbblCFGoOsaRdAIHzsskwEu/DAjJ4WSwMg++4HR9ALUEGdMy2xPi+h62frKtqX9ndWroKkzF8lxiWiZndqwn50+pVHb/xSkD0zaU+GSqT6u3H97Ot+lCTV0EHQGjcAemlGXad8TK7/0=",
"cost": 0.0099,
"bitsUsed": 8,
"bitsLeft": 249862,
"requestsLeft": 998,
"advisoryDelay": 1690
},
"id": 28076
}
The result is very similar to that in Example 1. The element
of note here, is that the API key used has a 'Flexible Gambling'
license. Because of this, the information provided for the
licenseData parameter in the request, is reflected
not only in the licenseData property in the response,
but also in the license object's text
property.
Please note that the licenseData parameter may
also be used with the 'Developer' API key, but it is not a
requirement. When used with a 'Developer' license, the string
in license.text does not contain any of the information
given in the licenseData parameter. It will always read
"Random values licensed strictly for development and testing only".
generateSignedIntegerSequences (method)
This method generates uniform or multiform sequences of true
random integers within user-defined ranges. Uniform sequences
all have the same general form (length, range, replacement and
base) whereas these characteristics can vary for multiform sequences.
Your client must set the method property of its JSON-RPC
request object to generateSignedIntegerSequences.
The request must also contain an id member, which will
be returned in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynlengthlength must be an integer in
the [1,
10000]
range. For multiform sequences, length can be an array
with n integers, each specifying the length of the
sequence identified by its index. In this case, each value in
length must be within the
[1,
10000]
range and the total sum of all the lengths must be in the
[1,
10000] range.
minmin must be an
integer in the [-1000000000,
1000000000] range.
For multiform sequences, min can be an array with
n integers, each specifying the lower boundary of
the sequence identified by its index. In this case, each value
in min must be within the
[-1000000000,
1000000000] range.
maxmax must be an
integer in the [-1000000000,
1000000000] range. For
multiform sequences, max can be an array with
n integers, each specifying the upper boundary of
the sequence identified by its index. In this case, each value
in max must be within the
[-1000000000,
1000000000] range.
The following parameters are optional and can be included in
the params object of your JSON-RPC request if you
want functionality that is different from the default:
replacement (default value true)replacement
must be a Boolean value where true indicates the
sequences will be picked with replacement and false
indicates that they will not. For multiform sequences,
replacement can be an array with n
Boolean values, each specifying whether the sequence identified
by its index will be created with (true) or without
(false) replacement.
base (default value 10)base must be an integer with with one of the
values 2, 8, 10 or
16. For multiform sequences, base
can be an array with n integer values taken from
the same set, each specifying the base that will be used to
display the sequence identified by its index. Use of the
base parameter affects the JSON types and
formatting of the resulting data as discussed in the documentation
for the generateSignedIntegers method.
pregeneratedRandomization (default value null)null value (or does not
specify a value), then RANDOM.ORG will
generate true randomness specifically for the caller and will
discard this randomness immediately after it has been used to
generate the random values requested. This is the standard way
of using a true random number generator.
{ "date": "YYYY-MM-DD" } where YYYY-MM-DD
is a date in ISO
8601 format, then RANDOM.ORG uses
historical true randomness generated on the corresponding date.
The date must be in the past or the current date in UTC time.
{ "id": "PERSISTENT-IDENTIFIER" } where
PERSISTENT-IDENTIFIER is a string, then
RANDOM.ORG uses historical true randomness
derived from the corresponding identifier in a deterministic
manner. The identifier must have a length in the
[1,
64] range.
null forms for the
pregeneratedRandomization parameter causes
RANDOM.ORG to generate the random values
based on a pregenerated randomization, i.e., historical true
randomness generated by RANDOM.ORG at some
point in the past. This makes it possible for the client to
replay a given sequence of numbers at a later stage, and also
allows multiple parties in different locations to get the same
numbers in a predictable fashion. These modes effectively turn
RANDOM.ORG into a pseudo-random number
generator.
licenseData (default value null)apiKey. This is required
for API keys with the following license types:
Flexible Gambling.
It is optional for the following: Developer. For such API keys,
the caller must specify the Maximum Payout Value (MPV) for the
game round or lottery draw for which the true random values are
used to determine the outcome. The client must do this by specifying
for the licenseData parameter an object of the form
{ "maxPayoutValue": { "currency": "XTS", "amount": 0.0 } }
where XTS is an
ISO 4217
currency code for a currency supported by RANDOM.ORG and 0.0 is an amount expressed in that currency. The
amount given is used to construct the license object
in the response, licensing the random values as requested by the
caller, and is also used for billing. Currently, the following
currencies are supported as values for
licenseData.maxPayoutValue.currency:
USD, EUR, GBP, BTC, ETH.
userData (default value null)ticketId (default value null)createTickets method. Specifying a value for
ticketId will cause RANDOM.ORG to record that the ticket was used to generate the requested
random values. Each ticket can only be used once.
If the numbers were generated successfully,
RANDOM.ORG returns a JSON-RPC response with the
result property containing an object with the following
named values:
randomrandom object contains the
following properties.
methodhashedApiKeyrandom object
to a third party and allow that third party to associate the
response with a given apiKey, without requiring
the client to disclose the actual apiKey.
n, length, min,
max, replacement, base,
pregeneratedRandomization
params
object. Values that are optional and did not appear in the
request will appear in the response with the default values.
The reason these are included in the response is to allow them
to be signed by RANDOM.ORG.
datalicensedata can be used.
The API key owner selects a license for each API key created,
which affects this field in the responses generated for this
API key. For example, an API key could be licensed for
non-profit use only, or for commercial gambling up to a
certain prize value per month. If a
Flexible Gambling license is used, then the license.text property
will reflect the information given in the request's
licenseData parameter.
licenseDatalicenseData
object. If the request did not contain a value for
licenseData, it will be included in the response
with the value null.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response
with the value null.
ticketDataticketId was specified
in the request, then ticketData contains an object
with the following properties: ticketId,
previousTicketId and nextTicketId.
The value in ticketData.ticketId will contain a
copy of ticketId from the request. The value of
ticketData.previousTicketId will contain the
identifier of the ticket preceding ticketId
in the chain and will be null if ticketId
was the first ticket in its chain. The value in
ticketData.nextTicketId will contain the identifier
of the newly created ticket in the chain, which will be unused
at the time when the call returns, and which can be used in future
calls to the Signed API. If the caller did not specify a value for
ticketId (or specified null) in the request,
then the value of ticketData will be null.
completionTimeserialNumberapiKey (and, consequently, within the corresponding
hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
costbitsUsedbitsLeftrequestsLeftadvisoryDelay
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": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 2,
"length": [ 5, 1 ],
"min": 1,
"max": [ 69, 26 ],
"replacement": false,
"base": 10,
"userData": null,
"ticketId": null
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegerSequences",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 2,
"length": [ 5, 1 ],
"min": 1,
"max": [ 69, 26 ],
"replacement": false,
"base": 10,
"pregeneratedRandomization": null,
"data": [
[ 54, 3, 0, 26, 36 ],
[ 19 ]
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 10:13:58Z",
"serialNumber": 6139
},
"signature": "ggeQrrjX9M1FFT2Uv4xlz4AIpjMMdPvJfkE0RUIOj6oBsfTLpit+tz9XsNKRgqyoGUnygXW7EWEkzFESXk5QeizLZrEkmEylzC4QOv2Cu5xE7xY+S7jv+BHK/Db5FnBRPOiPiY7KpxSyLBlOZ4PeCshNacsXlFK6nV9SF+CvECMUchA7q8VOr2PYsFVRTVg7vVhRxZD1Qy9ba9TGC+F+TkbNkFJrTGHsqA3KUXeDVDEeueQxDyPsM6Z2gqAt7ciFCRcHcIp52Ik20eLlXiV6PgVppeRk9AHl14cfujB5aUtDsqldGWgARqmxWah4R9RhLzuill3PolB0HTe+VfQr9BcuiHgWazKbDsibhGWCLP3tLKdBpe+ow1xy0fVK6OWsMMzpznahlehl33NmHQI+t6e6uY0yVVlIB0wcTNzTRdrWqJoHD4c36mMgqweZGYwfzpsEnm3SWTyQpCLxxfEqdkuGf9mjLxIN4bvgHtDG9X66sle7jO21Ssvq6F4Hyo6g2yKuJFORSYYu6ukgU3u/MhU08iRBMbT9dvnN30cH1ay/HOULEXu5WHdWYiUMPKWpFqZPiV9yn4rSlGXIqRs6zYCJxz41zL0JTAZMd9eTbx3cCcuK5ws0f8tNfR7Bi1xEOr1F/5U89JXu4wHutqomy4AL7bXd0aNxnQ8taMwH0xk=",
"cost": 0,
"bitsUsed": 36,
"bitsLeft": 249924,
"requestsLeft": 998,
"advisoryDelay": 1560
},
"id": 6995
}
The method, n, length,
min, max, replacement,
base and userData parameters are the
same that appeared in the request. The
pregeneratedRandomization and licenseData
properties are included with their default values of null,
despite not being used in the request. Similarly, as the
ticketId parameter was set to null,
ticketData is also returned as null.
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 development and testing only. The serial number
indicates that this is the 6139th 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.
This example is similar to Example 1, but this time we're
specifying a value in the userData string.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegerSequences",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 2,
"length": [ 5, 1 ],
"min": 1,
"max": [ 69, 26 ],
"replacement": false,
"base": 10,
"userData": "Winning numbers for Week 41.",
"ticketId": null
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegerSequences",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 2,
"length": [ 5, 1 ],
"min": 1,
"max": [ 69, 26 ],
"replacement": false,
"base": 10,
"pregeneratedRandomization": null,
"data": [
[ 13, 10, 28, 25, 8 ],
[ 26 ]
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": "Winning numbers for Week 41.",
"ticketData": null,
"completionTime": "2021-03-16 10:17:34Z",
"serialNumber": 6140
},
"signature": "2WrSlf2EXmwoL499sg8UXWf0flOxnUreLSQkwhDhtpskKzsvU003r8muneBtIbytjT3ypMO2HVv9CuIcmOsS/i/XLXUDEdLgfIxpHZpjBVF4x+8QXoqfVYLP1iVXRmhSrNK1ZDWvCQWUoXV4K0hJKVhHVSnA5DqSr9Z6QnggOWJpwloY5H4pO88FZ7NhnUgzIgrkOA4puBXKlAf9Wz2CFYBSKMHIiyEygnYUbIKDXTAS3EoxaVjv1bSjGskXPz2oWO/SVyPniwpOKML/uZHNIzy6//e4O08nC1yRFvViYHeQs1LGlcEdwk0HNeZjNh2wTOeb6xNQ3V3XqLue6plzQjxpjT/YIRPW7KbWnsIZLR2qgCS/V+KTgqGtiBgmVOng6CpyR1jc6kq0d6utNXSdjfiVRnuONRPVKfKckDLXVNsJ+2oVy86NDBplFrwclPTeTXsE9u+Kft0U5CiLjpXuTNiuLxry6nNtv3uJlpg+d3IQX1bEa33VsOMJNUoUa1QxtEqhiqsD5uLnXCrMtvTIdlzw8lB3uYm+HAQygFqqXFSM8sUzj+dA/oQB8MO0ueOAJg43nC2KaW3ryuSfDCH3kLvS/AS+Syn+Ti3/keHujUcIT+l2dvfBLxAFRVOeOrZTGu/3cGcbS4x5BpVstOToK2RZ4EvvFECGT1Rvo8FeLNA=",
"cost": 0,
"bitsUsed": 36,
"bitsLeft": 249888,
"requestsLeft": 997,
"advisoryDelay": 1690
},
"id": 6995
}
The result is very similar to that in Example 1, except
that the userData property contains a non-null
value, as defined in the request's userData
parameter.
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.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegerSequences",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 2,
"length": [ 1, 3 ],
"min": [ 1, 1 ],
"max": [ 8, 6 ],
"replacement": [ true, true ],
"base": 10,
"userData": null
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegerSequences",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 2,
"length": [ 1, 3 ],
"min": [ 1, 1 ],
"max": [ 8, 6 ],
"replacement": [ true, true ],
"base": 10,
"pregeneratedRandomization": null,
"data": [
[ 5 ],
[ 2, 4, 3 ]
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 10:21:14Z",
"serialNumber": 6141
},
"signature": "hxVQJQB3HJuhxSIrz3Mevqz6M9TCmsmCCxI1YCOlBfqkaiJ16EWUyFvKcliOs1l62fFxtKiKrhEZkngtxDTa2Xe+9bYJiPdxg1KvKzXhkNfh+OSU9QxaXlqOvx2HfWppihuW1cnUbuf8VKeVTi8rVf0cvMY/Q8Uw1ORQ5qW+Ca85y/KICFPqNMt5KJKPKsl9FBMsrRLveK0K4ysfGmMQJD6kbOU2Vb1LxHRPGz8v8pTj7YoncfmJ30Xa0+WqBogjfMgtaxN3ZtZG5+PA0Oxoq+v5KP/ZSBUl3iUR5PUCssk6cX1Pw6kONWZ9+75ED4lcMyrDfEo2FxRLVlv/cQZOnZ8Ef+FMYzQY4L3Q7xk4Cb0SuS3wJluuQxR2zt9ZxJ8xvlbPFXGItVN35D7p5YfuxfUV6O83SWP6dfFeEaOmqjMAid99oO2uHYp8oDiS1jldo3Mktre7bx355vspdasIbeJCImdGZRy8ZlxDCRutCp2CNZrnFBM19hTu7ZQdRwo5pFzRLM+2Qo2q+lVcdPIV1abxe6ic8PMY6so8ziga+1namMX6+nn9EYtGsEPAAHxn6KURGchrLwFEzdQaAMzZz/phbYfFE+XxFQzCuqmiX1QMYHuJGY+ero/5l9uYcbD5r3fS4W+FtmjhO52CxwVAzMkqSWbvU1EfIl2nMoweP54=",
"cost": 0,
"bitsUsed": 11,
"bitsLeft": 249877,
"requestsLeft": 996,
"advisoryDelay": 1640
},
"id": 6995
}
The method, n, length,
min, max, replacement,
base and userData parameters are the
same that appeared in the request. The
pregeneratedRandomization and licenseData
properties are set to null, as they were not used.
The hashedApiKey allows the client to share the
full contents of the random and signature
objects with third parties without disclosing its apiKey.
The randomobject 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 development and testing purposes. The
ticketData object is null, as the
ticketId parameter did not appear in the request.
The serial number indicates that this is the 6141st 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 that
the client can issue the next request after a short delay.
The following requests three 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.
We're also specifying a ticketId, which is the ticket
identifier returned by our Example 3 under the
generateSignedIntegers method. This ticket is the
second in its chain.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegerSequences",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 3,
"length": 52,
"min": 1,
"max": 52,
"replacement": false,
"base": 10,
"userData": null,
"ticketId": "d7563dedd09b6b80"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegerSequences",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"length": 52,
"min": 1,
"max": 52,
"replacement": false,
"base": 10,
"pregeneratedRandomization": null,
"data": [
[ 50, 48, 25, 13, 7, 31, 45, 34, 14, 2, 22, 39, 10, 20, 26, 3, 18, 19, 46, 4, 27, 51, 17, 15, 44, 9, 12, 52, 38, 32, 28, 29, 35, 42, 41, 30, 1, 5, 37, 33, 47, 11, 8, 49, 21, 40, 24, 23, 36, 43, 16, 6 ],
[ 40, 10, 42, 5, 34, 11, 19, 50, 12, 31, 35, 27, 21, 44, 23, 36, 4, 38, 46, 32, 51, 7, 25, 48, 1, 22, 41, 9, 8, 29, 28, 33, 52, 24, 18, 15, 43, 14, 20, 26, 13, 49, 6, 47, 16, 39, 30, 37, 2, 17, 3, 45 ],
[ 31, 4, 42, 18, 43, 39, 34, 13, 25, 9, 35, 11, 37, 44, 24, 30, 16, 40, 14, 50, 41, 3, 32, 6, 49, 28, 33, 5, 17, 2, 46, 38, 19, 29, 15, 20, 27, 22, 12, 7, 1, 21, 23, 45, 51, 52, 8, 26, 10, 36, 47, 48 ]
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "d7563dedd09b6b80",
"previousTicketId": "ca71d8928623cee5",
"nextTicketId": "2b08a317fa982ec6"
},
"completionTime": "2021-03-26 15:23:22Z",
"serialNumber": 6278
},
"signature": "ZRmOaJ9QlrB7ljaYe3uEIlI7JDrk79XVnz4RA8burX0snCnqQeGLtR6XfST0zFVlYxNRoJSjxxpSBEaVqi2Oj1FevlPHBAnPp+ZXCO2Z+/tOnv13H54jVloYFbduigL4VQjxCzgEEQrbZo3CQ3QV0yNHnBG+ko0VLnygmDkdiL0aSB3ssZfryHd6spyB62YeuicfXDO55kV0Fe/S8H0BhgPJZbxyW2pRW3ffC9dAK+1s5F3ixe7VSzk4OXvHYKEOUJX49t4a4H5OeGBOReq6OQABn7ge0uKej4D5amJgVTyNHNmLPLUTYRwmPTU2LoYRPzYc42utYopJjATR5eLG3Wu+qZYkNrSK6DKwaYPLsEm7/YeLWektGUJILkXvkrbDiOQSwTdeic4b3yRqYA0MGUSN4SKZkLf+xqz/rmHleecdt8St7j700sSwh84jeymgpGs12yt+nGLd0uq+2X/PnmcJ6PCMkM68d6pTak7qe1Meaz/ppuiZavdj2THgWzqWPsPn8ZRM9lts5VKBtKuzVIhfrW6QvO0Y1pY1T9rkqpBtSS5aSiElNe/iIOj34vH479r+V0ayEL88JV+FmBrPhGcxlweNn2d5MCV5wVjH70d8Wd1I42rLYvhcROyLK1G4nVYc2+pn+IPVngVCfljbUDAJTtOcZB/50dZ++HJajww=",
"cost": 0,
"bitsUsed": 888,
"bitsLeft": 249102,
"requestsLeft": 991,
"advisoryDelay": 3340
},
"id": 22746
}
The method, n, length,
min, max, replacement,
base and userData properties are the
same that appeared in the request. ThepregeneratedRandomization
and licenseData parameters were not used in the request,
but are included in the response with their default values
(null). 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 development
and testing only. The completionTime specifies UTC time
zone (‘Zulu time’) by the letter ‘Z’ after the
clock time. The service advises that this is the 6278th request to
be completed with this API key.
The ticketData object contains the ticketId
from the client's request. The request has now used this ticket identifier
and it will not be possible to use it again in future calls to the API.
The ticketData object contains two other properties. The
value of previousTicketId contains the ticket which was
used in Example 3 of the generateSignedIntegers method.
The value of nextTicketId contains a newly created ticket,
which the client can use for their next request.
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.
This example is very similar to Example 4 above, but this time,
we specify a ticket that was created with showResult
set to true. This will allow the random values returned
in response to the request to also be displayed by getTicket
later. The ticket was returned in Example 4 in the description of the
generateSignedIntegers method.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegerSequences",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 3,
"length": 52,
"min": 1,
"max": 52,
"replacement": false,
"base": 10,
"userData": null,
"ticketId": "448c8e3467a07577"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegerSequences",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"length": 52,
"min": 1,
"max": 52,
"replacement": false,
"base": 10,
"pregeneratedRandomization": null,
"data": [
[ 32, 31, 36, 23, 26, 42, 39, 47, 11, 48, 5, 44, 49, 7, 40, 1, 43, 18, 10, 16, 20, 13, 45, 30, 14, 6, 22, 3, 51, 28, 29, 38, 50, 17, 2, 19, 24, 15, 33, 27, 4, 46, 35, 34, 41, 12, 25, 52, 9, 8, 21, 37 ],
[ 11, 26, 37, 10, 50, 6, 51, 9, 13, 5, 52, 17, 46, 12, 43, 3, 8, 4, 15, 48, 47, 28, 34, 27, 16, 45, 19, 38, 25, 2, 22, 20, 40, 44, 23, 33, 21, 30, 29, 31, 7, 42, 39, 14, 24, 32, 18, 36, 41, 35, 1, 49 ],
[ 47, 40, 27, 16, 48, 7, 43, 23, 18, 37, 25, 21, 11, 52, 28, 4, 13, 20, 49, 32, 15, 2, 5, 42, 30, 35, 26, 6, 1, 45, 36, 51, 39, 31, 19, 46, 24, 33, 38, 3, 50, 10, 22, 41, 9, 8, 17, 14, 12, 44, 34, 29 ]
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "448c8e3467a07577",
"previousTicketId": "992104b84ba7aed6",
"nextTicketId": "9ab36e27a0113a34"
},
"completionTime": "2021-03-26 18:53:13Z",
"serialNumber": 6279
},
"signature": "421Gym7BM8f8BdpyNbN9TQp1U9ASNroic6vaGvX47d7TOcSK+AcYrXUKygekoZxm9VI0LQasOolXqznr+B+Z2sudsX/t02pDtkDMGPhXz3A/GJQhZNtgpiswVPHqUiMpw8XpiI/AgKOhwZTamHckX3hrgVQwmmJzxBNsAazmAvzn7R+YCgj3Kl3ST2tXBVUZVt/9TjSrx+E0t0FQvbrHxCorZb9wLqxsZptnjwGUtgOsR8FNe+suP0fZwRAr1XGjf64fvXZg7LxoonI5/HT7K6SmdUkx1jr9hawuLKkNbg8rk/ho8o2HauyZS9D521fnDhNaw9kdOWoUT9P9yoCh+Nz08MrIyIGpHUxXm+e5s7cV31j+ylnkj9ePSxYzLTAEXSowYoDzoCB0l4kmoSNxahlm5aBjP2/Sx0dEn127M7sh4OhBrnwlx+PxNPgyq6wyHpsmDj6nBzB0PoerLamSjmy6APUfMNCc5PUnGMONM+gp3HMGOzSAbdW6tsdKX3GDPG+aevt3U9d5tMaD2eyV8aIeqhUrdaHzW7xudomwk4sP0KpQuXHKBsU7kwOya9ZUUy1wSrb2vVvokLjn5ehuGL4Tl8EM+yyOmKYCyN8WY1xng9nweNT1P8ekau7zP2nkhQtKFC9fpkA+vdcroIjz6oL73s1IuNxnCI/gtBBjlFc=",
"cost": 0,
"bitsUsed": 888,
"bitsLeft": 248214,
"requestsLeft": 990,
"advisoryDelay": 2320
},
"id": 22746
}
The response is very similar to that discussed under Example
4 above. The difference is visible when the getTicket
method is used to retrieve the two tickets. For this ticket,
i.e. the ticket with showResult set to true,
all of the information including the values generated will
be returned when the getTicket method is used.
Like Example 1, the following requests six numbers, five from
the [1,69] range and one from [1,26]. Duplicates within each
sequence are not allowed as the replacement
parameter has been set to false. The client also
specifies a value of type date for the optional
pregeneratedRandomization parameter, meaning
that the results will be historical true randomness generated
by RANDOM.ORG at some point in the past.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegerSequences",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 2,
"length": [ 5, 1 ],
"min": 1,
"max": [ 69, 26 ],
"replacement": false,
"base": 10,
"pregeneratedRandomization": {
"date": "2010-12-31"
}
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegerSequences",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 2,
"length": [ 5, 1 ],
"min": 1,
"max": [ 69, 26 ],
"replacement": false,
"base": 10,
"pregeneratedRandomization": {
"date": "2010-12-31"
},
"data": [
[ 57, 59, 7, 25, 15 ],
[ 3 ]
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 11:05:43Z",
"serialNumber": 6149
},
"signature": "lgqT65qTtvaJ9OCUn2PWG1z1updV9ppayjWZ8WF/Q8+bBgejCvFAcalD7vLcj0Ouqc513CxL9ZzZD2sWFADvGZLaY6zvCCjwrsJGHebGobq8rtPQ7Or+DwXl/u1utS6dJC/3qWHOqV2/cy9ah5fSoXXGJMLoeSxbNeyi4Lqnla2SZPE7m4fHl7GNoFqRNy8UXSDwWzTFXbqHH+h0uNOFJNczGtOoqTWfg6eHOHterArUzVmeUL9rTsUbuDoHbAPOr2tLs5iWdl+jxqFimDDz9YMviCR2ciCUDJbuq/EBlhbcmia/ENlLHjLN+Q6HgfYadKPfIxbdIWDz5z5LtJzMxBFaZLcs1DJkxjEuYDe47jvNVBi3EuamIuPO2gYpU8+Yqus2bWPahF8ys3HWu346XnbRIsfEiHE/g2T9U35/2hZzm8fsd/FYXWo9ih2UcEf5j4GLFgYjlfR7e8p6dAucueIkZF/1AhrGPts3U6AzdjE1/9QM75j47RmIdEQihwfba0jFvDPE8wp6kcnLmKjsXFZkiREewSQ9/++1rtJnXm30bsgvlLJcMWedM4YdktNGMG8ehGj06G+eG6r+/POzsDGQYI73j9MGUFM2fXPrFjl7bZTCQnbm05SGTFCZ0K3fZboCbk6XTvggHyhczEU+0QsOLpnRXY54SxIISiNnyYI=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 247451,
"requestsLeft": 988,
"advisoryDelay": 2150
},
"id": 6995
}
The random object contains the random integer
sequences returned by the server.By asking for pregenerated
random values, any request with the same specifications, i.e.
the same values for n, length,
min, max, replacement
and pregneratedRandomization, will return the same
data. This also applies to the equivalent method in the
Basic API, see Example 4 of the
generateIntegerSequences method.
The service also advises that this was the 6149th request using this API key, and that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.
The following request differs from that in Example 6 only
in that the optional pregeneratedRandomization
parameter contains an id value instead of a
date value.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegerSequences",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 2,
"length": [ 5, 1 ],
"min": 1,
"max": [ 69, 26 ],
"replacement": false,
"base": 10,
"pregeneratedRandomization": {
"id": "foobar"
}
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegerSequences",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 2,
"length": [ 5, 1 ],
"min": 1,
"max": [ 69, 26 ],
"replacement": false,
"base": 10,
"pregeneratedRandomization": {
"id": "foobar"
},
"data": [
[ 59, 7, 63, 49, 69 ],
[ 6 ]
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 11:11:14Z",
"serialNumber": 6152
},
"signature": "hRvCtBxfco7/2JE99cq0HAKK3MCvOrTLFRlnr0Rpww//Lx+pkRN84rS/sor4n3k5z1JX7f/jsJsL3GXG046f1hpi+aP2G9/zF3LchAXNt4LRzs57FZDcldvpbYgSm1npNoR8FGqz1cj6vM/ClQn21cX4+5uySoO3Y+IG6OcylxUZ3BlizSmrx+WqDfHpIhr7U5daGB/ZbFTg5EEZUYXePldJLfU9JdlEDnAs9KqN/1/EyPdwAZTE04v7NSqj5+ILEij0+rqcsYRl+C+14Pz1LLTK8MiwH2qlNBfDg7N2s7Ru9RWPO8oflb2EsvpJaAFmMSELpb79rbGU6Yvdt7zpEd2KVMMNmfqzpQGjifBUyWCef/Awyh1yzx/mUNU3/EXmLxKf7GPUYcRHZqwMnXGGZuRU95cTGr4z3cUuxiWFj7Vh4sLKTVjeA2yVEB2m32OaosVjiAOGjt5xPSZDxD4AAzvPXwNzZ3oESOJWeLWxw/YBminrCMG2TjroiM3s5qooitMtBcuLAFjb1Ym6RlmEzlsYjISJ+j4k/FS9w4THCNforv/d7mbSzBjAvIElkow2s5pzrs2s3r92ItNmnhRoR0JgSNfxaLV8OF2i2T2XZSaSjv1N9gn5Wk30SyCGkDYS4w63nULbntfjFHonJlEmb2cJrXpX6MlXsfDtjEJa9bU=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 247451,
"requestsLeft": 985,
"advisoryDelay": 2140
},
"id": 6995
}
As in Example 6, the values in the data object
were generated at some point in the past and any time a request
with the same parameters is issued, the data returned will be
identical. Making a request to generateIntegerSequences
(i.e. the basic version of this method) with the same parameters,
will also return the same values.
The following, like examples 1, 6 and 7 above, requests six numbers,
five from the [1,69] range and one from [1,26]. Duplicates within
each sequence returned, are not allowed as the replacement
parameter has been set to false. In addition to this,
we are using an API key with a 'Flexible Gambling' license, as
opposed to the 'Developer' license used in the other examples.
Because of this, the licenseData parameter is required.
Here, we indicate that the Maximum Payout Value (MPV) for any game
or lottery using these values is 99 USD.
{
"jsonrpc": "2.0",
"method": "generateSignedIntegerSequences",
"params": {
"apiKey": "0e8c1eb1-cf1c-4ba8-9c2e-284f78b4bd98",
"n": 2,
"length": [ 5, 1 ],
"min": 1,
"max": [ 69, 26 ],
"replacement": false,
"base": 10,
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
}
},
"id": 18334
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegerSequences",
"hashedApiKey": "2ySfUFzaKECQS9yl99r8gdx5izVMkyCRElp8NxNEpj0KbTLIjI5C30FRqDtp0IsdLpdV9p5N+/ReyUQyxvHXPA==",
"n": 2,
"length": [ 5, 1 ],
"min": 1,
"max": [ 69, 26 ],
"replacement": false,
"base": 10,
"pregeneratedRandomization": null,
"data": [
[ 69, 67, 34, 14, 21 ],
[ 22 ]
],
"license": {
"type": "gambling-flexible",
"text": "Random values licensed for use in games with a payout of up to $99.00 USD",
"infoUrl": null
},
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
},
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 11:18:54Z",
"serialNumber": 3
},
"signature": "V6mpBzwzZdP8nCxXgyN6TLYj0UYXOwQkaqSgX5EtDuU3Xa13H/JhFAWkIFsHyb5GuPT0WhSfH1ApURN9GbnJq++5bbX7B/X+18aW0YzLxbTWvoI4p51oqjaJCmy+IY0YxaAsFArQE6wVPNiVpmWuf2nh5JllviKrBB6cLfPDMhUQB7b40S7Cf/LPgO53r5rLaz7ISUbsVXiG7ZnNKiekRhBAfMuPMS7fUhyrDatYUgiz5y1FWMQX+vk+GkSOIl2HMW5SGSySBuHoYQgVSZBMew8hko54EBhodLYs05YGS8l+u+VSYWtwaNFEK15OHbCg0mxJQVshocODCOeESYJ40AAvVIwTF0gOt/BrMf3O9mufq+4ugJNJFVWJ1M/NCdaAWQiMc0L4hxo9UcnO4H07LYLUM4Bq6SPI9OyC5irHckO+QF7i4rC33Qd0N5KRjAxHqF7j2tdK2ZWqfz+4KkUTxRg3aCoqXKBUXDzfRb5HbzVpn02mX2UZ53ZOL0pPGa15V0uZoy/f7D5+mSujeLDD83/JnjfnmQWDkHoFidgwYYx97Zt3Pyuv0DENEcdaQcr6Ui0dxg+3sdxWWdduPxy/7OTmJTw3C4f2BdlY+LbEfhD6jydWhhBwbzcl+Hjov+WpyuM9dJhs1O2ZHVXwer1EbnsWlJnPEbMKwQK6N1rCD2c=",
"cost": 0.0099,
"bitsUsed": 36,
"bitsLeft": 249826,
"requestsLeft": 997,
"advisoryDelay": 2380
},
"id": 18334
}
The result is very similar to that in Example 1. The primary
difference is that the API key used has a 'Flexible Gambling'
license. Because of this, the information provided for the
licenseData parameter in the request, is reflected
not only in the licenseData property in the response,
but also in the license object's text
property. The cost property also shows that the
RANDOM.ORG account associated with the
apiKey will be charged $0.0099 USD for making the
request.
Please note that the licenseData parameter may
also be used with the 'Developer' API key, but it is not a
requirement. When used with a 'Developer' license, the
license.text property returned does not contain
any of the information provided in the licenseData
parameter. It will always read
"Random values licensed strictly for development and testing only".
generateSignedDecimalFractions (method)
This method generates true random
decimal fractions from a uniform distribution across the [0,1)
interval with a user-defined number of
decimal
places. Your client must set the method property of
its JSON-RPC request object to generateSignedDecimalFractions.
The request must also contain an id member, which will
be returned in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeyndecimalPlaces
The following parameters are optional and can be included in
the params object of your JSON-RPC request if you
want functionality that is different from the default:
replacement (default value true)true) will cause the
numbers to be picked with replacement, i.e., the resulting
numbers may contain duplicate values (like a series of dice
rolls). If you want the numbers picked to be unique (like
raffle tickets drawn from a container), set this value to
false.
pregeneratedRandomization (default value null)null value (or does not
specify a value), then RANDOM.ORG will
generate true randomness specifically for the caller and will
discard this randomness immediately after it has been used to
generate the random values requested. This is the standard way
of using a true random number generator.
{ "date": "YYYY-MM-DD" } where YYYY-MM-DD
is a date in ISO
8601 format, then RANDOM.ORG uses
historical true randomness generated on the corresponding date.
The date must be in the past or the current date in UTC time.
{ "id": "PERSISTENT-IDENTIFIER" } where
PERSISTENT-IDENTIFIER is a string, then
RANDOM.ORG uses historical true randomness
derived from the corresponding identifier in a deterministic
manner. The identifier must have a length in the
[1,
64] range.
null forms for the
pregeneratedRandomization parameter causes
RANDOM.ORG to generate the random values
based on a pregenerated randomization, i.e., historical true
randomness generated by RANDOM.ORG at some
point in the past. This makes it possible for the client to
replay a given sequence of numbers at a later stage, and also
allows multiple parties in different locations to get the same
numbers in a predictable fashion. These modes effectively turn
RANDOM.ORG into a pseudo-random number
generator.
licenseData (default value null)apiKey. This is required
for API keys with the following license types:
Flexible Gambling.
It is optional for the following: Developer. For such API keys,
the caller must specify the Maximum Payout Value (MPV) for the
game round or lottery draw for which the true random values are
used to determine the outcome. The client must do this by specifying
for the licenseData parameter an object of the form
{ "maxPayoutValue": { "currency": "XTS", "amount": 0.0 } }
where XTS is an
ISO 4217
currency code for a currency supported by RANDOM.ORG and 0.0 is an amount expressed in that currency. The
amount given is used to construct the license object
in the response, licensing the random values as requested by the
caller, and is also used for billing. Currently, the following
currencies are supported as values for
licenseData.maxPayoutValue.currency:
USD, EUR, GBP, BTC, ETH.
userData (default value null)ticketId (default value null)createTickets method. Specifying a value for
ticketId will cause RANDOM.ORG to record that the ticket was used to generate the requested
random values. Each ticket can only be used once.
If the numbers were generated successfully,
RANDOM.ORG returns a JSON-RPC response with
the result property containing an object with the
following named values:
randomrandom object contains the
following properties.
methodhashedApiKeyrandom object
to a third party and allow that third party to associate the
response with a given apiKey, without requiring
the client to disclose the actual apiKey.
n, decimalPlaces,
replacement, pregeneratedRandomization
params
object. Values that are optional and did not appear in the request
will appear in the response with the default values. The reason
these are included in the response is to allow them to be signed
by RANDOM.ORG.
datalicensedata can be used.
The API key owner selects a license for each API key created,
which affects this field in the responses generated for this
API key. For example, an API key could be licensed for
non-profit use only, or for commercial gambling up to a
certain prize value per month. If a
Flexible Gambling license is used, then the license.text property
will reflect the information given in the request's
licenseData parameter.
licenseDatalicenseData
object. If the request did not contain a value for
licenseData, it will be included in the response
with the value null.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response
with the value null.
ticketDataticketId was specified
in the request, then ticketData contains an object
with the following properties: ticketId,
previousTicketId and nextTicketId.
The value in ticketData.ticketId will contain a
copy of ticketId from the request. The value of
ticketData.previousTicketId will contain the
identifier of the ticket preceding ticketId
in the chain and will be null if ticketId
was the first ticket in its chain. The value in
ticketData.nextTicketId will contain the identifier
of the newly created ticket in the chain, which will be unused
at the time when the call returns, and which can be used in future
calls to the Signed API. If the caller did not specify a value for
ticketId (or specified null) in the request,
then the value of ticketData will be null.
completionTimeserialNumberapiKey (and, consequently, within the
corresponding hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
costbitsUsedbitsLeftrequestsLeftadvisoryDelay
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": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 10,
"decimalPlaces": 8
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedDecimalFractions",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 10,
"decimalPlaces": 8,
"replacement": true,
"pregeneratedRandomization": null,
"data": [
0.23213486,
0.97593769,
0.88911014,
0.63882311,
0.90541324,
0.81344571,
0.69891248,
0.6300596,
0.8323724,
0.17882089
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 11:30:16Z",
"serialNumber": 6156
},
"signature": "0arTfIyzLtMA1+Nzo++qeKtSEC2pxCuc4Bb5EsoA3FSTfmEctBQJeuWa4Tl4h/DEPvoiNQ4c/awzjFMOlcN8SsyJnRNSDUpOp8L48gFAvLAyDVflTwe3kJT6N9AAeqIt57m/R+Vzl5RAvS0LMH0tMg1L8mB43aRyZP1rF/YrPJ4dMOugOD+G7Dgqi1U3q+SxcpXoQpbsm1DptpIBMXyBQmxSC6kwkzbPXq4dDY8hcbNG+rcUaWDjbS1ptkFIuDlNhgvY6quC3AiuDt6wYgeLFzGl6WYQ/pGd9B0lklyn3Op2WfgPGqwyhe3FpZ0iWULj8WvdN/ZNkJ67Okz1fRIv7Q/zYIq9btL06Sw+IL2UDSin4Jr/gbjoNpBnfVgvbrQJkieg/aFZIB/KTmTOGfYfsRFsLXSebJALj+F4TWSiEuX7B5qsZq+gNN/5B4GNFoA6khUaJQ9yMaiyi/s7VTI4Au5pvu+lJ+I+tucVJf4uuKKwEuzlpUSxmZZ2HZvYoG2mi8rZo8hTZmGEBjQ4wSZeyp81Y1umZ321qwC42d3sgTS/sLpQaAMTs752zxwJSmGwEkS+NzswGurghtsirNhu0ZhN7yNe3iWX5hqtkncJiEYvH/vXqT90QyUQOvDz3xjOpYYhh/muYTL9kJbypSsKmO8vdiapmGfrVkSEcJFS0GU=",
"cost": 0,
"bitsUsed": 266,
"bitsLeft": 246919,
"requestsLeft": 981,
"advisoryDelay": 2070
},
"id": 6995
}
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,
pregeneratedRandomization, licenseData
and userData properties have been added with default values,
even though they did not appear in the request. Similarly,
ticketData has been added with the value of null
as no tickets were used in making 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 eighth and ninth values appear to have fewer decimal
places. The license shows that the values are licensed
for testing and development only. 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 6156th
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 20 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.
The client specifies that it wishes to use a ticket (see
the documentation for createTickets) that was
returned in Example 4 of the generateSignedIntegerSequences
method. The showResult property of the first ticket
in this chain was set to false.
{
"jsonrpc": "2.0",
"method": "generateSignedDecimalFractions",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 20,
"decimalPlaces": 14,
"replacement": true,
"userData": "Values for Simulation #42",
"ticketId": "2b08a317fa982ec6"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedDecimalFractions",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 20,
"decimalPlaces": 14,
"replacement": true,
"pregeneratedRandomization": null,
"data": [
0.38335468261153,
0.27368931236887,
0.30477311119179,
0.0674389524643,
0.07526825106629,
0.12401051623907,
0.80238755553127,
0.8635195122181,
0.77830772574916,
0.08656009621906,
0.05440508853413,
0.72757165565767,
0.93870999383615,
0.83538433989441,
0.00043397273894,
0.28189889211291,
0.81682148049757,
0.48568191339133,
0.57901345097361,
0.70392200854913
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": "Values for Simulation #42",
"ticketData": {
"ticketId": "2b08a317fa982ec6",
"previousTicketId": "d7563dedd09b6b80",
"nextTicketId": "4e3f60bb110a9d4a"
},
"completionTime": "2021-03-26 19:04:07Z",
"serialNumber": 6280
},
"signature": "3gL8NLUkR3hKVazrHb4eedvhJwG8U+89Zk/02N5GtCtFq+DWXmfzpUssYsF3RYMduyhPUGAU9+YcjzDD3fLzWSLtWBikg0uBzEzf3v2qGNUcvyQtuWzjAU3P2UsROvfsgHvewnYLbgvy2HbxgAXGShHny0C61GQoOoNCbf/lkeejHaGqOumGeRL3gLR32hKw1JsfM6jys1wzj3XOQqA1pqMaICFoTp/MeA0xQpmEydZp7Gf9aFSHk7tlttxQihyRRDsQkZz63Et6YYbd2T+tIs3IrexYs8bY6aWg7v5aAD+2Ngv+tNfXPOgVEoC0q2EjeRrLOfbl45UoLwUQuJa7PQYPKhy5KXlIkqhM/wKD2FnxkUVOUn7i95lii2pjK3goxbG2v3j+1+7xZFG63owlegeLW544eNMN5BScEf6AGhJZIFH/N9XJPopxbQ/4sI23o1SW0y5iUXhDbTGF8VYRxa0R2qDDynNGLYTrmK+MiJzOxcxHSZbAwqfI6wcEB+i3f0sz2OTdbbcPHvBgkCvAxHu0BcFBjaB9dEGCL0skQI35pxaMfGtzDQFtmjisXahcRsG/K6PjtHh3e4F8Y8kBOt/5RALkU2n5+8FX7/X8LOU21yqxs6eOnhNFdW0tuOwna0HBu/fL1pVoHU2mJ+SKV0qgu09MqAnvdMBZaQnLKCQ=",
"cost": 0,
"bitsUsed": 930,
"bitsLeft": 247284,
"requestsLeft": 989,
"advisoryDelay": 2080
},
"id": 22746
}
The method, n decimalPlaces,
replacement and userData properties are
the same that appeared in the request. The pregeneratedRandomization
and licenseData parameters were not included in the request,
but they appear in the response with their default values (null
for both, in this case). 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 testing
and development only. The completion time is also included.
The ticketData object contains the ticketId
from the client's request. The request has now used this ticket identifier
and it will not be possible to use it again in future calls to the API.
The ticketData object contains two other properties. The
value of previousTicketId contains the ticket which was used
in Example 4 of the generateSignedIntegerSequences method.
The value of nextTicketId contains a newly created ticket,
which the client can use for their next request.
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.
The client specifies that it wishes to use a ticket (see the
documentation for createTickets) that was returned in
Example 5 of the generateSignedIntegerSequences method.
The first ticket in the chain was created with showResult
set to true. This will allow the random values returned
in response to the request to also be displayed by getTicket
later.
{
"jsonrpc": "2.0",
"method": "generateSignedDecimalFractions",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 4,
"decimalPlaces": 2,
"replacement": false,
"userData": "Sample values for Experiment X.",
"ticketId": "9ab36e27a0113a34"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedDecimalFractions",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 4,
"decimalPlaces": 2,
"replacement": false,
"pregeneratedRandomization": null,
"data": [
0.18,
0.32,
0.26,
0.86
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": "Sample values for Experiment X.",
"ticketData": {
"ticketId": "9ab36e27a0113a34",
"previousTicketId": "448c8e3467a07577",
"nextTicketId": "7032e9128e1dde1c"
},
"completionTime": "2021-03-26 19:07:44Z",
"serialNumber": 6281
},
"signature": "o63MDq5b6c89Yb9NVF6JMquy2StgqPfovv0bi5wIr1FN6ew1yB5APlQgouHtj2CqdSJu/CmPvySgxiH9vJUmO3vVQ4JBPIjJd8HRKSMX1Eyi9/UdEynKlalpaxLKJictBxVx0GGZIgDyNmL7zH8k67W/zh8IDV0JYONL8cQDmDA1fQbZwiDzCYKiJe6U8q+T/g2tUhVhrmTuufdNqWV7mqcRC0bTZhtb8COg/m25b4yprUW6pKYhtAir+gfJ8AkwlWA2QUBCv2Sd8N2GJc70vXIQtiw9W1EJg2/ufjaTbNWyxbbOM5lJUaHYPEmK05CfDq8batUtZiBX8p3ekH5MhX7ssqRwq7WFtQpQsH6Rvd2pSOS6zn4dbS5W9y2P5zplSVDgH4RMf/4hDFmN8SBBMYn7pavI/btqpWZUPjrytnGH10qaUHv1q5KjT5ZOtLk+Mxui9bt+NDFXsaBe+xi8U10ENUt+K3ifsDE+Rs5oSfE/NVYyvDbz8quzB2z3n7soDXtQJd4gfHc0zGsDCs0rsKxno6YYoDstwuWTTE2c7jKJVoDuOhUq4yDLerhOu/njH5EI5RnO18zBwSAO6gIGoSQFwlREfRifM1fXsaPslhDHBS+tHh2yo1c7+RkpabWRgUk4qDZSRN8DoDQKPn4YFbUUPoOGcKH7/z0SjU3mElE=",
"cost": 0,
"bitsUsed": 27,
"bitsLeft": 247257,
"requestsLeft": 988,
"advisoryDelay": 2690
},
"id": 22746
}
The response is very similar to that discussed under Example
2 above. The difference is visible when the getTicket
method is used to retrieve the two tickets. For this ticket,
i.e. the ticket with showResult set to true,
all of the information including the values generated will
be returned when the getTicket method is used.
The following requests three decimal fractions, accurate up
to three decimal places. The client also specifies a value of type
date for the optional pregeneratedRandomization
parameter, meaning that the results will be historical true
randomness generated by RANDOM.ORG at some
point in the past.
{
"jsonrpc": "2.0",
"method": "generateSignedDecimalFractions",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 3,
"decimalPlaces": 3,
"pregeneratedRandomization": {
"date": "2010-12-31"
}
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedDecimalFractions",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"decimalPlaces": 3,
"replacement": true,
"pregeneratedRandomization": {
"date": "2010-12-31"
},
"data": [
0.455,
0.954,
0.228
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 11:52:43Z",
"serialNumber": 6158
},
"signature": "Dw3kz9KlD0ohgzoqSC+amed+JL31WEVVnaZsIYK1vRbwJPfRSB2bPaHAgb1BaF8EXyu+vNFEzMgpLTLrHIEa4PxwkEj0W+Eh6YhbbFl51p08lyqbBclvGeU1NZe//3znH+OEUguyVoaEzxSlcUEQb+jMvvWkXc3bkXB4TukEPBdiswCkQ/J/TLvMwt/dQifI6by4ez41xeEwZiA8ELBdq6rg4za1H1r510usUc9G5qFbfhvQxl4UlcHsizxRDiWSmEPaKB9lw9DwSmroGa+pbhDj8RQvwgErBtlqQr5pMsh7qYaiNKGIIWmoLlxBnrC4y5rCTTw5xAYsx3yjJ8D8Ck2XWb/mINb8DCrL1wyyU2tB6m1bf5mHup+KC3kSXOrP5lZ6tvW9DRTWNC/lR378jo9iFoi/XZytZPTD5w4yxfj8W0SBU4Mr4f0SoDKEdl2fJ/G55eUKgQ2QJtFSMYUtYUjMvwbi6QBHTet9/tMfZAfKKdVvKABU+uYNTrgQV5ZW/ep1jn3uX4kXqJoWq4zufv6ELNUVS2ZFIy8nXpB33eusSQI8dySd+uJAJlNjpjWMDnKbMsFk5Gf8FyhHBXNokS3lX0/LyyIt7xo/ksCZcxFA81XBaXY4PyoiUb+XqunzJge3IyK4h67fplE3PUysZqEXX6NkDvAX4fmz8YxYL5M=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 246919,
"requestsLeft": 979,
"advisoryDelay": 2220
},
"id": 6995
}
The random object contains the random decimal
fractions returned by the server. By asking for pregenerated
random values, any request with the same specifications, i.e.
the same values for n, decimalPlaces,
replacement and pregneratedRandomization,
will return the same data. This also applies to the equivalent
method in the Basic API, see Example 4 of
the generateDecimalFractions method.
The service also advises that this was the 6158th request using this API key, and that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.
The following request differs from that in Example 4 only in that
the optional pregeneratedRandomization parameter
contains an id value instead of a date
value.
{
"jsonrpc": "2.0",
"method": "generateSignedDecimalFractions",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 3,
"decimalPlaces": 3,
"pregeneratedRandomization": {
"id": "foobar"
}
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedDecimalFractions",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"decimalPlaces": 3,
"replacement": true,
"pregeneratedRandomization": {
"id": "foobar"
},
"data": [
0.464,
0.414,
0.489
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 11:54:26Z",
"serialNumber": 6159
},
"signature": "mZDmSwi5u8yN0a/9wmMA7+4kxYgxUY810+iDi6V16v8dh68w4VYU2/h3l/0yISFNCahccik5qFmEbGYR4Y9OJ8Shr/7u5OBIE6OPrHOOO+arcW7OzhuXASmNPOfR7iYw5+umLC1DZaGY99aiUFVs0Uu2vV4pMhz9ItDClss77IAfODCU8rmljU9SXCQvshBX229JH+HqkgsrRgiGhvHsWQCP53ranQ3QiE4NF1hasDeVSfBVRkA8cHSk3zQFkm8oATtEJiSnu7xgWDV6liPg9ZhbzzFnGijI0vo8iPJwDDnwCXXZq0TNKOlhbW0m3kkw0sEYUdO6XbkehFNkcSLM+qSVZikMZ03O/5dMvh69bXnpUBnLRnyi/7kKmgK7JI2pUVKcry24ePc6MMCBdTQ2l6AU0H0tiwLKFD9VDZHdXK/alSDI37hFYFADNs1L9vkE9sB03Y+TDMc9c+iTkO7OOzRXLNKANdwNULqwIkX948nhu4Khg3JiHNGGSWe+OB/bWvC7+PZTxAYLJ+qVWJFybusb+BKuwIdRYHLy4IjHHmDZfQ0shg78/FrpBLBbTNgULHLQKfD6w7AgbIzukoHUlRw8RZMAdPtnO7pNkso1q6eXZk18+BDzD2QjwBBtp6rcRZJI5fqlsCV6AB04Yb64WpS+RNAth9j1/CLtnb1/kBA=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 246919,
"requestsLeft": 978,
"advisoryDelay": 2300
},
"id": 6995
}
As in Example 4, the values in the data object
were generated at some point in the past and any time a request
with the same parameters is issued, the data returned will be
identical. Making a request to generateDecimalFractions
(i.e. the basic version of this method) with the same parameters,
will also return the same values.
The following requests four decimal fractions with an accuracy
of up to four decimal places. The replacement parameter
is set to false, so duplicates are not allowed. In
addition to this, we are using an API key with a 'Flexible Gambling'
license, as opposed to the 'Developer' license used in the other
examples. Because of this, the licenseData parameter
is required. Here, we indicate that the Maximum Payout Value (MPV)
for any game or lottery using these values is 99 USD.
{
"jsonrpc": "2.0",
"method": "generateSignedDecimalFractions",
"params": {
"apiKey": "0e8c1eb1-cf1c-4ba8-9c2e-284f78b4bd98",
"n": 4,
"decimalPlaces": 4,
"replacement": false,
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
}
},
"id": 18334
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedDecimalFractions",
"hashedApiKey": "2ySfUFzaKECQS9yl99r8gdx5izVMkyCRElp8NxNEpj0KbTLIjI5C30FRqDtp0IsdLpdV9p5N+/ReyUQyxvHXPA==",
"n": 4,
"decimalPlaces": 4,
"replacement": false,
"pregeneratedRandomization": null,
"data": [
0.9547,
0.3804,
0.5826,
0.9672
],
"license": {
"type": "gambling-flexible",
"text": "Random values licensed for use in games with a payout of up to $99.00 USD",
"infoUrl": null
},
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
},
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 11:57:21Z",
"serialNumber": 4
},
"signature": "h9wYhAZZ09GmISj1MlVlHJyKqeXkeyGzBBQ7GPl0Bmi6rNNPaOj1SyYISc0NeL8Fl7FA7ODklzUIpOJMQ5jXZu26DbIZ0HOvtqT8b5T6kBfN7vv/3pV+MCenwoF3wu3RYHMMyWZ2rTB6sjTwfobthWGHpZvIng9hos3+Ehxt/d8A5/I1el2uGY67ZktJ2eqdFr9Dr61bjgGwEh0LcXoZRx4SUfujh+6TEqxa9/dJkJp39RJzSxsY2XZQCxt2iYCX9vNvaMXhmOoGBm9nc8POfHZUcn4arbZVRlMp0yyQTftf8Z7yetjGNipoyy4mo+9PSz3fV6UTvkHahU//xD6lyI2I69CGQqq2+Uc0IiIecKegg9KG4gJ1WhUxATNrzHyYSx8m1XzD2CFDc32cd6j1zo76688CqEE4F3ZkNdM6SAPzUiwti46aQ2EBTWJ/Rfi/FwDwpUYn1u5bj7eSc9YvFeEfcr++2x7N743Q6MhpNHRHDXXvVSXaMAjtsEins6BWWlzn4rAxuQi45aVJ5j+dorDjUmQHA1JbYxhTFiTt8SbcN7Avaf0RBbX+JAPjEfQ54ZHyCgI1bwyEbyBPFApmggfwvER8DIRSERtD5YpHYL0wFMX86HygCZOIjPOGL6k7I/5GSQvplv3baeQmc1jxcq08sDa0sUhsJJHgNt+DUsk=",
"cost": 0.0099,
"bitsUsed": 53,
"bitsLeft": 249773,
"requestsLeft": 996,
"advisoryDelay": 2740
},
"id": 18334
}
The overall result is very similar to those described in
the examples above. The primary difference here is that the
API key used has a 'Flexible Gambling' license. Because of
this, the information provided for the licenseData
parameter in the request, is reflected not only in the
licenseData property in the response, but also
in the license object's text property.
The cost property also shows that the
RANDOM.ORG account associated with the
apiKey will be charged $0.0099 USD for making
this request.
Please note that the licenseData parameter may
also be used with the 'Developer' API key, but it is not a
requirement. When used with a 'Developer' license, the text
value of the license property returned does not
contain any of the information given in the licenseData
parameter. It will always read
"Random values licensed strictly for development and testing only".
generateSignedGaussians (method)
This method generates true random numbers from a
Gaussian
distribution (also known as a normal distribution).
The method uses a
Box-Muller Transform to generate the Gaussian distribution
from uniformly distributed numbers. Your client must set the
method property of its JSON-RPC request object
to generateSignedGaussians. The request must also
contain an id member, which will be returned in the
response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynmeanstandardDeviationsignificantDigits
The following 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:
pregeneratedRandomization (default value null)null value (or does not
specify a value), then RANDOM.ORG will
generate true randomness specifically for the caller and will
discard this randomness immediately after it has been used to
generate the random values requested. This is the standard way
of using a true random number generator.
{ "date": "YYYY-MM-DD" } where YYYY-MM-DD
is a date in ISO
8601 format, then RANDOM.ORG uses
historical true randomness generated on the corresponding date.
The date must be in the past or the current date in UTC time.
{ "id": "PERSISTENT-IDENTIFIER" } where
PERSISTENT-IDENTIFIER is a string, then
RANDOM.ORG uses historical true randomness
derived from the corresponding identifier in a deterministic
manner. The identifier must have a length in the
[1,
64] range.
null forms for the
pregeneratedRandomization parameter causes
RANDOM.ORG to generate the random values
based on a pregenerated randomization, i.e., historical true
randomness generated by RANDOM.ORG at some
point in the past. This makes it possible for the client to
replay a given sequence of numbers at a later stage, and also
allows multiple parties in different locations to get the same
numbers in a predictable fashion. These modes effectively turn
RANDOM.ORG into a pseudo-random number
generator.
licenseData (default value null)apiKey. This is required
for API keys with the following license types:
Flexible Gambling.
It is optional for the following: Developer. For such API keys,
the caller must specify the Maximum Payout Value (MPV) for the
game round or lottery draw for which the true random values are
used to determine the outcome. The client must do this by specifying
for the licenseData parameter an object of the form
{ "maxPayoutValue": { "currency": "XTS", "amount": 0.0 } }
where XTS is an
ISO 4217
currency code for a currency supported by RANDOM.ORG and 0.0 is an amount expressed in that currency. The
amount given is used to construct the license object
in the response, licensing the random values as requested by the
caller, and is also used for billing. Currently, the following
currencies are supported as values for
licenseData.maxPayoutValue.currency:
USD, EUR, GBP, BTC, ETH.
userData (default value null)ticketId (default value null)createTickets method. Specifying a value for
ticketId will cause RANDOM.ORG to record that the ticket was used to generate the requested
random values. Each ticket can only be used once.
If the numbers were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property
containing an object with the following named values:
randomrandom contains the following properties.
methodhashedApiKeyrandom object to a third
party and allow that third party to associate the response with
a given apiKey, without requiring the client to
disclose the actual apiKey.
n, mean, standardDeviation,
significantDigits, pregeneratedRandomization
params
object. The reason these are included in the response
is to allow them to be signed by RANDOM.ORG.
datalicensedata can
be used. The API key owner selects a license
for each API key created, which affects this
field in the responses generated for this API
key. For example, an API key could be licensed for
non-profit use only, or for commercial gambling
up to a certain prize value per month. If a
Flexible Gambling license is used, then the license.text
property will reflect the information given in
the request's licenseData parameter.
licenseDatalicenseData
object. If the request did not contain a value for
licenseData, it will be included in the response
with the value null.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response with
the value null.
ticketDataticketId was specified
in the request, then ticketData contains an object
with the following properties: ticketId,
previousTicketId and nextTicketId.
The value in ticketData.ticketId will contain a
copy of ticketId from the request. The value of
ticketData.previousTicketId will contain the
identifier of the ticket preceding ticketId
in the chain and will be null if ticketId
was the first ticket in its chain. The value in
ticketData.nextTicketId will contain the identifier
of the newly created ticket in the chain, which will be unused
at the time when the call returns, and which can be used in future
calls to the Signed API. If the caller did not specify a value for
ticketId (or specified null) in the request,
then the value of ticketData will be null.
completionTimeserialNumberapiKey (and, consequently, within the corresponding
hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
costbitsUsedbitsLeftrequestsLeftadvisoryDelay
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": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 4,
"mean": 0,
"standardDeviation": 1,
"significantDigits": 8,
"userData": null
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedGaussians",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 4,
"mean": 0,
"standardDeviation": 1,
"significantDigits": 8,
"pregeneratedRandomization": null,
"data": [
0.21100315,
0.46885842,
1.5617242,
0.68414464
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 12:14:41Z",
"serialNumber": 6160
},
"signature": "Gg/71JaukP5j+sEIlxUPjKO877NzvuXk5BZBu3jkmxjeKZL9CBvb38mvWaZl2RqrV40ysESne/Kpsi4ehqZVdx1Xsq7SM4jkAmS1HrhBoBKrfpXu2yb0O9qMCZweGKhpSQWZOeQKHqNJK5ZvIeiDhfS/kUKFPY96LvSX5vTgT+EvOb3ET2WNN5o6wwy7WNmPaVAgCKR17y9fwrhbALcNbhgf67oQr/nHTsC8Kfe8qYnVtb4/gxCfDQib6tjemgqMrLck5jWweOnscIPh84ACHnBtTE1Mqvjbc2iTE8O9le2aq18wqnzY6jD+zVlkigsl0wWBlUAy1ssobst7odfA26c73bypN+XhkFc37nuTmJk3ffzPndHDrGSBUwAJAWSDs0Y5j6IYT4wfRWoohaka+69RkFuJ7tN/vs3jymW4fey1bp7WrBfaqunKqQeKopSAy0kb2stUuSum5ZG87ubnRVPkKsykEeFbwPCDKh/X9u3TalKAgF+bOUHhImuwJ7npiRyWF7+nKyI0zgaJ7PANhAZPRyj6DnefpdehJY446pyhduiIeIDo8Fk7t0sQiKzMp8/enPqSvQXg6YEFGxqgmJuQq1vc4xRikaRvcmRmkKHcJPeBHodq/56oqNEqPUtlwEd4EncinPjKGWdbfFbWBXynSu2ERU1AisaJPYke/no=",
"cost": 0,
"bitsUsed": 106,
"bitsLeft": 246813,
"requestsLeft": 977,
"advisoryDelay": 1850
},
"id": 6995
}
The method, n, mean,
standardDeviation, significantDigits
and userData parameters are the same that appeared
in the request. The pregeneratedRandomization and
licenseData parameters are included in the response
with their default values of null, despite not appearing
in the request. The ticketData object is also
null, as no ticket was used. 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 testing
and development only. 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 6160th 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 significant digits. 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": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 2000,
"mean": 1100,
"standardDeviation": 100,
"significantDigits": 4,
"userData": {
"simulation": "Lightbulb Lifetimes",
"dataSetNumber": 42
}
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedGaussians",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 2000,
"mean": 1100,
"standardDeviation": 100,
"significantDigits": 4,
"pregeneratedRandomization": null,
"data": [
1053.0,988.8,1056.0,1288.0,1076.0,918.1,1273.0,1093.0,1109.0,1073.0,1207.0,1022.0,1237.0,1261.0,919.7,1076.0,923.7,1075.0,1066.0,977.7,1100.0,1211.0,1128.0,973.9,1089.0,1150.0,1164.0,921.8,1089.0,1020.0,988.5,1058.0,1021.0,1047.0,1170.0,1051.0,1177.0,1183.0,1111.0,978.3,1284.0,1158.0,920.5,922.0,1168.0,917.7,1056.0,1042.0,1265.0,1153.0,1083.0,1068.0,1121.0,1115.0,1153.0,1044.0,1030.0,956.2,1132.0,1160.0,991.1,1068.0,1124.0,1072.0,1105.0,1113.0,1219.0,1094.0,1153.0,1149.0,1014.0,1113.0,1154.0,964.0,1259.0,1135.0,1178.0,1177.0,1279.0,1129.0,1091.0,1069.0,1148.0,966.1,1050.0,1074.0,1133.0,1347.0,1148.0,992.6,871.5,942.9,1045.0,1106.0,1066.0,1025.0,1240.0,1123.0,1339.0,1088.0,1299.0,1177.0,1003.0,998.9,1127.0,1141.0,1095.0,987.3,967.2,1094.0,1146.0,1067.0,958.6,993.2,1113.0,1083.0,1124.0,1132.0,1162.0,1119.0,985.5,903.8,1171.0,1055.0,1014.0,1205.0,1194.0,1079.0,1041.0,1123.0,1011.0,1106.0,1079.0,1008.0,885.6,1176.0,1005.0,1069.0,1190.0,1173.0,1212.0,1095.0,1278.0,1028.0,1017.0,1200.0,1172.0,1221.0,1128.0,1137.0,1115.0,1004.0,968.9,1143.0,1057.0,1014.0,1051.0,1118.0,1131.0,1146.0,1209.0,1142.0,1126.0,1013.0,1126.0,1023.0,1114.0,1107.0,988.9,1144.0,1036.0,966.0,1092.0,1119.0,1127.0,917.7,1027.0,1209.0,1121.0,1183.0,1163.0,1056.0,1078.0,1196.0,1194.0,957.8,1114.0,1164.0,1170.0,1058.0,1128.0,1082.0,1180.0,1166.0,1121.0,1090.0,903.9,1106.0,1200.0,1164.0,985.9,1033.0,1273.0,1199.0,1091.0,1047.0,1184.0,1210.0,1190.0,1164.0,1096.0,1073.0,1197.0,1069.0,1027.0,998.0,1112.0,1042.0,1121.0,917.3,1204.0,1094.0,1118.0,1178.0,1153.0,1145.0,1158.0,1202.0,1061.0,1003.0,1150.0,1160.0,1026.0,1139.0,1097.0,1205.0,976.4,1082.0,983.0,1155.0,920.7,1042.0,1090.0,1190.0,1206.0,951.4,1111.0,1030.0,1017.0,1229.0,1244.0,1162.0,1006.0,950.9,1233.0,1188.0,863.2,1045.0,1114.0,1008.0,1186.0,1297.0,1161.0,1197.0,1026.0,997.7,1027.0,1111.0,934.6,1121.0,969.1,1192.0,1173.0,1109.0,989.2,1098.0,1026.0,951.7,1013.0,1064.0,1173.0,1205.0,1278.0,1175.0,1143.0,1227.0,1070.0,1253.0,1300.0,1062.0,1268.0,976.1,1112.0,1255.0,1099.0,971.6,1276.0,1181.0,1083.0,1081.0,1154.0,1178.0,1028.0,1086.0,1058.0,1120.0,1037.0,1108.0,1094.0,1100.0,1272.0,1212.0,978.9,1020.0,1196.0,1286.0,1141.0,1140.0,1221.0,1071.0,1088.0,1143.0,1001.0,1092.0,1080.0,1046.0,1211.0,1184.0,1042.0,1174.0,1076.0,967.0,892.7,987.5,1030.0,1035.0,1193.0,1036.0,1059.0,1001.0,1233.0,1103.0,1125.0,1252.0,1003.0,1080.0,1073.0,1164.0,1053.0,1056.0,1160.0,1017.0,1082.0,951.9,1193.0,988.4,1083.0,1079.0,1105.0,1333.0,1129.0,1054.0,901.2,1034.0,1126.0,1189.0,1097.0,982.6,842.9,927.5,1000.0,1179.0,1168.0,1151.0,1166.0,911.4,1129.0,1126.0,1023.0,1105.0,1033.0,1121.0,988.2,1040.0,1245.0,1299.0,1180.0,1190.0,823.6,924.5,1110.0,981.2,1079.0,1117.0,1138.0,1113.0,1048.0,1163.0,855.3,958.1,1020.0,989.0,908.7,1133.0,978.7,1168.0,1037.0,1223.0,1207.0,1055.0,839.6,1192.0,1066.0,1036.0,1118.0,1221.0,967.9,1036.0,1031.0,1223.0,1228.0,1104.0,1247.0,1199.0,999.1,981.0,1151.0,1081.0,1319.0,1219.0,1146.0,1032.0,927.0,1294.0,1222.0,971.9,1078.0,1182.0,1066.0,1162.0,1099.0,1165.0,1170.0,1007.0,1088.0,1154.0,1137.0,1171.0,1001.0,1047.0,1151.0,1097.0,1151.0,1013.0,894.9,993.9,997.2,1169.0,1051.0,1140.0,952.5,1160.0,1172.0,1245.0,1162.0,1017.0,1096.0,1174.0,1166.0,1124.0,881.4,1061.0,1046.0,1226.0,1129.0,1064.0,1036.0,1041.0,1166.0,1256.0,1103.0,1312.0,1063.0,951.7,922.4,1024.0,1258.0,1008.0,1282.0,945.9,1108.0,1090.0,1268.0,1124.0,1106.0,1073.0,1142.0,1150.0,894.6,1140.0,1055.0,1110.0,942.2,1184.0,1130.0,1159.0,1115.0,1082.0,1179.0,1050.0,1041.0,1175.0,1085.0,1006.0,1193.0,1108.0,1035.0,1077.0,913.6,1041.0,1248.0,1061.0,1175.0,1100.0,915.7,1058.0,951.6,1160.0,1165.0,989.8,1072.0,1170.0,1009.0,1288.0,1271.0,945.6,1023.0,906.7,1166.0,1234.0,1148.0,1030.0,1200.0,1085.0,1041.0,1149.0,1142.0,1170.0,1073.0,1173.0,976.1,1037.0,1058.0,1162.0,1192.0,1262.0,1163.0,1165.0,1113.0,1058.0,1072.0,1096.0,1226.0,1160.0,875.8,1094.0,1067.0,1135.0,1147.0,1066.0,924.3,1065.0,1187.0,1150.0,1069.0,1026.0,1098.0,1197.0,1101.0,1117.0,1021.0,1099.0,1187.0,992.0,1171.0,1030.0,1029.0,1013.0,1103.0,978.5,1041.0,1277.0,1030.0,1023.0,1171.0,935.3,1038.0,1068.0,1035.0,1080.0,1142.0,997.6,1099.0,1006.0,947.6,916.4,1029.0,1030.0,1085.0,1113.0,1158.0,1148.0,1059.0,1100.0,1173.0,1317.0,1208.0,1067.0,1090.0,1176.0,1015.0,1173.0,1144.0,1133.0,1240.0,1029.0,1033.0,1008.0,1173.0,994.6,1156.0,1027.0,1082.0,1191.0,1029.0,1132.0,1182.0,981.6,1034.0,1080.0,1269.0,1144.0,1085.0,1311.0,1045.0,893.9,1065.0,1068.0,1095.0,1244.0,1197.0,1134.0,1188.0,1175.0,906.4,1098.0,1269.0,1042.0,1183.0,1249.0,1092.0,1114.0,1153.0,1106.0,1302.0,1071.0,1199.0,1198.0,1137.0,1086.0,1098.0,1170.0,1097.0,1101.0,812.6,1122.0,1214.0,1249.0,1184.0,1234.0,763.9,1073.0,1046.0,1191.0,1169.0,1082.0,984.4,1086.0,1063.0,1245.0,1109.0,1155.0,1010.0,1069.0,1056.0,1200.0,962.5,916.5,1174.0,1083.0,1157.0,986.2,1182.0,1053.0,1059.0,1121.0,1159.0,1100.0,1068.0,1281.0,1090.0,1003.0,960.1,876.4,1072.0,1148.0,1269.0,1061.0,948.9,1164.0,903.0,1206.0,1051.0,1023.0,1010.0,1065.0,961.7,1212.0,1093.0,1115.0,1047.0,1248.0,1180.0,997.5,1054.0,1167.0,1234.0,1025.0,1212.0,1069.0,960.6,1131.0,1078.0,989.1,938.7,1054.0,1000.0,874.1,953.8,1123.0,1074.0,933.8,1075.0,1358.0,1158.0,1093.0,1144.0,1113.0,1101.0,1110.0,1022.0,1035.0,1222.0,1153.0,1149.0,1235.0,1040.0,1150.0,1046.0,1089.0,1137.0,1101.0,1209.0,1058.0,1060.0,1330.0,1049.0,1078.0,1175.0,1152.0,1083.0,1188.0,1175.0,1137.0,1309.0,1160.0,1204.0,1086.0,1041.0,957.6,1117.0,1220.0,990.6,1125.0,1109.0,1111.0,1016.0,1032.0,981.2,969.9,1125.0,1037.0,954.3,1164.0,1187.0,1106.0,1004.0,1167.0,1234.0,1187.0,911.2,968.3,965.5,996.3,827.4,1128.0,1248.0,1012.0,1087.0,1306.0,1028.0,1077.0,1203.0,1133.0,1171.0,1091.0,1168.0,1223.0,1108.0,1137.0,1133.0,1322.0,1035.0,965.7,1020.0,1015.0,1091.0,1074.0,1107.0,1120.0,951.2,1137.0,1116.0,1023.0,1033.0,1185.0,1229.0,1146.0,966.1,1092.0,1233.0,1030.0,1138.0,948.6,904.2,994.5,1066.0,1070.0,1038.0,873.5,1245.0,1184.0,881.4,1083.0,1228.0,1417.0,1030.0,1060.0,1071.0,1048.0,1380.0,1181.0,1138.0,1309.0,1198.0,1012.0,1236.0,1216.0,1116.0,1152.0,1221.0,1135.0,1191.0,1138.0,1176.0,1042.0,1235.0,1230.0,750.9,1033.0,1115.0,1362.0,1284.0,1161.0,1011.0,1118.0,907.7,1164.0,1053.0,1161.0,1011.0,1236.0,1030.0,1214.0,1094.0,1040.0,1039.0,1088.0,1179.0,1039.0,1062.0,1090.0,1119.0,1099.0,938.6,1042.0,1115.0,997.7,1054.0,1120.0,1035.0,1052.0,1025.0,1122.0,1028.0,1088.0,1211.0,980.6,1090.0,1102.0,1191.0,1027.0,1019.0,1082.0,1145.0,1206.0,968.6,1129.0,1271.0,1071.0,1066.0,1156.0,1130.0,1194.0,1021.0,1109.0,1059.0,1120.0,968.5,1051.0,1128.0,1146.0,969.3,1253.0,1053.0,1196.0,1262.0,1128.0,1222.0,1261.0,1120.0,960.2,1217.0,1082.0,1026.0,1083.0,982.9,942.7,1168.0,1070.0,997.6,1266.0,1073.0,1044.0,1094.0,1086.0,1113.0,1119.0,1105.0,1129.0,1143.0,1310.0,1100.0,1037.0,1156.0,1019.0,1078.0,1205.0,1036.0,1006.0,1222.0,1111.0,1046.0,1102.0,1172.0,889.5,1257.0,1145.0,1060.0,1114.0,1010.0,1037.0,1216.0,1045.0,1187.0,1200.0,1066.0,1276.0,951.1,1202.0,857.9,1181.0,1213.0,1209.0,1060.0,1089.0,1198.0,1314.0,1009.0,1208.0,1163.0,1167.0,1003.0,975.5,1212.0,1070.0,960.3,1067.0,1070.0,1103.0,1098.0,1149.0,971.0,1156.0,1081.0,1166.0,1189.0,707.1,1005.0,1076.0,1028.0,1110.0,1124.0,1010.0,1038.0,1146.0,1021.0,1237.0,876.6,1022.0,1170.0,1099.0,974.8,1086.0,1074.0,967.4,1080.0,997.8,1142.0,970.7,1166.0,1280.0,1072.0,1176.0,1152.0,1187.0,1037.0,1095.0,1095.0,1089.0,1067.0,1142.0,1192.0,1079.0,1143.0,1013.0,893.4,1245.0,906.0,1036.0,1164.0,1028.0,1043.0,1251.0,1056.0,1120.0,1030.0,1146.0,1078.0,1145.0,937.9,1218.0,1073.0,990.7,1077.0,1283.0,1212.0,1153.0,1045.0,1030.0,1162.0,1221.0,1158.0,1084.0,1027.0,1153.0,1062.0,1016.0,984.6,1314.0,1032.0,1087.0,1253.0,754.8,1200.0,1109.0,1043.0,1094.0,1017.0,1137.0,1018.0,995.8,1166.0,1071.0,1028.0,1165.0,1005.0,1220.0,1018.0,1190.0,1169.0,1192.0,1040.0,1048.0,1036.0,1090.0,987.1,919.0,872.2,1167.0,1117.0,1024.0,1101.0,965.7,1008.0,1084.0,1251.0,1123.0,1164.0,878.4,1232.0,1138.0,1132.0,1024.0,1072.0,1107.0,1012.0,1100.0,1028.0,994.3,1264.0,1238.0,1161.0,1049.0,1168.0,1090.0,1163.0,1145.0,1093.0,953.6,1047.0,1206.0,1208.0,1130.0,1077.0,1172.0,1041.0,1215.0,1034.0,1079.0,929.0,1050.0,1192.0,1144.0,1144.0,968.8,973.8,925.7,1123.0,1039.0,1076.0,1155.0,1104.0,1031.0,1048.0,1188.0,1113.0,1132.0,1045.0,1307.0,1163.0,1028.0,1104.0,1187.0,1092.0,1231.0,1123.0,1056.0,1158.0,1160.0,1063.0,1135.0,1084.0,1135.0,1275.0,959.7,1236.0,1064.0,1252.0,1259.0,993.8,1315.0,982.1,1162.0,1010.0,1149.0,1189.0,1124.0,1157.0,1169.0,955.4,1011.0,957.2,1167.0,1115.0,1190.0,1193.0,917.3,1113.0,1336.0,1072.0,914.9,1310.0,1158.0,987.9,913.6,1171.0,1046.0,995.6,1049.0,1122.0,1191.0,1134.0,1138.0,1039.0,1020.0,1089.0,1038.0,1182.0,1125.0,1050.0,1033.0,1042.0,1005.0,1122.0,965.5,1148.0,1189.0,1086.0,1062.0,1103.0,1098.0,971.5,1133.0,1181.0,1119.0,1114.0,847.9,1016.0,1069.0,959.1,979.4,1013.0,1181.0,1336.0,1132.0,970.5,1155.0,1021.0,1104.0,1147.0,1149.0,1056.0,1071.0,1125.0,1208.0,1017.0,1068.0,1035.0,1209.0,1094.0,1116.0,1284.0,1080.0,1171.0,1223.0,1168.0,1097.0,976.3,1097.0,1118.0,1169.0,1297.0,1137.0,1202.0,995.8,1055.0,1116.0,1119.0,1091.0,1116.0,1130.0,1117.0,1266.0,1198.0,1146.0,1008.0,1174.0,1091.0,1152.0,1168.0,1177.0,1168.0,1128.0,1129.0,1028.0,1196.0,1165.0,1181.0,1088.0,1286.0,1142.0,1023.0,1170.0,1171.0,914.2,1062.0,1140.0,942.4,982.9,1156.0,1107.0,1125.0,1133.0,1093.0,896.5,1256.0,823.7,938.8,1107.0,1077.0,1046.0,1382.0,1166.0,1018.0,1167.0,1092.0,1187.0,1240.0,950.7,842.9,1190.0,1151.0,1082.0,1023.0,1066.0,1030.0,903.7,1179.0,1021.0,1025.0,979.6,1084.0,1038.0,1177.0,1309.0,1203.0,1060.0,1047.0,919.8,937.1,1122.0,1255.0,1120.0,1126.0,983.3,1214.0,905.9,1189.0,1067.0,962.9,1094.0,1101.0,1063.0,1193.0,895.7,1086.0,1206.0,1105.0,1302.0,1307.0,1041.0,1233.0,1096.0,1125.0,1016.0,1018.0,1151.0,1042.0,1194.0,1009.0,1036.0,1212.0,1144.0,1066.0,1182.0,863.3,1185.0,1082.0,965.4,1140.0,981.5,1117.0,1034.0,1103.0,1050.0,1148.0,1094.0,1274.0,889.6,1112.0,997.4,959.2,1194.0,1027.0,1150.0,959.0,1298.0,1075.0,981.6,1068.0,1330.0,1181.0,1120.0,1064.0,906.4,1175.0,1154.0,999.4,1116.0,927.4,1132.0,1052.0,1050.0,1260.0,1145.0,967.8,1072.0,890.0,961.0,1053.0,933.5,1241.0,1127.0,1253.0,864.1,1052.0,1161.0,984.4,962.8,1008.0,1051.0,1019.0,909.5,1224.0,1009.0,1266.0,894.5,1142.0,1260.0,912.9,1193.0,1195.0,1203.0,1271.0,994.4,962.1,1258.0,1131.0,1106.0,1064.0,1107.0,1278.0,1067.0,1182.0,1346.0,1006.0,1019.0,1073.0,981.9,1052.0,1135.0,1048.0,1149.0,1158.0,1295.0,1124.0,1016.0,1210.0,1173.0,1108.0,959.8,1084.0,1216.0,1029.0,1149.0,1165.0,1240.0,1309.0,1223.0,1296.0,1139.0,986.2,991.9,1103.0,1072.0,1114.0,1297.0,1057.0,1064.0,1175.0,1058.0,1204.0,1252.0,1196.0,1195.0,1135.0,1113.0,1130.0,1015.0,1070.0,1094.0,961.8,1148.0,1188.0,1086.0,1014.0,1143.0,1102.0,1101.0,1197.0,978.2,1062.0,1140.0,1195.0,1120.0,1080.0,1207.0,1014.0,1284.0,1162.0,1048.0,980.5,1033.0,1140.0,860.3,1175.0,993.8,995.9,889.0,945.7,963.0,1241.0,1022.0,1015.0,978.8,1171.0,1087.0,1093.0,1251.0,1147.0,1108.0,1258.0,1075.0,1155.0,1054.0,1161.0,1079.0,999.0,971.6,951.2,1042.0,915.8,1024.0,1149.0,1193.0,1031.0,957.8,1078.0,1025.0,1096.0,1111.0,1243.0,1061.0,1061.0,1146.0,1194.0,1079.0,1065.0,1034.0,1272.0,1118.0,1318.0,1193.0,1105.0,1116.0,1058.0,949.1,1157.0,1022.0,1067.0,1097.0,1028.0,1046.0,1012.0,991.3,925.9,1044.0,1074.0,1207.0,1112.0,1021.0,1143.0,1029.0,1047.0,1165.0,1035.0,885.0,924.1,1100.0,1080.0,1123.0,1058.0,1030.0,1094.0,1210.0,1113.0,1088.0,1001.0,1123.0,1093.0,1103.0,1115.0,1076.0,1088.0,1145.0,1145.0,1086.0,1125.0,1133.0,1170.0,1160.0,1130.0,1272.0,1153.0,899.0,1140.0,1238.0,1162.0,982.7,1170.0,1045.0,1022.0,1098.0,1021.0,1282.0,1062.0,1187.0,1003.0,984.5,1167.0,1134.0,1123.0,1060.0,1100.0,1101.0,1141.0,939.1,1129.0,1036.0,1180.0,1187.0,1154.0,1238.0,1275.0,899.0,1024.0,1184.0,1400.0,966.6,969.9,1157.0,1163.0,1050.0,1025.0,1116.0,1158.0,984.6,1031.0,1005.0,1208.0,1112.0,1170.0,1134.0,1016.0,1181.0,1106.0,1114.0,983.3,1126.0,1140.0,981.8,1106.0,1049.0,1146.0,862.9,1018.0,1248.0,1063.0,865.4,1217.0,1196.0,1172.0,1049.0,1207.0,1188.0,1218.0,1185.0,1252.0,1136.0,1168.0,1051.0,1117.0,1089.0,1135.0,987.6,852.9,883.2,992.0,1094.0,1027.0,1239.0,1106.0,1061.0,1174.0,1002.0,1146.0,1232.0,1051.0,902.9,1049.0,1144.0,1143.0,1201.0,1157.0,1032.0,1075.0,1090.0,976.8,1054.0,1125.0,1187.0,881.2,1061.0,1185.0,960.4,994.4,1111.0,1051.0,1009.0,1306.0,1167.0,900.9,981.0,943.6,1063.0,1029.0,1058.0,1089.0,1046.0,950.3,1008.0,1069.0,1029.0,1130.0,961.6,892.6,1183.0,1002.0,978.4,1050.0,1120.0,1145.0,996.3,1148.0,1109.0,1135.0,1206.0,928.1,1121.0,1165.0,1009.0,1060.0,1102.0,1051.0,1153.0,1157.0,1105.0,1210.0,1198.0,1187.0,1115.0,1111.0,1099.0,1147.0,969.1,949.2,1101.0,1032.0,993.5,1388.0,1091.0,1115.0,1179.0,1029.0,982.2,1168.0,1093.0,1200.0,1074.0,1124.0,1072.0,1164.0,980.8,1087.0,1043.0,976.4,1150.0,986.8,1085.0,1107.0,1128.0,1313.0,1079.0,1061.0,1152.0,1065.0,1280.0,1177.0,1103.0,1109.0,1231.0,1132.0,1084.0,1034.0,1137.0,1063.0,1306.0,1203.0,1057.0,1008.0,1154.0,1089.0,1111.0,1060.0,1205.0,1124.0,1021.0,1204.0,1098.0,1226.0,1260.0,1204.0,1071.0,1059.0,1113.0,1402.0,1008.0,1062.0,1078.0,1015.0,1102.0,1176.0,934.3,1137.0,1081.0,1192.0,1181.0,1039.0,1201.0,1111.0,1251.0,1053.0,1153.0,1114.0,1193.0,1151.0,1113.0,1006.0,1077.0,1032.0,1011.0,1130.0,1071.0,1259.0,1108.0,930.6,926.2,1146.0,910.8,1080.0,1148.0,1090.0,1229.0,1151.0,997.2,1164.0,1190.0,1043.0,1233.0,1003.0,1095.0,1159.0,1263.0,1177.0,1076.0,1020.0,1055.0,1197.0,1228.0,1219.0,1129.0,898.0,1179.0,1106.0,1210.0,1126.0,1113.0,1189.0,1063.0,1228.0,895.6,1062.0,1274.0,902.6,998.4,1104.0,1066.0,1143.0,1038.0,1083.0,1123.0,985.5,923.7,1129.0,1178.0,1329.0,1076.0,1048.0,1076.0,1236.0,1067.0,1114.0,1165.0,1154.0,1019.0,994.3,1311.0,1145.0,992.5,1133.0,1072.0,1209.0,1132.0,946.9,1214.0,918.3,1104.0,1083.0,931.3
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": {
"simulation": "Lightbulb Lifetimes",
"dataSetNumber": 42
},
"ticketData": null,
"completionTime": "2021-03-16 12:28:24Z",
"serialNumber": 6161
},
"signature": "WO0h6RmI20D8GEZbNeenoYZwz/j1g4zXqoVYX6w+mpV+6cTqwWWaaIfKZEp+lbhPb9RMuBtZd0X8k1TIw6dY+0UDWjghr/9SI9PBcrBCGVQoh4tSPItoG0F3IJ94lsxhECBGXBUqCPX6djzswmb5yP/tQ35zrpSV5IK1uCvshzgxytv0d6RSVVoTusxx/rOThOPxd+xHlR5YWdyOm8OQt3rI3G2DPvfJEoZTQRKjDSuIGjil5TW7IMxPn0Bm53HZ2gM/ELReDw1+kHpcxoMI2r3NWA+b07jx71zrZiOh/mMgD3uifO+0AB+HJCBaDYV2Sz9A814V+I/LKnk7FeKlzA+kwEGI1+RFi1qciVjn6BchvZ0eazk6ZYY2KS1yFU2kWiCWBgYoFuRmhfR8dvnct6nL2Nd/7oB2ftO7Y6oT8Q/qVBlx5EYfM13PqChQq47EbUs9b0d1hXJ7EP+GhhC0hJYmdsxZnmZEZcDgZxDRikT5T1TnBQ9fpu+OJ3k5iRo2xaQC5IVIocp1WjTvGRtngUQxt9zzqFAqonbsh5jU/Uzd2mbXeQoYeSn+a7dAOdLGM2AWJxfqeS6+hqIiYEJibvHicR5fPbg7m1qk0qDA7zmmOwZ1R01RfFu6lOUc+Rw+iRgpcsS8MgYIFL0Axp3R7CITctO0m6iWkbamtaa/67o=",
"cost": 0,
"bitsUsed": 26575,
"bitsLeft": 220238,
"requestsLeft": 976,
"advisoryDelay": 2260
},
"id": 6995
}
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 random
object contains the true random numbers (in the data
array) produced. The license shows that the values
are licensed for testing and development only. The
ticketData is null as no ticket was
used. Similarly, the pregeneratedRandomization
and licenseData properties are included with their
default values (null) as they did not appear in the
request. 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 6161st 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 random numbers from a Gaussian distribution with mean 0.0 and standard deviation 1.0, accurate up to 6 significant digits.
The client specifies that it wishes to use a ticket that was
returned in Example 2 of the generateSignedDecimalFractions
method. The first ticket in the chain was created with
showResult set to false. This means the
random values returned in response to the request will not be
included in later responses by getTicket.
{
"jsonrpc": "2.0",
"method": "generateSignedGaussians",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 10,
"mean": 0,
"standardDeviation": 1,
"significantDigits": 6,
"userData": null,
"ticketId": "4e3f60bb110a9d4a"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedGaussians",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 10,
"mean": 0,
"standardDeviation": 1,
"significantDigits": 6,
"pregeneratedRandomization": null,
"data": [
1.62113,
0.824606,
2.06339,
-0.449611,
-1.0216,
-0.821404,
0.653303,
0.981576,
-0.894676,
-1.72633
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "4e3f60bb110a9d4a",
"previousTicketId": "2b08a317fa982ec6",
"nextTicketId": "0307ed44a0750be5"
},
"completionTime": "2021-03-26 19:10:35Z",
"serialNumber": 6282
},
"signature": "I4sPBnWGETnPDr0d28VnFv6pUPAo3kUWv4NTiPoLA+8pUHfqVNkzN5klhvqjEIwPoftKX67Tf/4CR/R3XO8xdLy2fvqH5ibqewMYIyFJabTmg10e7JMCf38iggtZALDs3kxfnQcBP32gbVzcYVYFPTjXAvyPHxJyn7uRy8YEPfnxf7nLwK1aVhHDwutvN9pCKIzWCgvKkB2t3dziFfSEUZvJgAyDwMdGGxn3dCvdrJfdEBAhCiEmHIHpU/8tpYGUl6GQig/rOPkK0Jodi9feAMGW/fyDpegYPUwn2RT+HRYID/KrRRyjAUdyG/js1WymkM1knH95bqQORZfviRhQ6a+AbxwH3jwVAysN8PhtZ6QsQflfPID3e65x4m5w5JJTbdUIYzqi1+lBvxA+QBKqWCTI11ufxAzbWA7Sh+HUKnINcbJ2qQJxlxszKp79roX3ULjouyOegB2pJJDB3PhKhy56MQqpiNknsN+VYfK8r3nThW0PQEctmK7hIrYd29oRzEOHRXRrfuf4msUlGZuBw5HGszRYGXcblmoophmCd3uB95/8S4KofIZkaazNbOkOglSSsdon6Jd2YZl1tESa92h1Zt5XqTUfx3n1tHNgPkVW47DiyjFyLvOpOqkf7h/E4C5hAAUW7c61HmV/0Tzua3DT+GomKLOsOJlVFabTAmk=",
"cost": 0,
"bitsUsed": 199,
"bitsLeft": 247058,
"requestsLeft": 987,
"advisoryDelay": 3170
},
"id": 22746
}
The method, n, mean,
standardDeviation, significantDigits
and userData parameters are the same that appeared
in the request. The pregeneratedRandomization and
licenseData properties have been added with their
default values (null), despite not appearing 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 testing and development only.
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 6282nd request to be completed with this API key.
The ticketData object contains the ticketId
from the client's request. The request has now used this ticket
identifier and it will not be possible to use it again in future
calls to the API. The ticketData object contains
two other properties. The value of previousTicketId
contains the ticket that was used in Example 2 of the
generateSignedDecimalFractions method. The value of
nextTicketId contains a newly created ticket, which
the client can use for their next request.
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.
Like Example 3 above, the following requests ten random numbers from a Gaussian distribution with mean 0.0 and standard deviation 1.0, accurate up to 6 significant digits.
The client specifies that it wishes to use a ticket that was
returned in Example 3 of the generateSignedDecimalFractions
method. The first ticket in the chain was created with
showResult set to true. This will
allow the random values returned in response to the request
to also be displayed by getTicket later.
{
"jsonrpc": "2.0",
"method": "generateSignedGaussians",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 10,
"mean": 0,
"standardDeviation": 1,
"significantDigits": 6,
"pregeneratedRandomization": null,
"licenseData": null,
"userData": null,
"ticketId": "7032e9128e1dde1c"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedGaussians",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 10,
"mean": 0,
"standardDeviation": 1,
"significantDigits": 6,
"pregeneratedRandomization": null,
"data": [
0.590618,
0.69929,
-0.610013,
-0.91564,
-2.18704,
1.36777,
-2.08481,
-1.56437,
-2.62085,
0.0772126
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "7032e9128e1dde1c",
"previousTicketId": "9ab36e27a0113a34",
"nextTicketId": "d3e67f77c12f638f"
},
"completionTime": "2021-03-26 19:12:29Z",
"serialNumber": 6283
},
"signature": "wtrA9v7BgQVfldZF21tmfecZtrf3zrMEewL8NLRv8L8VzKyXeZwwAv3l4mhL1vJpb65/t1UzVl8t2FNBvK2qZBbnUE/dNkazCHTOR2+BFVARsMyyQybgmZkrlCo3d0xStHs/nCH2mA3pcEYku0Ytb6rJI499OIkxxycxS9Pz58jSIMe4W4WpEPhRr4lTIA25py8DVHaxe8naQecT1NUAelGyVkRm7B2FJUS4RvPeyPTJS+xvEHrnqqdgIQmq8DADGkivZzXTprznbXJ4PnTy5vwsCjk2vKBfDSlpZrMrPzX0eACC/sgmaZ1FPPx9IV0t54pGHL07LSPEjsx1nRcL8O8CjkX7QAwdqg+yIfbEccB0s5vrxLWci6x3nKJ/fmbdJQrlnwLjujSulJEJ0QoVUQs4qvvQbUbNAD/f3C1+EteCHawB5kltwb6zAl8J8J1aVccwae11mv+4vjEO3m2FvE0+xk25MF9haEfeUI+eUBWpNW7bnzzE5f0XV8SYss3Y6kq9AMMDqa8cUFBjzMvXzIwE6U909wQAR16080DiMCuumiwhpe4R8B1xariv++mQf5hZ/UK3dUOPHDb4wNwQAnUomL5sBTiq7aVv3Y0sl9rL3RtPOhh2RN2tEbjAsBfhrJFbwTLyopXxqYQIEE4W7BZVaGrJCnA03mNlLjp5OKc=",
"cost": 0,
"bitsUsed": 199,
"bitsLeft": 246859,
"requestsLeft": 986,
"advisoryDelay": 2750
},
"id": 22746
}
The response is very similar to that discussed under Example
3 above. The difference is visible when the getTicket
method is used to retrieve the two tickets. For this ticket,
i.e. the ticket with showResult set to true,
all of the information including the values generated will
be returned when the getTicket method is used.
The following requests five random numbers from a Gaussian
distribution with mean 50 and standard deviation 10, accurate
up to four significant digits. The client also specifies a
value of type date for the optional
pregeneratedRandomization parameter, meaning that
the results will be historical true randomness generated by
RANDOM.ORG at some point in the past.
{
"jsonrpc": "2.0",
"method": "generateSignedGaussians",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 5,
"mean": 50,
"standardDeviation": 10,
"significantDigits": 4,
"pregeneratedRandomization": {
"date": "2010-12-31"
}
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedGaussians",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 5,
"mean": 50,
"standardDeviation": 10,
"significantDigits": 4,
"pregeneratedRandomization": {
"date": "2010-12-31"
},
"data": [
56.98,
53.79,
41.23,
41.17,
41.69
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 12:44:24Z",
"serialNumber": 6162
},
"signature": "SgYJ4gseGvSxAgBccCiMeCUydMaXFC89fQzlYY6n2WXk5L2wLtUwXIRCUe3HqRuwD+NO6n7teR2Li+JUE9KHy5rApxVDWYdmELf5NWFpEu/0MkyMsmEL9WHzj+HaXwrXwSxFNK+SmGfoOvehyWa3V5cAir2PeCgPxtv69LAnRMNn6eZUSA8jZORgcceZEpp+Wxg7ixMQxujLf4YGUseMGGAO5RZFuoDALEl9I4sF9l7mhXmrbT3kOdSkqrAqcwOy8daP/+Sm2S82ufQIXdDytQdJfVNUkjl5AY3SA6+Hm7q/t1IK0DZMECKrTDf5/UISICiZRkjRdOY7MeLd2Y3Pp+LQgs/a5HCZs83XE1mbzBrMBqRrhqGK4urwNd6UL/FRWb/4TNYCziYLiT1c9QUWIxCvcAn0gyG/0aLsDRgkcr2c2OuNobPDUhHlk2JDEWUrWILx8fjUGreP43nPPmipld00KkqaV9caQRX8C/bQ6qcqwagiQt6KQ1AInbdzQ3i/bCRLooN0W6OYRPeAQzuUG7gkdAxhv08NE449WcDEbw2jEahotbg2iSRR49gOReH/P6iY9RezztSWzmbLPp9rs/v9tyLHWihFlYQXTschxBvrxvK7j0bUeR3EXVAPx6qAYh3+Tv99C9Vd6t+g+GNkRWbccOA6EtfI5GPj9MeXPz4=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 220238,
"requestsLeft": 975,
"advisoryDelay": 1660
},
"id": 6995
}
The random object contains the random numbers
returned by the server. By asking for pregenerated random values,
any request with the same specifications, i.e. the same values
for n, mean, standardDeviation,
significantDigits and pregneratedRandomization,
will return the same data. This also applies to the equivalent
method in the Basic API, see Example 4 of
the generateGaussians method.
The service also advises that this was the 6162nd request using this API key, and that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.
The following request differs from that in Example 5 only
in that the optional pregeneratedRandomization
parameter contains an id value instead of a
date value.
{
"jsonrpc": "2.0",
"method": "generateSignedGaussians",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 5,
"mean": 50,
"standardDeviation": 10,
"significantDigits": 4,
"pregeneratedRandomization": {
"id": "foobar"
}
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedGaussians",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 5,
"mean": 50,
"standardDeviation": 10,
"significantDigits": 4,
"pregeneratedRandomization": {
"id": "foobar"
},
"data": [
51.45,
42.43,
46.58,
59.34,
36.39
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 12:48:13Z",
"serialNumber": 6163
},
"signature": "C+uKqxdQRHDaft3CdWl6vA3JR5C7apYauOVZehzRSqpE3yNh2e9P2Nc6B+NezpWS/FZL8Oml0WPW2oDXM11r2J//GE/o6FLK6DGZ7DeQYih+AZ+WhTiMql5PJuyjnWvMbVXNpoOQK021FGXEwxEhrmSCPtndbro5g9wbP6CNEZqOJSzBgO4AgYV8hjPqz6mbM3fBJQ4fMD1JozKkuEhDqCNufTJMSrlQQE/A199p/Wo0knsK8I9TDRuTSrzNZ0Uh3kPUgNk+G1liAYp9yJRTHAbpDmuWzyRnuwYuHs3YWN3CX16vCSpDOkQWowN1meopV3GeMSKo75kLyc+ZXwKHR+NHTl1ReqcbN2ANPhs/anoAOUb5HnWYfmhsXqZXfbQKKJLbUzHedQKDoEj+LRWc9ATNpyeEc2Hb2vT6JLyhx80c/j4eG4uWNhQlfgXtRVPUGP8kMcW8wCcAsjwFrLtpKiniJgafcr9z9C6RH5K0lPiWTSNPCsYvzPZwQX9oaxuZkCUwUYczhaL+7FGu81obuEnz/mhm8k/QzJdGREtVCjg019SXmM82fpDrirdre9GgQZMecBImem1aGp+BmFLXX5cGHQ0ANoX6d4zE8Z2EFNZnInTYNoL8f2DLwYrg6sriU/UIyfLHDuQv7GupaCwovyvttS7OVr8ZUngMUqScbPw=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 220238,
"requestsLeft": 974,
"advisoryDelay": 2180
},
"id": 6995
}
As in Example 5, the values in the data object
were generated at some point in the past and any time a
request with the same parameters is issued, the data returned
will be identical. Making a request to generateGaussians
(i.e. the basic version of this method) with the same parameters,
will also return the same values.
The following requests ten random numbers from a Gaussian
distribution, with a mean of 100, standard deviation of 10
and an accuracy of up to six significant digits. In addition
to this, we are using an API key with a 'Flexible Gambling'
license, as opposed to the 'Developer' license used in the
other examples. Because of this, the licenseData
parameter is required. Here, we indicate that the Maximum
Payout Value (MPV) for any game or lottery using these values
is 99 USD.
{
"jsonrpc": "2.0",
"method": "generateSignedGaussians",
"params": {
"apiKey": "0e8c1eb1-cf1c-4ba8-9c2e-284f78b4bd98",
"n": 10,
"mean": 100,
"standardDeviation": 10,
"significantDigits": 6,
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
}
},
"id": 18334
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedGaussians",
"hashedApiKey": "2ySfUFzaKECQS9yl99r8gdx5izVMkyCRElp8NxNEpj0KbTLIjI5C30FRqDtp0IsdLpdV9p5N+/ReyUQyxvHXPA==",
"n": 10,
"mean": 100,
"standardDeviation": 10,
"significantDigits": 6,
"pregeneratedRandomization": null,
"data": [
90.6534, 106.38,
116.053, 78.0593,
86.841, 85.8713,
105.564, 107.499,
114.599, 87.77
],
"license": {
"type": "gambling-flexible",
"text": "Random values licensed for use in games with a payout of up to $99.00 USD",
"infoUrl": null
},
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
},
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 12:52:52Z",
"serialNumber": 5
},
"signature": "P5oeH6I/mh05enrYTV7JQq8aqHoHJvgRcbjenN3IsnDQiOAYWaNCBvwHIrZiMPX0+3SA/1OQVN4FVn0X+SVeIX0mLWI7hh+zocjGDqCKfuUBA9zG+t1U60OiAfAThgsAfWlsNFN+nCh7SmKeg9vwpyhXPuvG3rNAjqUMrniWrnaoKgZcw4qa6E9PNmVkmU9R020Gcca9hdnQQjAhD/MMlGM6T1Pcvi2Xq3x4tgY0P89S5mZ/cKtXnfh4+/0hYz2guyx7wxthdmncB33UAbgiccHjoZS5LMd6KXEP6ncykdLpQmdD/8ChPh6xDOSEUS70nKAar/7n6Ma6tEJdxqFjAGfz56/rbCICXhLhEPuf0i0vql7alEpX6IkOc+taasBqNpxqgn2VfhdjBQJgIfuTLrvqXTnoSXiLNrCFIr5kFuWTj74/cKY8pA0Fb9C/o+x/bWT2UWpInU/Gq74qOXpj0Qu6XHPlkrnrghou61GyhKk8/e28BBV0opNASu1JIOQskbSP99KmqNTqtS7O7eo0eC/8+17JAR3VtjAQ5l5vifStPKu+FZon7biX0685mPw+IBErhgsRAb2PSvJksQOvM/XmgcRWCyUKHxuo17xtEoGeWkuT6SKUxmPf5cQ544I9tjKskUtBQpAQgpljfpKBj68iwXkbXXzcYgOAw/b7T88=",
"cost": 0.0099,
"bitsUsed": 199,
"bitsLeft": 249574,
"requestsLeft": 995,
"advisoryDelay": 2070
},
"id": 18334
}
The overall result is very similar to those described in
the examples above. The primary difference here is that the
API key has a 'Flexible Gambling' license. Because of this,
the information provided for the licenseData parameter
in the request is reflected not only in the licenseData
property in the response, but also in the license
object's text property. The cost
property shows that the RANDOM.ORG account
associated with the apiKey will be charged
$0.0099 USD for making the request.
Please note that the licenseData parameter may
also be used with the 'Developer' API key, but it is not a
requirement. When used with a 'Developer' license, the
license.text property returned does not contain
any of the information given in the licenseData
parameter. It will always read
"Random values licensed strictly for development and testing only".
generateSignedStrings (method)
This method generates true random strings. Your client must
set the method property of its JSON-RPC request
object to generateSignedStrings. The request must
also contain an id member, which will be returned
in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynlengthcharacters
The following parameters are optional and can be included in
the params object of your JSON-RPC request if you
want functionality that is different from the default:
replacement (default value true)true) will cause the
strings to be picked with replacement, i.e., the resulting
list of strings may contain duplicates (like a series of dice
rolls). If you want the strings to be unique (like
raffle tickets drawn from a container), set this value to
false.
pregeneratedRandomization (default value null)null value (or does not
specify a value), then RANDOM.ORG will
generate true randomness specifically for the caller and will
discard this randomness immediately after it has been used to
generate the random values requested. This is the standard way
of using a true random number generator.
{ "date": "YYYY-MM-DD" } where YYYY-MM-DD
is a date in ISO
8601 format, then RANDOM.ORG uses
historical true randomness generated on the corresponding date.
The date must be in the past or the current date in UTC time.
{ "id": "PERSISTENT-IDENTIFIER" } where
PERSISTENT-IDENTIFIER is a string, then
RANDOM.ORG uses historical true randomness
derived from the corresponding identifier in a deterministic
manner. The identifier must have a length in the
[1,
64] range.
null forms for the
pregeneratedRandomization parameter causes
RANDOM.ORG to generate the random values
based on a pregenerated randomization, i.e., historical true
randomness generated by RANDOM.ORG at some
point in the past. This makes it possible for the client to
replay a given sequence of numbers at a later stage, and also
allows multiple parties in different locations to get the same
numbers in a predictable fashion. These modes effectively turn
RANDOM.ORG into a pseudo-random number
generator.
licenseData (default value null)apiKey. This is required
for API keys with the following license types:
Flexible Gambling.
It is optional for the following: Developer. For such API keys,
the caller must specify the Maximum Payout Value (MPV) for the
game round or lottery draw for which the true random values are
used to determine the outcome. The client must do this by specifying
for the licenseData parameter an object of the form
{ "maxPayoutValue": { "currency": "XTS", "amount": 0.0 } }
where XTS is an
ISO 4217
currency code for a currency supported by RANDOM.ORG and 0.0 is an amount expressed in that currency. The
amount given is used to construct the license object
in the response, licensing the random values as requested by the
caller, and is also used for billing. Currently, the following
currencies are supported as values for
licenseData.maxPayoutValue.currency:
USD, EUR, GBP, BTC, ETH.
userData (default value null)ticketId (default value null)createTickets method. Specifying a value for
ticketId will cause RANDOM.ORG to record that the ticket was used to generate the requested
random values. Each ticket can only be used once.
If the strings were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property
containing an object with the following named values:
randomrandom object contains the
following properties.
methodhashedApiKeyrandom object
to a third party and allow that third party to associate the
response with a given apiKey, without requiring
the client to disclose the actual apiKey.
n, length, characters,
replacement, pregeneratedRandomization
params
object. Values that are optional and did not appear in the request
will appear in the response with the default values. The reason
these are included in the response is to allow them to be signed
by RANDOM.ORG.
datalicensedata can be used.
The API key owner selects a license for each API key
created, which affects this field in the responses generated
for this API key. For example, an API key could be licensed
for non-profit use only, or for commercial gambling up to a
certain prize value per month. If a
Flexible Gambling license is used, then the license.text
property will reflect the information given in
the request's licenseData parameter.
licenseDatalicenseData
object. If the request did not contain a value for
licenseData, it will be included in the response
with the value null.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response
with the value null.
ticketDataticketId was specified
in the request, then ticketData contains an object
with the following properties: ticketId,
previousTicketId and nextTicketId.
The value in ticketData.ticketId will contain a
copy of ticketId from the request. The value of
ticketData.previousTicketId will contain the
identifier of the ticket preceding ticketId
in the chain and will be null if ticketId
was the first ticket in its chain. The value in
ticketData.nextTicketId will contain the identifier
of the newly created ticket in the chain, which will be unused
at the time when the call returns, and which can be used in future
calls to the Signed API. If the caller did not specify a value for
ticketId (or specified null) in the request,
then the value of ticketData will be null.
completionTimeserialNumberapiKey (and, consequently, within the corresponding
hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
costbitsUsedbitsLeftrequestsLeftadvisoryDelay
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., duplicate strings may be returned.
{
"jsonrpc": "2.0",
"method": "generateSignedStrings",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 8,
"length": 10,
"characters": "abcdefghijklmnopqrstuvwxyz",
"replacement": true,
"userData": null
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedStrings",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 8,
"length": 10,
"characters": "abcdefghijklmnopqrstuvwxyz",
"replacement": true,
"pregeneratedRandomization": null,
"data": [
"udyymatdsv", "wvoovwzyhx", "uxmldlbxtk", "salrxyvyrt", "izqfbvylun", "irjzsrdmvv", "kvfddurxhr", "acdhjcqkcw"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 12:59:24Z",
"serialNumber": 6164
},
"signature": "Gzd0oXxZ01ctQKm+28vsL4OjvQ/Mzdx3zvwgpZVAaQyeNKj12cO+WTETnWQuPHESBPAiieKjcoKc20I23GnHHhmcUYn/Z9ufjGo2eq4q+TDgz5czrdKrKwe4r35EqxG56xJQz4SgQ8AgmcH+JthypTxFN6xNNeXjGiQ3a4nJO0wC5tdkoRZ4/sv+TieVzJ07R8/0ANjCbZXn+qcehDJUpIhcufYlbTRzzrhs/2DkdJxrdZesEmtAT98Kaf+BYbTJJmjoesq3l8rOHXyYC4N3idYg/Ik56MHVlgch3XroeY6JKb6OumTq/YUmXO57f5wRWIcAeIxAMsTw/n/it5zJz8nnYvqXSNN71d7ZrRxAbBC4p4maBSafldcqk0SIGuLSIvtLy576dUOnrAKlYbDvOe+7hCy9Pm0gfhQaHTChYaK4h+tenpCbgbHNdbK9+cq+FKmLXwTfED3Gu59yvmhOxYymuqplTOslqZ3QmBEmHP41hdS4tb+oclx7UUfCev2Z8SLiI6iXINOxaI7IFTTScyrHvwqbCVSuGKRz1fBTFChIlpXjjo4h5/8Mj3QuuBH4GcBTwDSNOkC+tOPlxkDgHwITVchU90GN2dB7eGtEeHSJfU1X+Kzl8Y+nhwUFltJWV+6jPqMdyRPywVhFiXDvDGz3QMTToI7YJE12O66myF8=",
"cost": 0,
"bitsUsed": 376,
"bitsLeft": 219862,
"requestsLeft": 973,
"advisoryDelay": 2280
},
"id": 6995
}
The method shows which part of the
RANDOM.ORG API was used to generate
the true random strings. The hashedApiKey
allows the client to share the full contents of the
random and signature objects
with third parties without disclosing its apiKey.
The n, length, characters,
replacement and userData parameters
from the request are included too. The data array
within the result contains the true random strings
produced. The license shows that the values are
licensed for testing and development only. The ticketData
property has been added with its default value of null
because ticketId did not appear in the request.
Similarly, the pregeneratedRandomization and
licenseData are added with their default values
(null), despite not being included in the request.
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 6164th 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": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 10,
"length": 8,
"characters": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$%&*",
"replacement": false,
"userData": null
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedStrings",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 10,
"length": 8,
"characters": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$%&*",
"replacement": false,
"pregeneratedRandomization": null,
"data": [
"lE$bsLNh", "!lq8hTr2", "DovWlc2U", "Duvqrzfd", "mwIiCLvu", "KvJqbJf!", "yArwXrGv", "FLZ%CSkK", "1txAGtLQ", "%SR*$kDi"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 13:05:36Z",
"serialNumber": 6165
},
"signature": "jwl4gGED4xPBNMOY4s+6dWAL3d27nrk0UVNnMo0xEEOfGa5VdISEjsZ/tlKGViwzMP5kLHv++RX708txs1sWVyPjyM0xsnnQXyuGPDePgQUre7/sU+3vsAOXyLDRNmiCeV/kY2hpurM6JoMpFTfaYOy8LrP+x1xAy39MFDKvasI/4uugfl2kDLO+MM7HMR/BGfzeso25UegKxuxU/5T4VNdNQqZ/lr4gymwXWXOjtkdATieLnpZs3ocdZtrNsN24fOIaQi0crfCG4N27aT21mvDD2lf06j4E65fvrsCQ1WPJuVxnQvXJF2iCIn0iS3x7uowd25NrxogQFdmECRGPUeehbeiK8JBoD6PYcaJvfcJQg/wc3VmfrV5K5SKpB96PxZGT3euvEUGytqKkqFnHBCUlVt6WoZoQoM3jEG/eFoUhSAHwax/HUfbwpIPO1v64iM37yR8LYqC3w4cIiTJ6haEE8QT84se8DtifTSI0OsCXhxxq0Ag+FCkRNY4g6KAiUxRe/dSFTuWu6vBDS4DxnhM9lb83mnW1pkQi8foPdVUgvKW+4MkH2b/Dfk0oEZnEpIdMNfSmZj1weQh9eLIEaEQfb8GGfMkX7S3cG71/i8DQa/AQczkRTzxpDMVJj+cHTQWp2CERB8gKLeMe2fTy8jj0GUm9mt5kRNwt/ssyPKc=",
"cost": 0,
"bitsUsed": 487,
"bitsLeft": 219375,
"requestsLeft": 972,
"advisoryDelay": 2760
},
"id": 6995
}
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 testing and development only.
The ticketData property has been added with its
default value of null because ticketId
did not appear in the request. The pregeneratedRandomization
and licenseData properties were not given in the request,
either, but were also added to the response with their default
values (null). 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 6165th
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": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 16,
"length": 4,
"characters": "abcdefghijklmnopqrstuvwxyzæøåABCDEFGHIJKLMNOPQRSTUVWXYZÆØÅ",
"userData": null
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedStrings",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 16,
"length": 4,
"characters": "abcdefghijklmnopqrstuvwxyzæøåABCDEFGHIJKLMNOPQRSTUVWXYZÆØÅ",
"replacement": true,
"pregeneratedRandomization": null,
"data": [
"Idqo", "ZrfJ", "SIdC", "dvHÅ", "fsxd", "EYDz", "JgQm", "QrxZ", "lErU", "djjå", "fRÆY", "SSåt", "hzyb", "wAiE", "DXfÆ", "xqXR"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 13:14:21Z",
"serialNumber": 6166
},
"signature": "h9cnArscmmbdEmNGsACSMLLMkRkzXynFzKlxjUqlQLhBN0W1ZrJQW+lVjIBwIsoQQY8elBFJ/XqcGd0g+tK4zgs3BjrPJqiLZxbnc1hJs8CPf/ZEend7KibXXUy335hrOsJo/77OPeH1NZFI4LKVrRYgxVFgzow2rvv6tFk8uQ8HV7yloDRPReXOfNF1mEMJkA+sC2vZdQnzX6rsgqdvGAC3TTuljZxzjj8D2YWAFXq1Sg8EtXneHGLtO0LMoMxLKOF1mFK2D5UgeyAkWDmONctZgvAOG6TSCbO0tLNNDnoukskV8d7qh2epyvABWxNXI8Ay+MwZcbj1g6BVWtZcUSHd9HYpOLG4RwPOWQ/TOGY6cuCdXDQk9JdloIuU0lL9lTH/NdT3/3+LgJA1C/oDdxwCAzuhsp2XYHxYcPHX0bhDnLz4xNHTeQMeP8CoumozbxSVgzMgdiXAKfglocix+vjMmu7jmkpv7GMZf2LBrDx+uK4Z6DQsHl2uZBXNF8khjKeHVt38YNhxfrYUjXvVUYi/3DfXqLFFvopRTp7OcRMlNK1qaWtd9t3C0w1+xsKz4kW5B/894SWiEQftjsuBPgBOdNvsM4OjndEE6YFHOb+yZz7V27rk43WKAw3J9tpMlS8x4EMbKJwBYD/txeGVjwTjSGKaWZUYp2S/Hg1a/Mw=",
"cost": 0,
"bitsUsed": 375,
"bitsLeft": 219000,
"requestsLeft": 971,
"advisoryDelay": 1970
},
"id": 6995
}
The method, n, length,
characters and userData parameters
are the same that appeared in the request. The replacement,
pregeneratedRandomization and licenseData
parameters were not specified in the request and have therefore
been added with their respective default 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 random object contains the random data generated
by the server. The license shows that the values are
licensed for testing and development only. The ticketData
property has been added with its default value of null
because ticketId did not appear in the request. 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 6166th 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.
Similar to Example 1 above, the following requests five strings of ten characters in length using only lowercase characters from the English alphabet, while also allowing duplicate strings.
The client specifies that it wishes to use a ticket which was
returned in Example 3 in the description of the
generateSignedGaussians method. As the first ticket
in the chain was created with showResult set to
false, the random values returned in response to
this request will not be included in later responses by
getTicket.
{
"jsonrpc": "2.0",
"method": "generateSignedStrings",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 5,
"length": 10,
"characters": "abcdefghijklmnopqrstuvwxyz",
"replacement": true,
"pregeneratedRandomization": null,
"licenseData": null,
"userData": null,
"ticketId": "0307ed44a0750be5"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedStrings",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 5,
"length": 10,
"characters": "abcdefghijklmnopqrstuvwxyz",
"replacement": true,
"pregeneratedRandomization": null,
"data": [
"uxamhpkizv",
"axkpcugzvr",
"ahkzbfbzzn",
"ubvywtkgbo",
"ktxoldwjtf"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "0307ed44a0750be5",
"previousTicketId": "4e3f60bb110a9d4a",
"nextTicketId": "994554a0fefe96db"
},
"completionTime": "2021-03-26 19:14:08Z",
"serialNumber": 6284
},
"signature": "aFcEmt6sdoquRJ3/+zLRb2T09Eq8TbWUijx6v2vC5BSw5GueAedQqiUvBI//oA5r6pKzUimTyIE/0JabX8kL4ceJHc3ZUTi1CoZVQTTH1KQ34uE3dkzw7RxGN6caMhzqOY/5b30FaQNvBeihLo5w09YaX+nTlaV02Y41JFABxByD7wDgLirR8+gUZHVlPiiDINYwFgQc+hU3Vts4Brlof1lKIpXTTXp+EvGv3RfnAzpez5h37E6ftjB0VGxnrI2bLXbmlw6Tf421HHDY8GzOnJA7aQ3XA3kS1sQ7xPXIPi4uqP4m7/TBimYwoZGPIRQGXOcFCGrmF8md/Frg+PlXLxqJ68G/vyNkUy4GPsp3e/MtvHvgD5bldOhs+auv13Mkm3T/pn5ZgEDhomLq3cH15NiWH9/yvwZJn/tVwDppFI/a+PnDv2qFrjCfQAqufGYScm8fkG1BgP2v6H6hv3PRDkSy9sH8mGvS35x0fxVEwiN+MQReVN+WZqRMdnaHBhHtkv3ZHypR67kRzOrehsc+dWubiYFvkO7IoffbNmf3sNdfDC3Kfwa2PNghJ5wnKkkTdYotRv1PYeUQ7rPHGo6uFVD78CoyZKAw7OCUMa+VQjyExEibBFWJntgoVeeJlqhxmuLNjc6E/4Ju5fVIv6yctwuI9HS/zLaEox65q66IwiA=",
"cost": 0,
"bitsUsed": 235,
"bitsLeft": 246624,
"requestsLeft": 985,
"advisoryDelay": 3050
},
"id": 22746
}
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, pregeneratedRandomization,
licenseData 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 testing and development only. 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
6284th request to be completed with this API key.
The ticketData object contains the ticketId
from the client's request. The request has now used this ticket
identifier and it will not be possible to use it again in future
calls to the API. The ticketData object contains two
other properties. The value of previousTicketId contains
the identifier for the preceding ticket in the chain, which was used
in Example 3 of the generateSignedGaussians method. The
value of nextTicketId contains a newly created ticket,
which the client can use for their next request.
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.
Like Example 4 above, the following requests five strings of ten
characters in length using only lowercase characters from the English
alphabet, while also allowing duplicate strings. But this time, we
specify a ticket that was created with showResult set
to true. This will allow the random values returned in
response to the request also be displayed by getTicket
later. The ticket was returned in Example 4 in the description of
the generateSignedGaussians method.
{
"jsonrpc": "2.0",
"method": "generateSignedStrings",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 5,
"length": 10,
"characters": "abcdefghijklmnopqrstuvwxyz",
"replacement": true,
"pregeneratedRandomization": null,
"licenseData": null,
"userData": null,
"ticketId": "d3e67f77c12f638f"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedStrings",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 5,
"length": 10,
"characters": "abcdefghijklmnopqrstuvwxyz",
"replacement": true,
"pregeneratedRandomization": null,
"data": [
"zwduweojhy",
"ecgdujbmvq",
"dmcuwwksyl",
"twudbcnzcc",
"nvaotxraxm"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "d3e67f77c12f638f",
"previousTicketId": "7032e9128e1dde1c",
"nextTicketId": "0f99fedbbb5312ec"
},
"completionTime": "2021-03-26 19:17:11Z",
"serialNumber": 6285
},
"signature": "MtNQD0DTB0Vu8M63nUQc+An7xc5tqGHSpV+yRjuHObJfZNpeqiN2L8+K6sj4fPzz2H1Svl28Cna5L8VUlPZqLjZkDSTohUfWUsU1oXeFeKuUPy+GvnwL/rZbszp22Vn8rtxcaB6jth7uFOVTcRbG8qCPYO/H750EYtjLtg2jCJqB9r45mXN0pUgitk4MlRWN+mHGso98RNhUiPXtybc2Uptllbg/ciApli92MF/l4XRKkcBICbwfr+kkNt0NwNzxPRAt9ILqpGQ+J+jakLohGk3ydVe7sRurwVlarLDlBVrf9n7t3wuEuXHwDTtmA1dQh0Lvmu4yPCpR/n2WDCkC41ODhwxb011EclQDy6LTsdyb8t4oG12XnjP1/hwfBQAuPGhGaNMBbmrbnxdidufpKI6q6ihbZ+g+Ec9N660iSHRS8K5xT/nOs1QaMVTdyAFxV3pMw0bjdfzIL9M0kHQdJU2PIqlyqjrE6rwPicHubFrwWQA5jzlhXySCSDXw4Hl0zxSTfsiGB8FO4lxfcDNFWOrMgYce6wWchrVPQnZLvL+B4rD4ekJqZTi1fqM4lInF7+vG37nlYsTjUnKKbrr/LmIb5kzXU5Zo4/rFTM64PYRtnwIwwsP9Ia8rydzNFLGjERNz1qlSAKPHautIdHj7TCOr55kuyihMTsoPLpNcaKs=",
"cost": 0,
"bitsUsed": 235,
"bitsLeft": 246389,
"requestsLeft": 984,
"advisoryDelay": 2760
},
"id": 22746
}
The response is very similar to that discussed under Example
4 above. The difference is visible when the getTicket
method is used to retrieve the two tickets. For this ticket,
i.e. the ticket with showResult set to true,
all of the information including the strings generated will
be returned when the getTicket method is used.
The following requests four strings of four characters in
length using only lowercase characters from the English alphabet.
The replacement parameter is set to false,
indicating that duplicate strings are not allowed. The client also
specifies a value of type date for the optional
pregeneratedRandomization parameter, meaning that
the results will be historical true randomness generated by
RANDOM.ORG at some point in the past.
{
"jsonrpc": "2.0",
"method": "generateSignedStrings",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 4,
"length": 4,
"characters": "abcdefghijklmnopqrstuvwxyz",
"replacement": false,
"pregeneratedRandomization": {
"date": "2010-12-31"
}
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedStrings",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 4,
"length": 4,
"characters": "abcdefghijklmnopqrstuvwxyz",
"replacement": false,
"pregeneratedRandomization": {
"date": "2010-12-31"
},
"data": [
"nhij", "dikv", "olsn", "koxq"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 13:28:24Z",
"serialNumber": 6168
},
"signature": "RBRx3DQLuFKUFStiTE06MOTQZoEVmbN4X6MUEvuy0S+FK8LwoKtmsLCWZUtokz1SAY0IQXorfmUrnbefAhXccI2OXmRsF65dt3f8nEpUABIyCb/Usn5PDHQGfBAdyNKV/LWpeBMP8ErX29/FtimPdLoFKb1XMp+5DwDhjfGQHiYOztQAPszHiBEiPW/xqfpK8ocrODH0pXPINOQTUyhvhk06VgsjKn+zgP5SsFSbJK1jl9OENCew7s76ftL78oETnpzV+hlZeaujSMDhukTqoI+Yeic7DHUKBeKhf/qUBH8TYVPIYwic7qQZRMVaJa8xGAXRRb/aPvFGIWlKnL0XMqnK57HDLxm3kKMoudHs8V0Be8hgOBMZtYehLbhym1v+gVdfy1oLCdsdvxSTnV0fsgkPf713OTfUzu1nfu1n/0Nl8aDvLweRyxnsGynewwKI5+gxlXFmjIVcbC8Ljt2kfPnPajeero+02qOc9d0KF+60awJ16XqrkPHFzlVxFG5mDKExJu9FAI5A/dJbzAjw4BsU4wvariea/KjPn5KFnIiI0ZtYmn/P/Ix4LXbPdPWirb1QZEko7S5ZL4pQ/zxiD8erEMhuI/Ypk00DzG+9J9FYGLn8CsMISHyTor4KRQoXLXZ+yryYnLt5ExD2vpJyjc9FYdNE4BOUW2fp9vSrX7M=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 219000,
"requestsLeft": 969,
"advisoryDelay": 2410
},
"id": 6995
}
The random object contains the random strings
returned by the server. By asking for pregenerated random values,
any request with the same specifications, i.e. the same values
for n, length, characters,
replacement and pregneratedRandomization,
will return the same data. This also applies to the equivalent
method in the Basic API, see Example 4 of
the generateStrings method.
The service also advises that this was the 6168th request using this API key, and that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.
The following request differs from that in Example 6 only in
that the optional pregeneratedRandomization parameter
contains an id value instead of a date value.
{
"jsonrpc": "2.0",
"method": "generateSignedStrings",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 4,
"length": 4,
"characters": "abcdefghijklmnopqrstuvwxyz",
"replacement": false,
"pregeneratedRandomization": {
"id": "foobar"
}
},
"id": 6995
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedStrings",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 4,
"length": 4,
"characters": "abcdefghijklmnopqrstuvwxyz",
"replacement": false,
"pregeneratedRandomization": {
"id": "foobar"
},
"data": [
"nntf", "hdjo", "ldpl", "qxan"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 13:31:45Z",
"serialNumber": 6174
},
"signature": "hW1pu4Db4WBmEIsI/f5EOgtS5yHm+WR/vWh7YhBzN7CnfrLl2iQOqrBWSafr2EPcTIL5MLaQDN4AmlqKeDcuoGlhJ96ZFSEPOxjRJOooST7kw8p5Nq/cqioEF2kGVB5vyCd6KtStqcKpmZNt0X7GoDw6VcVmeUDTXRNlOL1sv0kTsw6Yet4McI+L9tCu08NcMFEIphA6Gd86qCeKQHWkacWTDujq1da9KX1EfwG65urt4sgxe7AfV9BzYwRhy2odZu0WjUStW6V3nlhhbI9Dj/raNXAJBsW4td56vqMyfwSKg+cytm+JgabhCEXzeUFhHDp30Sbehd0NsKcU4yAfCk2dG5XvcSV7a7Ge51kwdoGc3tzrRPq3U3T4qddvZWtKc6fDJxu8oAOol9na5n+Jd8b5fxTL4dPH4amKdzPAlnn+/fo1cT7aMAlDUJrWg3lzjKspsjOVpsfgg/VeoA3BrPAy/bhif84zTZZjoPHHBb3sfjTctSz+n6cMCY5Zv4EF3tcJgNDbKeyzzOzig/YCB+/8S8N0PsHAXcTEeN7r0PClY+KDDZEE16EPVqX/vWrqvkJBgITPQQ1qS7xC1Ss/3k4285EVsFtO50hzQPxzs3EDw1Is5ig54YGGEvMzbiv+RjjsEn2bKKoXQZIfWtWf4ypgC1Q+83YjPVDh39kLA7o=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 219000,
"requestsLeft": 963,
"advisoryDelay": 2220
},
"id": 6995
}
As in Example 6, the values in the data object
were generated at some point in the past and any time a request
with the same parameters is issued, the data returned will be
identical. Making a request to generateStrings
(i.e. the basic version of this method) with the same parameters,
will also return the same values.
The following requests five strings of five characters in length
using uppercase characters from the English alphabet and decimal
digits. The replacement parameter is set to
false, indicating that duplicate strings are not
allowed. In addition to this, we are using an API key with a
'Flexible Gambling' license, as opposed to the 'Developer'
license used in the other examples. Because of this, the
licenseData parameter is required. Here, we
indicate that the Maximum Payout Value (MPV) for any game
or lottery using these values is 99 USD.
{
"jsonrpc": "2.0",
"method": "generateSignedStrings",
"params": {
"apiKey": "0e8c1eb1-cf1c-4ba8-9c2e-284f78b4bd98",
"n": 5,
"length": 5,
"characters": "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
"replacement": false,
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
}
},
"id": 18334
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedStrings",
"hashedApiKey": "2ySfUFzaKECQS9yl99r8gdx5izVMkyCRElp8NxNEpj0KbTLIjI5C30FRqDtp0IsdLpdV9p5N+/ReyUQyxvHXPA==",
"n": 5,
"length": 5,
"characters": "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
"replacement": false,
"pregeneratedRandomization": null,
"data": [
"AWV2H", "5PGM7", "IETEK", "1HGUF", "NPXCG"
],
"license": {
"type": "gambling-flexible",
"text": "Random values licensed for use in games with a payout of up to $99.00 USD",
"infoUrl": null
},
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
},
"userData": null,
"ticketData": null,
"completionTime": "2021-03-16 13:37:19Z",
"serialNumber": 6
},
"signature": "U6jCyIj4ASgUbl7mHN+2wdn5aGVk4leCqxzvFr2zX3dT1UxliaMAyGtuaPrheofBYSz7lWBRqL8wthAZuVsnLDl/aV3EPMPW1M3Uxr2YVxPI9MSNiOhw0/bLTpIJuIs2EyduMzyS4aij4j6/qAYAs5Kng6EKJw5kQRr04gA73zTm8kq8ltoPr1M3hOBpRTPzMpUqPbLWzBX/vOMeNUW9LTLkw9yNeql5QYy+cYUtfnHENRkJhyKgqY/pv4f/MXss6ha8Spb2kKtek3o5skv9HhG4dICPD2U2EVanbbrhD9joi2+doRRg56CDe8rnV/fdNu0OG2PzhSJ2AJ7tkXEJZfxaj95Ulwq33IWGKr2AP/4CPjRQ4yGwL3xNo8xzmNs+QhzFfT/yiMunMdqcgMt2ImxUp6qjMvC87ECDuSD+UkC/Gx4GDxYX4ngSso1d2zBxhbBMF4f/AMmUWPNuBz55IYkCG+sw9eYvA+3kagR01RypzMoGRTvFiL1QHPq4JFRsMH59N5sR5aQLpKyyi93iH4OGV96Lk811UNs2SKIs7oOhWBxeE05cm6MqaZ2wS4YiutISUYrFTGCc/dW/WXdg2EpC/JFxx9Bjz019La1dZIhloHzy+tYU6HYoFig8BHGPnEEQgM5wnZ756m173JQxH5jxJCp5tQdMsCmK++7xcjk=",
"cost": 0.0099,
"bitsUsed": 129,
"bitsLeft": 249445,
"requestsLeft": 994,
"advisoryDelay": 2370
},
"id": 18334
}
The overall result is very similar to those described in the
examples above. The primary difference here is that the API
key has a 'Flexible Gambling' license. Because of this, the
information provided for the licenseData parameter
in the request, is reflected not only in the licenseData
property in the response, but also in the license
object's text property. The cost
property advises that the RANDOM.ORG account that owns
the apiKey will be charged $0.0099 USD for issuing
this request.
Please note that the licenseData parameter may also
be used with the 'Developer' API key, but it is not a requirement.
When used with a 'Developer' license, the license.text
property returned does not contain any of the information given in
the licenseData parameter. It will always read
"Random values licensed strictly for development and testing only".
generateSignedUUIDs (method)
This method generates version 4 true random
Universally Unique IDentifiers (UUIDs) in accordance with
section 4.4 of
RFC 4122. Your client must set the method property
of its JSON-RPC request object to generateSignedUUIDs.
The request must also contain an id member, which will
be returned in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeyn
The following 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:
pregeneratedRandomization (default value null)null value (or does not
specify a value), then RANDOM.ORG will
generate true randomness specifically for the caller and will
discard this randomness immediately after it has been used to
generate the random values requested. This is the standard way
of using a true random number generator.
{ "date": "YYYY-MM-DD" } where YYYY-MM-DD
is a date in ISO
8601 format, then RANDOM.ORG uses
historical true randomness generated on the corresponding date.
The date must be in the past or the current date in UTC time.
{ "id": "PERSISTENT-IDENTIFIER" } where
PERSISTENT-IDENTIFIER is a string, then
RANDOM.ORG uses historical true randomness
derived from the corresponding identifier in a deterministic
manner. The identifier must have a length in the
[1,
64] range.
null forms for the
pregeneratedRandomization parameter causes
RANDOM.ORG to generate the random values
based on a pregenerated randomization, i.e., historical true
randomness generated by RANDOM.ORG at some
point in the past. This makes it possible for the client to
replay a given sequence of numbers at a later stage, and also
allows multiple parties in different locations to get the same
numbers in a predictable fashion. These modes effectively turn
RANDOM.ORG into a pseudo-random number
generator.
licenseData (default value null)apiKey. This is required
for API keys with the following license types:
Flexible Gambling.
It is optional for the following: Developer. For such API keys,
the caller must specify the Maximum Payout Value (MPV) for the
game round or lottery draw for which the true random values are
used to determine the outcome. The client must do this by specifying
for the licenseData parameter an object of the form
{ "maxPayoutValue": { "currency": "XTS", "amount": 0.0 } }
where XTS is an
ISO 4217
currency code for a currency supported by RANDOM.ORG and 0.0 is an amount expressed in that currency. The
amount given is used to construct the license object
in the response, licensing the random values as requested by the
caller, and is also used for billing. Currently, the following
currencies are supported as values for
licenseData.maxPayoutValue.currency:
USD, EUR, GBP, BTC, ETH.
userData (default value null)ticketId (default value null)createTickets method. Specifying a value for
ticketId will cause RANDOM.ORG to record that the ticket was used to generate the requested
random values. Each ticket can only be used once.
If the UUIDs were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property
containing an object with the following named values:
randomrandom object contains the
following properties.
methodhashedApiKeyrandom object to a third
party and allow that third party to associate the response
with a given apiKey, without requiring the client
to disclose the actual apiKey.
n, pregeneratedRandomizationparams
object. The reason it is included in the response is to
allow it to be signed by RANDOM.ORG.
datalicensedata can be used.
The API key owner selects a license for each API key created,
which affects this field in the responses generated for this
API key. For example, an API key could be licensed for
non-profit use only, or for commercial gambling up to a
certain prize value per month. If a
Flexible Gambling license is used, then the license.text
property will reflect the information given in
the request's licenseData parameter.
licenseDatalicenseData
object. If the request did not contain a value for
licenseData, it will be included in the response
with the value null.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the response
with the value null.
ticketDataticketId was specified
in the request, then ticketData contains an object
with the following properties: ticketId,
previousTicketId and nextTicketId.
The value in ticketData.ticketId will contain a
copy of ticketId from the request. The value of
ticketData.previousTicketId will contain the
identifier of the ticket preceding ticketId
in the chain and will be null if ticketId
was the first ticket in its chain. The value in
ticketData.nextTicketId will contain the identifier
of the newly created ticket in the chain, which will be unused
at the time when the call returns, and which can be used in future
calls to the Signed API. If the caller did not specify a value for
ticketId (or specified null) in the request,
then the value of ticketData will be null.
completionTimeserialNumberapiKey (and, consequently, within the corresponding
hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
costbitsUsedbitsLeftrequestsLeftadvisoryDelay
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 any of the optional parameters.
{
"jsonrpc": "2.0",
"method": "generateSignedUUIDs",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 4
},
"id": 29700
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedUUIDs",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 4,
"pregeneratedRandomization": null,
"data": [
"9a00c01e-36ed-48dc-a520-9b72e9bb211d",
"b84ec99e-b9f8-4420-899c-0877c8cdb2fe",
"6cddeef4-8395-4162-be11-3c918d98aa30",
"69cbe7e2-20b7-4336-95b7-bd2596c23051"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-19 11:46:39Z",
"serialNumber": 6226
},
"signature": "WRRGf/WA/obKbuKvrKWKbW7Yh3U44VoYy2J8pwC25xxrjcvXQMrHJGEMCfRDLKM7X1p2nSO4Sk2VOlC2Z6eYEDy0it2dvWkwPgOLaslzA1G+JknbFxIWRuT294ddYuLCCLhZEriCZVcb3KE08dZNj8XAlV2uc6tBduFPJmfg75gbWa9L/qdewMbLRIWKvUMcS8/TIEgWICD9RHl4BNIUEESvM0KOPPdgtgU/bAeEJ1/ORBXHIEFLs/FV5kZnGlqNGvGhFtXgzU3d8P9oOSp/AYmj317gVhLlR0uS5D56tjuCuUQ72eoSI80yktXLZ+Tjpa9Bu0en9pGaU7pxlRY5ej/cVxedGNoVrkyAHRvwl8NAZv03ft5FlD3qI6DmB3f2gv4M6tNUKbnkroAO4LielRFfTzs4eXpiqCVHgmGA01jbmKLszn8G7eftPXLuUX51djOQSMeyIueqf89qsdmdFtaxBlY8kofceSRN8pZdop+zlYgLc5J0RznrIpeJA9Tm3WsotMfPQSkCZKfzcIJk0goaSamGSEOUt1s5P64EAbx+Ww08IhVHV0j2D7kRb10uUipIHbUX/jO9UEKn7HqRuvjIGPFTxBrimj1Wo9FY5Z1hEH7c3meRrVC3++fv9qhumdEMT5GjgdZmY8kYnY62IFhe4Qrrm3OzzS4LCgkexvw=",
"cost": 0,
"bitsUsed": 488,
"bitsLeft": 234585,
"requestsLeft": 975,
"advisoryDelay": 1820
},
"id": 29700
}
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 is included too. The pregenerateRandomization,
licenseData and userData parameters
were not specified in the request and have therefore been
added with the default value of null, even though
they did not appear in the request. The ticketData
property has been added with its default value of null
because no ticket was used in this request. The data
array within the result contains the true random
values produced. The license shows that the values
are licensed for testing and development only. The
completionTime specifies UTC time zone (‘Zulu
time’) by the letter ‘Z’ after the clock
time. The service advises that this is the 6226th 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.
As in Example 1 above, the following requests four UUIDs. In
addition to this, the client specifies that it wishes to use a
ticket which was returned in Example 4 in the description of the
generateSignedStrings method. As the first ticket
in the chain was created with showResult set to
false, the random values returned in response to
this request will not be included in later responses by
getTicket.
{
"jsonrpc": "2.0",
"method": "generateSignedUUIDs",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 4,
"pregeneratedRandomization": null,
"licenseData": null,
"userData": null,
"ticketId": "994554a0fefe96db"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedUUIDs",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 4,
"pregeneratedRandomization": null,
"data": [
"ff1b87fa-9072-488f-8cf6-b26a4db2e1ae",
"67505464-1ba1-448a-89e3-d0e86443a48b",
"b985a455-4144-4255-8d06-a06c34f59f77",
"c4885e2d-61f3-44d9-b76e-22dba7af4a4c"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "994554a0fefe96db",
"previousTicketId": "0307ed44a0750be5",
"nextTicketId": "7b87a7c5b4ae505f"
},
"completionTime": "2021-03-26 19:18:50Z",
"serialNumber": 6286
},
"signature": "0NOB0B+KmeZBCRzt2Ya8fYLQO1vGXMQGn2yKscziY6PFcF2jJKdMsOYGEq6xaAGQU/DQEtXlLFBIJ3sugwbgzfyUnurNf5fHJ83iGy/VDqLzVAHjnqVFnH1P2JG7rV17G03PbCPDsCWRl8pwAFGjs/n4aSK9jj1a6aQcBUiSjjLJzqmmSzXAtp3sC68DJ2faKLp/1fHrnTy7ac2OueGwc2/g9iK+iR1heqXC/6cxBHanyoOkjQafqD8yvhxzmi7hXMLQFC5H4TV7HWEC4aZ/JfjvdTwBQv9YJrSG6dw0hwT0z0J18YFMY2bBnBldHtPA/VeEdX+zgeFhZMcq5jDbToRWrVWZ1etw1efFhQ45XtULeDgAvzb89FpU4FmBAKobto14kxQlAZPtDEjaDZPw6lAX+33V4EaJn1vQLRlTwCif52R6opH/PH2AxWH5s8G9w7RvkL1S//YS/XPtEIeXRSb61q0kfnjH6crQO3MHhmsZchgVOjUMeOsG0pnqmktKVfWSPft0TJsPB5KEvxpet5HpvJhPY1fheDlo9Z8I8Dt5IEDv2EKWh9cTL2DQr1WAI0s2xQ5CL8cwpkw0LIZQce5NnQdnRxaC+ej7Ttqf99Ixz326+Bm3eNCm76Nd0JOWlh6Leuqq/JMkttWxazDP5zbZOZZB8fYPhcqvPsxKvIs=",
"cost": 0,
"bitsUsed": 488,
"bitsLeft": 245901,
"requestsLeft": 983,
"advisoryDelay": 2410
},
"id": 22746
}
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,
pregeneratedRandomization, licenseData
and userData parameters from the request are
included too. The data array within the
result contains the true random values produced.
The license shows that the values are licensed
for testing and development only. The completionTime
specifies UTC time zone (‘Zulu time’) by the letter
‘Z’ after the clock time. The service advises that
this is the 6286th request to be completed with this API key.
The ticketData object contains the ticketId
from the client's request. The request has now used this ticket
identifier and it will not be possible to use it again in future
calls to the API. The ticketData object contains two
other properties. The value of previousTicketId contains
the identifier for the preceding ticket in the chain, which was used
in Example 4 of the generateSignedStrings method. The
value of nextTicketId contains a newly created ticket,
which the client can use for their next request.
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.
Like Example 2 above, the following requests four UUIDs. But this
time, we specify a ticket that was created with showResult
set to true. This will allow the random values returned
in response to the request to also be displayed by getTicket
later. The ticket was returned in Example 5 in the description of the
generateSignedStrings method.
{
"jsonrpc": "2.0",
"method": "generateSignedUUIDs",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 4,
"pregeneratedRandomization": null,
"licenseData": null,
"userData": null,
"ticketId": "0f99fedbbb5312ec"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedUUIDs",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 4,
"pregeneratedRandomization": null,
"data": [
"25267020-c99c-49eb-b863-a7c69f838b2b",
"210bf89f-444d-45f1-ae63-e004ab61cf65",
"bee704ae-fe44-49c7-9848-8ceb1f4e5281",
"8cebf921-cf49-4784-b495-ee5e3aef86f2"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "0f99fedbbb5312ec",
"previousTicketId": "d3e67f77c12f638f",
"nextTicketId": "fc8324a8bce5c9b6"
},
"completionTime": "2021-03-26 19:19:32Z",
"serialNumber": 6287
},
"signature": "5pHJ/qQ6mFnBZ/xFOUX/D9468fPKhxHtC1ZodYXjmjnvvUUOHNnt0srANbG8Amzw/O8JOTvRa+VhMgwAV3PSWnCqStyxzpuPV8mgZQGH6FO3uJWE/cr7vYdlky9SWS5dMWQNC/8Rf9KKQxvIWY6mGjQ/v90jzZuvoJ+/ECemfK/V6VuymV27s0Oes32CQfYjofULdpkDbC4HYMctChjUPHO1XncjDsJpSJSFmEQ+EYpetzSE7v8bY/3imYbDbzjUDBNjPH8YuKAXSTNtgLlswgX3Pj/ckCQzMW2c/QRwurK5QlmQKelgW2gPDQA06FSLpTiZs6OZcUClCPq2HMx6zUu/h1pGMlbq6lzj0poRnK3wgzS+o7EZn6MkpAxoxHeqz+50xsbFhgI12Gx7K9KWPgYlkeLhm6SIs4h97dvg5bUfsIe7kdqGDnWa4Qh8TTapVMkCmsxhhH10RS+7GfG+wU0APsVxeciReKdL93seMLyn1iL6f/6IIp7WWo047mYojBmoka/u5QmCzP27Ykw0vW55RTMenm00Bs6aOVKfJ1bU4hQ/6dz8aecyPDijyhNvz97hUzKJJwef38qGWCcl8ZA9Fvc3sLi06Uq/6jq760MdJcg7uCHwzGdLBhnIxAT0hmgtE8TNya2XPzcTWZZCprTeFXI9YkIQ3BwLTg7Ly8s=",
"cost": 0,
"bitsUsed": 488,
"bitsLeft": 245413,
"requestsLeft": 982,
"advisoryDelay": 2390
},
"id": 22746
}
The response is very similar to that discussed under Example
2 above. The difference is visible when the getTicket
method is used to retrieve the two tickets. For this ticket,
i.e. the ticket with showResult set to true,
all of the information including the values generated will
be returned when the getTicket method is used.
The following requests three UUIDs. The client also specifies
a value of type date for the optional
pregeneratedRandomization parameter, meaning that
the results will be historical true randomness generated by
RANDOM.ORG at some point in the past.
{
"jsonrpc": "2.0",
"method": "generateSignedUUIDs",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 3,
"pregeneratedRandomization": {
"date": "2010-12-31"
}
},
"id": 29700
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedUUIDs",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"pregeneratedRandomization": {
"date": "2010-12-31"
},
"data": [
"71fba390-c5f0-4df0-8675-abdb51fe61bf",
"932ffbef-64fb-4efd-bd96-2af5de10a733",
"468fef5f-c14d-467a-92a8-8b54f8d5e3c4"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-19 16:30:10Z",
"serialNumber": 6229
},
"signature": "HcxVDj5HTQ8/4d9J83+a2zrIqe+1h5Tzjh9sEhv9vJpn+nq0/uxiRkVYpGuWTAJlllB5ehzejnxtISq/DJh3HcC2hEcgwv2m0fJja0Gu84AwEIc0iGI0cCh+BfAyOFe1sf4n8gs7UOd+VJb4RGtXNpVyOtPDtd6h5QvNCON/pXAhTQWKrn3zoCFBT6RV6+kqHMv4M+F75L5nKvRXB+fa3w+yOoNVvpYSX2WjfftpiDQzNzyx4b4fTYRjBpKYEUVN0mtFGxBGQ8WLGXb44rY4oOihfOSd+GB/Jhjeb1UUNdBmAji1xgEQbYciiiIYlm4xeR1dNlTcrROWWMEFIJ811zNoZxmHeigl9q8LHUSeW+di0hvodnDuuFGDtin8r2FkChNikiuXnM25mogfktx22++vWWotrrNYWM6BQk9sKX6L9X1+q/WMxxmiuKIgiXj4DZ7ngdt7CPxhb0/dj3kTw60ionvRygcMj7ov2Y5J+Myk0xiPNto3EuJaGNdKHGMTvL/zPrJXtc9ZTqRTI7LOvYo4JodYZpDU/k1te941+1qAaOgMm3S5LCp50s65USpNjGeyyV1fUN5fs1pxbUj67MDquMxB7esIGxyHHAVmofVigsCqjkJwZBwrOAu/ttjARPPENWSdpBZPREUJWiF6BtFvy9UBnUGyBRLIBHKyyhA=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 233609,
"requestsLeft": 972,
"advisoryDelay": 2840
},
"id": 29700
}
The random object contains the random UUIDs returned
by the server. By asking for pregenerated random values,
any request with the same specifications, i.e. the same values
for n and pregneratedRandomization,
will return the same data. This also applies to the equivalent
method in the Basic API, see Example 3 of
the generateUUIDs method.
The service also advises that this was the 6229th request using this API key, and that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.
The following request differs from that in Example 4 only in that
the optional pregeneratedRandomization parameter
contains an id value instead of a date
value.
{
"jsonrpc": "2.0",
"method": "generateSignedUUIDs",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 3,
"pregeneratedRandomization": {
"id": "foobar"
}
},
"id": 29700
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedUUIDs",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"pregeneratedRandomization": {
"id": "foobar"
},
"data": [
"7419e7a5-f3f3-402f-8b49-0e8d8d825735",
"704cca8d-a540-4c44-9ec7-07a343727641",
"e9557ad7-ec40-4ebd-b866-fe4be31bd830"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-19 16:31:23Z",
"serialNumber": 6230
},
"signature": "YnnCHoTBqMGcC0kXwNtlsID+iyn3gNaAyS8XpUFv/gZPNHAfZSIr7LtFMnAtD86SzpAtqo52+QowduFaumE/+oAkAcNd260UddQcG6rKd3i8AgW96LM6Y678/yPosoAUWmk1HXuVCok57OEQScYdxVmXUjhurkuQnVLBUWeTHvO6qzU59GZMnG/UZgVKEywJAqABEySHLd4cpYWkAcPonU70axlJmOha93CRz6HajnNso/XQWQhW8N1V1UylupXQl1O7AsfpYp7OkJ5HrKnfO7SJ9CplRPwCLaVU3VWPOQ7+9/bIkrN/t85U8tmKRfJ0TjBrfx/P72CW5hxwArdgLXhwEIaywp2uSqYWMvVulBDRObmozmQcjrhsZ4RihqijNGFumlrlEgausQ/U+ThwiLRasOQg+yuVY5oddR2CFEnQNSrdynH3cHQDzFYHose3cKELcGOQa8KiWriZbruABXMkeBbjh/FOTkyEmsaSCNappUPs2P2U1Xw/YlmQ2xVqVy46faCeRiDkqBwahrSXNH+As/vl7BuWwd3BwEjZAflV7GVnVuV1Jb66qeZBjXervR3gSJ6JgOTFDiv70OltxTz6SJHIOqOpMeZMpfRNSoR8j/j3zhq/KKzEmHfEJtVq6fu8K+ySGvoyht3Sftf8N4V8wtNJQ0jQV9bFdsPCZqI=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 233609,
"requestsLeft": 971,
"advisoryDelay": 2860
},
"id": 29700
}
As in Example 4, the values in the data object
were generated at some point in the past and any time a request
with the same parameters is issued, the data returned will be
identical. Making a request to generateUUIDs (i.e.
the basic version of this method) with the same parameters, will
also return the same values.
The following requests a single UUID. In addition to this,
we are using an API key with a 'Flexible Gambling' license, as
opposed to the 'Developer' license used in the other examples.
Because of this, thelicenseData parameter is required.
Here, we indicate that the Maximum Payout Value (MPV) for any
game or lottery using this value is 99 USD.
{
"jsonrpc": "2.0",
"method": "generateSignedUUIDs",
"params": {
"apiKey": "0e8c1eb1-cf1c-4ba8-9c2e-284f78b4bd98",
"n": 1,
"pregeneratedRandomization": null,
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
},
"userData": null,
"ticketId": null
},
"id": 22301
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedUUIDs",
"hashedApiKey": "2ySfUFzaKECQS9yl99r8gdx5izVMkyCRElp8NxNEpj0KbTLIjI5C30FRqDtp0IsdLpdV9p5N+/ReyUQyxvHXPA==",
"n": 1,
"pregeneratedRandomization": null,
"data": [
"baba1e32-37dd-4182-84e0-e7816304692c"
],
"license": {
"type": "gambling-flexible",
"text": "Random values licensed for use in games with a payout of up to $99.00 USD",
"infoUrl": null
},
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
},
"userData": null,
"ticketData": null,
"completionTime": "2021-03-19 16:37:42Z",
"serialNumber": 7
},
"signature": "Ttbr77q3De54xjwK6vIm911VquC6CIYMCbT5VXrtXcUMDirdUIzONFuYdxOV7RjQV01ZpoSNnglHz07AaEEaA0ygtBUEwhiLynfboBLZvlCM6EMOM+6yTveYYKfqib92J8EC49ce7IFzCuweSEiMvoGftxrn/0IE3hpNdLekKrIjH9w2+oAkvEvHrqdlw5Yw5rImORHRcJfGjJE4DlmQF3DfH8DdUP3s89ukVqFo7t7VhpAnrRomOKj8SVxnA4xpxtDorwqWCDz8qRxPWubSDXfBp/G9m3er5ZGkeZk4fJ8J/2kifFKnzSCRvdGJi63F91z2kvI8ISpTUD5LsudFKl2aIM/XfpWqqJB/P/yPKAh90SVbpmkXRhpT/yemJ9TqMoL5ObTEBafaXAT99eOC/iWa5i/TN6mMjyW+1fMPzkdORfZTwtxEh8qF5lamU2oOYKNABUNrzsNGnsUosGouXaTH6wKJu4B2/SIE4RF30QD+06SfwMuB2DVuhoepa/GFID/IGPpCxxsaJgk2WskItDVihBo812AWPyK1gkN857ay5qBDS7g61qN1GHByjNaFRjfLZVZJfoyukoHtnvm9HHhaoW0wVEkBMbv8Aw9f8pdHTkB1UTqMUb4KbZHSK4Ke4CLSw4zxDU7CssPCImbvcqklzLymHf0ZPzl5uXp78aA=",
"cost": 0.0099,
"bitsUsed": 122,
"bitsLeft": 999999878,
"requestsLeft": 999999,
"advisoryDelay": 2920
},
"id": 22301
}
The overall result is very similar to those described
in the examples above. The primary difference here is
that the API key has a 'Flexible Gambling' license.
Because of this, the information provided for the
licenseData parameter in the request, is
reflected not only in the licenseData
property in the response, but also in the license
object's text property. The cost
property shows that the RANDOM.ORG account that owns
the apiKey will be charged $0.0099 for this
request.
Please note that the licenseData parameter
may also be used with the 'Developer' API key, but it is
not a requirement. When used with a 'Developer' license,
the license.text property returned does not
contain any of the information given in the
licenseData parameter. It will always read
"Random values licensed strictly for development and testing only".
generateSignedBlobs (method)
This method generates
Binary
Large OBjects (BLOBs) containing true random data. Your
client must set the method property of its JSON-RPC
request object to generateSignedBlobs. The request
must also contain an id member, which will be returned
in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynsizeThe total size of all BLOBs requested must not exceed 1,048,576 bits (128 KiB).
The following parameters are optional and can be included in
the params object of your JSON-RPC request if you
want functionality that is different from the default:
format (default value base64)base64 and hex.
pregeneratedRandomization (default value null)null value (or does not
specify a value), then RANDOM.ORG will
generate true randomness specifically for the caller and will
discard this randomness immediately after it has been used to
generate the random values requested. This is the standard way
of using a true random number generator.
{ "date": "YYYY-MM-DD" } where YYYY-MM-DD
is a date in ISO
8601 format, then RANDOM.ORG uses
historical true randomness generated on the corresponding date.
The date must be in the past or the current date in UTC time.
{ "id": "PERSISTENT-IDENTIFIER" } where
PERSISTENT-IDENTIFIER is a string, then
RANDOM.ORG uses historical true randomness
derived from the corresponding identifier in a deterministic
manner. The identifier must have a length in the
[1,
64] range.
null forms for the
pregeneratedRandomization parameter causes
RANDOM.ORG to generate the random values
based on a pregenerated randomization, i.e., historical true
randomness generated by RANDOM.ORG at some
point in the past. This makes it possible for the client to
replay a given sequence of numbers at a later stage, and also
allows multiple parties in different locations to get the same
numbers in a predictable fashion. These modes effectively turn
RANDOM.ORG into a pseudo-random number
generator.
licenseData (default value null)apiKey. This is required
for API keys with the following license types:
Flexible Gambling.
It is optional for the following: Developer. For such API keys,
the caller must specify the Maximum Payout Value (MPV) for the
game round or lottery draw for which the true random values are
used to determine the outcome. The client must do this by specifying
for the licenseData parameter an object of the form
{ "maxPayoutValue": { "currency": "XTS", "amount": 0.0 } }
where XTS is an
ISO 4217
currency code for a currency supported by RANDOM.ORG and 0.0 is an amount expressed in that currency. The
amount given is used to construct the license object
in the response, licensing the random values as requested by the
caller, and is also used for billing. Currently, the following
currencies are supported as values for
licenseData.maxPayoutValue.currency:
USD, EUR, GBP, BTC, ETH.
userData (default value null)ticketId (default value null)createTickets method. Specifying a value for
ticketId will cause RANDOM.ORG to record that the ticket was used to generate the requested
random values. Each ticket can only be used once.
If the BLOBs were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property
containing an object with the following named values:
randomrandom object contains the
following properties.
methodhashedApiKeyrandom object to
a third party and allow that third party to associate the response
with a given apiKey, without requiring the client
to disclose the actual apiKey.
n, size, format,
pregeneratedRandomization
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.
dataformat
specified in the request.
licensedata can
be used. The API key owner selects a license
for each API key created, which affects this
field in the responses generated for this API
key. For example, an API key could be licensed for
non-profit use only, or for commercial gambling
up to a certain prize value per month. If a
Flexible Gambling license is used, then the license.text
property will reflect the information given in
the request's licenseData parameter.
licenseDatalicenseData
object. If the request did not contain a value for
licenseData, it will be included in the response
with the value null.
userDatauserData
object. If the request did not contain a value for
userData, it will be included in the
response with the value null.
ticketDataticketId was specified
in the request, then ticketData contains an object
with the following properties: ticketId,
previousTicketId and nextTicketId.
The value in ticketData.ticketId will contain a
copy of ticketId from the request. The value of
ticketData.previousTicketId will contain the
identifier of the ticket preceding ticketId
in the chain and will be null if ticketId
was the first ticket in its chain. The value in
ticketData.nextTicketId will contain the identifier
of the newly created ticket in the chain, which will be unused
at the time when the call returns, and which can be used in future
calls to the Signed API. If the caller did not specify a value for
ticketId (or specified null) in the request,
then the value of ticketData will be null.
completionTimeserialNumberapiKey (and, consequently, within the corresponding
hashedApiKey).
signaturerandom object,
signed with RANDOM.ORG's private key.
costbitsUsedbitsLeftrequestsLeftadvisoryDelay
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": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 1,
"size": 1024
},
"id": 29700
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedBlobs",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 1,
"size": 1024,
"format": "base64",
"pregeneratedRandomization": null,
"data": [
"54jEyAOPEeqgRQKgKV4XFQYwlQWMjEXP7KfuL29v5igzbIYcObw3ea3ML+ToKZRAWpsISBaLgZ4cqDlL+1pLM6j5wJfUh4Giu9PIU/P4lCe1b3ithEAxnd/jMoU3GQp8UwNaic5px+bhTlnrlkxfJVnBMhM/4tucCzkakiGQcfg="
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-19 11:43:44Z",
"serialNumber": 6225
},
"signature": "TX3J7Hrj+aYblFKA3IE5+b3M4/yWAatJZIAnEBxM9u7syTTiXUshZBrXKZQxqs6RpeuQid0KmW4Q2bU4qdMU2JEFlPnT8F0f2ldNviE4sLJiFTEXfLxd0SVSvKACP6032OAuoWi8be/udHZ2TN95r6+P75tf05VCGLeTwu+BK0O5/3e3OLQY98BcNirgzNjjH7504ANs03CcX78YVEAd35mhKpWXBTU6CJpAN4THMcrfA6OOSeBMOJdFQmLI/MxFiNCz+KzFOQpVREVEl3k+/GpTqZNATV3ttRiTSH9N1V3AIBe+N/RwsobHpUousk19Cae9A9WypyjJXfZg+1rRKES1dvPgMTXjDEdgXLtU0aAuY3R+cC9t/IrKyeO9dXzZa7vBeFTJV0ieQAHZTnrqWcwZFA4acFs0tJRNK2gJkN8sx2jStDf7eTZRcAhkdtyhY685FMuSCWRQNlFYVkSxMso9IhouHpqA7xi22uVsl170h6WDJpPAoRGhVtePmHUQ8VsVao2HQldPKuxzulaDX4HubgJfBZCXZ1icsE/sZP13dhfc5/RKEKusNB6nPDTXRa1UjZ5vetPvxeE6+fomeIgVgxTkjQDyvMKPYz4EbKIAPKc1UHu52VMBCMjSduHx01voQGTGguKUFfZThf7/KClqJXENpLKoqMHBSy2FD0k=",
"cost": 0,
"bitsUsed": 1024,
"bitsLeft": 235073,
"requestsLeft": 976,
"advisoryDelay": 1780
},
"id": 29700
}
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 and
size parameters from the request are included
too. The format, pregeneratedRandomization,
licenseData 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
ticketData property has been added with its
default value of null because ticketId
did not appear in the request. The completionTime
specifies UTC time zone (‘Zulu time’) by the
letter ‘Z’ after the clock time. The
serialNumber indicates that this is the 6225th
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": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 4,
"size": 6144,
"format": "hex",
"userData": null
},
"id": 8337
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedBlobs",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 4,
"size": 6144,
"format": "hex",
"pregeneratedRandomization": null,
"data": [
"64de352c028aa26588b6dd6feef07fcfbdd06c6b70c813f88d78c019b3a2aa648a0cf7e8a39e2156de4123277f1f860ed670027b551517aa5e2126ce792e92b8ea673b14d208e21d311432760a47d3800f4c9621daed3cd768b8466088e31ab9a01fecda8a6ab5a057db290413768d2366856fb691ace3c57415ef6a4c901ee5a643eee9c10f79058361f533e811bd8f7223ea8c115a6cd6e75f0e2f149c92fc75f4c0efa5b53a4e44e25fb92c4f744a1dc3c21b269f89fac84ee2747156dee1dbf707fe6acc5bc726807a59b89a6d79e48e04ab1db406e18807ffb21acf00da60e556f9f8f14d36ba6717e2d7323ffe18486ae52677391f0f45500a1df1dcc5d508fe7665bb4580e72cdb43b044d00074d029155256293d1bff08dccce0f8994d5f528db81ecfd55d3f809bd720dda9946d6a3888ebdafb06c48a8eb8adfc8a4d1ca0965b99d43aedb5d64f1c5c7e75082c21756f05c4c7df195219afb4420c8dcb4c8b3c85e79fb9f81b5fef9799ac40d3148c7fbdecc677cb7b4059b9e738b9d94269c61eda3143b89c2157ac47b607cd3d0ad83b68a6eaf4673f0a0cd5dc49aaa61acb0de2933fee963646bd4477593261468d2e19fc18cfb74268c548ff2733e3dd13ff593304a301c95aecf79d58d69615e5ba282b108283747b21681ad49ba83dde9ee96538bcc49e1c78b250bc87f011ea8acc949cfdc53092937150bde3b383b67c71ba8233bb47855bc6881dbcf5dc674c805fc227eba6ef12293fb34e763303e1cc896a33ad5e8fd495a7d5b14732b6f57e9453f79f53c068a49e214f906c6c147d9e8481bd28f2c8b895792e40173c6566c410e9969359d03d92a47aebfdab217b7608455d4122d44ead9c3fd0cb9020012a8d855273068fd124f912832f86c1e5e1853e4cb362e204c8a5775fd0af3818243ca25253556644492e33e2a745f8b1707058a9f43805ddba0a7f80a9fa4afdaacc7c8dfca0b30c617b485671b41dd9d4aae547e505b392644fa958f799d0d5f7b9d5f51184232333d8a316553ef27b3ae1de0e171d8b7fc063fb8394ba82f62b2371d5fd720a6a02",
"f4651bebf791cd628c7e4e3f6de6762aea9035205076b4cc9eadadc4f1db4cf5615ec8039b5948b688797ab0987b0cb1bebf1801f335579e42f2f8a0a5c135651524cad13e8e71b7142ace98250723d3383eff93324e104a4d164f568778890b1989efa5f3bb5f5574224618603daea91811efddb36fe32023044da9b3734b0085c5652973be1f9ef9682b36af7b677870d61af7a776b7bbd7ad5774ea86e45789fa4d8cade0c1933f82fccd083da4374abcc757afb65a652d90ef085e2c70800ec9d98b1a8708b2c76c055becbf0f2a464f60bd2bbddf3c82baa60883016c7587c771194031b820a06edf085edc34a7b0e6a146259c7d03ad5cfcb12352893c1dc420822c42277dc5afe5e8b04c348e36ff367f970fd97f7f39ab948129ec98bee25d19662503fe06866da96b9f24d8ec56e3736f084283bdfba17a26def3cd041e42470046daf12300736d75b2d0b1fb59f093048fdc9797645481bf08cc40b0bd253fa54550696ba538b3c5f034cff582c9f107cb6a8f43f4e0e24c0c63e713a94e32649cf1cfe20219ef7cd1d06ff43db753de4550243cea7f0f94b3c599e311f49d7ff8272c0a9ca7296cc490bdf4d7424885f01185f96c69431bd008bb0645fa9c2093c4c83c3ed1de6d6c6c5c52f2b91f34410bddf220b3d2560e3151f061e1a1f8e1cff836ea066a880c0a24a95d193b280c887eee913d44f9a39466f78ded907e6d67ee2f88969079d4397f921b983287667f1e540ca0eefa90d52daadcd27f8cc9fac8332ce2f8d4eb819f429eab8a03cc58e7e6c159d6636cd6e66a9c3c26d5a670887c88f4ab112e49b89dd42ac3976f9ab0b83f6a6bcb7dedd3be2e26d1979aa0cd9a72ca4f2756c9602485531db85b39536436f579bc78f7a0ee73cbe5008ae7ecb8bd6a072f725b93ac3a3c6427f1db8e540539ddc3c7dfc7ba2cfab8aee54cc381ff3bda17650c69228c9949ada559c0d245ae644a964327ff301cd3a470406f4871f38ceb648acf04e868b81e7b9a47102e24bd818418067a52d273ce47127dd7a18099b8dde66c68ecf8cdc4d3f0d466c47e22e358d92d",
"54bfa53091edf7857ac68ecb3117cb154c4a055a4ab476657d6d6673bc46776dff0fe3401d2ff6647f5173a2bbb891937560cfa65d101bdf6d3c1f3b86d5512a91709bc0dcf5793c70c0c43dcbe0a605482f838841b7416de483462731d67d1d4b6ddd3f429ff234977550fd56a3c4117c8e6b27f587a8b539e227ad6f0aed064b5cfb1225a4419d7297fcd2432bff4015e5d76dfaa57a17dda37b8d6316886c4aed045b0e041b80abd85821f3cc96e95f91659412d553b5f3a8811d55ca09fd271c44ee4d10d4c4749127a118e12ecf2145436eb538e71798fd769f83702a9f29803649b075a341817da49fc4c77f36b7860656359c101b35aff0607c22d5e8f63f787660db319fe03c93917e0bf81227db9f03a5526d6ebf20c2c9ce22f9b0dc390115ff65a166d59cd61d99507fcf004a989f1ad52d58b9b7bf296f3db6fb38edd3a980c0239154d7fe0b704cc7e20cdd51112088ae3339120b9f7480fdddeb5ba33d1b7d7663b7737f80579732f601a8f1dd72b117510a42ac7bbdbae28507bace3b35a363a0dde5b2f9069249997f01e23eb5f12980bdea0510301828301c2155412ab2e8d61f85541da73ba13af801f94471285d0b70921976dd08e04ffec3742ffaa92bb404e6e9c07c3191b3c9d9437ddc25f8a3d434bbd6e495db56ce4c56bd7b06b704c77ff5d8cef0c2b752a0d432d945751e1659bb09c9b4a38eb416c600e1c40f98d22af2007f2ac986c2e022c449b706ab2a9ca537e138878be5ce0b0c84eac897423890476706aa421967cf51b7b14ef22628c65661efb1a53426e2de73c2a495e55a9d9654895b3a427a43415cb5cf5a4d9500b1206b1e7260e87e924d03df6d2e2d209d36f3c91464a5564fb46caa384cfda009615d1a00bd41fc1a0994512f87ccc379ea472d2fd015b7e73dd83a3e4207d67f8c7f81fdc1532a56db9e17857de3d024fec3cb20e31feb22fab09b9d87f41d1c55122cdd74406fa27a67e730d8b16722b98f8db0e0510d669e2aba84673bef19a5a9c88894294460a222dffcb2060fcd53a9c7780b88a8bc177df6fb742043307f929f21",
"9a11ef78cebc27f63f84cd5aadd33d2992f92a8ccac086854e3b7f27d7d6475978b7ce297388a60bca024d766c6c7d1caac8e6f54c6e68a492a77213b4873c2227e82f0fbba30b7237f0df0ba5ba07fb41bf73a8d34a63c9684ec59ab729f1a48f88df9e2348ba80ace6beafc484dd19854eae16d2cc4dace9f8e4bec1e6c53dbe67564652ad743f3a2b696473657e3f21d63c0225fd082149a305e07e55265fab445bfbb82c91e2c3c69570c469a8598904d40c892288f0a5ff1b3a2eeee43516275aabb94d8aee2966221936c3d4211fe6e10e649de7e34e0bd0a9ad061eed11a0e5079e4f7c1478a0956ab5b60d25151cb0bde22a81236400985d7e84baab5f365c47c996ab31956d2345367c5367aa82efddc3592fe0285dd785275fd9323d16b55c517e5fe0a04efcf13d3eab7de786d3e7036667a87eba595397941d75903ac34fa9f87d17d444c33ee42db7072f3c0427d43da81ea65eb72dba6e1f420af42b102a732201dd7dd0b5e4ddd4a3f0996c2841691591deda35c91d5f7516b3b7b6e072715fccab4662d5a48ac4228405aed02d0b3494c5430597208b6ecfd0b8b561848ac36ae7d4dbfdf0a93ef8469561a13c2328d711b37c7e1405a4b0cb8d57e04d944be68e604309d0ad6234d6687fe142863d5aa1081cd5af58c7bb8ec06b45f5ee5a341c3dc0746727e21681267fdff930c90c5b71759579dbf38fb7fafda64fe2f75d34d0d2c588e1e196fbe054e6098dbab117ee1ec1e38c55d5e3ceca9a52cd77bb087a65631e7a8e4a7d8f0fb766a9231e8ea6e94650de24c2d8586f3b9288db69c361f63710e3ac9e22d7e582b3d25f618993d83157ae6e26e8a2316a3c9422b009648ede91fbe6305bc42a521971f2a7465098edddb47bd5adfed9989575226b609ff322c0cbc3fa58ae24a12f945eff46d6282b041dbb71d05ac53c65c5a50c1cb22fb537efe32bef0b5329fe43c25c1516664fb493503690a8ce289b2a3cf28cb69cfcc1de9074d46d823ef497293ff091fb5b35296381dd1eebf5c422a16b09c8c6a5f326c169722de49b27f97a9af1f49a4ad4b1f973"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-22 09:54:00Z",
"serialNumber": 6231
},
"signature": "BGtITSBikqtThAVSV6KdaNUCdc0jD6If7J6Ymts6+L3lDbe3EY7k7O9/02kwbS2ksJ5v+YbSc4qlpBX0+vevvpA1aDSUcV/D7S9Y3sKt20tiqnf5hjMB6EX4bBSVbj9ixQdEe60FaGJJMVd1kFwzTh0ELHYA6tZy1yV0cP85CD0u1vPNyRMtomEmXsabeB9tfIpgqZtbAY5HpJFq4kqR8Rgq+buZb+VFIzb8/6qMEC5X1VKATI4IFLeYGXepFQ5YMhj121t7/16IzPeg5XJ8EgvdU+B/Z1DCRo3k1xFkE1HErCnKIy/vORAHV/QZqTnuy8vXWzkba2lzI3p/YB3yt3luLAjxy/d1I3qxmXSLEZo6WTTnDvbu906Q2La+Z4WuzCUoJJL64/XS3pXVdz8YD+AI4wzdC8ddqaNACxQ49Ffn3ELhHPtRrlX03DbUSGgj+PpSChWTybDKjQC7aCiNuKyAuJtLHM+4MDwvf4EFm7yoUHcyYQSQy/9zGzXWcO5qvbKryVHa8fT3BGOKCCgPJ5/6QeM+rqF8MtsGH3NaE8NQHu118pZgCEZOc7UB7WWqUAYQRZOpe3AV9zP91TQJgTy3d4R4ZanevjYJGWLqpcUenMTSwsrsoclIMypfdWzLK1Q4zQz+Xo7e7PbgirsPYACAo5sEr5s+FRqVynQy+7o=",
"cost": 0,
"bitsUsed": 24576,
"bitsLeft": 225424,
"requestsLeft": 999,
"advisoryDelay": 1450
},
"id": 8337
}
The method, n, size,
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
testing and development only. The ticketData
property has been added with its default value of null
because no tickets were used in the request. The
pregeneratedRandomization and licenseData
properties are also included with their default values, despite
not appearing in the request. The serial number indicates that
this is the 6231st request to be completed with this API key.
The result contains a signature of the
entire random object, which allows the authenticity
of the random object to be verified. The remaining
fields in the result indicate how many true random
bits were used to satisfy the request as well as how many bits and
requests are left in the client's quota. The service advises the
client when it can issue the next request, after a short delay.
The following requests one BLOB, containing 128 true random bits
(16 bytes) encoded as a hex string. In addition to this, the client
specifies that it wishes to use a ticket which was returned in
Example 2 in the description of the generateSignedUUIDs
method. As the first ticket in the chain was created with
showResult set to false, the random values
returned in response to this request will not be included in later
responses by getTicket.
{
"jsonrpc": "2.0",
"method": "generateSignedBlobs",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 1,
"size": 128,
"format": "hex",
"pregeneratedRandomization": null,
"licenseData": null,
"userData": null,
"ticketId": "7b87a7c5b4ae505f"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedBlobs",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 1,
"size": 128,
"format": "hex",
"pregeneratedRandomization": null,
"data": [
"ff89e412283aa77c4aae3e4665ac65c2"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "7b87a7c5b4ae505f",
"previousTicketId": "994554a0fefe96db",
"nextTicketId": "ea2c0d31720d66e4"
},
"completionTime": "2021-03-26 19:21:29Z",
"serialNumber": 6288
},
"signature": "lU6EXXvA/ab2aodRoDPJ5LHGEL1Qubfc8U1WQFrzS1RZQqOc4DghTBROF5cVjPV57kP2TsPeWY5bP4QVgIgZ1NgXTmtkep7xGkqITaFUO/k9QV2yzimSM+3aVzjolstFq5ZqieSaUYaGXSN+DxqJDj49Gl7SzbS2io+Ttl1kDfzydIt1v58H6NwChuodIbsg9MglKyJW6rwc+V3YmlANQSYuSbvPwL4u3O8l7VrJ8AMG843LYvALUAy5qIAgPQsN/LEvQ+H1uyV62aQgk1pr9JiSEff9EDMszhxFOarZxOdazQxjSqdwI+46wJldyFcBM808tsRy+Mag4xtBa1NzK4+mSo6GNo9s8qJ2yAruTbPH2Bo025YE99r9jk7N30yD3HryYdmjHRWYQ/OMIQ52pbBpRjnEIkG5uMLOqaj4ateZg/jM99nvN9W82Os5HGj7fHXwSgK09I1tlU9IeFTXzjP9YvikqlZ2HsHpztBZVrAcDNDTtxxNLhNqAjVJWY/vgiqSoOYbf6Ed+Lee8BDjt7GvYqYVlneQtWltHfL34ue65wpsY1fvyQLdVHnQYyDgyjFE0S/D4cpiyfGQ2SoXn1iYwVQaqaeZF3dY3AMSaojhvjYaizH6geeLel4LUvzKmosPzXJrWp7yKopbI0tK29N4LH0V9a06c0Za1ZsNWj0=",
"cost": 0,
"bitsUsed": 128,
"bitsLeft": 245285,
"requestsLeft": 981,
"advisoryDelay": 2440
},
"id": 22746
}
The method, n, size,
format, pregeneratedRandomization,
licenseData 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 BLOB produced,
formatted as a hex string. The license shows that the
values are licensed for testing and development only. The serial
number indicates that this is the 6288th request to be completed
with this API key.
The ticketData object contains the ticketId
from the client's request. The request has now used this ticket identifier
and it will not be possible to use it again in future calls to the API.
The ticketData object contains two other properties. The
value of previousTicketId contains the identifier for the
preceding ticket in the chain, which was used in Example 2 of the
generateSignedUUIDs method. The value of
nextTicketId contains a newly created ticket, which the
client can use for their next request.
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.
Like Example 3 above, the following requests one BLOB, containing
128 true random bits (16 bytes) encoded as a hex string. But this
time, we specify a ticket that was created with showResult
set to true. This will allow the random values returned
in response to the request to also be displayed by getTicket
later. The ticket was returned in Example 3 in the description of the
generateSignedUUIDs method.
{
"jsonrpc": "2.0",
"method": "generateSignedBlobs",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 1,
"size": 128,
"format": "hex",
"pregeneratedRandomization": null,
"licenseData": null,
"userData": null,
"ticketId": "fc8324a8bce5c9b6"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedBlobs",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 1,
"size": 128,
"format": "hex",
"pregeneratedRandomization": null,
"data": [
"40332a1850b07efcb09b23b146a962f9"
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "fc8324a8bce5c9b6",
"previousTicketId": "0f99fedbbb5312ec",
"nextTicketId": "3ec86fbe9f502a95"
},
"completionTime": "2021-03-26 19:22:25Z",
"serialNumber": 6289
},
"signature": "3lRWi+StBUsnSeKwS5IUZSupd38HMdgBOW7W632tSLmmgucyQ7upaoEp3k007DrcVeQXe91r6m44Lr20PwMQaODeLxe0zScvg/X4N0NdOcbcXxFZEnmntKD5mzqEqU/ngcC56RZ08Kny9Q5+wAlY/g6Z2TQ7UScYJYAsKDf6YZ6RRXSqof3pitpuqfLESIEz9Xq/0fs+6pzM4yjx+JQGYMcXP213TmaDe57taPgPoSbGaKN3dsVHGFbiEsz6brbtturLs1SaKXDrrcKL1HtpcyHiEqeym65VL89EAUFdrHs4x49BzEpLwGPzgYSI0tYG+VpcN1swHhdgLaf6yJYl4Cp+dOE3XjyzcP6hfcby2gZc6ULoavoatSEV+w4tgV95DUOnzhlXoMQFd0DkEXcis/DhE6OTX4lp3AVwvG58Rb4sJqfWQcslpvXmnyBkMrNQYY4ft5M4VPOgC0Ph69g7vdcROex0U3UYzNuVkeQFO0MJMoM4qCZAKooNyDFty4krfXf/0gvzfTB6O5wp7PFK0OwcN8IVKQ97VRV0E5V3YY4fxd5XIhbtZfRZgXZ+eXQLz7Y3IvFidr816+FpHBifi9/dck+d5MYfpXnoip1Axm4zgCuUL+cGeSKYWnr56NhqG0wCNKK87B0MjdS+017JRTBz9aJXos82urCXMszbObw=",
"cost": 0,
"bitsUsed": 128,
"bitsLeft": 245157,
"requestsLeft": 980,
"advisoryDelay": 3300
},
"id": 22746
}
The response is very similar to that discussed under Example 3
above. The difference is visible when the getTicket
method is used to retrieve the two tickets. For this ticket,
i.e. the ticket with showResult set to true,
all of the information including the values generated will
be returned when the getTicket method is used.
The following requests three BLOBS, each containing 256 bits (32 bytes).
The client also specifies a value of type date for the
optional pregeneratedRandomization parameter, meaning
that the results will be historical true randomness generated by
RANDOM.ORG at some point in the past.
{
"jsonrpc": "2.0",
"method": "generateSignedBlobs",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 3,
"size": 256,
"pregeneratedRandomization": {
"date": "2010-12-31"
}
},
"id": 8337
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedBlobs",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"size": 256,
"format": "base64",
"pregeneratedRandomization": {
"date": "2010-12-31"
},
"data": [
"cfujkMXwDfCGdavbUf5hv5Mv++9k+779fZYq9d4QpzM=",
"Ro/vX8FN5nqSqItU+NXjxHN3/PIBXnzNWmmYsCFJ3Cw=",
"TqWS3EXlfRPrMtU1M1cMZxmicecrmWfWGqOz+3mWMBk="
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-22 10:16:17Z",
"serialNumber": 6234
},
"signature": "05271PIQaEkasO1pnn1CxltoYkBm5UY9L8czgHTWX3UljsMPr011Nr47/hSBAOcuIfFPdre5bukfN+grnabRiaXcUlK4ju5ewGLmrmeiwSHXW9ToMJMhCf2vcxwsVFknEnJq2OCsV4zUHTl/47bIIXpNkmWfQhKpYnJriNAG5ZVpiJrFXvVyyKGwxoOupED8Rhx9LG4ElsfO1g1oPKku0otfz1LVTbbRD3I+4VsfAoVsnPrZdKh5XT9n16Y81jTVFlvZhwXPbgTJa9LJzgtwmO8jd5D3Wg0ghlukSYj9LIYF+8qS+l8sAH2Q87fZ4RMsSr4vbOuSRHJuZJOI24t92757HNZMUakclg5ko+SYH6WWDlgJ+mlgUJagiSPAxg/eHHLJMMv1kHR9alKlq6/nq5W1s7aMXEDljOfi0fuVvMpL3bVuiMPqvuXgrYy/onI/Zmc0d/Pw3nZ6li3yewITzJpgoUVNjJQYnYu3MyULcIimo7o6AgaeRiTaiNjnM0EyOcl0j0nNZcV1FrEM56wfwc0AO7ISX7Vw/QCbWWLOhncggNi8MaixA6zLZIOpyxXyn4UKug1Dq3zVW+baaPvoHdqtQt897yLBVfPup6YImLTa9Jk1ueyrNpTZv7ezwaFCvLaqFGK7g/mZH04yWjW3pEJXIEq93K2VL/wermKTur8=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 225168,
"requestsLeft": 996,
"advisoryDelay": 1430
},
"id": 8337
}
The random object contains the random BLOBs returned
by the server. By asking for pregenerated random values,
any request with the same specifications, i.e. the same values
for n, size, format
and pregneratedRandomization, will return the same
data. This also applies to the equivalent method in the
Basic API, see Example 3 of the
generateBlobs method.
The service also advises that this was the 6234th request using this API key, and that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.
The following request differs from that in Example 5 only in that
the optional pregeneratedRandomization parameter
contains an id value instead of a date
value.
{
"jsonrpc": "2.0",
"method": "generateSignedBlobs",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 3,
"size": 256,
"pregeneratedRandomization": {
"id": "foobar"
}
},
"id": 8337
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedBlobs",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"size": 256,
"format": "base64",
"pregeneratedRandomization": {
"id": "foobar"
},
"data": [
"dBnnpfPzQC/LSQ6NjYJXNXBMyo2lQNxEXscHo0NydkE=",
"6VV61+xATr34Zv5L4xvYMNK4i6sJRbaZ1o4ZDl3lZn8=",
"SUAuzcxSTdaSDokWVDnGxHTthu9FSJUMORTDOBbH8Sg="
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-22 10:18:11Z",
"serialNumber": 6237
},
"signature": "HimbSF93RkwFXI5vqs1fKe0ryfGOvuKz8T3ffOEgjcroLtMeirIPyJo1UjVB4x0JdbGn5u7ghqN28vg3hNxRHiyWOpP+gTdvRiRCGJklAzlPRzCN8ZLSdAj1wOlziPKOnNIQwI3fioXgq8Tn9a1UI6qBu00dAC3Ayx7AJEE0w9RIJzHsMFeEKLwcLbsmnUxz6/MuEQn5bB50K7b7nVE46IyIeeB3lh2FwWOoAJkiJqiFo7B3bMzktU9jqiDss6nrzmLMm9zMDOtxzposKUl+uUn9EJ12TYQtlv64jT43xLKQlItNi3NIw6iU/n2Ir16+wkiKPjgiC/xvyy0UqPVeM128YB3BKx4FkiAKW9Uu/BaYaxVvKP9B5to/QMTrQ3g3mLAEYmkZeqkI3GjtKPlf9hUQQStmZp7cyqq9f4V147sKyoLvLMv4W3ttjc+3HCIjYY3o+tBdP1iOx6Er8E5sUTOTvxEvxCbzJGXnUbmVBSqpIJ0EHAad03QpLexL5MEVmU2v/S8IQltWjbfrbXUD0ejVl17LorR5F/6SpHWiqTX0W664FdRCxri5J16cc/NpfS4Wv1AAo3I+aoSuxuI+/J7i57SI0XLhQLWWUTVvhAiVxMl1nDipRjcWtLtwSgZvLDSghLFWIdCFxNd6K0uyzox8CnfO+5mtz5sWA4qiRl0=",
"cost": 0,
"bitsUsed": 0,
"bitsLeft": 225168,
"requestsLeft": 993,
"advisoryDelay": 1960
},
"id": 8337
}
As in Example 4, the values in the data object
were generated at some point in the past and any time a request
with the same parameters is issued, the data returned will be
identical. Making a request to generateBlobs (i.e.
the basic version of this method) with the same parameters, will
also return the same values.
The following requests five BLOBS with 512 bits (64 bytes) each.
In addition to this, we are using an API key with a 'Flexible
Gambling' license, as opposed to the 'Developer' license used in
the other examples. Because of this, thelicenseData
parameter is required. Here, we indicate that the Maximum Payout
Value (MPV) for any game or lottery using these values is 99 USD.
{
"jsonrpc": "2.0",
"method": "generateSignedBlobs",
"params": {
"apiKey": "0e8c1eb1-cf1c-4ba8-9c2e-284f78b4bd98",
"n": 5,
"size": 512,
"format": "base64",
"pregeneratedRandomization": null,
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
},
"userData": null,
"ticketId": null
},
"id": 2346
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedBlobs",
"hashedApiKey": "2ySfUFzaKECQS9yl99r8gdx5izVMkyCRElp8NxNEpj0KbTLIjI5C30FRqDtp0IsdLpdV9p5N+/ReyUQyxvHXPA==",
"n": 5,
"size": 512,
"format": "base64",
"pregeneratedRandomization": null,
"data": [
"tU7AI0A9ZoLNIgKNS91O9xuX+ycd4MwZaulC4zxLua7+PhTmM0X4riS53R4Ti4KSg87twb9YYOhERB9gCIOlUw==",
"XaNUILZL4YZBp3fr4tcs1Jom7qkJGqOjOVWBlogTpYASjXfot7CWNqck7m8t34Jp/uhc5zxpjuZs0dgbYg9KGQ==",
"ms6sz9x+ZsuTG3FjjSla6dKr05MnOW2e7c7PQhXZVe8OpLiWuQ1UMJK7zR4/PO5dVHHPVryI6IJae6XJbZ4l1w==",
"Hkap0wgPjdmYfGsu/e4/C394eiV3+PI+QCAWze7xsnUxhAF591NZBhlEasC8lhtCaJ+V/9UmAWSCo5QwCFk0NQ==",
"lNwpp5eICbNoEor9EJgHKrfot5nNSD0VxHcVLCnZvKHHosEcH7InS2TBif5tNsuM6kUMyVBc79fh5Z8dAEYy8Q=="
],
"license": {
"type": "gambling-flexible",
"text": "Random values licensed for use in games with a payout of up to $99.00 USD",
"infoUrl": null
},
"licenseData": {
"maxPayoutValue": {
"currency": "USD",
"amount": 99
}
},
"userData": null,
"ticketData": null,
"completionTime": "2021-03-22 10:20:14Z",
"serialNumber": 8
},
"signature": "QFIh6wNlJqzQE479DPKy9lFZhpgDWtwrPis0vgvDbP1p1Ab646ELS0K5KuWef3PBD/WSSNIPsZpLthoYeRwtshzVIKqWOuIUXgos4XS/W2tozsF0E0UGeVUzrzxhsDRly8YzRKKD+uwRyZk1MwGl+S3d93tR8uHLwDtsboWRwl9wEIobJE8EtVXcz2eXKB4FUcNmK69/NzC4fQ/JnaFsdgkhWvffguSSiKiL7j4Qr+MaYqTl+8REx+TlNR6eMMuljQMTzT193GpqOyZJ0L6M3InL+31edz3HGxeZR65vCjmuha616zdEwejFYS7QHL5YN9ZIztIon+rS8jT9zgJDyec38p6yxaoDZZ6e/6hVSnmX+ipcKzmJXdYiqhicJDcIko1BQJ/LPyaPn4fUwml8uVR2rLFZ6ywNaS/P8X6UjV6PyDU+GhDWg9zMs1mWbvWWlfQ4eJULjIcTx5OFKofxH0Bivg23kqFlpQA3L1YDjdkaQzI52dKgeEsp2uqKMwq2RBgg68mgQOI43SQsjapCZ1z1wsEI1lXJje3fd87teZHnXEHpc3P6hc85njm2qm7DDuUiMk2KTp2GpMhtMMwVJaAzZOLfDNxpcT7tnd4/g95/SzmU2ChtAo0nM8SZW5h481pn77PLmtVoQazC+1mSP/phVEgJirDTD0d37OzGWr4=",
"cost": 0.0099,
"bitsUsed": 2560,
"bitsLeft": 999997440,
"requestsLeft": 999999,
"advisoryDelay": 2020
},
"id": 2346
}
The overall result is very similar to those described in the
examples above. The primary difference here is that the API
key has a 'Flexible Gambling' license. Because of this, the
information provided for the licenseData parameter
in the request, is reflected not only in the licenseData
property in the response, but also in the license
object's text property. The cost
property shows that the cost of this request was $0.0099 USD.
This is the amount that the RANDOM.ORG account that owns the
apiKey will be charged with.
Please note that the licenseData parameter may
also be used with the 'Developer' API key, but it is not a
requirement. When used with a 'Developer' license, the
license.text property returned does not contain
any of the information given in the licenseData
parameter. It will always read
"Random values licensed strictly for development and testing only".
getUsage (method)
This method returns information related to the usage of a given
API key. Your client must set the method property
of its JSON-RPC request object to getUsage. The
request must also contain an id member, which will
be returned in the response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeyThis method has no optional parameters.
If the request succeeded, RANDOM.ORG returns
a JSON-RPC response with the result property containing
an object with the following named values:
statusstopped or running. An API key
must be running for it to be able to serve
requests.
creationTimebitsLeftrequestsLefttotalBitstotalRequests
For a successful response, the error property is
absent.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result property is
absent and the error property contains an error
object as described in Error Codes and
Messages.
The following requests usage information for an API key that exists and is running.
{
"jsonrpc": "2.0",
"method": "getUsage",
"params": {
"apiKey": "00000000-0000-0000-0000-000000000000"
},
"id": 15998
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"status": "running",
"creationTime": "2013-02-01 17:53:40Z",
"bitsLeft": 998532,
"requestsLeft": 199996,
"totalBits": 1646421,
"totalRequests": 65036
},
"id": 15998
}
RANDOM.ORG informs that the API key in question is running and advises how many bits (998,532) and requests (199,996) are left in its quota. The response also contains information about how many bits (1,646,421) and requests (65,036) have been served with this API key since it was created (on 1 February 2013 at 5.53pm UTC).
The following requests usage information for an API key that is stopped.
{
"jsonrpc": "2.0",
"method": "getUsage",
"params": {
"apiKey": "00000000-0000-0000-0000-000000000000"
},
"id": 21185
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"status": "stopped",
"creationTime": "2013-02-01 17:53:40Z",
"bitsLeft": 871365,
"requestsLeft": 199977,
"totalBits": 3519123,
"totalRequests": 69274
},
"id": 21185
}
RANDOM.ORG advises that the API key in question exists but is stopped, which means that it cannot be used to serve requests. The service also informs how many bits (871,365) and requests (199,977) are left in the quota for this API key. The response also contains information about how many bits (3,519,123) and requests (69,274) have been served with this API key since it was created (on 1 February 2013 at 5.53pm UTC).
The following requests usage information for an API key that does not exist.
{
"jsonrpc": "2.0",
"method": "getUsage",
"params": {
"apiKey": "ffffffff-ffff-ffff-ffff-ffffffffffff"
},
"id": 3677
}
The service responds with the following:
{
"jsonrpc": "2.0",
"error": {
"code": 400,
"message": "The API key you specified does not exist",
"data": null
},
"id": 3677
}
RANDOM.ORG advises that the API key in question
does not exist. More information about the error object contained
in the error property can be found
in Error Codes and Messages.
getResult (method)
When your client uses the Signed API to generate random values,
RANDOM.ORG stores the signed result for a minimum
of 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:
apiKeyserialNumberNo optional parameters.
If the historical response was found, RANDOM.ORG returns a JSON-RPC response with the result property
containing the same values that were returned by the method that
was used to generate the values. They are not listed here, since
they depend on the method that was used to generate the random values.
This is illustrated by example below.
Note that all values within the result object are
historical, including not only signature, but also
bitsUsed, bitsLeft, requestsLeft
and advisoryDelay. For this reason, the client when
invoking getResult should not adapt its behavior in
response to these properties, as it normally should when generating
random values using the Signed API.
For a successful response, the error property is
absent.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result property is
absent and the error property contains an
error object as described above.
The following requests the result generated in Example 1 from
the generateSignedIntegers method description above.
{
"jsonrpc": "2.0",
"method": "getResult",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"serialNumber": 6116
},
"id": 8337
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"pregeneratedRandomization": null,
"data": [
1, 3, 1
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-15 13:51:32Z",
"serialNumber": 6116
},
"signature": "hprai35Zc95uAM47oVpqUTEiVla/GvF+u/8GjZCvcGKRG86fQrnVvuzn1HN5VrJoU13SDE96DmggtTYECzkk9bzfVnhHg47/Zn+7w27GedseB2F4QxNtf7aycvcdBHnSg08IaVo+ohPiqlZcxpx5TVUfmLb6LfYRPirQUHMv5vpT7ba/hDSb7bQ6wGpiV1By48nDC5p/ncZEvfAHQcrNxtrtCbwQoI9BMBxRXqV5DaG6YYPxTpQeg9dWJMhZJuBNWIf4hsCKoOGkyBI/uHPaGgTy5jmSk4cFutK3jQP+9vWkDwYQ9sgok0U9Dgp5jG2zC6JOwaEgosagY7B29r1s6aXxcZCXFtX9yBdAh6Of7Z1PeLeva14lQWdZmqYSYvD56HlYWQfeb0lY2Lgf7Yvr9W/lxUxSg9OUvXi+urR0sprXpGwOcml5dSVRXyG6oyDphwXsvJ8h9ofiCP5rkyxHNphR6s1LF5NQ91OCBDllXiwXAKvJBcBxftFVAJRqpRALuLQB2xTXlrld/XBEBc93Pve3e+B0DancFa1XHgBFLlRSmF+MpSY+8qIT2U4hHSGO38ISSX2RdHYR+talXoQ8Vj6fiibzZCUNMbXp4HcYRjmWUVCii0otGYC/fSg25ZmnpG/SMJXfDbVpzx8sC49qYpaN9GRG5QC5pHfA69nJVqo=",
"cost": 0,
"bitsUsed": 8,
"bitsLeft": 249992,
"requestsLeft": 999,
"advisoryDelay": 2310
},
"id": 8337
}
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
generateSignedIntegers).
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
}
createTickets (method)
This method creates a number of tickets. The tickets can be used
in one of the methods that generate random values. Your client must
set the method property of its JSON-RPC request object
to createTickets. 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:
apiKeynshowResultgetTicket will return. If showResult is
false, getTicket will return only the
basic ticket information. If showResult is true,
the full random and signature objects from
the response that was used to satisfy the ticket is returned. For
more information, please see the documentation for getTicket.
No optional parameters.
If the request completed successfully, the response contains an array of ticket objects, each of which has the following properties:
ticketIdcreationTimenextTicketIdnextTicketId
will be null.
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 two tickets for a particular API key.
{
"jsonrpc": "2.0",
"method": "createTickets",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 2,
"showResult": false
},
"id": 22746
}
By setting showResult to false in the
request, the caller specifies that if getTicket
is later invoked for one of the tickets created, then only the
basic details of the ticket will be returned; not the random values
that the ticket was used for. For more information, please see the
documentation for the getTicket method.
The service responds with the following:
{
"jsonrpc": "2.0",
"result": [
{
"ticketId": "ca71d8928623cee5",
"creationTime": "2021-03-26 14:43:54Z",
"previousTicketId": null,
"nextTicketId": null
},
{
"ticketId": "8d8b2bded2c3ed28",
"creationTime": "2021-03-26 14:43:54Z",
"previousTicketId": null,
"nextTicketId": null
}
],
"id": 22746
}
The following requests two tickets for a particular API key.
{
"jsonrpc": "2.0",
"method": "createTickets",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"n": 2,
"showResult": true
},
"id": 22746
}
By setting showResult to true
in the request, the caller specifies that if getTicket
is later invoked for one of the tickets created, then the full
details of the ticket will be returned, including the random values
produced when the ticket was used. For more information,
please see the documentation for the getTicket method.
The service responds with the following:
{
"jsonrpc": "2.0",
"result": [
{
"ticketId": "992104b84ba7aed6",
"creationTime": "2021-03-26 14:43:27Z",
"previousTicketId": null,
"nextTicketId": null
},
{
"ticketId": "5f279f7a7aecdcd3",
"creationTime": "2021-03-26 14:43:27Z",
"previousTicketId": null,
"nextTicketId": null
}
],
"id": 22746
}
revealTickets (method)
This method marks a specific ticket and all its predecessors in its chain as being revealed,
meaning that subsequent calls to getTicket will
return the full details of the tickets, including the random values
produced when the tickets were used. Using revealTickets effectively
changes the value of showResult (which was specified when
the first ticket in the chain was created) from false to true.
The reason that not only the ticket specified (but also
its predecessors in its chain) are revealed is to
ensure maximum transparency. The method does not
affect any successors to the ticket in the chain.
Your client must set the method property of its JSON-RPC request object
to revealTickets. 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:
apiKeyticketIdNo optional parameters.
If the request completed successfully, the response contains an object with the following properties:
ticketCountrevealTickets is invoked on
a ticket that is already revealed (or which was
created with showResult set to true),
then the value for ticketCount returned will be zero.
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 a ticket to be revealed. The ticket is the first in its chain.
{
"jsonrpc": "2.0",
"method": "revealTickets",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"ticketId": "ca71d8928623cee5"
},
"id": 18873
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"ticketCount": 1
},
"id": 18873
}
Because the ticket is the first in its chain, it has no predecessors. This means that only a single ticket is revealed and the method returns a ticketCount value of 1.
The following requests a ticket to be revealed. The ticket is the third in its chain, and its two predecessors have not been revealed previously.
{
"jsonrpc": "2.0",
"method": "revealTickets",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"ticketId": "2b08a317fa982ec6"
},
"id": 5862
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"ticketCount": 3
},
"id": 5862
}
Because the ticket is the third in its chain (and the predecessors
have not been revealed already), the number of tickets revealed by the call is three.
Any successors to the ticket designated by ticketId are not affected by the call.
The following requests a ticket that is the tail in its chain, i.e., the last ticket in the chain. The tail ticket in a chain is always unused.
{
"jsonrpc": "2.0",
"method": "revealTickets",
"params": {
"apiKey": "20172d1c-aec1-432a-92ea-d2af3b1014c3",
"ticketId": "ea2c0d31720d66e4"
},
"id": 20944
}
The service responds with the following:
{
"jsonrpc": "2.0",
"error": {
"code": 426,
"message": "The ticket you specified has not yet been used",
"data": null
},
"id": 20944
}
The ticket cannot be revealed because it has not been used yet. The caller should use the ticket first and then reveal it.
listTickets (method)
This method obtains information about tickets that exist for a
given API key. Your client must set the method property
of its JSON-RPC request object to listTickets. The
request must also contain an id member, which will be
returned in the response.
The maximum number of tickets that can be returned by this method is 4000.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeyticketTypesingleton,
head and tail.
singleton will cause
listTickets to return tickets that have no
previous or next tickets, i.e., tickets that are their only
ones in their chains.
head will cause listTickets
to return tickets that do not have a previous ticket but that
do have a next ticket, i.e., tickets that are the heads in a
chain.
tail will cause listTickets
to return tickets that have a previous ticket but do not have a
next ticket, i.e., tickets that are the tails in a chain.
No optional parameters.
If the request completed successfully, the response contains an array of objects with the following properties:
ticketIdapiKey
specified in the request.
hashedApiKeyshowResultgetTicket will return for the ticket. If
showResult is false, getTicket
will return only the basic ticket information. If
showResult is true, the full
random and signature
objects from the response that was used to satisfy the
ticket is returned. For more information, please see the
documentation for getTicket.
creationTimeusedTimenull.
serialNumberserialNumber returned to obtain the full result
via the getResult method. If the ticket has not
been used yet, this value is null.
expirationTimenull.
previousTicketIdpreviousTicketId is null.
nextTicketIdnextTicketId is null.
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 obtains the details of some of the tickets created
in Examples 1 and 2 of the description of the createTickets
method:
{
"jsonrpc": "2.0",
"method": "listTickets",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"ticketType": "singleton"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": [
...,
{
"ticketId": "5f279f7a7aecdcd3",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"showResult": true,
"creationTime": "2021-03-26 14:43:27Z",
"usedTime": null,
"serialNumber": null,
"expirationTime": "2021-04-25 14:43:27Z",
"previousTicketId": null,
"nextTicketId": null
},
...,
{
"ticketId": "8d8b2bded2c3ed28",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"showResult": false,
"creationTime": "2021-03-26 14:43:54Z",
"usedTime": null,
"serialNumber": null,
"expirationTime": "2021-04-25 14:43:54Z",
"previousTicketId": null,
"nextTicketId": null
},
...
],
"id": 22746
}
The response gives the details of all singleton tickets
currently belonging to this API key. To save space, only
the singleton tickets that were created in Examples 1 and
2 of the description of the createTickets
method are shown here.
The following obtains the details of some of the tickets
created in Examples 1 and 2 of the description of the
createTickets method:
{
"jsonrpc": "2.0",
"method": "listTickets",
"params": {
"apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
"ticketType": "head"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": [
...,
{
"ticketId": "992104b84ba7aed6",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"showResult": true,
"creationTime": "2021-03-26 14:43:27Z",
"usedTime": "2021-03-26 15:19:59Z",
"serialNumber": 6277,
"expirationTime": "2021-04-25 14:43:27Z",
"previousTicketId": null,
"nextTicketId": "448c8e3467a07577"
},
...,
{
"ticketId": "ca71d8928623cee5",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"showResult": false,
"creationTime": "2021-03-26 14:43:54Z",
"usedTime": "2021-03-26 15:18:32Z",
"serialNumber": 6276,
"expirationTime": "2021-04-25 14:43:54Z",
"previousTicketId": null,
"nextTicketId": "d7563dedd09b6b80"
},
...
],
"id": 22746
}
The response originally returned the heads of every ticket
chain created by the this apiKey. To save space,
only those created in Examples 1 and 2 of the createTickets
documentation are shown here. The first tickets was also used
in Example 3 and the second in Example 4, in the description of
the generateSignedIntegers method.
getTicket (method)
This method obtains information about a single ticket. Your
client must set the method property of its JSON-RPC
request object to getTicket. 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:
ticketIdcreateTickets method.
No optional parameters.
If the request completed successfully, the response contains an object with the following properties:
ticketIdticketId specified
in the request.
hashedApiKeyshowResultgetTicket will return for the ticket. If
showResult is false, getTicket
will return only the basic ticket information. If
showResult is true, the full random
and signature objects from the response that was used to
satisfy the ticket is returned.
creationTimeusedTimenull.
serialNumberserialNumber returned to obtain the full result
via the getResult method. If the ticket has not
been used yet, this value is null.
expirationTimenull.
previousTicketIdpreviousTicketId is null.
nextTicketIdnextTicketId is null.
For a successful response, the error property is
absent. If the caller has access to the unhashed API key, it can
use the serialNumber from the response to obtain full
details of the response through the use of the getResult
method.
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 obtains the details of the ticket used in Example
3 of the description of the generateSignedIntegers
method:
{
"jsonrpc": "2.0",
"method": "getTicket",
"params": {
"ticketId": "ca71d8928623cee5"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"ticketId": "ca71d8928623cee5",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"showResult": false,
"creationTime": "2021-03-26 14:43:54Z",
"usedTime": "2021-03-26 15:18:32Z",
"serialNumber": 6276,
"expirationTime": "2021-04-25 14:43:54Z",
"previousTicketId": null,
"nextTicketId": "d7563dedd09b6b80"
},
"id": 22746
}
The response shows that the ticket exists and when it was used,
which was in Example 3 of the description of the
generateSignedIntegers method. Because the caller
specified false for the showResult parameter
when the ticket was created, the response from getTicket
method only contains the basic ticket details, not the random values
produced when the ticket was used. If the caller has the unhashed API
key corresponding to hashedApiKey, then they can call
getResult to get the full details of the response.
The following obtains the details of the second of the tickets
created in Example 1 of the description of the createTickets
method:
{
"jsonrpc": "2.0",
"method": "getTicket",
"params": {
"ticketId": "8d8b2bded2c3ed28"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"ticketId": "8d8b2bded2c3ed28",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"showResult": false,
"creationTime": "2021-03-26 14:43:54Z",
"usedTime": null,
"serialNumber": null,
"expirationTime": "2021-04-25 14:43:54Z",
"previousTicketId": null,
"nextTicketId": null
},
"id": 22746
}
The response shows that the ticket exists but that it has not been used yet.
The following obtains the details of the ticket used in Example
4 of the description of the generateSignedIntegers
method:
{
"jsonrpc": "2.0",
"method": "getTicket",
"params": {
"ticketId": "992104b84ba7aed6"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"ticketId": "992104b84ba7aed6",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"showResult": true,
"creationTime": "2021-03-26 14:43:27Z",
"usedTime": "2021-03-26 15:19:59Z",
"serialNumber": 6277,
"expirationTime": "2021-04-25 14:43:27Z",
"previousTicketId": null,
"nextTicketId": "448c8e3467a07577",
"result": {
"random": {
"method": "generateSignedIntegers",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 1,
"min": 0,
"max": 36,
"replacement": true,
"base": 10,
"pregeneratedRandomization": null,
"data": [
6
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": {
"ticketId": "992104b84ba7aed6",
"previousTicketId": null,
"nextTicketId": "448c8e3467a07577"
},
"completionTime": "2021-03-26 15:19:59Z",
"serialNumber": 6277
},
"signature": "DNELqzKkBC78nAXPk5+TnrolPSY3mzpXYXHdmrOHjyWSDAPE2YICg+02qP5pJR2xjqv+UUl0o52GHRqAB6o75cAa8qd6b6F724M7tAzlZWHKH7Z16/HGDPf82HnMvyd4xA5n0/A4vlvoX9A63hjz30O0qaivqdYEHJOevu9l3e6Q2QVMrMkd3GxCrILOquNZAjrWorMKvHITrJh8zwVxZSDU4mjGX3GEHuFBsImJloQaDrxabgZH5Sc15F6076ULfZ7dzE0W8x3+xm4IeckOo4/Z8jMV0W6AxSmAJEK2dq4xLSyWIVR6wpiPS5v0z9aHkhu6+uXh3UyQVLq3hglCm6Gx4cRTFO+vq1I5xOCXHvQc1RtWYsLbSvLWUCnDQdDwpXIq5kpYhgbbnR1tQmlsmkQOzaHF7IYoSKcg8JGM5y1fDldE+RaUgkQmMEmAMJ9SLs/67W5OW5Gjetqlg4k1rENx7PiZQ91DxJWaIA+G3v3qABDuSNVNSkqLJS6eUvAZu8lLX57FBvwYbbMH41d4fdxnJNk1jkzxeLn3PoUZ6OEnDNCdQv37xaeP/McHwQF9yazNuc/8LyNv6amkzHM0qZooXfbFgV/q3MSDhQ97wEDUiMlEJkIwFw1HFMT8aHA7ChhLxSJtINmWCfjRKZ0p3FRiDTk+uz6doKeXRuckKWo=",
"cost": 0,
"bitsUsed": 5,
"bitsLeft": 249990,
"requestsLeft": 992,
"advisoryDelay": 2430
}
},
"id": 22746
}
The response shows that the ticket exists and when it was used,
which was in Example 4 of the description of the
generateSignedIntegers method. Because the caller
specified true for the showResult parameter
when the ticket was created, the response from getTicket
contains the entire result from the method that was used to generate
the random values.
The following obtains the details of the second of the tickets
created in Example 2 of the description of the createTickets
method:
{
"jsonrpc": "2.0",
"method": "getTicket",
"params": {
"ticketId": "5f279f7a7aecdcd3"
},
"id": 22746
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"ticketId": "5f279f7a7aecdcd3",
"hashedApiKey": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"showResult": true,
"creationTime": "2021-03-26 14:43:27Z",
"usedTime": null,
"serialNumber": null,
"expirationTime": "2021-04-25 14:43:27Z",
"previousTicketId": null,
"nextTicketId": null,
"result": null
},
"id": 22746
}
The response shows that the ticket exists but that it has not
been used yet. Because showResult was set to
true when createTickets was used to
create the ticket, the response from getTicket
includes a result property. However, it is
null because the ticket has not been used yet.
The following attempts to obtain the details of a ticket that does not exist:
{
"jsonrpc": "2.0",
"method": "getTicket",
"params": {
"ticketId": "7777777777777777"
},
"id": 13354
}
The service responds with the following:
{
"jsonrpc": "2.0",
"error": {
"code": 420,
"message": "The ticket you specified does not exist",
"data": null
},
"id": 13354
}
verifySignature (method)
This method verifies the signature of a response previously
received from one of the methods in the Signed API. This is used
to examine the authenticity of numbers. Your client must set the
method property of its JSON-RPC request object to
verifySignature. The request must also contain
an id member, which will be returned in the
response.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
randomrandom field from a response returned by
RANDOM.ORG through one of the Signed API
methods.
signaturesignature field from the same response that
the random field originates from.
No optional parameters.
If the signature was examined successfully,
RANDOM.ORG returns a JSON-RPC response with
the result property containing an object with the
following named values:
authenticitytrue if the
random 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": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"pregeneratedRandomization": null,
"data": [
1, 3, 1
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-15 13:51:32Z",
"serialNumber": 6116
},
"signature": "hprai35Zc95uAM47oVpqUTEiVla/GvF+u/8GjZCvcGKRG86fQrnVvuzn1HN5VrJoU13SDE96DmggtTYECzkk9bzfVnhHg47/Zn+7w27GedseB2F4QxNtf7aycvcdBHnSg08IaVo+ohPiqlZcxpx5TVUfmLb6LfYRPirQUHMv5vpT7ba/hDSb7bQ6wGpiV1By48nDC5p/ncZEvfAHQcrNxtrtCbwQoI9BMBxRXqV5DaG6YYPxTpQeg9dWJMhZJuBNWIf4hsCKoOGkyBI/uHPaGgTy5jmSk4cFutK3jQP+9vWkDwYQ9sgok0U9Dgp5jG2zC6JOwaEgosagY7B29r1s6aXxcZCXFtX9yBdAh6Of7Z1PeLeva14lQWdZmqYSYvD56HlYWQfeb0lY2Lgf7Yvr9W/lxUxSg9OUvXi+urR0sprXpGwOcml5dSVRXyG6oyDphwXsvJ8h9ofiCP5rkyxHNphR6s1LF5NQ91OCBDllXiwXAKvJBcBxftFVAJRqpRALuLQB2xTXlrld/XBEBc93Pve3e+B0DancFa1XHgBFLlRSmF+MpSY+8qIT2U4hHSGO38ISSX2RdHYR+talXoQ8Vj6fiibzZCUNMbXp4HcYRjmWUVCii0otGYC/fSg25ZmnpG/SMJXfDbVpzx8sC49qYpaN9GRG5QC5pHfA69nJVqo="
},
"id": 8337
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"authenticity": true
},
"id": 8337
}
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 1 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": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 3,
"min": 1,
"max": 6,
"replacement": true,
"base": 10,
"pregeneratedRandomization": null,
"data": [
6, 3, 1
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": null,
"ticketData": null,
"completionTime": "2021-03-15 13:51:32Z",
"serialNumber": 6116
},
"signature": "hprai35Zc95uAM47oVpqUTEiVla/GvF+u/8GjZCvcGKRG86fQrnVvuzn1HN5VrJoU13SDE96DmggtTYECzkk9bzfVnhHg47/Zn+7w27GedseB2F4QxNtf7aycvcdBHnSg08IaVo+ohPiqlZcxpx5TVUfmLb6LfYRPirQUHMv5vpT7ba/hDSb7bQ6wGpiV1By48nDC5p/ncZEvfAHQcrNxtrtCbwQoI9BMBxRXqV5DaG6YYPxTpQeg9dWJMhZJuBNWIf4hsCKoOGkyBI/uHPaGgTy5jmSk4cFutK3jQP+9vWkDwYQ9sgok0U9Dgp5jG2zC6JOwaEgosagY7B29r1s6aXxcZCXFtX9yBdAh6Of7Z1PeLeva14lQWdZmqYSYvD56HlYWQfeb0lY2Lgf7Yvr9W/lxUxSg9OUvXi+urR0sprXpGwOcml5dSVRXyG6oyDphwXsvJ8h9ofiCP5rkyxHNphR6s1LF5NQ91OCBDllXiwXAKvJBcBxftFVAJRqpRALuLQB2xTXlrld/XBEBc93Pve3e+B0DancFa1XHgBFLlRSmF+MpSY+8qIT2U4hHSGO38ISSX2RdHYR+talXoQ8Vj6fiibzZCUNMbXp4HcYRjmWUVCii0otGYC/fSg25ZmnpG/SMJXfDbVpzx8sC49qYpaN9GRG5QC5pHfA69nJVqo="
},
"id": 8337
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"authenticity": false
},
"id": 8337
}
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": "ncGk4bCmDT7GSc64MzGzNvRUoDT++pTPjntmtuu075JFqKbz/G4nKerq0JQoldvtQxYOCePxMN5gcYZSOC2DTg==",
"n": 52,
"min": 1,
"max": 52,
"replacement": false,
"base": 10,
"pregeneratedRandomization": null,
"data": [
45, 1, 43, 18, 25, 23, 11, 50, 38, 15, 34, 9, 30, 33, 48, 20, 29, 19, 2, 47, 40, 16, 14, 3, 6, 46, 12, 10, 7, 26, 35, 41, 13, 24, 49, 42, 32, 31, 4, 51, 27, 8, 37, 52, 28, 22, 44, 39, 21, 36, 5, 17
],
"license": {
"type": "developer",
"text": "Random values licensed strictly for development and testing only",
"infoUrl": null
},
"licenseData": null,
"userData": {
"myHashType": "md5",
"myHashValue": "a7d8eb2cb9c55110a91e2a80b7932177"
},
"ticketData": null,
"completionTime": "2021-03-15 14:40:05Z",
"serialNumber": 6126
},
"signature": "xlmLISGNHgy0S5zBmwn3D1ogtqkpj8thJmkqZQQC1muO6nHxCUhQ5OELFlsnYVkyaJ2xX+J1wlltM6RfrfbdOUKozEHiZ7cuRt/FRbRyl7MI/JlFHi4DiPvAPIbhHWh4JgHZcC/b3r1MzjspYJ+UGIYd60oGsjxbKA4gXas5EE6JRZTi2rZeeqmwVXIWoR8lrEuvQffwUghR0wHXZStOMikyyjbrR7WYDqmEbonkQpM7S+vfdLyNYzQF2JKa1AxImKI963njWgt5D8OvsZz875c6dxkgL/uNt4OhZi4LA/kH2moDn3r67yVBLov7Iq6XDBWU+Ory3T318L3NTP7y2WEeGt94tuoVqarU574J68Whg6QPus3vEi8D0AxAmBuMdV573u9IxdKbiXiUjMjdExtMH7lVwqpmMtPU+BDyHvVh7rK/SQmKifqEmN3Dzz5vq3O61YUdERUwhDgAcfcERyJZyhqHzaB4l/nms2KMpmBbYqdvi515NEX/iF3eqdvsg0ctkzpfxJAsGymQmYRe0r46LJAj/SDZ79XrGRvRIiXGlu8YRR+rctMCrL6328BgLFWXPVzA5krhusEqvAcxIi38+d+F8CUA0/cBORVF2h0fX+/JTNi2AvHuGzTCLsHCyxaqmxWOP5aPbYToz3Wet3jIPWRjE+JUfGDGjj+80hI="
},
"id": 8337
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"authenticity": false
},
"id": 8337
}
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.