---
description: Access configured RPC endpoints and make JSON-RPC calls
---

## RPC Cheatcodes

### Signature

```solidity
struct Rpc {
    string key;
    string url;
}

function rpcUrl(string calldata rpcAlias) external view returns (string memory url);
function rpcUrls() external view returns (string[2][] memory urls);
function rpcUrlStructs() external view returns (Rpc[] memory urls);
function rpc(string calldata method, string calldata params) external returns (bytes memory data);
function rpc(string calldata urlOrAlias, string calldata method, string calldata params)
    external
    returns (bytes memory data);
function rpcJson(string calldata method, string calldata params) external returns (string memory data);
function rpcJson(string calldata urlOrAlias, string calldata method, string calldata params)
    external
    returns (string memory data);
```

### Description

Provides cheatcodes to access RPC endpoints configured in the `rpc_endpoints` object of `foundry.toml` and make JSON-RPC calls.

The two-parameter request overloads use the currently active fork's URL. The three-parameter overloads accept either a configured alias or a URL directly.

### Functions

#### `rpcUrl`

Returns the URL for a configured RPC alias.

| Parameter  | Type     | Description                    |
|------------|----------|--------------------------------|
| `rpcAlias` | `string` | The alias name from config     |

| Returns  | Description              |
|----------|--------------------------|
| `string` | The configured RPC URL   |

#### `rpcUrls`

Returns all configured (alias, URL) pairs.

| Returns        | Description                          |
|----------------|--------------------------------------|
| `string[2][]`  | Array of [alias, url] pairs          |

#### `rpcUrlStructs`

Returns all configured RPC aliases and URLs as `Rpc` structs.

| Returns | Description |
|---------|-------------|
| `Rpc[]` | Array whose `key` and `url` fields contain each configured endpoint |

#### `rpc`

Performs an Ethereum JSON-RPC request and ABI-encodes the result. The two-parameter overload uses the current fork URL; the three-parameter overload uses `urlOrAlias`.

| Parameter | Type | Description |
|-----------|------|-------------|
| `urlOrAlias` | `string` | Configured RPC alias or endpoint URL (optional) |
| `method` | `string` | JSON-RPC method name |
| `params` | `string` | JSON-encoded array of parameters |

| Returns | Description                    |
|---------|--------------------------------|
| `bytes` | The RPC response data          |

#### `rpcJson`

Performs the same request as `rpc`, but returns the JSON result as a string. Strings remain JSON-quoted, while arrays and objects retain their JSON structure. This is useful when you need to inspect the result with JSON cheatcodes instead of relying on `rpc`'s inferred ABI encoding.

| Parameter | Type | Description |
|-----------|------|-------------|
| `urlOrAlias` | `string` | Configured RPC alias or endpoint URL (optional) |
| `method` | `string` | JSON-RPC method name |
| `params` | `string` | JSON-encoded array of parameters |

| Returns | Description |
|---------|-------------|
| `string` | JSON representation of the RPC result |

### Configuration

Configure RPC endpoints in your `foundry.toml`:

```toml [foundry.toml]
[rpc_endpoints]
optimism = "https://optimism.alchemyapi.io/v2/..."
mainnet = "${RPC_MAINNET}"
```

:::note
Environment variables must be wrapped in `${}` syntax.
:::

### Examples

#### Get a configured RPC URL

```solidity [test/Rpc.t.sol]
string memory url = vm.rpcUrl("optimism");
assertEq(url, "https://optimism.alchemyapi.io/v2/...");
```

#### Handle missing environment variables

```solidity [test/Rpc.t.sol]
vm.expectRevert("Failed to resolve env var `${RPC_MAINNET}` in `RPC_MAINNET`: environment variable not found");
string memory url = vm.rpcUrl("mainnet");
```

#### Get all configured RPC URLs

```solidity [test/Rpc.t.sol]
string[2][] memory allUrls = vm.rpcUrls();
assertEq(allUrls.length, 2);

string[2] memory val = allUrls[0];
assertEq(val[0], "optimism");

string[2] memory env = allUrls[1];
assertEq(env[0], "mainnet");
```

Use `rpcUrlStructs` when named fields are more convenient:

```solidity [test/RecentCheatcodes.t.sol]
// [!include ~/snippets/projects/cheatcodes/test/RecentCheatcodes.t.sol:rpc-url-structs]
```

#### Make an RPC call

```solidity [test/Rpc.t.sol]
// Get balance at block 18332681
bytes memory result = vm.rpc(
    "eth_getBalance",
    "[\"0x8D97689C9818892B700e27F316cc3E41e17fBeb9\", \"0x117BC09\"]"
);
assertEq(hex"10b7c11bcb51e6", result);
```

Use `rpcJson` to preserve the JSON representation:

```solidity [test/RecentCheatcodes.t.sol]
// [!include ~/snippets/projects/cheatcodes/test/RecentCheatcodes.t.sol:rpc-json]
```

### Gotchas

:::warning
If an RPC alias references an environment variable that is not set, `rpcUrl()` will revert with an error message.
:::

### Related Cheatcodes

- [`createFork`](/reference/cheatcodes/create-fork) - Creates a new fork
- [`createSelectFork`](/reference/cheatcodes/create-select-fork) - Creates and selects a fork

### See Also

- [RPC Endpoints Configuration](/config/reference/testing#rpc_endpoints)
