Sperax Ecosystem Crypto & DeFI MCP Server

Model Context Protocol Server for Sperax DeFi Ecosystem

Enable AI agents to interact with USDs (auto-yield stablecoin), SPA governance, veSPA staking, and Demeter yield farms, and Plutus on BNB Chain and Arbitrum.

🔧 Development

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm

Setup

# Clone repository
git clone https://github.com/nirholas/sperax-crypto-mcp
cd sperax-crypto-mcp

# Install dependencies
pnpm install

# Build TypeScript
pnpm build

# Run in development mode (with auto-rebuild)
pnpm dev

Running

# Start stdio server (for Claude Desktop)
pnpm start

# Start HTTP server (for integrations)
pnpm start:http

# Run with BNB Chain RPC
CUSTOM_RPC_URL="https://..." pnpm start

# Run with Arbitrum RPC
ARBITRUM_RPC_URL="https://..." pnpm start

Testing

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Test with MCP Inspector
npx @modelcontextprotocol/inspector dist/index.js

Linting & Type Checking

# Lint code
pnpm lint

# Type check
pnpm typecheck

🤝 Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "sperax": {
      "command": "npx",
      "args": ["-y", "@sperax/mcp-server"]
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

Cursor / VS Code

Add to your MCP settings:

{
  "mcp.servers": {
    "sperax": {
      "command": "npx",
      "args": ["-y", "@sperax/mcp-server"]
    }
  }
}

With Custom RPC Endpoint

For better performance and reliability, use your own Arbitrum RPC:

{
  "mcpServers": {
    "sperax": {
      "command": "npx",
      "args": ["-y", "@sperax/mcp-server"],
      "env": {
        "ARBITRUM_RPC_URL": "https://your-rpc-endpoint.com"
      }
    }
  }
}

HTTP Server Mode

For advanced integrations, run as an HTTP server:

# Start HTTP server on port 3000
pnpm start:http

# Or with custom port
PORT=8080 pnpm start:http

🛠️ Available Tools

USDs Stablecoin (7 tools)

Vault & Collateral (10 tools)

SPA & Staking (8 tools)

Demeter Farms (7 tools)

Dripper (5 tools)

Oracle (5 tools)

Analytics (6 tools)

Governance (5 tools)

Yield Reserve (4 tools)

📚 Available Resources

💡 Example Conversations

Check USDs Yield

User: "What's the current USDs APY and how much would I earn on $10,000?"

Agent: Uses usds_get_yield_info and calculates projections

Find Best Farms

User: "Show me Demeter farms with over 20% APR"

Agent: Uses demeter_get_top_farms with minApr filter

Calculate veSPA Power

User: "How much voting power would I get locking 1000 SPA for 2 years?"

Agent: Uses vespa_calculate_power with amount=1000, days=730

Protocol Health Check

User: "Give me an overview of the Sperax protocol health"

Agent: Uses multiple tools to compile health dashboard

Portfolio Analysis

User: "Check my USDs balance at 0x..."

Agent: Uses usds_get_balance and usds_get_yield_info

💬 Example Prompts

📖 How USDs Works

The Auto-Yield Mechanism

USDs is unique among stablecoins because it generates yield automatically:

1. Deposit Collateral → User deposits USDC, USDT, DAI, or FRAX
2. Mint USDs → Protocol mints USDs 1:1 (minus small fee)
3. Deploy to Strategies → Collateral deployed to Aave, Compound, Stargate, Fluid
4. Generate Yield → Strategies earn yield from lending/liquidity
5. Collect & Distribute → Protocol collects yield daily
6. Auto-Rebase → Your USDs balance increases automatically!

Yield Distribution

Why It's Special

• ✅ No claiming — Yield appears in your wallet automatically
• ✅ No staking — Just hold USDs in any wallet
• ✅ Composable — Use USDs in DeFi while earning yield
• ✅ Fully backed — 100%+ collateralized by stablecoins
• ✅ Transparent — All operations visible on-chain

🏗️ Protocol Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         SPERAX PROTOCOL                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
│  │   USDs      │◄───│   Vault     │───►│  Strategies │          │
│  │ Stablecoin  │    │  (TVL Hub)  │    │ Aave/Comp/  │          │
│  │  ~5% APY    │    │             │    │  Stargate   │          │
│  └─────────────┘    └─────────────┘    └─────────────┘          │
│         ▲                  │                   │                │
│         │                  ▼                   ▼                │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
│  │   Dripper   │◄───│Yield Reserve│◄───│   Oracles   │          │
│  │ (Daily Drip)│    │ (70%/30%)   │    │ (Chainlink) │          │
│  └─────────────┘    └─────────────┘    └─────────────┘          │
│         │                  │                                    │
│         ▼                  ▼                                    │
│  ┌─────────────┐    ┌─────────────┐                             │
│  │   Rebase    │    │ SPA Buyback │                             │
│  │  (70% →     │    │   (30% →    │                             │
│  │   Holders)  │    │    Burn)    │                             │
│  └─────────────┘    └─────────────┘                             │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                      GOVERNANCE LAYER                           │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
│  │    SPA      │───►│   veSPA     │───►│  Governance │          │
│  │   Token     │    │   (Locked)  │    │  (Snapshot) │          │
│  └─────────────┘    └─────────────┘    └─────────────┘          │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────┐    ┌─────────────┐                             │
│  │   xSPA      │───►│   Demeter   │                             │
│  │  (Rewards)  │    │   (Farms)   │                             │
│  └─────────────┘    └─────────────┘                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

📐 Key Protocol Formulas

veSPA Voting Power

veSPA = SPA × (lockDays / 365)

⚠️ Note: Voting power decays linearly as unlock time approaches. No early unlock!

xSPA Redemption

SPA_out = xSPA × (vestingDays + 150) / 330

USDs Rebase (Auto-Yield)

USDs uses a credit system for automatic yield distribution:

balance = credits / creditsPerToken

When yield is distributed:

1. Protocol collects yield from strategies (Aave, Compound, Stargate, Fluid)
2. 70% is distributed to USDs holders via rebase
3. creditsPerToken decreases globally
4. Your balance increases automatically!

No claiming required. Your wallet balance grows daily.

🔒 Security

Security Considerations

• This server provides read-only access to on-chain data
• Transaction signing must happen through user's wallet
• Always verify contract addresses before interacting
• Use official RPC endpoints or trusted providers

⚙️ Environment Variables

🔗 Links

📋 Contract Addresses (Arbitrum One)

Core Protocol

Staking

Yield Distribution

Oracles

Demeter Protocol

Yield Strategies

Supported Collaterals

📊 Server Capabilities

✨ Features

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ by the Sperax Team

_{Empowering Autonomous Finance on Arbitrum and BNB Chain}