# What are RPC and RPC Aggregator?

RPC (Remote Procedure Call) is a protocol used for communication between a client and a server over a network. In the context of the web3 industry, RPC is used to allow communication between web applications and blockchain nodes.

When a user interacts with a Dapp, the Dapp uses the RPC service of the user's web3 wallet to communicate with the blockchain network. For example, if a user wants to view their account balance and transfer tokens, the Dapp will ask the user to connect the MetaMask and use the RPC endpoint in MetaMask to retrieve the user's account balance from the blockchain network and submit a transaction to transfer tokens on the user's behalf.

The RPC service is also used by developers to test and debug their applications during the development process. Developers can use the RPC service to simulate interactions with the blockchain network without incurring the cost of real transactions. RPC is a crucial infrastructure in the web3 industry, as it allows users and developers to interact with the blockchain network without running a node by themselves.

An aggregator is a software running locally to distribute RPC requests to multiple RPC endpoints. RPCHub aims to be the leading aggregator in the Web3 industry.


# What problems does RPCHub solve?

As the web3 industry continues to grow, more users and developers are using and building on blockchain networks. However, using a single RPC endpoint has limitations such as slow response times, downtime, rate limit, or unsupported methods. This is where RPCHub comes in,  a leading RPC aggregator that offers you the fastest and most robust RPC service solutions by integrating your owned nodes, as well as private and public endpoints. 

The Benefits of Using RPCHub as an RPC aggregator

1. Scalable and Stable: RPCHub is able to integrate public endpoints,  private endpoints, as well as owned nodes to provide developers with the highest level of capacity and uptime.
2. Fast Response Times: RPCHub let you configure the strategy of load balancing to ensure fast response times.
3. Customizable Solutions: RPCHub offers customizable solutions that can be tailored to meet the specific needs of individuals, including integration with existing infrastructure and security requirements.
4. Privacy Benefits: Strategy configurations are stored and utilized locally to best protect your privacy. Routing your RPC requests to multiple service providers makes it harder to create a profile of customers.
5. Fully Open-source: Since the source code is openly available, the community can review it and share RPC resources. The team provides quick feedback on constructive suggestions and adds new features to the program.


# Installation and run

The Github repo of RPCHub is <https://github.com/BlockPILabs/aggregator>

Following these simple steps to download and install RPCHub

### Prerequisite

RPCHub is developed by Go. Before installation, check your Go version or install Go language from the official site. <https://go.dev/doc/install>

### Installation

{% tabs %}
{% tab title="Linux" %}

```
//If you have old configurations and want to start over, delete it first
rm -rf $HOME/.rpchub/aggregator/

// git from source and make
git clone https://github.com/BlockPILabs/aggregator.git
cd aggregator
make

//start the aggregator
build/aggregator
```

{% endtab %}

