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

Sperax MCP Server Repository

For best compatability, use within SperaxOS. The servers provided in this repo largely are based upon the already built and tested products on app.sperax.io. The Sperax Crypto and Defi MCP Server project is an additional product of Sperax and SperaxOS, created for the open source community. For the millions of developers that may not have had the tools available to use cryptocurrency, blockchain, defi, and web3 tools within their usual workspace, we are thrilled to be laying the groundworks for the use of blockchain and cryptocurrency use paired with the Model Context Protocol. Sperax is building an autonomous financial infrastructure, centered around its auto-yield stablecoin USDs and its utility/governance token SPA, using AI-driven agents to automate yield generation and financial management across blockchains like Arbitrum and BNB Chain. It combines collateralized stability with algorithmic mechanisms, aiming to offer passive income for users through its integrated system, which includes the SperaxOS AI infrastructure. SperaxOS is the world's first AI-native operating system for decentralized finance, transforming how enterprises, developers, and DeFi protocols manage on-chain capital. SperaxOS replaces manual DeFi workflows with autonomous, intelligent automation. While traditional AI agents generate content or answer questions, SperaxOS agents execute capital, automatically optimizing yields, rebalancing portfolios, defending against risks, and managing treasury operations 24/7 with zero human intervention. This repo will initially focus on Sperax ecosystem products such as USDs and SPA. For organizational purposes, SperaxOS documents and tools are seperated in their respective repositories.

🛠️ Available Tools

USDs Stablecoin (7 tools)

| Tool | Description | |------|-------------| | usds_get_info | Get USDs overview including supply, APR, and last rebase time | | usds_get_balance | Get USDs balance and rebase state for any address | | usds_get_rebase_state | Check if an address receives yield rebases | | usds_get_mint_params | Get current mint fees and parameters | | usds_get_yield_info | Get current yield metrics, APR, and distribution | | usds_get_collateral_ratio | Get protocol collateralization ratio | | usds_estimate_mint | Simulate minting USDs with specific collateral |

Vault & Collateral (10 tools)

| Tool | Description | |------|-------------| | vault_get_status | Get Vault TVL, health status, utilization, and fees | | vault_get_collaterals | List all supported collaterals with current allocations | | vault_get_collateral_details | Get detailed info for specific collateral (USDC, USDT, DAI, FRAX) | | vault_get_strategies | List all active yield strategies and their performance | | vault_get_strategy_details | Get specific strategy allocation and APY | | vault_get_oracle_prices | Get all collateral oracle prices from Chainlink | | vault_get_peg_status | Check USDs peg health and deviation from $1 | | vault_simulate_mint | Simulate mint with fees and expected output | | vault_simulate_redeem | Simulate redemption with fees and slippage | | vault_get_allocation_targets | Get target vs actual collateral allocations |

SPA & Staking (8 tools)

| Tool | Description | |------|-------------| | spa_get_info | Get SPA token overview including supply and staking stats | | spa_get_balance | Get SPA, veSPA, and xSPA balances for address | | vespa_get_position | Get veSPA lock position details and voting power | | vespa_calculate_power | Calculate voting power for specific lock amount/duration | | vespa_get_stats | Get global veSPA statistics (total locked, holders) | | xspa_get_position | Get xSPA vesting position and pending redemptions | | xspa_calculate_redemption | Calculate SPA output for xSPA redemption | | buyback_get_stats | Get SPA buyback & burn statistics |

Demeter Farms (7 tools)

| Tool | Description | |------|-------------| | demeter_list_farms | List all active farms with APR, TVL, and filters | | demeter_get_farm_details | Get specific farm detailed info and mechanics | | demeter_get_user_position | Get user's positions across all Demeter farms | | demeter_calculate_rewards | Calculate pending rewards for user in farm | | demeter_estimate_apr | Estimate APR for specific deposit amount | | demeter_get_top_farms | Get highest APR farms with optional filters | | demeter_get_farm_types | Get supported farm types (UniV3, Camelot, Balancer) |

Dripper (5 tools)

| Tool | Description | |------|-------------| | dripper_get_status | Get Dripper operational status and health | | dripper_get_balance | Get pending yield balance waiting to be distributed | | dripper_get_config | Get drip period and distribution configuration | | dripper_estimate_next_rebase | Estimate next rebase time and expected amount | | dripper_calculate_earnings | Calculate projected earnings for USDs holdings |

Oracle (5 tools)

| Tool | Description | |------|-------------| | oracle_get_all_prices | Get all collateral prices from Chainlink oracles | | oracle_get_price | Get specific asset price with timestamp | | oracle_check_staleness | Check if oracle data is fresh (within heartbeat) | | oracle_check_deviation | Check price deviation from $1 peg | | oracle_get_sources | Get oracle source information and configuration |

Analytics (6 tools)

| Tool | Description | |------|-------------| | analytics_get_tvl | Get Total Value Locked breakdown by component | | analytics_get_revenue | Get protocol revenue metrics and trends | | analytics_get_apy_history | Get historical APY data (7d, 30d, 90d, 1y) | | analytics_get_user_stats | Get comprehensive user statistics | | analytics_compare_yields | Compare USDs yields with competitors (Aave, Compound) | | analytics_get_protocol_health | Get overall protocol health score and indicators |

