<div align="center">

⛓️ Sonic Blockchain MCP Server v0.1

Production-ready Model Context Protocol (MCP) server for Sonic blockchain integration

Features • Quick Start • Tools • Examples • Prompts • Use Cases • Security

</div>

---

🚀 Features

⚡ Sonic Blockchain Integration

• 10,000+ TPS - Lightning-fast EVM-compatible transaction processing
• Sub-second Finality - Transactions confirmed in under 1 second
• EVM Compatible - Full Ethereum compatibility with Sonic speed
• Low Fees - Minimal transaction costs on native S token
• Bridge Support - Seamless Ethereum ↔ Sonic token bridging

🛠️ Core Capabilities

• Wallet Management - Generate wallets with mnemonic phrases
• Balance Checking - Check native S, wS, WETH, USDC balances on Sonic and ETH on Ethereum
• Transactions - Transfer native S tokens and ERC20 tokens (wS, WETH, USDC)
• Staking Operations - Stake/unstake S tokens to validators, claim rewards
• Bridge Operations - Bridge tokens between Ethereum and Sonic networks
• Token Information - Get ERC20 token details (name, symbol, decimals)
• Network Monitoring - Real-time staking statistics and validator information

🔧 Developer Tools

• Multi-Network Support - Seamless Sonic/Ethereum switching
• Explorer Integration - Direct links to Sonicscan and Etherscan
• Environment Configuration - Easy wallet setup via .env
• Token Symbol Support - Built-in mapping for S, wS, WETH, USDC, USDT
• Dynamic Decimals Detection - Automatic token decimals from contracts
• Archive Node Support - eth_getProof for bridge claims

🏛️ Enterprise-Ready

• Built with ethers.js v6
• Comprehensive error handling
• Automatic network selection (Sonic/Ethereum)
• Docker containerization support
• MCP protocol implementation
• 18 specialized blockchain tools
• Multi-chain bridge infrastructure

---

📦 Quick Start

✅ Prerequisites

# Required
Node.js >= 18.0.0
npm >= 9.0.0

📥 Installation

# Clone the repository
git clone https://github.com/Tairon-ai/sonic-mcp.git
cd sonic-mcp

# Install dependencies
npm install

# Configure environment (optional)
cp .env.example .env
# Edit .env to set wallet credentials and RPC endpoints

# Start the server
npm start

# Development mode
npm run dev

# MCP stdio server for Claude Desktop
npm run mcp

🤖 Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "sonic": {
      "command": "node",
      "args": ["/path/to/sonic-mcp/mcp/index.js"],
      "env": {
        "WALLET_ADDRESS": "your_wallet_address_here",
        "WALLET_PRIVATE_KEY": "your_private_key_here",
        "SONIC_RPC_URL": "https://rpc.soniclabs.com",
        "ETHEREUM_RPC_URL": "https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY"
      }
    }
  }
}

---

🛠 Available Tools

👤 Wallet Operations

Tool	Description	Key Parameters
generate_wallet	Generate new Sonic wallet with address, private key, and mnemonic	-
check_balance	Check wallet balances (Sonic: S, wS, WETH, USDC; Ethereum: ETH)	address (optional), chain (optional)
get_token_info	Get ERC20 token information (name, symbol, decimals)	token_address

💸 Transaction Operations

Tool	Description	Key Parameters
transfer	Transfer native S or ERC20 tokens (wS, WETH, USDC)	amount, token, to_address, private_key (optional)
get_token_price	Get current S token price in USD	-

🪙 Staking Operations

Tool	Description	Key Parameters
get_network_staking_stats	Get network-wide staking statistics (APR, total stake, rewards)	-
get_staking_validators	Get list of all available validators with IDs and names	-
stake	Stake S tokens to a validator (14-day unstaking period applies)	validator_id, amount, private_key (optional)
unstake	Unstake S tokens from a validator	validator_id, withdrawal_request_id, amount, private_key (optional)
get_staking_info	Get staking information for wallet and validator	address (optional), validator_id
claim_rewards	Claim staking rewards from a validator	validator_id, private_key (optional)

🌉 Bridge Operations (Ethereum → Sonic)

Tool	Description	Key Parameters
bridge_to_sonic	STEP 1: Deposit tokens from Ethereum to Sonic bridge (ETH→WETH, USDC, USDT)	token, amount, private_key (optional)
check_bridge_status	STEP 2: Check if bridge deposit is ready to claim on Sonic	deposit_block_number
claim_on_sonic	STEP 3: Claim bridged tokens on Sonic (requires archive node)	deposit_id, token_address, amount, block_number, private_key (optional)

🌉 Bridge Operations (Sonic → Ethereum)

