> ## 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 Solana Networks

MoonKey supports all [Solana clusters](https://solana.com/docs/core/clusters) including Mainnet Beta, Devnet, and Testnet.

This guide shows you how to configure Solana RPC endpoints and work with different Solana environments in your application.

## Solana Clusters

Solana provides three primary clusters for different purposes:

| Cluster          | Purpose             | Use Case                                   |
| ---------------- | ------------------- | ------------------------------------------ |
| **Mainnet Beta** | Production network  | Live applications with real SOL and tokens |
| **Devnet**       | Development network | Testing and development with free test SOL |
| **Testnet**      | Performance testing | Stress testing before mainnet deployment   |

## Configuring RPC Endpoints

To configure custom RPC endpoints for Solana embedded wallets, set them in the `MoonKeyProvider` configuration:

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

export default function Providers({ children }) {
  return (
    <MoonKeyProvider
      publishableKey="your-moonkey-publishableKey"
      config={{
        solana: {
          rpcs: {
            'solana:mainnet': {
              rpc: 'https://api.mainnet-beta.solana.com',
              rpcSubscriptions: 'wss://api.mainnet-beta.solana.com'
            },
            'solana:devnet': {
              rpc: 'https://api.devnet.solana.com',
              rpcSubscriptions: 'wss://api.devnet.solana.com'
            },
            'solana:testnet': {
              rpc: 'https://api.testnet.solana.com',
              rpcSubscriptions: 'wss://api.testnet.solana.com'
            }
          }
        }
      }}
    >
      {children}
    </MoonKeyProvider>
  );
}
```

<Info>
  Custom RPC configuration is only required for embedded wallet UIs. If you're using external Solana wallets (Phantom, Solflare, etc.) without embedded wallet functionality, you don't need to configure RPCs.
</Info>

## Default Configuration

If you don't configure custom RPC endpoints, MoonKey uses default Solana cluster endpoints:

* **Mainnet Beta**: `https://api.mainnet-beta.solana.com`
* **Devnet**: `https://api.devnet.solana.com`
* **Testnet**: `https://api.testnet.solana.com`

These default endpoints work for development and moderate usage, but production applications should use dedicated RPC providers.

## Custom RPC Providers

For production applications, we strongly recommend using dedicated RPC providers to ensure reliability and performance.

### Popular Solana RPC Providers

| Provider                                | Features                                 | Notes                      |
| --------------------------------------- | ---------------------------------------- | -------------------------- |
| [Helius](https://helius.dev/)           | High-performance RPCs, webhooks, DAS API | Recommended for production |
| [QuickNode](https://www.quicknode.com/) | Global infrastructure, analytics         | Enterprise features        |
| [Alchemy](https://www.alchemy.com/)     | Enhanced APIs, developer tools           | Full-featured platform     |
| [Triton](https://triton.one/)           | Geyser plugin support                    | Advanced use cases         |

### Configuring a Custom Provider

Example using Helius:

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

const HELIUS_API_KEY = process.env.NEXT_PUBLIC_HELIUS_API_KEY;

export default function Providers({ children }) {
  return (
    <MoonKeyProvider
      publishableKey="your-moonkey-publishableKey"
      config={{
        solana: {
          rpcs: {
            'solana:mainnet': {
              rpc: `https://mainnet.helius-rpc.com/?api-key=${HELIUS_API_KEY}`,
              rpcSubscriptions: `wss://mainnet.helius-rpc.com/?api-key=${HELIUS_API_KEY}`
            }
          }
        }
      }}
    >
      {children}
    </MoonKeyProvider>
  );
}
```

## Custom SVM Networks

You can interact with custom SVM-compatible networks by creating a `Connection` instance with the custom RPC URL:

```tsx theme={null}
import { useSendTransaction } from '@moon-key/react-auth/solana';
import { Connection, Transaction } from '@solana/web3.js';

export default function CustomNetworkTransaction() {
  const { sendTransaction } = useSendTransaction();

  const handleTransaction = async () => {
    // Initialize connection with custom RPC
    const connection = new Connection('https://custom-rpc-url.com');

    const transaction = new Transaction().add(
      // Add your instructions here
    );

    const signature = await sendTransaction({
      transaction,
      connection
    });

    console.log('Transaction sent:', signature);
  };

  return <button onClick={handleTransaction}>Send Transaction</button>;
}
```

## Environment-Based Configuration

Configure different RPC endpoints for different environments:

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

const isDevelopment = process.env.NODE_ENV === 'development';

const MAINNET_RPC = process.env.NEXT_PUBLIC_SOLANA_MAINNET_RPC;
const DEVNET_RPC = process.env.NEXT_PUBLIC_SOLANA_DEVNET_RPC;

export default function Providers({ children }) {
  return (
    <MoonKeyProvider
      publishableKey="your-moonkey-publishableKey"
      config={{
        solana: {
          rpcs: {
            'solana:mainnet': {
              rpc: MAINNET_RPC || 'https://api.mainnet-beta.solana.com',
              rpcSubscriptions: MAINNET_RPC?.replace('https', 'wss') || 
                'wss://api.mainnet-beta.solana.com'
            },
            'solana:devnet': {
              rpc: DEVNET_RPC || 'https://api.devnet.solana.com',
              rpcSubscriptions: DEVNET_RPC?.replace('https', 'wss') || 
                'wss://api.devnet.solana.com'
            }
          }
        }
      }}
    >
      {children}
    </MoonKeyProvider>
  );
}
```

**Environment variables (.env.local):**

```bash theme={null}
NEXT_PUBLIC_SOLANA_MAINNET_RPC=https://mainnet.helius-rpc.com/?api-key=YOUR-KEY
NEXT_PUBLIC_SOLANA_DEVNET_RPC=https://devnet.helius-rpc.com/?api-key=YOUR-KEY
```

## Working with Different Clusters

### Switching Between Clusters

You can work with different clusters by creating separate `Connection` instances:

```tsx theme={null}
import { Connection } from '@solana/web3.js';

const mainnetConnection = new Connection('https://api.mainnet-beta.solana.com');
const devnetConnection = new Connection('https://api.devnet.solana.com');
const testnetConnection = new Connection('https://api.testnet.solana.com');

// Use the appropriate connection for your needs
const balance = await mainnetConnection.getBalance(publicKey);
```

### Detecting Current Cluster

Determine which cluster a connection is using:

```tsx theme={null}
import { Connection, clusterApiUrl } from '@solana/web3.js';

function getClusterFromUrl(url: string): string {
  if (url.includes('mainnet')) return 'mainnet-beta';
  if (url.includes('devnet')) return 'devnet';
  if (url.includes('testnet')) return 'testnet';
  return 'custom';
}

const connection = new Connection('https://api.devnet.solana.com');
const cluster = getClusterFromUrl(connection.rpcEndpoint);
console.log('Current cluster:', cluster); // 'devnet'
```

## Common Configurations

### Development Setup (Devnet)

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

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    solana: {
      rpcs: {
        'solana:devnet': {
          rpc: 'https://api.devnet.solana.com',
          rpcSubscriptions: 'wss://api.devnet.solana.com'
        }
      }
    }
  }}
>
  {children}
</MoonKeyProvider>
```

### Production Setup (Mainnet with Helius)

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

const HELIUS_KEY = process.env.NEXT_PUBLIC_HELIUS_API_KEY;

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    solana: {
      rpcs: {
        'solana:mainnet': {
          rpc: `https://mainnet.helius-rpc.com/?api-key=${HELIUS_KEY}`,
          rpcSubscriptions: `wss://mainnet.helius-rpc.com/?api-key=${HELIUS_KEY}`
        }
      }
    }
  }}