Governance (5 tools)

| Tool | Description | |------|-------------| | governance_get_overview | Get governance overview and current state | | governance_get_proposals | List recent/active governance proposals | | governance_get_proposal_details | Get specific proposal details and voting status | | governance_get_voting_power | Get voting power for address (veSPA-based) | | governance_get_delegates | Get delegation information for address |

Yield Reserve (4 tools)

| Tool | Description | |------|-------------| | yield_reserve_get_status | Get yield reserve status and balance | | yield_reserve_get_balance | Get available yield for distribution | | yield_reserve_get_config | Get reserve configuration parameters | | yield_reserve_get_history | Get historical yield collection data |

📚 Available Resources

| Resource URI | Description | |--------------|-------------| | sperax://docs/overview | Complete protocol overview and architecture | | sperax://docs/usds | USDs stablecoin documentation and mechanics | | sperax://docs/staking | veSPA/xSPA staking guide with formulas | | sperax://docs/demeter | Demeter yield farming guide | | sperax://docs/vault | Vault and collateral management documentation | | sperax://docs/oracles | Oracle system documentation and addresses | | sperax://docs/governance | DAO governance guide and voting | | sperax://docs/security | Security audits and bug bounty program | | sperax://docs/formulas | Key protocol formulas and calculations | | sperax://docs/api | Complete API reference for all tools | | sperax://contracts/addresses | All deployed contract addresses on Arbitrum |

💡 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

| Prompt | Description | |--------|-------------| | what_is_usds | Learn about USDs auto-yield stablecoin | | how_to_mint | Step-by-step guide for minting USDs | | how_to_redeem | Guide for redeeming USDs to stablecoins | | my_usds_balance | Check USDs balance and yield info | | my_yield_earnings | Calculate potential yield earnings | | stake_spa | Guide for staking SPA to get veSPA | | my_staking_position | Check veSPA staking position | | best_yield_farms | Find the best Demeter yield farms | | my_farm_rewards | Check pending farm rewards | | protocol_health | Get overall protocol health report | | spa_tokenomics | Explain SPA token economics | | compare_yields | Compare USDs yield to other options | | rebase_calculator | Calculate potential rebase earnings | | vespa_calculator | Calculate veSPA voting power |

📖 How USDs Works

The Auto-Yield Mechanism

USDs is unique among stablecoins because it generates yield automatically:

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

Yield Distribution

| Recipient | Share | Purpose | |-----------|-------|---------| | USDs Holders | 70% | Distributed via auto-rebase | | SPA Buyback | 30% | Buy and burn SPA tokens |

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)

| Lock Duration | 1000 SPA → veSPA | |---------------|------------------| | 7 days | 19.2 veSPA | | 1 year | 1,000 veSPA | | 2 years | 2,000 veSPA | | 4 years | 4,000 veSPA |

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

xSPA Redemption

SPA_out = xSPA × (vestingDays + 150) / 330

| Vesting Period | SPA Received | |----------------|--------------| | 15 days (min) | 50% | | 30 days | 54.5% | | 90 days | 72.7% | | 180 days (max) | 100% |

USDs Rebase (Auto-Yield)

USDs uses a credit system for automatic yield distribution:

balance = credits / creditsPerToken

When yield is distributed:

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

No claiming required. Your wallet balance grows daily.

🔒 Security

| Feature | Description | |---------|-------------| | Read-Only | No transaction execution—server only reads blockchain state | | No Private Keys | Server never handles or stores private keys | | Rate Limited | Built-in RPC rate limiting prevents abuse | | Validated Inputs | All inputs validated with Zod schemas | | Audited Contracts | Sperax contracts audited by leading firms |

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

| Variable | Description | Default | |----------|-------------|---------| | ARBITRUM_RPC_URL | Arbitrum One RPC endpoint | https://arb1.arbitrum.io/rpc | | LOG_LEVEL | Logging level (debug, info, warn, error) | info | | PORT | HTTP server port (for HTTP mode) | 3000 |

🔗 Links

| Resource | Link | |----------|------| | 🌐 Website | sperax.io | | 📖 Documentation | docs.sperax.io | | 🚀 App | app.sperax.io | | 🐦 Twitter | @SperaxUSD | | 💬 Discord | discord.gg/sperax | | 📊 DeFiLlama | defillama.com/protocol/sperax | | 🔍 Arbiscan (USDs) | arbiscan.io/token/0xD74f...5748 | | 🗳️ Governance | snapshot.org/#/speraxdao.eth | | 🐙 GitHub | github.com/sperax |

📋 Contract Addresses (Arbitrum One)

Core Protocol

| Contract | Address | |----------|---------| | USDs Token | 0xD74f5255D557944cf7Dd0E45FF521520002D5748 | | SPA Token | 0x5575552988A3A80504bBaeB1311674fCFd40aD4B | | Vault | 0x6Bbc476Ee35CBA9e9c3A59fc5b10d7a0BC6f74Ca | | Collateral Manager | 0xdA6B48BA29fE5F0f32eB52FBA21D26DACA04E5e7 |

