soliris-mcp

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

46 tools. Rug-pull & scam detection with bundle analysis. Birdeye Data integration — trending tokens, new-listing radar, token overview, security check. Arc divergence signals via x402 autopayment. Explain any transaction in plain English. Score wallet P&L. Execute Jupiter swaps with MEV protection. Autonomous copy-trading agent loop.

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 — 46 total

Eyes (18) — Read Solana, no wallet needed

| Tool | What it does | |---|---| | soliris_holder_distribution | Premium ($0.02 USDC, x402-paid) — Full SPL token holder distribution: top holders with balance & supply %, top10/top50 concentration, and an insider-cluster heuristic (top-50 holders funded from the same wallet within a 5-min window, surfacing clusters >5% of supply). | | soliris_sentinel_scan | Rug-pull & scam detection — 9+ on-chain signals: bundle/coordinated launch detection, holder concentration, dev farming, Rugcheck score, mint authority. Returns 0–100 risk score + SAFE/WARNING/DANGER verdict. Free. | | 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_token_scan | Real-time DexScreener intelligence — price, liquidity, buy/sell ratio, momentum signals | | soliris_wallet_pnl | Score any wallet's real P&L — win rate, avg return, best/worst trades, composite score | | 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 | | soliris_birdeye_trending | Birdeye Data — trending Solana tokens ranked by composite score (volume + price action). Returns symbol, mc, fdv, vol24h, 24h change. Free, ~30s cache. | | soliris_birdeye_new_listings | Birdeye Data — fresh token listings across Raydium / Meteora / Orca / Pump. Catches new pools the moment liquidity is added. Free, ~30s cache. | | soliris_birdeye_token_overview | Birdeye Data — full snapshot for any mint: price, mc, fdv, liquidity, holders, market count, 24h volume + buy/sell breakdown, unique-wallet trend. Free, ~30s cache. | | soliris_birdeye_token_security | Birdeye Data — mint/freeze authority status, top-10 holder concentration, transfer-fee, mutable-metadata flags. Returns safe / warning / danger verdict. Premium-tier endpoint; free-tier keys get a graceful fallback pointing to soliris_sentinel_scan. |

Hands (8) — 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_jito_bundle_submit | MEV-protected bundle submit — 1–5 base64 signed txs to Jito Block Engine. Auto-appends signed tip to rotating Jito tip account. Pre-flight simulation + anti-exfiltration cap (1 SOL + tip). x402-gated at $0.02 USDC. Region selectable: mainnet | amsterdam | frankfurt | ny | tokyo. Returns bundleId + Jito explorer URL. | | 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)
• GET /api/arc/signal/latest — Arc divergence signals (pay-per-call via x402, use soliris_arc_signal)
• POST /api/sentinel/demo/check — Rug-pull scan via Sentinel (free, use soliris_sentinel_scan)

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".

Jito Bundles — soliris_jito_bundle_submit

Submit MEV-protected bundles atomically through the Jito Block Engine. Useful for sandwich-resistant swaps, arbitrage legs, and any tx sequence that must execute together or not at all.

Pricing: $0.02 USDC per call (x402-gated against SOLIRIS_API_URL/api/execute/jito-authorize). If SOLIRIS_API_URL is unset or DISABLE_EXECUTION_GATING=true, the call proceeds free.

Inputs:

• transactions: string[] — 1–5 base64-encoded SIGNED Solana transactions (Legacy or VersionedTransaction).
• tipLamports?: number — Default 100000 (0.0001 SOL). When > 0, a tip transfer tx is appended and signed by the agent wallet.
• region?: "mainnet" | "amsterdam" | "frankfurt" | "ny" | "tokyo" — Default mainnet.
• skipSimulation?: boolean — Skip per-tx simulateTransaction pre-flight (default false).

Tip mechanics: tip transfers are sent to one of the 8 published Jito tip accounts, randomly rotated per call to avoid hot-spotting. The tip tx is built fresh with the latest blockhash and signed by SOLANA_PRIVATE_KEY. If you supply a 5-tx bundle, set tipLamports=0 (Jito caps bundles at 5 txs total) or include your own tip in one of the supplied txs.

Safety:

• Pre-flight simulates each tx; bundle is dropped on first err.
• Anti-exfiltration cap: any supplied tx that would SystemProgram.transfer more than 1 SOL + tipLamports from the agent wallet is rejected.
• Returns { status, bundleId, sentTo, simulated, region, tip, bundleSize, explorerUrl } on success.

Example output:

{
  "status": "submitted",
  "bundleId": "abc123…",
  "sentTo": "https://mainnet.block-engine.jito.wtf/api/v1/bundles",
  "region": "mainnet",
  "tip": { "lamports": 100000, "account": "96gYZGLnJYVF…", "appended": true },
  "bundleSize": 2,
  "explorerUrl": "https://explorer.jito.wtf/bundle/abc123…",
  "executionFeeUSDC": 0.02
}

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