V2 Bot JSON-RPC Provider Setup

With v2 detection bots, developers can scan any EVM-compatible chain by bringing their own RPC endpoints. This guide discusses a few options for setting up your bot's RPC provider for local development and production.

Public RPC URLs

The simplest way to get started is to use a public RPC endpoint for your specific chain. These endpoints are free to use, but typically come with rate limits to prevent misuse. Depending on the rate limits, your bot's performance will vary. Unless you are certain that your bot will stay within the set limits, we don't recommend using public RPC URLs in production. However, you may find these convenient for local development.

Private RPC URLs

Another common way to communicate with RPC providers is to create a private RPC endpoint which typically contains some sort of secret API key within the URL itself. These are usually offered through a freemium payment model with more generous rate limits. However, hardcoding the RPC URL (and secret API key) within the bot itself is a security issue because the bot Docker images are stored in a public repository which anyone can view. For this reason, private RPC URLs are better suited for local development but not for production.

JWT-Authenticated RPC URLs

Certain RPC providers have the option to create a JWT-authenticated RPC endpoint that can only be accessed by scan nodes that are running your bot. Setting up this kind of RPC endpoint is easy and requires registering the Forta public key with the provider. Suggested providers that support this kind of authentication mechanism include (but are not limited to) Alchemy, dRPC and Infura. The main benefit of using such a RPC endpoint is that you can hardcode the RPC URL into the bot without giving away public access to anyone who can view the bot's Docker image.

Registering the Forta public key

For example, to create a JWT-authenticated RPC URL on Alchemy you would do the following:

Go to the Alchemy JWT Public Keys dashboard
Click "Import Public Key"
Enter a name for this new key
Select the App ID (i.e. RPC endpoint) you want to associate with the public key
Copy and paste the Forta public key (as seen below)
Click "Create" to register the key
Click on the created key's name to expand it and view the key ID e.g. 67694d31-0d90-47a4-8241-0a8546958512a
Use the key ID inside your bot e.g.

Typescript/JavascriptPython

scanEthereum({
  rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2',
  rpcKeyId: '67694d31-0d90-47a4-8241-0a8546958512a',
  ...
})

scan_ethereum({
  'rpc_url': 'https://eth-mainnet.g.alchemy.com/v2',
  'rpc_key_id': '67694d31-0d90-47a4-8241-0a8546958512a',
  ...
})

Forta public key

Forta RPC Cache

When running on scan nodes in production, v2 detection bots also have access to a RPC cache (courtesy of the Forta Network). The cache provides access to basic blockchain data including blocks, transactions and logs. The cache is short-lived and only stores blockchain data for the past 5 minutes for certain chains. Currently the following 8 chains are supported by the cache:

Ethereum (includes trace data)
Polygon
Base
BSC
Avalanche
Arbitrum
Fantom (includes trace data)
Optimism

Local RPC URLs

Note that JWT-authenticated RPC URLs can only work inside of a scan node (i.e. only in production). When developing locally, these URLs will not work as they require a scan node environment. To work around this when developing locally, you can specify a local RPC URL in your bot that will be used only when running locally. This way you can use public/private RPC URLs locally without exposing them to the world. For example, you would put the public/private URLs inside your forta.config.json like so:

{
  ...
  "localRpcUrls": {
    "1": "https://cloudflare-eth.com/",
    "137": "https://polygon-rpc.com"
  }
}

and then use them inside your bot like this:

Typescript/JavascriptPython

scanEthereum({
  localRpcUrl: '1',
  rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2', // only used in prod
  rpcKeyId: '67694d31-0d90-47a4-8241-0a8546958512a', // only used in prod
  ...
})

scan_polygon({
  'local_rpc_url': '137',
  'rpc_url': 'https://polygon-mainnet.g.alchemy.com/v2', # only used in prod
  'rpc_key_id': '89694d31-0c50-58b4-8241-0e0543959513b', # only used in prod
  ...
})