Guides → QRNG

As of January 1, 2025, API3 will no longer be supporting the QRNG service. Learn more

SearchHighlight.vue

FLEX_START_TAG

Getting Started with QRNG

This is the getting started section for QRNG along with some frequently asked questions. If you have a question that is not answered here, you can head over to our Discord server.

What is the QRNG?

QRNG stands for Quantum Random Number Generator. It is a free to use service that provides quantum randomness on-chain. It is powered by Airnode, the first-party oracle that is directly operated by the QRNG API providers. You can read more about QRNG here.

How many providers are there for QRNG?

Currently, there are 4 providers for QRNG:

• Australian National University
• Quintessence Labs
• Quantum Blockchains Random Numbers
• Testnet Random Numbers

Click here to view the list of providers.

ANU, Quintessence Labs and Quantum Blockchains are running Airnodes in production serving 20+ chains. Testnet Random Numbers emulates QRNG using pseudorandom numbers on testnets.

Click here to view the list of chains where QRNG is available.

How can you access QRNG?

The qrng-example project demonstrates how to build a smart contract (known as a requester) using the Airnode Request–Response Protocol (RRP) to access QRNG services. It is recommended to run the example project to learn how it uses the QRNG service on a testnet, and read the associated README file. It also contains example code that will be useful when creating a requester (smart contract) that requests a quantum random number.

• qrng-example/contracts/
  • QrngExamples.sol: A sample requester used to call the QRNG service.
• qrng-example/deploy/
  • deploy.js: Script that deploys a requester to a chain.
  • setup.js: Script that sets the parameters on the requester contract. These parameters are used when calling the QRNG Airnode.
  • fund.js: Script that funds the sponsorWallet the requester uses to pay the gas costs.

Gas Costs

Using the QRNG service is free, meaning there is no subscription fee to pay. There is a gas cost incurred on-chain when Airnode submits the random number on-chain in response to a request, which the requester needs to pay for.

Sponsor Wallet

The QRNG example project sets the sponsor wallet using the requester address. The wallet is then used to pay gas costs when the Airnode responds to a request. An alternate method is to use the Admin CLI as is the case with the Using QRNG - Remix Example guide.

Designated Sponsor Wallets

Sponsors should not fund a sponsorWallet with more than they can trust the Airnode with, as the Airnode controls the private key to the sponsorWallet. The deployer of such Airnode undertakes no custody obligations, and the risk of loss or misuse of any excess funds sent to the sponsorWallet remains with the sponsor.

Withdrawals

In the QRNG example project, the requester contract was written with the scope of demonstrating on-chain requests for random numbers.

WARNING

For brevity, the requester contract does not contain withdrawal or other additional functionality.

For those inclined, withdrawal functionality can be added to the requester contract. Check out the Requester contract in Using QRNG - Remix Example guide for an example on adding a withdrawal function to the requester contract and requesting a withdrawal from the Airnode.

How much does it cost to use QRNG?

QRNG is free to use. You can use it as much as you want without paying anything. However, you will have to fund the sponsorWallet that incurs the gas fees for the transaction for the fulfillment of the request. A sponsorWallet address is derived from the requester contract address, the QRNG Airnode address and its extended public key (xpub). A sponsor wallet must be derived using the command derive-sponsor-wallet-address from the Admin CLI for your specific requester contract.

You can refer to the funding table below to get an idea of how much you will have to fund the sponsorWallet for a request on a specific chain.

Funding table reference

Testnet	Amount	Unit	Chain Id
Ethereum-Goerli	0.1	ETH	5
Ethereum-Sepolia	0.05	SEP	11155111
RSK testnet	0.001	tRBTC	31
POA Network Sokol testnet	0.05	POA	77
BNB Chain testnet	0.005	tBNB	97
Optimism testnet	0.05	ETH	420
Moonbase Alpha testnet	0.1	DEV	1287
Fantom testnet	0.5	FTM	4002
Avalanche Fuji testnet	0.3	AVAX	43113
Polygon Mumbai testnet	0.05	MATIC	80001
Milkomeda C1 testnet	0.5	mTAda	200101
Arbitrum testnet	0.01	AGOR	421613

You can read more about sponsorWallethere.

How to request a single random number?

To request a single random number, use the endpointIdUint256 of the QRNG provider while making the request. You can find all the parameters of the QRNG providers here. To see how to code a basic QRNG Requester contract and make a request for a single random number, click here.

How to request multiple random numbers?

Similar to requesting a single random number, you can request multiple random numbers by using the endpointIdUint256Array of the QRNG provider while making the request. It returns an array of random numbers. You will also have to mention the size of the array and encode it within the parameters. To see how to code a basic QRNG Requester contract and make a request for an array of random numbers, click here.

How to request a random number within a range?

To have a random number within a specific range while making a request to the QRNG Airnode, you can use the endpointIdUint256 to return a single random number and have it modulo the range difference and add the minimum number of the range. Refer to the code snippet below to see how to convert the random number and have it within the range [x, y].

uint256 randomNumber = (qrngUint256 % (y - x + 1)) + x;
// y is the max number for the range, x is min number for the range.
// the randomNumber will be in range [x, y].

Can additional chains be supported?

At the moment, we've paused new QRNG chain integrations. If additional chains were to be supported in the future, support would be more likely on chains with active dAPIs.

FLEX_END_TAG