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)

X402_NETWORK=base
X402_NETWORK_RPC_URL=https://mainnet.base.org
USDC_TOKEN_ADDRESS=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Development/Testing

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:

# 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. 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.

---

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

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
• BaseScan Block Explorer
• MetaMask Documentation
• Configuration Guide
• Securitization Feature Documentation

---

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