# svm402-mcp

**The honest Solana token analysis MCP for AI agents.**

On-chain data that's more accurate and transparent than any screener app — with wash trading detection that no screener shows you. Pay per call in USDC on Solana. No API keys, no signup, no subscriptions.

## Why svm402?

**Screeners show you volume. svm402 tells you if it's real.**

Most "trending" tokens on screener apps are boosted by bot farms — hundreds of wallets wash trading to inflate volume and attract retail buyers. Screeners won't show you this because their business model profits from boosted tokens.

svm402 pulls **live on-chain data** from Helius RPC and Jupiter v2, then tells you:
- What percentage of volume is **organic** vs bot-driven
- How many trades per trader per day (80+ = bots, 2-5 = humans)
- How many buyers are **organic** vs bot wallets
- Whether mint/freeze authority is revoked
- Whether liquidity is locked
- Real pool vault balances (not cached estimates)
- Full data source transparency with timestamps

**Agents using svm402 avoid bot-farmed tokens. Agents using only screeners get rekt.**

## Tools

| Tool | Cost | What it does |
|------|------|-------------|
| `analyze_token` | $0.05 USDC | Full analysis: price, liquidity, safety, holders, wash trading detection, data sources |
| `wallet_analyze` | $0.02 USDC | Analyze a Solana wallet's holdings — total value, SOL balance, top 20 token holdings, risk summary |
| `discover_tokens` | $0.02 USDC | Find organic Solana tokens — filtered to exclude wash trading |
| `check_wash_trading` | $0.02 USDC | Wash trading detection — bot volume manipulation indicators |
| `check_safety` | $0.02 USDC | Honeypot/safety risk check with deterministic 0-10 score |
| `get_price` | $0.01 USDC | Price, liquidity, market cap, 24h volume, multi-timeframe changes |

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

## The Edge

### Wash Trading Detection (unique to svm402)

```
Agent: analyze_token("8Byg9wi43TNzgJpYta6UXxPz3LPe8v6ZwvmWWoWQpump")

Result:
  wash_trading:
    suspected: true
    trades_per_trader: 80.5      ← bots make 80+ trades/day, humans make 2-5
    organic_volume_pct: 3.2%    ← 96.8% of volume is bot cycling
    organic_buyer_pct: 6.2%     ← only 6% of "traders" are real buyers
    note: "Wash trading suspected: bots may be inflating volume to attract retail"
```

Any screener shows this token as "high volume, trending." svm402 tells you 97% of that volume is fake.

### Organic Token Discovery (unique to svm402)

```
Agent: discover_tokens()

Result: 6 organic tokens, each with:
  - Organic score (0-100)
  - Organic volume percentage
  - Mint/freeze authority status
  - Top holders percentage
  - Wash trading flag
  - Full token address for analysis
```

No screener offers this. Screeners sort by total volume (manipulatable). svm402 sorts by organic activity (not manipulatable).

### Real On-Chain Liquidity (more accurate than any screener)

svm402 reads actual pool vault balances from Helius RPC at request time — not cached/indexed data with delays. Every response shows `liquidity_source: pool-vaults` so agents know it's real on-chain data.

### Data Source Transparency

Every response includes `data_sources` showing exactly which APIs were called and when:
```json
{
  "data_sources": {
    "jupiter_v3_price": "2026-08-05T12:30:00Z",
    "jupiter_v2_token_info": "2026-08-05T12:30:00Z",
    "helius_rpc": "2026-08-05T12:30:00Z",
    "pool_vaults": "2026-08-05T12:30:00Z"
  },
  "fetched_at": "2026-08-05T12:30:26Z"
}
```

No screener provides this level of transparency. Agents can audit every data point.

## Quick Start

### 1. Install

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

```bash
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

```bash
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

# Set environment variables
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')
"

hermes gateway restart
hermes mcp test svm402
```

#### Claude Desktop

Add to `claude_desktop_config.json`:

```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"
      }
    }
  }
}
```

#### Cursor / Windsurf / Other MCP Clients

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

## Usage Examples

### Discover organic tokens ($0.02)

```
discover_tokens()
```

Returns tokens ranked by genuine organic activity — filtered to exclude wash trading. Each token includes mint/freeze authority status, organic score, and wash trading flag.

### Analyze a token ($0.05)

```
analyze_token({ address: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7Ya1pPB263" })
```

Returns: token metadata, price, market cap, real pool vault liquidity, safety risk score (0-10), top holders with LP detection, buy/sell tax, liquidity lock status, wash trading analysis, data source lineage, and timestamp.

### Check safety ($0.02)

```
check_safety({ address: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7Ya1pPB263" })
```

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

### Check wash trading ($0.02)

```
check_wash_trading({ address: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" })
```

Returns: detected flag, confidence level (high/medium/low), individual indicators with thresholds, raw metrics (trades per trader, organic volume %, organic buyer %, vol/liq ratio).

### Get price ($0.01)

```
get_price({ address: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" })
```

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

### Analyze a wallet ($0.02)

```
wallet_analyze({ address: "37fMqbe7vNoDuE15B1qas8TZyhqvYwgLVSViRa4DEmwa" })
```

Returns: total portfolio value, SOL balance + value, top 20 token holdings with prices and risk scores, portfolio risk summary (high-risk %, verified %, illiquid %), top 3 holding mints.

## The Pipeline

```
discover_tokens()  → find organic tokens (excludes wash trading)
       ↓
analyze_token()    → deep-dive: safety, holders, wash trading, real liquidity
       ↓
check_safety()     → quick honeypot/risk check before trading
       ↓
check_wash_trading() → detect bot volume manipulation
       ↓
get_price()        → current price for order sizing
       ↓
wallet_analyze()   → check portfolio holdings and risk after trading
```

## 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 (honest about gaps)

## Data Sources

svm402.com uses only Jupiter and Helius — no third-party data providers:

- **Jupiter v3/v2 API** — price, market cap, liquidity, 24h stats, organic score, audit data (mint/freeze authority)
- **Helius RPC** — real pool vault balances, holders, honeypot checks, liquidity lock detection, LP holder identification
- **Pump.fun bonding curve** — price fallback for brand new tokens not yet on Jupiter

No screeners. No aggregators. No third-party data providers. Just raw on-chain data.

## 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 on-chain, returns data
     → MCP server: returns data to agent
```

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

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

## Tech Stack

- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [@x402/fetch](https://www.npmjs.com/package/@x402/fetch) — x402 payment handling
- [@x402/svm](https://www.npmjs.com/package/@x402/svm) — Solana x402 scheme
- [@solana/web3.js](https://github.com/solana-labs/solana-web3.js) — Solana SDK

## License

MIT — see [LICENSE](LICENSE)

## Links

- [svm402.com](https://svm402.com) — Live service
- [x402 Protocol](https://x402.org) — Payment standard
- [MCP Protocol](https://modelcontextprotocol.io) — Agent tool protocol
- [solana-x402-mcp](https://github.com/dchu3/solana-x402-mcp) — Generic x402 payment MCP