Tool	Description	Key Parameters
bridge_to_ethereum	STEP 1: Withdraw tokens from Sonic to Ethereum (WETH, USDC, USDT only)	token, amount, private_key (optional)
check_withdrawal_status	STEP 2: Check if withdrawal is ready to claim on Ethereum	withdrawal_block_number
claim_on_ethereum	STEP 3: Claim withdrawn tokens on Ethereum	withdrawal_id, token_address, amount, private_key (optional)

---

🌉 Bridge Process

Overview

Bridging between Ethereum and Sonic is a 3-step process that takes approximately 9 minutes. Each step must be executed separately.

🔵 Ethereum → Sonic

1. Deposit - Use bridge_to_sonic with ETH, USDC, or USDT (ETH auto-wraps to WETH)
2. Wait - Use check_bridge_status with blockNumber until ready: true (~9 min)
3. Claim - Use claim_on_sonic with depositId, token, amount, blockNumber

🟠 Sonic → Ethereum

1. Withdraw - Use bridge_to_ethereum with WETH, USDC, or USDT (⚠️ S/wS NOT supported)
2. Wait - Use check_withdrawal_status with blockNumber until ready: true (~9 min)
3. Claim - Use claim_on_ethereum with withdrawalId, token, amount

⚠️ Important Notes

• Save depositId/withdrawalId and blockNumber from Step 1
• Archive Node Required - Configure Alchemy/Infura in ETHEREUM_RPC_URL for claims
• Native S/wS cannot be bridged to Ethereum
• Track Status - Use https://gateway.soniclabs.com/ for manual tracking
• Supported Tokens - ETH→WETH, USDC, USDT only

---

🏦 Staking Guide

Overview

Stake your S tokens to validators on Sonic blockchain to earn rewards while helping secure the network.

⏱️ Staking Timeline

1. Stake - Instant (use stake tool with validator_id and amount)
2. Earn Rewards - Continuous rewards accumulation
3. Claim - Anytime (use claim_rewards - no waiting period)
4. Unstake - Initiates withdrawal (use unstake tool)
5. Wait - 14-day mandatory lock period ⏰
6. Withdraw - Available after 14 days

🛠️ Staking Tools

• get_staking_validators - List all 32 validators with IDs and names
• get_network_staking_stats - Check current APR, total stake, daily rewards
• stake - Stake S tokens to a validator (instant)
• get_staking_info - Check your stake, pending rewards, withdrawal status
• claim_rewards - Claim accumulated rewards (no lock period)
• unstake - Initiate unstaking (starts 14-day timer)

⚠️ Important: 14-Day Withdrawal Period

When you unstake S tokens, there is a mandatory 14-day waiting period before withdrawal. This is a protocol-level security feature and cannot be bypassed.

💡 Staking Tips

• Choose wisely - Validators with "MAX APR" offer higher rewards
• Claim often - Rewards can be claimed anytime without lock period
• Plan ahead - Remember the 14-day wait when planning to unstake
• Diversify - Consider staking to multiple validators
• Monitor APR - Check rates with get_network_staking_stats

📊 Example Workflow

# 1. Get list of validators
"Show me all validators"

# 2. Check network stats
"What's the current staking APR?"

# 3. Stake tokens
"Stake 100 S to validator 18"

# 4. Check your stake
"Get staking info for validator 18"

# 5. Claim rewards (anytime)
"Claim rewards from validator 18"

# 6. Unstake (starts 14-day timer)
"Unstake 50 S from validator 18 with wrID 0"

---

💡 Examples

Note on Transactions: To send tokens or perform staking operations, you need either:

• A configured wallet in .env with WALLET_PRIVATE_KEY
• Or provide the private key directly in the tool parameters

For read-only operations (balance checks, validator info), only addresses are needed.

🏦 Create and Check Wallet

// Generate new wallet
{
  "tool": "generate_wallet"
}
// Returns: address, privateKey, mnemonic

// Check balance on Sonic (default)
{
  "tool": "check_balance",
  "params": {
    "address": "0xYOUR_WALLET_ADDRESS"
  }
}

// Check balance on Ethereum
{
  "tool": "check_balance",
  "params": {
    "address": "0xYOUR_WALLET_ADDRESS",
    "chain": "ethereum"
  }
}

// Transfer S tokens with configured wallet (automatic)
{
  "tool": "transfer",
  "params": {
    "amount": 10.5,
    "token": "S",
    "to_address": "0xRECIPIENT_ADDRESS"
  }
}

// Transfer WETH with specific wallet
{
  "tool": "transfer",
  "params": {
    "amount": 1.5,
    "token": "WETH",
    "to_address": "0xRECIPIENT_ADDRESS",
    "private_key": "your_private_key_here"
  }
}

🪙 Staking Operations

// Get network staking statistics
{
  "tool": "get_network_staking_stats"
}

