svm402-mcp

An MCP (Model Context Protocol) server that provides AI agents with Solana token analysis from svm402.com via x402 USDC payments.

What It Does

Agents call simple named tools — the MCP server handles the x402 payment flow automatically:

Agent calls: analyze_token("DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263")
  → MCP server pays $0.05 USDC to svm402.com via x402
  → Returns: price, safety, holders, risk score, metadata

The agent never sees wallets, private keys, or x402 protocol details. Just call a tool, get data.

Disclaimer

This software is experimental and provided "as is", without warranty of any kind. Use at your own risk.

This software initiates real cryptocurrency transactions that are irreversible. Test on devnet before using on mainnet.

Tools

Tool	Cost	Description
analyze_token	$0.05 USDC	Full analysis: price, liquidity, safety, holders, metadata
check_safety	$0.02 USDC	Safety/honeypot risk check with deterministic 0-10 score
get_price	$0.01 USDC	Price, liquidity, market cap, 24h volume, multi-timeframe changes

Each tool handles the x402 payment automatically — the agent just provides a Solana token address.

Quick Start

1. Install

git clone https://github.com/dchu3/svm402-mcp.git
cd svm402-mcp
npm install
npm run build

2. Configure

Copy .env.example and set your Solana private key:

cp .env.example .env
# Edit .env with your private key

Variable	Required	Default	Description
SOLANA_PRIVATE_KEY	✅	—	Base58-encoded Solana private key
SOLANA_NETWORK	❌	mainnet	mainnet or devnet
SOLANA_RPC_URL	❌	api.mainnet-beta.solana.com	Custom RPC (use Helius for cloud servers)
SVM402_BASE_URL	❌	https://svm402.com	svm402 service URL
MAX_PAYMENT_PER_CALL	❌	0.05	Max USDC per payment
MAX_DAILY_SPEND	❌	10.00	Max daily USDC spend
PAYMENT_LOG_PATH	❌	./svm402-payments.jsonl	Payment audit log

3. Connect to Your Agent

Hermes Agent

The hermes mcp add command has issues with --env flags. Use hermes config set instead:

# 1. Add the MCP server
hermes config set mcp_servers.svm402.command "node"
hermes config set mcp_servers.svm402.args '["/path/to/svm402-mcp/dist/index.js"]'
hermes config set mcp_servers.svm402.enabled true

# 2. Set environment variables (as a YAML dict, not string)
python3 -c "
import yaml
with open('$HOME/.hermes/config.yaml') as f:
    config = yaml.safe_load(f)
config['mcp_servers']['svm402']['env'] = {
    'SOLANA_PRIVATE_KEY': 'your-base58-key',
    'SOLANA_NETWORK': 'mainnet',
    'SOLANA_RPC_URL': 'https://api.mainnet-beta.solana.com',
}
with open('$HOME/.hermes/config.yaml', 'w') as f:
    yaml.dump(config, f, default_flow_style=False, allow_unicode=True)
print('Config saved')
"

# 3. Restart Hermes gateway
hermes gateway restart

# 4. Test connection
hermes mcp test svm402

Note: If the connection test times out, increase the connect timeout:

hermes config set mcp_servers.svm402.connect_timeout 30
hermes config set mcp_servers.svm402.timeout 60
hermes gateway restart

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "svm402": {
      "command": "node",
      "args": ["/path/to/svm402-mcp/dist/index.js"],
      "env": {
        "SOLANA_PRIVATE_KEY": "your-base58-key",
        "SOLANA_NETWORK": "mainnet",
        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com"
        # For cloud servers (GCE, AWS), use Helius instead:
        # "SOLANA_RPC_URL": "https://mainnet.helius-rpc.com/?api-key=your-key"
      }
    }
  }
}

Cursor / Windsurf / Other MCP Clients

Use the same JSON config as Claude Desktop, adapted for your client.

Usage Examples

Analyze a token ($0.05)

analyze_token({ address: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" })

Returns: token metadata, price, market cap, safety risk score (0-10), top holders with LP detection, buy/sell tax, liquidity lock status, and degraded flag for partial data.

Check safety ($0.02)

check_safety({ address: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" })

Returns: risk score, honeypot check, mint/freeze authority status, liquidity lock, buy/sell tax, holder concentration.

Get price ($0.01)

get_price({ address: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" })

Returns: price, market cap, FDV, liquidity, 24h volume, multi-timeframe price changes (1h/6h/24h), organic score, holder count.

Safety Features

• Spending limits — MAX_PAYMENT_PER_CALL and MAX_DAILY_SPEND prevent runaway costs
• Payment logging — every payment logged to JSONL audit trail
• Structured errors — clear error codes for rate limits, insufficient balance, failed payments
• Degraded flag — svm402.com returns degraded: true when data is partial

How It Works

Agent → MCP tool: analyze_token(address)
     → MCP server: HTTP request to svm402.com/analyze
     → svm402.com: returns 402 (payment required)
     → MCP server: signs USDC payment on Solana
     → MCP server: retries with payment proof
     → svm402.com: verifies via CDP facilitator, returns data
     → MCP server: returns data to agent

The agent never touches a wallet or payment. Just data in, data out.

Data Sources

svm402.com uses:

• Jupiter v3/v2 API — price, market cap, liquidity, 24h stats, organic score, audit data
• Helius RPC — mint/freeze authority, holders, honeypot checks, liquidity lock detection
• Pump.fun bonding curve — price fallback for brand new tokens not yet on Jupiter

Development

npm install
npm run build
npm start

Tech Stack

• MCP SDK
• @x402/fetch — x402 payment handling
• @x402/svm — Solana x402 scheme
• @solana/web3.js — Solana SDK

License

MIT — see LICENSE

Links

• svm402.com — Live service
• x402 Protocol — Payment standard
• MCP Protocol — Agent tool protocol
• solana-x402-mcp — Generic x402 payment MCP