metamask-integration/docs/METAMASK_TOKEN_LIST_HOSTING.md

MetaMask Token List Hosting Guide

Date: $(date)
Purpose: Guide for hosting the MetaMask token list publicly

---

📋 Overview

The MetaMask token list (METAMASK_TOKEN_LIST.json) needs to be hosted on a public URL for automatic token discovery in MetaMask.

---

🚀 Hosting Options

Option 1: GitHub Pages (Recommended)

Advantages:

• Free hosting
• Easy to set up
• Automatic HTTPS
• Version control
• CDN-backed

Steps:

1. Prepare Token List

   cd /home/intlc/projects/proxmox
   bash scripts/host-token-list.sh github
   

   This creates token-list.json in the project root.

2. Create GitHub Repository (if not exists)

   • Create a new public repository
   • Or use existing repository

3. Add Token List to Repository

   git add token-list.json
   git commit -m "Add MetaMask token list for ChainID 138"
   git push
   

4. Enable GitHub Pages

   • Go to repository Settings → Pages
   • Select branch (usually main or master)
   • Select folder: / (root)
   • Click Save

5. Access Token List

   • URL format: https://<username>.github.io/<repo>/token-list.json
   • Example: https://yourusername.github.io/token-list/token-list.json

6. Add to MetaMask

   • MetaMask → Settings → Security & Privacy → Token Lists
   • Click "Add custom token list"
   • Enter your GitHub Pages URL
   • Click "Add"

---

Option 2: IPFS (Decentralized)

Advantages:

• Decentralized hosting
• Permanent URLs
• No single point of failure
• Censorship-resistant

Steps:

1. Install IPFS (if not installed)

   # Follow: https://docs.ipfs.io/install/
   

2. Start IPFS Node

   ipfs daemon
   

3. Add Token List to IPFS

   cd /home/intlc/projects/proxmox
   ipfs add docs/METAMASK_TOKEN_LIST.json
   

4. Pin the File (to keep it available)

   ipfs pin add <hash>
   

5. Access Token List

   • IPFS Gateway: https://ipfs.io/ipfs/<hash>
   • Pinata Gateway: https://gateway.pinata.cloud/ipfs/<hash>
   • Cloudflare Gateway: https://cloudflare-ipfs.com/ipfs/<hash>

6. Add to MetaMask

   • Use any of the gateway URLs above
   • Add to MetaMask token lists

Note: IPFS hashes are permanent. If you update the token list, you'll get a new hash.

---

Option 3: Custom Domain/Server

Advantages:

• Full control
• Branded URL
• Custom CDN
• Professional appearance

Steps:

1. Copy Token List to Server

   scp docs/METAMASK_TOKEN_LIST.json user@server:/var/www/html/token-list.json
   

2. Configure Web Server (nginx example)

   location /token-list.json {
       add_header Access-Control-Allow-Origin *;
       add_header Access-Control-Allow-Methods "GET, OPTIONS";
       add_header Content-Type application/json;
       try_files $uri =404;
   }
   

3. Ensure HTTPS

   • Use Let's Encrypt or similar
   • MetaMask requires HTTPS for token lists

4. Access Token List

   • URL: https://your-domain.com/token-list.json

5. Add to MetaMask

   • Use your custom domain URL

---

✅ Verification

Test Token List URL

# Test accessibility
curl -I https://your-url.com/token-list.json

# Should return:
# HTTP/2 200
# Content-Type: application/json
# Access-Control-Allow-Origin: *

Validate JSON

# Validate JSON structure
curl https://your-url.com/token-list.json | jq .

# Should return valid JSON without errors

Test in MetaMask

1. Add token list URL to MetaMask
2. Verify tokens appear automatically
3. Check token metadata (name, symbol, decimals)
4. Verify logos load (if configured)

---

📝 Token List Updates

Updating the Token List

1. Update Local File

   • Edit docs/METAMASK_TOKEN_LIST.json
   • Increment version number
   • Update timestamp

2. Deploy Update

   • GitHub Pages: Commit and push changes
   • IPFS: Add new file, get new hash, update URL
   • Custom Server: Upload new file

3. Version Control

   • Keep version numbers in sync
   • Document changes in commit messages
   • Consider semantic versioning

---

🔧 Current Token List

File: docs/METAMASK_TOKEN_LIST.json

Tokens Included:

1. ETH/USD Price Feed (0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6)

   • Decimals: 8
   • Symbol: ETH-USD

2. WETH9 (0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2)

   • Decimals: 18
   • Symbol: WETH

3. WETH10 (0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f)

   • Decimals: 18
   • Symbol: WETH10

---

🎯 Recommended Approach

For Production: Use GitHub Pages

• Easy to maintain
• Free hosting
• Automatic HTTPS
• Version control built-in

For Decentralization: Use IPFS

• Permanent URLs
• Decentralized
• Censorship-resistant

For Branding: Use Custom Domain

• Professional appearance
• Full control
• Custom CDN options

---

📚 Related Documentation

• MetaMask Integration Complete
• Token List File
• Hosting Script

---

Last Updated: $(date)