// Get all validators
{
  "tool": "get_staking_validators"
}

// Stake S tokens to validator
{
  "tool": "stake",
  "params": {
    "validator_id": 1,
    "amount": 100,
    "private_key": "your_private_key_here"
  }
}

// Get staking info for wallet
{
  "tool": "get_staking_info",
  "params": {
    "address": "0xYOUR_WALLET_ADDRESS",
    "validator_id": 1
  }
}

// Claim staking rewards
{
  "tool": "claim_rewards",
  "params": {
    "validator_id": 1,
    "private_key": "your_private_key_here"
  }
}

// Unstake S tokens
{
  "tool": "unstake",
  "params": {
    "validator_id": 1,
    "withdrawal_request_id": 0,
    "amount": 50,
    "private_key": "your_private_key_here"
  }
}

🌉 Bridge Tokens from Ethereum to Sonic

// STEP 1: Deposit ETH on Ethereum (auto-wrapped to WETH)
{
  "tool": "bridge_to_sonic",
  "params": {
    "token": "ETH",
    "amount": 0.5,
    "private_key": "your_private_key_here"
  }
}
// Returns: depositId, blockNumber (save these!)

// STEP 2: Check if deposit is ready
{
  "tool": "check_bridge_status",
  "params": {
    "deposit_block_number": 23497346
  }
}

// STEP 3: Claim tokens on Sonic
{
  "tool": "claim_on_sonic",
  "params": {
    "deposit_id": "23299771625655974319645644188271889555573968561718137144923912229732673662470",
    "token_address": "WETH",
    "amount": 0.5,
    "block_number": 23497346,
    "private_key": "your_private_key_here"
  }
}

🌉 Bridge Tokens from Sonic to Ethereum

// STEP 1: Withdraw WETH from Sonic
{
  "tool": "bridge_to_ethereum",
  "params": {
    "token": "WETH",
    "amount": 0.5,
    "private_key": "your_private_key_here"
  }
}
// Returns: withdrawalId, blockNumber (save these!)

// STEP 2: Check if withdrawal is ready
{
  "tool": "check_withdrawal_status",
  "params": {
    "withdrawal_block_number": 12345678
  }
}

// STEP 3: Claim tokens on Ethereum
{
  "tool": "claim_on_ethereum",
  "params": {
    "withdrawal_id": "98765432109876543210987654321098765432109876543210987654321098765432",
    "token_address": "WETH",
    "amount": 0.5,
    "private_key": "your_private_key_here"
  }
}

🔍 Token Information

// Get S token price
{
  "tool": "get_token_price"
}

// Get ERC20 token information
{
  "tool": "get_token_info",
  "params": {
    "token_address": "0x039e2fB66102314Ce7b64Ce5Ce3E5183bc94aD38"
  }
}

---

🤖 Prompts

💬 Example Prompts for AI Assistants

🏦 Wallet Management

"Generate a new Sonic wallet with mnemonic"
"Check balance for address 0xABC123..."
"Check my wallet balance on Ethereum"
"Generate 5 new Sonic wallets"
"Get my configured wallet balance"
"Check WETH balance for address 0xXYZ789..."
"What's the current S token price?"

💸 Transactions

"Transfer 10 S tokens to 0xRECIPIENT"
"Send 5 WETH from my wallet to 0xADDRESS"
"Transfer 100 USDC to 0xRECIPIENT"
"Send 0.5 wS tokens to 0xADDRESS"
"Get token info for wS contract"

🪙 Staking Operations

"Show me all available validators"
"Get network staking statistics"
"Stake 100 S tokens to validator 1"
"What's the current staking APR?"
"Get my staking info for validator 1"
"Claim my staking rewards from validator 1"
"Unstake 50 S tokens from validator 1"
"How much S is staked network-wide?"

🌉 Bridge Operations

"Bridge 1 ETH from Ethereum to Sonic"
"Bridge 100 USDC from Ethereum to Sonic"
"Check bridge status for block 23497346"
"Claim my deposit on Sonic"
"Bridge 0.5 WETH from Sonic to Ethereum"
"Check withdrawal status for block 12345678"
"Claim my withdrawal on Ethereum"
"What tokens can I bridge to Sonic?"

🔧 Development & Testing

"Get my configured wallet details"
"Show token information for WETH"
"Get ERC20 token decimals for USDC"
"Show me all supported token symbols"
"Check if my deposit is ready to claim"
"Get validator list with IDs"

---

🎯 Use Cases

💰 Token Management

• Generate and manage Sonic wallets
• Check balances across Sonic and Ethereum
• Transfer native S and ERC20 tokens
• Monitor token holdings
• Query token contract information

🪙 Staking Operations

• Stake S tokens to earn rewards
• Monitor staking APR and statistics
• Claim accumulated rewards
• Unstake tokens (with 14-day notice)
• Track validator performance

