---
title: Generate Random Numbers On-chain
description: Learn how to integrate Pyth Entropy to generate random numbers in your dapp
icon: Code
---

import { Step, Steps } from "fumadocs-ui/components/steps";

This guide explains how to integrate Pyth Entropy into EVM Contracts to generate on-chain random numbers.
The intended audience for this guide is developers of any application that needs on-chain randomness, such as NFT mints or games.

## Install the SDK

Pyth Entropy has a [Solidity SDK](https://github.com/pyth-network/pyth-crosschain/tree/main/target_chains/ethereum/entropy_sdk/solidity) that lets your contract interact with the Entropy contract.
Install the SDK using your package manager:

<Tabs items={['hardhat', 'foundry']}>
<Tab value="hardhat">
```shell copy
npm install @pythnetwork/entropy-sdk-solidity
```
</Tab>
<Tab value="foundry">
```shell copy
npm init -y
npm install @pythnetwork/entropy-sdk-solidity
```

Then add the following line to your `remappings.txt` file:

```text copy
@pythnetwork/entropy-sdk-solidity/=node_modules/@pythnetwork/entropy-sdk-solidity
```

</Tab>
</Tabs>

## Setup

The Solidity SDK exports two interfaces:

- [`IEntropyConsumer`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/IEntropyConsumer.sol) - The interface that your contract should implement. It makes sure that your contract is compliant with the Entropy contract.
- [`IEntropyV2`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/IEntropyV2.sol) - The interface to interact with the Entropy contract.
  You will need the address of an Entropy contract on your blockchain.
  Consult the current [Entropy contract addresses](./entropy/chainlist) to find the address on your chain.
  Once you have a contract address, instantiate an `console.log("IEntropyV2"){:bash}` contract in your solidity contract:

```solidity copy
code={`import { IEntropyConsumer } from "@pythnetwork/entropy-sdk-solidity/IEntropyConsumer.sol";
import { IEntropyV2 } from "@pythnetwork/entropy-sdk-solidity/IEntropyV2.sol";

// @param entropyAddress The address of the entropy contract.
contract YourContract is IEntropyConsumer {
IEntropyV2 public entropy;
  constructor(address entropyAddress) {
    entropy = IEntropyV2(entropyAddress);
  }
}
```

## Usage

To generate a random number, follow these steps.

<Steps>
<Step>
### Request a number from Entropy

Invoke the [`requestV2`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/IEntropy.sol#L83) method of the `IEntropyV2` interface.
The `console.log("requestV2"){:bash}` method requires paying a fee in native gas tokens which is configured per-provider.

The fee differs for every chain and also varies over time depending on the chain's current gas price.
The current value for each chain can be found on the [chainlist and fee details](./entropy/chainlist) page.
However, you should use the on-chain method [`getFeeV2`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/IEntropy.sol#L101) to compute the required fee and send it as the value of the `requestV2{:bash}` call.

These methods use the default randomness provider.

```solidity copy
function requestRandomNumber() external payable {
  uint256 fee = entropy.getFeeV2();
  uint64 sequenceNumber = entropy.requestV2{ value: fee }();
}
```

This method returns a sequence number and emits a [`Requested`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/EntropyEventsV2.sol#L30) event. You can store this sequence number to identify the request in next step.

Note that there are several variants of `requestV2` that allow the caller to configure the provider fulfilling the request and the gas limit for the callback. Refer [request callback variants](./entropy/request-callback-variants.mdx) for more details.

Please see the method documentation in the [IEntropyV2 interface](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/IEntropyV2.sol).

</Step>
<Step>

### Implement the Entropy callback

```solidity copy
pragma solidity ^0.8.0;

import { IEntropyConsumer } from "@pythnetwork/entropy-sdk-solidity/IEntropyConsumer.sol";
import { IEntropyV2 } from "@pythnetwork/entropy-sdk-solidity/IEntropyV2.sol";

contract YourContract is IEntropyConsumer {
IEntropyV2 entropy;

    // @param entropyAddress The address of the entropy contract.
    constructor(address entropyAddress) {
        entropy = IEntropyV2(entropyAddress);
    }

    function requestRandomNumber() external payable {
        // Get the fee for the request
        uint256 fee = entropy.getFeeV2();

        // Request the random number with the callback
        uint64 sequenceNumber = entropy.requestV2{ value: fee }();
        // Store the sequence number to identify the callback request

    }

    // @param sequenceNumber The sequence number of the request.
    // @param provider The address of the provider that generated the random number. If your app uses multiple providers, you can use this argument to distinguish which one is calling the app back.
    // @param randomNumber The generated random number.
    // This method is called by the entropy contract when a random number is generated.
    // This method **must** be implemented on the same contract that requested the random number.
    // This method should **never** return an error -- if it returns an error, then the keeper will not be able to invoke the callback.
    // If you are having problems receiving the callback, the most likely cause is that the callback is erroring.
    // See the callback debugging guide here to identify the error https://docs.pyth.network/entropy/debug-callback-failures
    function entropyCallback(
    uint64 sequenceNumber,
    address provider,
    bytes32 randomNumber
    ) internal override {
        // Implement your callback logic here.
    }

    // This method is required by the IEntropyConsumer interface.
    // It returns the address of the entropy contract which will call the callback.
    function getEntropy() internal view override returns (address) {
        return address(entropy);
    }

}
```

</Step>
</Steps>

When the final random number is ready to use, the entropyCallback function will be called by the Entropy contract. This will happen in a separate transaction submitted by the requested provider.

<Callout variant="warning">
  The `entropyCallback` function on your contract should **never** return an
  error. If it returns an error, the keeper will not be able to invoke the
  callback. If you are having problems receiving the callback, please see
  [Debugging Callback Failures](./entropy/debug-callback-failures).
</Callout>

## Additional Resources

You may find these additional resources helpful while integrating Pyth Entropy into your EVM contract.

### Debug Callback Failures

Check how to [Debug Callback Failures](./entropy/debug-callback-failures) if you are having trouble getting the callback to run.

### Pyth Entropy Contract Addresses

Consult the [Entropy contract addresses](./entropy/chainlist) to find the Entropy contract address on your chain.

### Current Fees

Check the [Current Fees](./entropy/current-fees) to find the current fee for each provider on your chain.

### Transform Entropy Results

Check out the [Transform Entropy Results](./entropy/transform-entropy-results) guide for tips to limit gas usage, or generate multiple random numbers in a single transaction.

### Randomness providers

Some methods on Entropy require selecting a **randomness provider**. The randomness provider is a third-party
who participates in the generation process. Each provider is identified by an address and hosts
a keeper service for fullfilling requests.

You can get the default provider's address by calling the [`getDefaultProvider`](https://github.com/pyth-network/pyth-crosschain/blob/f8ebeb6af31d98f94ce73edade6da2ebab7b2456/target_chains/ethereum/entropy_sdk/solidity/IEntropy.sol#L94) method:

```solidity copy
address provider = entropy.getDefaultProvider();
```