>
  {children}
</MoonKeyProvider>
```

### Multi-Cluster Support

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

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    solana: {
      rpcs: {
        'solana:mainnet': {
          rpc: 'https://api.mainnet-beta.solana.com',
          rpcSubscriptions: 'wss://api.mainnet-beta.solana.com'
        },
        'solana:devnet': {
          rpc: 'https://api.devnet.solana.com',
          rpcSubscriptions: 'wss://api.devnet.solana.com'
        }
      }
    }
  }}
>
  {children}
</MoonKeyProvider>
```

## Best Practices

### Use Dedicated RPCs for Production

* Default public RPCs have rate limits unsuitable for production
* Dedicated providers offer better performance and reliability
* Set up monitoring and alerts for RPC health
* Have fallback RPCs configured

### Secure Your API Keys

Store RPC API keys securely:

```bash theme={null}
# .env.local (never commit to git)
NEXT_PUBLIC_HELIUS_API_KEY=your-api-key-here
NEXT_PUBLIC_QUICKNODE_ENDPOINT=your-endpoint-here
```

```tsx theme={null}
// Use environment variables
const apiKey = process.env.NEXT_PUBLIC_HELIUS_API_KEY;
```

### Choose the Right Cluster

| Use Case     | Cluster      | Why                                |
| ------------ | ------------ | ---------------------------------- |
| Production   | Mainnet Beta | Real transactions with real SOL    |
| Development  | Devnet       | Free test SOL, stable for testing  |
| Load Testing | Testnet      | Performance testing before mainnet |
| CI/CD        | Devnet       | Automated testing with test tokens |

