soliris-mcp

Eyes, hands, and wallet for AI agents on Solana.

23 tools. Explain any Solana transaction in plain English. Score wallet risk. Decode any account. Execute Jupiter swaps with MEV protection. Pay autonomously with x402 USDC micropayments.

Built for the Solana x402 Hackathon — Best MCP Server track.

Quick Start

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "soliris": {
      "command": "npx",
      "args": ["-y", "soliris-mcp"],
      "env": {
        "RPC_URL": "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY",
        "SOLANA_PRIVATE_KEY": "your_base58_private_key",
        "SOLANA_NETWORK": "mainnet-beta",
        "PLATFORM_FEE_BPS": "20",
        "PLATFORM_FEE_ACCOUNT": "your_fee_ata",
        "SOLIRIS_API_URL": "https://soliris.replit.app"
      }
    }
  }
}

Read-only tools (eyes) work without SOLANA_PRIVATE_KEY. Write operations and x402 payments require a funded wallet.

Pricing

| Tier | Cost | Tools | |---|---|---| | Free | $0/call | All 12 eyes (read) tools — including tx parsing, wallet risk, account decoding | | Execute | $0.001 USDC/swap + 0.2% output | All 7 hands tools — x402 autonomous payment | | Custom | Set your own price | Register your own x402 endpoint (coming v0.4) |

Agents pay autonomously via x402. No human approval. Dual on-chain revenue per swap: execution fee + platform fee.

Tools — 23 total

Eyes (12) — Read Solana, no wallet needed

| Tool | What it does | |---|---| | soliris_explain_transaction | Decode any tx signature(s) into plain English — type, token flows, programs, risk flags | | soliris_wallet_activity | Full activity breakdown for any wallet — action types, protocols, volume, fees | | soliris_wallet_risk | Risk score (low/medium/high) with specific flags — bot detection, wash trading, new wallet signals | | soliris_decode_account | Identify any address — wallet, token account, PDA, stake account, program | | soliris_get_balance | SOL balance for any address | | soliris_get_account_info | Full on-chain account data | | soliris_get_token_balances | All SPL token holdings | | soliris_get_transaction_history | Recent txs, up to 100 | | soliris_get_network_stats | Live TPS, slot, block time | | soliris_get_token_price | USD price via Jupiter price API | | soliris_resolve_domain | .sol domain → wallet address | | soliris_get_slot | Current confirmed slot |

Hands (7) — Write on-chain, requires SOLANA_PRIVATE_KEY

| Tool | What it does | |---|---| | soliris_get_wallet_address | Derives pubkey from configured key | | soliris_transfer_sol | SOL transfer with balance check | | soliris_transfer_token | SPL token transfer, auto-creates destination ATA | | soliris_request_airdrop | Devnet/testnet faucet (mainnet blocked) | | soliris_jupiter_quote | Swap quote + MEV risk score + sandwich probability | | soliris_jupiter_swap | Simulate → guard → x402 authorize → execute | | soliris_session_pnl | Session-level swap history and P&L summary |

Wallet (4) — x402 autonomous payments

| Tool | What it does | |---|---| | soliris_x402_fetch | HTTP request with auto USDC micropayment on 402 | | soliris_payment_history | All payments made this session | | soliris_payment_summary | Total USDC spent, success rate | | soliris_check_usdc_balance | Agent wallet USDC balance |

x402 — The Key Differentiator

Soliris is both an x402 client (pays other endpoints) and an x402 server (gates its own execution):

Agent-as-client: soliris_x402_fetch

When an AI agent calls a 402-protected endpoint:

1. Initial request → server returns HTTP 402 with USDC payment requirements
2. Agent signs and submits a real Solana USDC transfer on-chain
3. Agent retries with X-PAYMENT proof header
4. Server verifies → returns premium data

Agent-as-payer: soliris_jupiter_swap (x402 gated)

Before executing any swap, the tool autonomously:

1. Calls the Soliris execution authorization endpoint
2. Receives HTTP 402 requiring $0.001 USDC
3. Pays from agent wallet on-chain
4. Receives authorization token
5. Executes the swap

This creates dual revenue per swap:

• $0.001 USDC execution authorization fee
• 0.2% of output platform fee via Jupiter routing

No human in the loop. No API keys to manage. Fully autonomous.

Live endpoints (Soliris API server):

• GET /api/premium/analytics/:address — Enhanced wallet analytics ($0.001 USDC)
• GET /api/premium/swap-risk/:inputMint/:outputMint — MEV exposure analysis ($0.001 USDC)
• GET /api/execute/swap-authorize — Swap execution authorization ($0.001 USDC)

MEV & Sandwich Risk

soliris_jupiter_quote now returns a risk object with every quote:

{
  "risk": {
    "mevRisk": "low",
    "sandwichProbability": "< 10%",
    "jitoRecommended": false,
    "recommendation": "Trade is small enough that MEV exposure is minimal."
  }
}

Risk is assessed from price impact, trade size, and route fragmentation. Jito bundle usage is recommended when mevRisk: "high".

Session P&L

soliris_session_pnl tracks all swaps executed in the current session:

{
  "swapCount": 3,
  "swaps": [
    { "inputToken": "SOL", "outputToken": "USDC", "inputAmount": 0.1, "outputAmount": 14.82, "executionFeeUSDC": 0.001, "signature": "...", "timestamp": "..." }
  ],
  "sessionMetrics": {
    "totalExecutionFeesUSDC": 0.003
  }
}

Jupiter Swaps — Platform Fee

Set PLATFORM_FEE_BPS (e.g. 20 = 0.2%) and PLATFORM_FEE_ACCOUNT (your ATA for the output mint) to collect a cut on every swap. Jupiter routes the fee on-chain — no custom logic, fully transparent.

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | RPC_URL | Recommended | Public mainnet | Solana RPC endpoint (Helius recommended) | | SOLANA_PRIVATE_KEY | For write ops | — | Base58 encoded keypair | | SOLANA_NETWORK | No | mainnet-beta | mainnet-beta | devnet | testnet | | MAX_PAYMENT_USDC | No | 1.0 | Cap per x402 auto-payment | | PLATFORM_FEE_BPS | No | 0 | Basis points collected on Jupiter swaps | | PLATFORM_FEE_ACCOUNT | No | — | SPL ATA to receive platform fees | | SOLIRIS_API_URL | No | — | Enables x402 swap execution gating | | DISABLE_EXECUTION_GATING | No | false | Set true to skip swap authorization fee |

Safety

• Jupiter swaps: simulation runs before every execution. Hard abort on simulation failure. 5% price impact guard blocks trades.
• x402 payments: max payment cap enforced before any USDC transfer is signed.
• SOL transfers: balance check before sending.
• SPL transfers: auto-creates destination ATA, uses getOrCreate pattern.
• Airdrops: mainnet blocked at the handler level.

License

MIT