> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streambird.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure EVM Networks

MoonKey is compatible with any EVM-compatible blockchain, making it easy to deploy your application on Ethereum, Layer 2s, sidechains, and custom networks.

Whether you're building on Ethereum mainnet, Base, Polygon, Arbitrum, Optimism, or a custom EVM chain, MoonKey provides flexible network configuration to match your needs.

## Overview

MoonKey exposes two key parameters for network configuration: a **default chain** and a list of **supported chains**.

If you don't configure these parameters, MoonKey will use its [default configuration](/get-started/frontend-sdks/react/advanced/configure-evm-networks#default-configuration) which supports popular networks out of the box.

### Default Chain

The **default chain** is the primary network that your application's wallets will use.

**For embedded wallets:**

* When users authenticate or create a wallet, MoonKey initializes it on the default chain
* The embedded wallet will use the default chain for all operations unless explicitly switched to another supported chain

**For external wallets:**

* When users connect, MoonKey will prompt them to switch to the default chain if their wallet supports it
* Users can decline the prompt and remain on their current network
* Users can manually switch their wallet's network at any time (MoonKey cannot prevent this)

<Info>
  Some wallets have limited network support. Rainbow Wallet's mobile app doesn't support testnets, and Trust Wallet SWIFT only supports specific networks (BSC, Polygon, Avalanche C-Chain, Arbitrum, OP Mainnet, Base, OpBNB).
</Info>

### Supported Chains

The **supported chains** list defines which networks are permitted in your application. This acts as a guardrail to prevent accidental transactions on unintended networks.

**For embedded wallets:**

* Attempting to send transactions on unsupported chains will throw an error
* Attempting to switch to an unsupported chain will throw an error

**For external wallets:**

* Programmatic network switches to unsupported chains will throw an error
* Users can still manually switch their wallet to any network (this cannot be prevented)

**Configuration behavior:**

* If you set `supportedChains` but not `defaultChain`, embedded wallets default to the first entry in the supported chains list
* External wallets won't be prompted to switch networks on connection
* The default chain must be included in the supported chains list

## Configuration

MoonKey embedded wallets support any EVM-compatible chain. Here's how to configure them.

### Using viem-Supported Networks