Staking

| Contract | Address | |----------|---------| | veSPA | 0x2e2071180682Ce6C247B1eF93d382D509F5F6A17 | | xSPA | 0x0966E72256d6055145902F72F9D3B6a194B9cCc3 |

Yield Distribution

| Contract | Address | |----------|---------| | SPA Buyback | 0xFbc0d3cA777722d234FE01dba94DeDeDb277AFe3 | | Yield Reserve | 0x0CB89A7A6a9E0d9E06EE0c52De040db0e2B079E6 | | Dripper | 0xEaA79893D17d4c1b3e76c684e7A89B3D46a6fb03 | | Rebase Manager | 0xC21b3b55Db3cb0B6CA6F96c18E9534c96E1d4cfc |

Oracles

| Contract | Address | |----------|---------| | Master Price Oracle | 0x14D99412dAB1878dC01Fe7a1664cdE85896e8E50 | | Chainlink Oracle | 0xB9e5A70e1B1F3C99Db6Ed28f67d8d7d1248F8b3B | | SPA Oracle | 0x5Fb534B4B07a0E417B449E264A8c7A6f9C5C2C69 | | USDs Oracle | 0x1C27c2a4aD63DE5F44f5a0e7a651e3FC7F3BBBe3 |

Demeter Protocol

| Contract | Address | |----------|---------| | Farm Registry | 0x45bC6B44107837E7aBB21E2CaCbe7612Fce222e0 | | Rewarder Factory | 0x926477bAF60C25857419CC9Bf52E914881E1bDD3 | | Farm Deployer | 0x0d9EFD8f11c0a09DB8C2CCBfF4cC6c26Ad98b956 |

Yield Strategies

| Contract | Address | |----------|---------| | Aave Strategy | 0x5E8422345238F34275888049021821E8E08CAa1f | | Compound Strategy | 0x8c9532a60E0E7C6BbD2B2c1303F63aCE1c3e9811 | | Stargate Strategy | 0x6cD7bEF920f4C05aF3386A2c0070e1e26CD85c85 | | Fluid Strategy | 0xE0f51Ec5f35B0D7Ce31b26b8C15b9B9f3fF1f5C5 |

Supported Collaterals

| Token | Address | Decimals | |-------|---------|----------| | USDC (Native) | 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 | 6 | | USDC.e (Bridged) | 0xFF970A61A04b1cA14834A43f5dE4533eBDDB5CC8 | 6 | | USDT | 0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9 | 6 | | DAI | 0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1 | 18 | | FRAX | 0x17FC002b466eEc40DaE837Fc4bE5c67993ddBd6F | 18 |

📊 Server Capabilities

| Capability | Count | Description | |------------|-------|-------------| | Tools | 57 | Comprehensive protocol interaction capabilities across 9 categories | | Resources | 11 | Complete documentation and contract references | | Prompts | 19 | Pre-built conversation starters for common tasks |

✨ Features

| Category | Description | |----------|-------------| | 🪙 USDs Stablecoin | Query balances, yields, rebase mechanics, mint/redeem simulations | | ⚡ Auto-Yield | ~5% APY distributed automatically via daily rebase | | 🗳️ veSPA Governance | Vote-escrowed staking with 7-day to 4-year locks | | 🌾 Demeter Farms | Discover and analyze yield farming opportunities | | 🏛️ Vault System | Collateral management and yield strategies | | 🔮 Oracle Integration | Chainlink price feeds and monitoring | | 📈 Yield Reserve | Protocol yield collection and distribution |

🤝 Contributing

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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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}

Sperax Ecosystem Crypto & DeFI MCP Server

🔧 Development

Prerequisites

Setup

Running

Testing

Linting & Type Checking

🤝 Quick Start

Claude Desktop

Cursor / VS Code

With Custom RPC Endpoint

HTTP Server Mode

🛠️ 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

Find Best Farms

Calculate veSPA Power

Protocol Health Check

Portfolio Analysis

💬 Example Prompts

📖 How USDs Works

The Auto-Yield Mechanism

Yield Distribution

Why It's Special

🏗️ Protocol Architecture

📐 Key Protocol Formulas

veSPA Voting Power

xSPA Redemption

USDs Rebase (Auto-Yield)

No claiming required. Your wallet balance grows daily.

🔒 Security

Security Considerations

⚙️ Environment Variables

🔗 Links

📋 Contract Addresses (Arbitrum One)

Core Protocol

Staking

Yield Distribution

Oracles

Demeter Protocol

Yield Strategies

Supported Collaterals

📊 Server Capabilities

| Capability | Count | Description | |------------|-------|-------------| | Tools | 57 | Comprehensive protocol interaction capabilities across 9 categories | | Resources | 11 | Complete documentation and contract references | | Prompts | 19 | Pre-built conversation starters for common tasks |

✨ Features

🤝 Contributing

📄 License

Install Package (if required)

Cursor configuration (mcp.json)