> ## Documentation Index
> Fetch the complete documentation index at: https://tonic-ai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MetaMask Setup Guide

> Configure MetaMask for Base network blockchain operations

## Overview

CreditNexus uses the **Base network** (Coinbase's Layer 2 on Ethereum) for blockchain operations including securitization, notarization, and x402 payments. This guide covers MetaMask network configuration.

**Code Reference**: `app/core/config.py` (lines 143-172), `contracts/hardhat.config.js`

***

## Base Network Overview

CreditNexus uses Base network for:

* x402 payment processing (USDC stablecoin)
* Smart contract deployments (securitization contracts)
* Notarization transactions
* ERC-721 tranche token minting

**Network**: Base (Coinbase Layer 2)\
**Chain ID**: 8453 (Mainnet) / 84532 (Sepolia Testnet)

***

## Required Networks

### Base Mainnet (Production)

**Network Details:**

* **Network Name**: Base Mainnet
* **RPC URL**: `https://mainnet.base.org`
* **Chain ID**: `8453` (decimal) / `0x2105` (hex)
* **Currency Symbol**: ETH
* **Block Explorer**: `https://basescan.org`

**USDC Token Address (Base Mainnet):**

```
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
```

### Base Sepolia (Testnet - Development/Testing)

**Network Details:**

* **Network Name**: Base Sepolia
* **RPC URL**: `https://sepolia.base.org`
* **Chain ID**: `84532` (decimal) / `0x14A34` (hex)
* **Currency Symbol**: ETH
* **Block Explorer**: `https://sepolia.basescan.org`

**USDC Token Address (Base Sepolia):**

```
0x036CbD53842c5426634e7929541eC2318f3dCF7e
```

***

## Manual MetaMask Configuration

### Option 1: Add Base Mainnet Manually

1. **Open MetaMask** → Click network dropdown (top of extension)
2. **Click "Add Network"** or "Add a network manually"
3. **Enter the following details:**

```
Network Name: Base Mainnet
RPC URL: https://mainnet.base.org
Chain ID: 8453
Currency Symbol: ETH
Block Explorer URL: https://basescan.org
```

4. **Click "Save"**

### Option 2: Add Base Sepolia (Testnet) Manually

1. **Open MetaMask** → Click network dropdown
2. **Click "Add Network"** or "Add a network manually"
3. **Enter the following details:**

```
Network Name: Base Sepolia
RPC URL: https://sepolia.base.org
Chain ID: 84532
Currency Symbol: ETH
Block Explorer URL: https://sepolia.basescan.org
```

4. **Click "Save"**

***

## Automatic Network Addition

CreditNexus can automatically prompt MetaMask to add the Base network. The frontend includes network detection and switching logic.

**Code Reference**: `client/src/context/WalletContext.tsx`, `client/src/hooks/useNetworkConfig.ts`

***

## Environment Configuration

CreditNexus automatically selects the network based on `X402_NETWORK_RPC_URL`:

### Production (Default)

```env theme={null}
X402_NETWORK=base
X402_NETWORK_RPC_URL=https://mainnet.base.org
USDC_TOKEN_ADDRESS=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
```

### Development/Testing

```env theme={null}
X402_NETWORK=base
X402_NETWORK_RPC_URL=https://sepolia.base.org
USDC_TOKEN_ADDRESS=0x036CbD53842c5426634e7929541eC2318f3dCF7e
```

**Code Reference**: `app/core/config.py` (lines 143-172)

***

## Smart Contract Addresses

After deploying contracts, add addresses to `.env`:

```env theme={null}
# Securitization Contracts (Base network, Base Sepolia, or local Hardhat)
SECURITIZATION_NOTARIZATION_CONTRACT=0x...
SECURITIZATION_TOKEN_CONTRACT=0x...
SECURITIZATION_PAYMENT_ROUTER_CONTRACT=0x...

# USDC Token (Base Mainnet; for Base Sepolia or local use the matching address)
USDC_TOKEN_ADDRESS=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
```

**Contract Deployment**: See [Smart Contract Deployment](../../README.md#06-smart-contract-deployment-optional---for-securitization-features). For **local development without a private key**, use `npm run deploy:local` or `npm run node` + `npm run deploy:localhost` in `contracts/`; see [`contracts/README.md`](../../contracts/README.md#deployment).

***

## Network Configuration Reference

### Base Mainnet (Production)

| Setting             | Value                                             |
| ------------------- | ------------------------------------------------- |
| **Network Name**    | Base Mainnet                                      |
| **RPC URL**         | `https://mainnet.base.org`                        |
| **Chain ID**        | `8453` (decimal) / `0x2105` (hex)                 |
| **Currency Symbol** | ETH                                               |
| **Block Explorer**  | `https://basescan.org`                            |
| **USDC Token**      | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`      |
| **Use Case**        | Production payments, securitization, notarization |

### Base Sepolia (Testnet)

| Setting             | Value                                                     |
| ------------------- | --------------------------------------------------------- |
| **Network Name**    | Base Sepolia                                              |
| **RPC URL**         | `https://sepolia.base.org`                                |
| **Chain ID**        | `84532` (decimal) / `0x14A34` (hex)                       |
| **Currency Symbol** | ETH                                                       |
| **Block Explorer**  | `https://sepolia.basescan.org`                            |
| **USDC Token**      | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` (test token) |
| **Use Case**        | Development, testing, contract deployment                 |

### Local Hardhat (development, no private key)

| Setting          | Value                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Network Name** | Localhost 8545                                                                                                                   |
| **RPC URL**      | `http://127.0.0.1:8545`                                                                                                          |
| **Chain ID**     | `1337`                                                                                                                           |
| **Use Case**     | Local development; deploy with `npm run deploy:local` or `npm run node` + `npm run deploy:localhost` (see `contracts/README.md`) |

***

## Quick Setup Checklist

### For Production Use:

* [ ] Add Base Mainnet to MetaMask (Chain ID: 8453)
* [ ] Ensure USDC is available in wallet (or use faucet)
* [ ] Verify network in MetaMask shows "Base Mainnet"
* [ ] Test connection in CreditNexus application
* [ ] Set `X402_NETWORK_RPC_URL=https://mainnet.base.org` in `.env`

### For Development/Testing:

* [ ] Add Base Sepolia to MetaMask (Chain ID: 84532), or use **local Hardhat** (Chain ID: 1337, RPC: `http://127.0.0.1:8545`) with `npm run node` and `npm run deploy:localhost` in `contracts/` (no private key)
* [ ] Get test ETH from Base Sepolia faucet (or use pre-funded Hardhat accounts locally)
* [ ] Get test USDC if needed (not required for local)
* [ ] Set `X402_NETWORK_RPC_URL=https://sepolia.base.org` or `http://127.0.0.1:8545` for local in `.env`
* [ ] Test contract deployment and interactions

***

## Troubleshooting

### Issue: "Unrecognized network"

**Solution**: Add Base network manually using the configuration above, or use the auto-add functionality in the application.

### Issue: "Insufficient funds"

**Solution**:

* **Mainnet**: Purchase ETH on an exchange and bridge to Base
* **Sepolia**: Use Base Sepolia faucet: [https://www.coinbase.com/faucets/base-ethereum-goerli-faucet](https://www.coinbase.com/faucets/base-ethereum-goerli-faucet)

### Issue: "Transaction failed"

**Solution**:

* Ensure you're on the correct network (Base Mainnet or Base Sepolia)
* Check you have sufficient ETH for gas fees
* Verify USDC token address matches the network

### Issue: "USDC not showing"

**Solution**:

* **Mainnet**: Add custom token with address `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
* **Sepolia**: Add test USDC token with address `0x036CbD53842c5426634e7929541eC2318f3dCF7e`

***

## Security Notes

1. **Never share your private key or seed phrase**
2. **Always verify network details** before adding to MetaMask
3. **Use testnet for development** to avoid spending real funds
4. **Double-check contract addresses** match the network you're on
5. **Verify transactions on block explorer** before confirming

***

## Additional Resources

* [Base Network Documentation](https://docs.base.org/)
* [BaseScan Block Explorer](https://basescan.org/)
* [MetaMask Documentation](https://docs.metamask.io/)
* [Configuration Guide](/getting-started/configuration#blockchain--smart-contract-configuration)
* [Securitization Feature Documentation](/features/securitization)

***

**Last Updated**: 2026-01-14\
**Code Reference**: `app/core/config.py`, `contracts/hardhat.config.js`