<Tip>
  If your network is supported by [viem/chains](https://viem.sh/docs/chains/introduction#chains), follow these instructions. Check the [full list of supported networks](https://github.com/wevm/viem/blob/main/src/chains/index.ts).
</Tip>

**Step 1: Install viem**

First, install the `viem` package which contains JSON representations of popular EVM networks:

```bash theme={null}
npm install viem
```

**Step 2: Import your desired chains**

Import the chains you want to use from `viem/chains`:

```tsx theme={null}
import { base, polygon, arbitrum, optimism } from 'viem/chains';
```

**Step 3: Configure the MoonKeyProvider**

Add the chains to your `MoonKeyProvider` configuration:

```tsx theme={null}
import { MoonKeyProvider } from '@moon-key/react-auth';
import { base, polygon, arbitrum, optimism } from 'viem/chains';

export default function Providers({ children }) {
  return (
    <MoonKeyProvider
      publishableKey="your-moonkey-publishableKey"
      config={{
        // Set your default network
        defaultChain: base,
        // Define all permitted networks
        supportedChains: [base, polygon, arbitrum, optimism]
      }}
    >
      {children}
    </MoonKeyProvider>
  );
}
```

**Important notes:**

* `supportedChains` cannot be an empty array
* `defaultChain` must be included in `supportedChains`
* The provider will throw an error if these rules are violated

That's it! Your app now supports multiple EVM networks. 🎉

### Using Custom Networks

<Tip>
  If your network isn't supported by viem/chains, you can still use it with MoonKey by defining it manually.
</Tip>

**Step 1: Define your custom chain**

Use viem's `defineChain` method to create a chain configuration:

```tsx theme={null}
import { defineChain } from 'viem';

export const myCustomChain = defineChain({
  id: 123456789, // Your chain's ID
  name: 'My Custom Chain',
  network: 'my-custom-chain',
  nativeCurrency: {
    decimals: 18,
    name: 'Custom Token',
    symbol: 'CUSTOM'
  },
  rpcUrls: {
    default: {
      http: ['https://rpc.my-custom-chain.network'],
      webSocket: ['wss://ws.my-custom-chain.network']
    }
  },
  blockExplorers: {
    default: {
      name: 'CustomScan',
      url: 'https://explorer.my-custom-chain.network'
    }
  }
});
```

**Required fields:**

* `id` — Chain ID
* `name` — Human-readable name
* `network` — Network identifier
* `nativeCurrency` — Native token details (name, symbol, decimals)
* `rpcUrls` — RPC endpoints (HTTP and/or WebSocket)
* `blockExplorers` — Block explorer URL

**Step 2: Use your custom chain**

Pass your custom chain to the `MoonKeyProvider`:

```tsx theme={null}
import { MoonKeyProvider } from '@moon-key/react-auth';
import { mainnet } from 'viem/chains';
import { myCustomChain } from './chains';

export default function Providers({ children }) {
  return (
    <MoonKeyProvider
      publishableKey="your-moonkey-publishableKey"
      config={{
        defaultChain: myCustomChain,
        supportedChains: [mainnet, myCustomChain]
      }}
    >
      {children}
    </MoonKeyProvider>
  );
}
```

## Custom RPC Providers

By default, MoonKey uses its own RPC providers for transactions. These are subject to rate limits suitable for development and moderate production usage.

**For production applications with significant traffic, we strongly recommend using your own RPC providers** from services like [Alchemy](https://www.alchemy.com/), [Infura](https://www.infura.io/), [QuickNode](https://www.quicknode.com/), or [Blast](https://blastapi.io/).

Benefits of custom RPC providers:

* Control over rate limits and throughput
* Better monitoring and analytics
* Reduced latency with dedicated infrastructure
* SLA guarantees

### Overriding RPC URLs

To use a custom RPC provider with MoonKey:

**Step 1: Import the helper function**

```tsx theme={null}
import { addRpcUrlOverrideToChain } from '@moon-key/chains';
import { mainnet } from 'viem/chains';
```

**Step 2: Override the RPC URL**

```tsx theme={null}
const mainnetWithCustomRpc = addRpcUrlOverrideToChain(
  mainnet,
  'https://eth-mainnet.g.alchemy.com/v2/YOUR-API-KEY'
);
```

**Step 3: Use the modified chain**

```tsx theme={null}
<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    defaultChain: mainnetWithCustomRpc,
    supportedChains: [mainnetWithCustomRpc]
  }}
>
  {children}
</MoonKeyProvider>
```

### Multiple chains with custom RPCs

Override multiple chains at once:

```tsx theme={null}
import { addRpcUrlOverrideToChain } from '@moon-key/chains';
import { mainnet, polygon, arbitrum } from 'viem/chains';

const mainnetOverride = addRpcUrlOverrideToChain(
  mainnet,
  'https://eth-mainnet.g.alchemy.com/v2/YOUR-API-KEY'
);

const polygonOverride = addRpcUrlOverrideToChain(
  polygon,
  'https://polygon-mainnet.g.alchemy.com/v2/YOUR-API-KEY'
);

const arbitrumOverride = addRpcUrlOverrideToChain(
  arbitrum,
  'https://arb-mainnet.g.alchemy.com/v2/YOUR-API-KEY'
);

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    defaultChain: mainnetOverride,
    supportedChains: [mainnetOverride, polygonOverride, arbitrumOverride]
  }}
>
  {children}
</MoonKeyProvider>
```

## Default Configuration

If you don't specify `defaultChain` or `supportedChains`, MoonKey defaults to supporting popular EVM networks:

<Tip>
  Need a network not listed below? Configure it using the instructions above.
</Tip>

### Default Supported Networks

| Network               | Chain ID  | Testnet |
| --------------------- | --------- | ------- |
| **Ethereum Mainnet**  | 1         |         |
| Ethereum Sepolia      | 11155111  | ✅       |
| **Base**              | 8453      |         |
| Base Sepolia          | 84532     | ✅       |
| **Polygon**           | 137       |         |
| Polygon Amoy          | 80002     | ✅       |
| **Arbitrum One**      | 42161     |         |
| Arbitrum Sepolia      | 421614    | ✅       |
| **Optimism**          | 10        |         |
| Optimism Sepolia      | 11155420  | ✅       |
| **Avalanche C-Chain** | 43114     |         |
| Avalanche Fuji        | 43113     | ✅       |
| **BNB Smart Chain**   | 56        |         |
| BNB Testnet           | 97        | ✅       |
| **Celo**              | 42220     |         |
| Celo Alfajores        | 44787     | ✅       |
| **Linea**             | 59144     |         |
| Linea Testnet         | 59140     | ✅       |
| **Zora**              | 7777777   |         |
| Zora Sepolia          | 999999999 | ✅       |

**Default behavior:**

* Embedded wallets initialize on Ethereum mainnet (or the user's last-used network)
* External wallets aren't prompted to switch networks
* All networks in the table above are available for use

## Switching Networks

Once configured, you can programmatically switch networks using MoonKey hooks.

### Switch embedded wallet network

```tsx theme={null}
import { useSwitchChain } from '@moon-key/react-auth/ethereum';
import { polygon } from 'viem/chains';

function SwitchNetworkButton() {
  const { switchChain } = useSwitchChain();

  const handleSwitch = async () => {
    await switchChain({ chainId: polygon.id });
  };

  return <button onClick={handleSwitch}>Switch to Polygon</button>;
}
```

### Get current network

```tsx theme={null}
import { useChainId } from '@moon-key/react-auth/ethereum';

function CurrentNetwork() {
  const chainId = useChainId();

  return <div>Current Chain ID: {chainId}</div>;
}
```

## Common Configurations

### Mainnet-only application

```tsx theme={null}
import { mainnet } from 'viem/chains';

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    defaultChain: mainnet,
    supportedChains: [mainnet]
  }}
>
  {children}
</MoonKeyProvider>
```

### Layer 2 focused

```tsx theme={null}
import { base, polygon, arbitrum, optimism } from 'viem/chains';

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    defaultChain: base,
    supportedChains: [base, polygon, arbitrum, optimism]
  }}
>
  {children}
</MoonKeyProvider>
```

### Development with testnets

```tsx theme={null}
import { sepolia, baseSepolia, polygonAmoy } from 'viem/chains';

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    defaultChain: sepolia,
    supportedChains: [sepolia, baseSepolia, polygonAmoy]
  }}
>
  {children}
</MoonKeyProvider>
```

### Multi-chain with custom RPC

```tsx theme={null}
import { addRpcUrlOverrideToChain } from '@moon-key/chains';
import { mainnet, polygon } from 'viem/chains';

const mainnetWithRpc = addRpcUrlOverrideToChain(
  mainnet,
  process.env.NEXT_PUBLIC_MAINNET_RPC
);

const polygonWithRpc = addRpcUrlOverrideToChain(
  polygon,
  process.env.NEXT_PUBLIC_POLYGON_RPC
);

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    defaultChain: mainnetWithRpc,
    supportedChains: [mainnetWithRpc, polygonWithRpc]
  }}
>
  {children}
</MoonKeyProvider>
```

## Best Practices

### Choose appropriate networks

* **Mainnet for production** — Use mainnet and established L2s for production deployments
* **Testnets for development** — Use Sepolia, Amoy, etc. during development to avoid real costs
* **Limit network count** — Only support networks your application actually uses

### Use environment variables

Store RPC URLs and chain configurations in environment variables:

```tsx theme={null}
// .env.local
NEXT_PUBLIC_MAINNET_RPC=https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY
NEXT_PUBLIC_POLYGON_RPC=https://polygon-mainnet.g.alchemy.com/v2/YOUR-KEY
```

```tsx theme={null}
const mainnetWithRpc = addRpcUrlOverrideToChain(
  mainnet,
  process.env.NEXT_PUBLIC_MAINNET_RPC!
);
```

### Monitor RPC usage

When using custom RPC providers:

* Set up monitoring and alerts for rate limits
* Track RPC call volumes and errors
* Have fallback providers configured
* Monitor response times and uptime

### Test network switching

Always test network switching functionality:

* Verify embedded wallets switch correctly
* Test external wallet prompts
* Handle user rejection of network switches
* Display clear network indicators in your UI

## Troubleshooting

### Chain not appearing in wallet

**Problem:** Users don't see your configured chain in their wallet.

**Solutions:**

* Verify the chain is in `supportedChains`
* Check that chain ID and RPC URL are correct
* For custom chains, ensure all required fields are defined
* Some wallets require manual network addition

### RPC rate limit errors

**Problem:** Transactions fail with rate limit errors.

**Solutions:**

* Use custom RPC providers (Alchemy, Infura, QuickNode)
* Implement RPC URL overrides
* Add fallback RPC endpoints
* Monitor your RPC usage and upgrade plans as needed

### Network switch fails

**Problem:** `switchChain` throws an error or doesn't work.

**Solutions:**

* Ensure target chain is in `supportedChains`
* For external wallets, check wallet supports the network
* Handle errors gracefully when users decline switches
* Verify RPC endpoints are accessible

### Configuration errors on startup

**Problem:** `MoonKeyProvider` throws an error during initialization.

**Solutions:**

* Ensure `defaultChain` is included in `supportedChains`
* Don't pass empty array to `supportedChains`
* Verify chain objects are properly formatted
* Check for typos in chain imports

## Related Resources

* [Viem Chains Documentation](https://viem.sh/docs/chains/introduction)
* [EVM Chains List](https://chainlist.org/)
* [Configure Solana Networks](/get-started/frontend-sdks/react/advanced/configure-solana-networks)
* [Wallet Management](/wallet-as-a-service/overview)