### Monitor RPC Performance

Track key metrics:

* Request latency
* Error rates
* Rate limit usage
* Websocket connection stability

### Use Websockets for Real-Time Data

For real-time updates (account changes, transaction confirmations), use websocket connections:

```tsx theme={null}
import { Connection, PublicKey } from '@solana/web3.js';

// Create connection with websocket support
const connection = new Connection(
  'https://mainnet.helius-rpc.com/?api-key=YOUR-KEY',
  {
    wsEndpoint: 'wss://mainnet.helius-rpc.com/?api-key=YOUR-KEY'
  }
);

// Subscribe to account changes
const subscriptionId = connection.onAccountChange(
  publicKey,
  (accountInfo) => {
    console.log('Account updated:', accountInfo);
  }
);
```

## Troubleshooting

### RPC Connection Errors

**Problem:** Cannot connect to Solana RPC.

**Solutions:**

* Verify RPC URL is correct and accessible
* Check API key is valid and not expired
* Ensure rate limits haven't been exceeded
* Try fallback RPC endpoints

### Transaction Timeouts

**Problem:** Transactions time out or fail to confirm.

**Solutions:**

* Use RPC providers with better uptime (Helius, QuickNode)
* Increase transaction confirmation timeout
* Implement retry logic with exponential backoff
* Check Solana network status for congestion

### Websocket Disconnections

**Problem:** Websocket connections drop frequently.

**Solutions:**

* Implement reconnection logic
* Use dedicated RPC providers with stable websockets
* Monitor connection health and reconnect proactively
* Consider using polling for less time-sensitive data

### Rate Limit Errors

**Problem:** Hitting RPC rate limits.

**Solutions:**

* Upgrade to paid RPC provider plan
* Implement request batching
* Cache responses when possible
* Use websockets instead of polling

## Testing on Different Networks

### Getting Test SOL

For development and testing:

**Devnet:**

```bash theme={null}
solana airdrop 2 YOUR_WALLET_ADDRESS --url devnet
```

Or use the [Solana Faucet](https://faucet.solana.com/)

**Testnet:**

```bash theme={null}
solana airdrop 2 YOUR_WALLET_ADDRESS --url testnet
```

### Network-Specific Testing

Test your application on different networks:

```tsx theme={null}
const networks = ['mainnet', 'devnet', 'testnet'];

networks.forEach(network => {
  test(`Transaction works on ${network}`, async () => {
    const connection = new Connection(getNetworkUrl(network));
    // Your test code here
  });
});
```

## Related Resources

* [Solana Clusters Documentation](https://solana.com/docs/core/clusters)
* [Solana RPC API Reference](https://solana.com/docs/rpc)
* [Configure EVM Networks](/get-started/frontend-sdks/react/advanced/configure-evm-networks)
* [Solana Web3.js Documentation](https://solana-labs.github.io/solana-web3.js/)
* [Helius RPC Documentation](https://docs.helius.dev/)