🌉 Cross-Chain Bridging

• Bridge ETH/WETH between networks
• Bridge USDC and USDT
• Track bridge transaction status
• Claim bridged tokens
• Multi-step bridge workflow

📊 Portfolio Tracking

• Monitor wallet balances
• Track staking positions
• View staking rewards
• Check bridge operations
• Multi-chain portfolio view

🏗️ Development & Testing

• Rapid wallet generation
• Token contract interaction
• Bridge testing and verification
• Integration with AI assistants
• Multi-network development

---

🔒 Security

🛡️ Security Features

• Private Key Management - Never expose keys, use secure storage
• Network Verification - Always confirm Sonic vs Ethereum
• Transaction Validation - Verify all parameters before signing
• Input Sanitization - All inputs validated and sanitized
• Environment Variables - Secure credential storage
• Optional Private Keys - Many read operations don't need keys

🔐 Best Practices

// DO: Use environment variables
const privateKey = process.env.WALLET_PRIVATE_KEY;

// DON'T: Hardcode sensitive data
const privateKey = "0xabc123..."; // Never do this!

// DO: Validate addresses before operations
if (!ethers.isAddress(address)) {
  throw new Error("Invalid address");
}

// DO: Use configured wallet for convenience
// No need to pass privateKey for every transaction
{
  "tool": "transfer",
  "params": {
    "amount": 10,
    "token": "S",
    "to_address": "0xRECIPIENT"
    // privateKey automatically used from env
  }
}

// DO: Use archive node for bridge claims
ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY

---

📊 Network Information

🌐 Networks

Network	Purpose	API Endpoint
Sonic Mainnet	Production	https://rpc.soniclabs.com
Ethereum Mainnet	Bridge operations	https://ethereum-rpc.publicnode.com
Archive Node	Bridge claims	https://eth-mainnet.g.alchemy.com/v2/API_KEY

⚡ Performance Metrics

• Block Time: ~1 second
• TPS: 10,000+ transactions per second
• Finality: Sub-second
• Gas: Low fees on S token
• Bridge Time: ~5-15 minutes

---

🚀 Deployment

🏭 Production Deployment

# Using npm
npm run start

# Using Docker
docker build -t sonic-mcp .
docker run -d -p 8080:8080 --env-file .env sonic-mcp

# Using Docker Compose
docker-compose up -d

🔑 Environment Variables

# Network RPC URLs
SONIC_RPC_URL=https://rpc.soniclabs.com
SONIC_RPC_URL_BACKUP=https://sonic-rpc.publicnode.com:443

# IMPORTANT: For bridge claims on Sonic, you need an Ethereum RPC with archive/historical block support
# PublicNode doesn't support eth_getProof for historical blocks, use Alchemy or Infura instead:
# Example: https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
# Example: https://mainnet.infura.io/v3/YOUR_API_KEY
ETHEREUM_RPC_URL=https://ethereum-rpc.publicnode.com

# Network Configuration
SONIC_CHAIN_ID=146
ETHEREUM_CHAIN_ID=1

# Wallet Configuration (Optional - used if not provided in tool calls)
WALLET_ADDRESS=
WALLET_PRIVATE_KEY=

# Server Configuration
PORT=8080
NODE_ENV=production

💰 Getting S Tokens

• Sonic Mainnet: Buy S from exchanges or bridge from Ethereum
• Bridge: Use the built-in bridge tools to transfer ETH/USDC from Ethereum
• Faucet: Check Sonic Discord for testnet faucets

---

📚 Resources

📖 Documentation

• Sonic Labs - Official website
• Sonic Documentation - Developer documentation
• MCP Protocol - Model Context Protocol specs
• Ethers.js Docs - Ethers.js v6 documentation

🛠️ Development Tools

• Sonic RPC - Public Sonic RPC endpoint
• Alchemy - Archive node provider for bridge claims
• Infura - Alternative archive node provider
• Node.js - JavaScript runtime required

🌍 Ecosystem

• Sonic Gateway - Bridge interface
• Sonic Discord - Community support
• Sonic Foundation - Official foundation

🔍 Block Explorers

• Sonicscan - Sonic blockchain explorer
• Etherscan - Ethereum blockchain explorer

Note: Explorer URLs are automatically included in all transaction responses

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING for guidelines.

# Fork and clone
git clone https://github.com/Tairon-ai/sonic-mcp.git
cd sonic-mcp

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
npm test

# Submit pull request
git push origin feature/amazing-feature

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

• Sonic Labs - Blockchain technology
• Ethereum Foundation - EVM compatibility
• Ethers.js - Ethereum library
• Model Context Protocol - AI integration standard

---

<div align="center">

Built by Tairon.ai team with help from Claude

</div>