Sperax Crypto Mcp

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/sperax/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:

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

| 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:

balan

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Sperax](https://github.com/Sperax)
- **Source:** [Sperax/sperax-crypto-mcp](https://github.com/Sperax/sperax-crypto-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.