{% tab title="Mac and Windows" %}
Download the latest installation package from [here](https://github.com/BlockPILabs/aggregator/releases).

If you have old configurations and want to start over, delete it first. Directory should be `/usr/.rpchub/`
{% endtab %}
{% endtabs %}

RPCHub will show a initial log like this if it is successfully started.

<figure><img src="/files/0K1vSc5UFgNtrbfRLAER" alt=""><figcaption></figcaption></figure>

The available chains are listed in the log. (e.g. <mark style="color:blue;"><http://localhost:8011/ethereum></mark>)Now you can use the local endpoint to send RPC requests. Check [Use RPCHub in MetaMask](/user-guide/use-rpchub-in-metamask)as an example to set the local endpoint in MetaMask.&#x20;


# Configuration

Configurations are only stored locally. RPCHub will route your requests based on the configurations.

Users can setup the configurations by either web explorer or posting raw configurations in CLI.

{% hint style="info" %}
You can only get access to the configurations when the RPCHub is running.
{% endhint %}

Before proceeding, we suggest that you check the reference to better understand the parameter settings of RPChub,

[Reference](/user-guide/reference)

## Configure With Web Explorer

We provide a user-friendly interface with web explorer.

Go to <https://ag-cfg.rpchub.io/>

Fill with the aggregator management endpoint <mark style="color:blue;"><http://localhost:8012></mark> and password <mark style="color:blue;">123456</mark>

<figure><img src="/files/gldsOkyJCGHsuvpK4zqf" alt=""><figcaption></figcaption></figure>

After login, there is the configuration console. On this page, you can perform the following settings.

<figure><img src="/files/rWH3keP8My22Zz0znQwM" alt=""><figcaption></figcaption></figure>

#### Set your password

It is recommended to set the password as soon as possible. Please note that your password is stored in your **local** profile. If you forget your password, you won't be able to get access to the configurations. To configure, you have to start over from [Installation and run](/user-guide/installation-and-run) and configure from default.

#### Add or edit RPC&#x20;

You can either add a new RPC or edit an existing RPC. In the popup tab, chose the chain, input endpoint name, endpoint url and weight.&#x20;

On each RPC card, you can delete the RPC, or switch the "Read Only" and "Disable"

<figure><img src="/files/yolv7CJRTP7vZnVJT6gM" alt=""><figcaption></figcaption></figure>

#### Basic setup

Here you can set the proxy address, request timeout, request max retries.

#### Phishing DB

The phishing database is a feature to prevent users from interacting with suspicious addresses. A user can add any phishing DB url on his own behalf. RPCHub will stop the request if the payload contains any address in the added database.

#### Find the localhost endpoint

To find the localhost endpoint for a specific chain, simply click the chain name and the endpoint will appear below the chains list.

<figure><img src="/files/SntGYDh5ZaZuHw6uCQmM" alt=""><figcaption></figcaption></figure>

## Configure With CLI

CLI provides more flexible configurations, including password reset and adding arbitry chains.

#### Default configuration

To set the configuration of the aggregator, you must know the format of the file first. To show the current configurations after the first run,

```
curl -u rpchub:123456 'http://localhost:8012/config'
```

The response payload should be like,

```
{
    "password": "123456",
    "request_timeout": 30,
    "max_retries": 3,
    "nodes": {
        "<chain1>": [
            {
                "name": "<name1>",
                "endpoint": "<endpoint1>",
                "weight": 100,
                "read_only": false,
                "disabled": false
            },
            {
                "name": "<name2>",
                "endpoint": "<endpoint2>",
                "weight": 100,
                "read_only": false,
                "disabled": false
            },
            ......
        ],
        "<chain2>": [
            ......
        ],
        ......
    },
    "phishing_db": [
        "https://cfg.rpchub.io/agg/scam-addresses.json"
    ],
    "phishing_db_update_interval": 3600,
    "mrt": 1
}
```

#### Set new configuration&#x20;

Parameters are explained in the "Configure With Web Explorer" part. Edit them as your wish.&#x20;

If you want to add or edit an RPC endpoint, just compose following this format,

```
{
    "name":"<endpoint name>",
    "endpoint":"<endpoint url>",
    "weight":<number>,
    "read_only":<true or false>,
    "disabled":<true or false>
}
```

And insert into or replace one in the payload. Then use the following command to post the entire payload back to the configuration,

```
curl -u rpchub:<password> -X POST 'http://localhost:8012/config' 
    --header 'Content-Type: application/json' 
    --data-raw 
    '<payload>' 
```

The new configurations should work after restart RPCHub.

Here is an example to set the configuration to use RPCHub for Arbitrum (2 endpoints) and BSC (1 endpoint),

```
curl -u rpchub:123456 -X POST 'http://localhost:8012/config' --header 'Content-Type: application/json' --data-raw 
{
	"password": "123456",
	"request_timeout": 30,
	"max_retries": 3,
	"nodes": {
		"arbitrum": [{
			"name": "blockpi-public-arbitrum",
			"endpoint": "https://arbitrum.blockpi.network/v1/rpc/public",
			"weight": 90,
			"read_only": false,
			"disabled": false
		}, {
			"name": "arbitrum-official",
			"endpoint": "https://arb1.arbitrum.io/rpc",
			"weight": 10,
			"read_only": false,
			"disabled": false
		}],
		"bsc": [{
			"name": "blockpi-official",
			"endpoint": "https://bsc-dataseed.binance.org",
			"weight": 100,
			"read_only": false,
			"disabled": false
		}]	
	},
	"phishing_db": ["https://cfg.rpchub.io/agg/scam-addresses.json"],
	"phishing_db_update_interval": 3600
}
```

#### Reset configuration

Stop RPCHub.

Delete the configuration directory,

```
rm -rf $HOME/.rpchub/aggregator/
```

Start RPCHub again.&#x20;

Configurations will be reset including the password.


# Use RPCHub in MetaMask

After configurations, your web3 wallet should be able use the local port as the RPC endpoint. This page shows how to add a RPCHub Ethereum network to your MetaMask.

#### Click the upper-right icon.

![](/files/6ByKyKl0tm2UIK7h7LfZ)

#### Go to the Settings.

![](/files/4mSCFapFbfATGjoBRR0Q)

#### And go to the tab of Network.

![](/files/ejYMIzMWOX2o7X51p5Bu)

#### Add a new network.

![](/files/KNBKCybkPJb7tgQXlrl5)

#### Click Add a network manually.

<figure><img src="/files/weUC1eZQE2E01gvYxgEn" alt=""><figcaption></figcaption></figure>

#### Input the local endpoint and other chain information.

<figure><img src="/files/LyZ01GRaK6fmyNmT9sT0" alt=""><figcaption></figcaption></figure>

Click "Save" and you are good to go! The netwok of MetaMask will be automatically switched to “RPCHub Ethereum”.

![](/files/7TPHuGO1EKTbIP6Qx1ma)


# Reference

<table><thead><tr><th width="219">Parameters</th><th>Description</th></tr></thead><tbody><tr><td>RPCHub management endpoint</td><td>http://localhost:8012 or https://127.0.0.1:8012<br>This is the local endpoint to access the configuraitons and only acccessable when RPCHub is running.</td></tr><tr><td>Username</td><td>RPCHub (Username is fixed, omitted on the web explorer login)</td></tr><tr><td>Password</td><td>Default is 123456. It is recommended to set your password after first login. </td></tr><tr><td>Proxy</td><td>You can input any functional proxy you wish to use, and all of the requests will be sent though this proxy. Support HTTPS and SOCKS5. Default is blank.</td></tr><tr><td>Request timeout</td><td>If an RPC request sent to an endpoint does not respond within this time, the request is considered a timeout.</td></tr><tr><td>Request max retries</td><td>RPCHub will retry the timeout request based on the strategy. If times of fail reach this number, this request is considered failed.</td></tr><tr><td>Phishing DB</td><td>A database contains scam or malicious addresses. Once input in the configuration, requests interacting with these addresses will be blocked by RPCHub.</td></tr><tr><td>Update interval</td><td>RPChub will refresh the addresses from saved database URL with this interval.</td></tr><tr><td>Weight</td><td><p>This number determines the ratio of total requests to be sent to this endpoint of the chain. It follows,<br><span class="math">Ri=Wi/(W1+W2+...+Wn)</span></p><p>where <em>R</em> is ratio and <em>W</em> is the weight of all endpoints for this chain in the configurations.</p></td></tr></tbody></table>


# Public Endpoints

Below are the public rpc we collected. We welcome the community to add available public rpc endpoints to this repository.

<table><thead><tr><th width="223">Chains</th><th>Endpoints</th></tr></thead><tbody><tr><td>Aptos</td><td><p>https://fullnode.mainnet.aptoslabs.com/v1 </p><p>https://aptos.blockpi.network/aptos/v1/public/v1</p></td></tr><tr><td>Arbitrum</td><td>https://arb1.arbitrum.io/rpc<br>https://arbitrum.blockpi.network/v1/rpc/public
</td></tr><tr><td>Avalanche</td><td>https://api.avax.network/ext/bc/C/rpc<br>https://avalanche.blockpi.network/v1/rpc/public</td></tr><tr><td>BSC</td><td>https://bsc-dataseed.binance.org<br>https://bsc.blockpi.network/v1/rpc/public
</td></tr><tr><td>BSC Testnet</td><td>https://data-seed-prebsc-1-s1.binance.org:8545</td></tr><tr><td>Cosmos-rpc</td><td>https://rpc-cosmoshub.keplr.app<br>https://cosmos.blockpi.network/rpc/v1/public
</td></tr><tr><td>Cosmos-lcd</td><td>https://lcd-cosmoshub.keplr.app<br>https://cosmos.blockpi.network/lcd/v1/public
</td></tr><tr><td>Cronos</td><td>https://evm.cronos.org<br>https://cronos.blockpi.network/v1/rpc/public
</td></tr><tr><td>Ethereum</td><td>https://ethereum.blockpi.network/v1/rpc/public</td></tr><tr><td>Ethereum-Goerli</td><td>https://goerli.blockpi.network/v1/rpc/public</td></tr><tr><td>Ethereum-Sepolia</td><td>https://ethereum-sepolia.blockpi.network/v1/rpc/public</td></tr><tr><td>Fantom</td><td>https://fantom.blockpi.network/v1/rpc/public</td></tr><tr><td>Gnosis</td><td>https://gnosis.blockpi.network/v1/rpc/public</td></tr><tr><td>Klaytn</td><td>https://public-node-api.klaytnapi.com/v1/cypress<br>https://klaytn.blockpi.network/v1/rpc/public</td></tr><tr><td>Klaytn-baobab</td><td>https://public-node-api.klaytnapi.com/v1/baobab<br>https://klaytn-baobab.blockpi.network/v1/rpc/public</td></tr><tr><td>Optimism</td><td>https://mainnet.optimism.io<br>https://optimism.blockpi.network/v1/rpc/public</td></tr><tr><td>Optimism Goerli</td><td>https://goerli.optimism.io</td></tr><tr><td>Polygon</td><td>https://polygon.blockpi.network/v1/rpc/public</td></tr><tr><td>Polygon-Mumbai</td><td>https://polygon-mumbai.blockpi.network/v1/rpc/public</td></tr><tr><td>Scroll-Testnet</td><td>https://alpha-rpc.scroll.io/l2<br>https://scroll-testnet.blockpi.network/v1/rpc/public
</td></tr></tbody></table>


# Phishing DB Warehouse

Phishing DB is collected by the community. It is recommended to check the DB before input it in the configuration.

<table><thead><tr><th width="424">Database URL</th><th>Description</th></tr></thead><tbody><tr><td><a href="https://cfg.rpchub.io/agg/scam-addresses.json
">https://cfg.rpchub.io/agg/scam-addresses.json
</a></td><td>A database of scam addresses provided by BlockPI team.</td></tr><tr><td></td><td></td></tr></tbody></table>


# Official Links

Official: <https://rpchub.io/>

Github: <https://github.com/BlockPILabs/aggregator>

Twitter: <https://twitter.com/RealRPCHub>