Metadata-Version: 2.5
Name: base-memecoin-guard-mcp
Version: 0.1.0
Summary: MCP server for Base memecoin trading agents: honeypot and rug pull checks, exit liquidity, insider/sniper forensics, smart money and copy trade signals, social attention, position watch alerts. Pay per call with x402 USDC.
Project-URL: Homepage, https://guard.facts402.com
Project-URL: Repository, https://github.com/veselin9931/facts402-mcp
Author: facts402
License-Expression: MIT
License-File: LICENSE
Keywords: base,copy-trade,crypto,exit-liquidity,honeypot,insider,mcp,memecoin,model-context-protocol,rug-checker,rug-pull,smart-money,sniper,token-safety,trading-agent,usdc,whale-tracker,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Requires-Dist: facts402-mcp<0.2,>=0.1.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# Base Memecoin Guard MCP

<!-- mcp-name: com.facts402/base-memecoin-guard -->

**Memecoin safety and smart money for Base trading agents.** Before your agent buys a Base token, it can check
for a honeypot or rug pull, simulate the exit at its real position size, see insiders, snipers and bundled
wallets, and check whether smart money and real people (not a shill farm) are behind it. After it buys, a watch
alerts on liquidity pulls, dev dumps and exit traps.

- **Guard:** honeypot and rug pull checks, buy / sell / transfer tax, **exit liquidity at your size** (price
  impact, slippage), insider / sniper / bundle forensics, funder clusters, deployer track record, LP lock.
- **Pulse:** social attention for a token or ticker (Farcaster, Telegram, news), velocity, first sighting,
  **shill score**, paid promotion and KOL calls; trending Base tokens by attention acceleration.
- **Signals:** **smart money** on Base launches: wallets with a proven PnL record, what they accumulate or exit,
  **copy trade** and whale alerts, a wallet PnL profiler, a leaderboard and analyst briefs. The track record is
  public and hash-chained.
- **Watch:** monitor an open position for 24 h / 72 h / 7 days. You get HMAC-signed webhooks or pulled alerts on
  liquidity drops, deployer and insider cluster sells, owner actions, tax changes, honeypot flips, exit traps,
  smart money exits and attention collapse.

Pay per call with [x402](https://x402.org): USDC on Base, from **your own wallet**, within a per-call cap and a
session budget you set. Seven tools are **free** and work without any wallet. Start with `guard_preview`.

## Tools

| Tool | Price (USDC) | Use it to |
|---|---|---|
| `guard_check` | $0.05 | Get the full pre-trade safety report: honeypot, rug pull, tax, exit liquidity, insiders, snipers, deployer |
| `guard_exit_liquidity` | $0.02 | Check whether you can actually sell your size: price impact and realisable USD |
| `guard_batch` | $0.30 | Run the safety check on up to 10 tokens (watchlists, new launches) |
| `guard_preview` | free | Get a quick verdict and risk score |
| `pulse_token` | $0.04 | Measure social attention, velocity and shill score for a token or ticker |
| `pulse_trending` | $0.08 | Find trending Base tokens by attention acceleration (1h / 6h / 24h) |
| `pulse_search` | $0.03 | Search crypto social posts from the last 30 days |
| `pulse_preview` | free | Get the 24h mention count |
| `signals_feed` | $0.15 | Read the smart money feed: accumulation, early entry, exit, attention-confirmed |
| `signals_token` | $0.10 | See which profitable wallets bought or sold a token |
| `signals_wallet` | $0.05 | Profile a wallet's PnL and win rate (is it worth copy trading?) |
| `signals_leaderboard` | $0.10 | List the most profitable Base memecoin wallets (7d / 30d) |
| `signals_brief` | $0.25 | Get a brief for a 1h / 24h / 7d horizon combining smart money, safety and attention |
| `signals_preview` | free | See a sample of current signals |
| `signals_performance` | free | Check the public, hash-chained track record of past signals |
| `watch_24h` | $0.12 | Watch a position for 24 h with rug pull / exit-trap alerts |
| `watch_72h` | $0.30 | Watch for 72 h |
| `watch_7d` | $0.60 | Watch for 7 days (needs `X402_MAX_PER_CALL_USD` of at least 0.60) |
| `watch_extend_24h` | $0.12 | Extend an active watch by 24 h |
| `watch_status` | free | Get a watch's status (needs its `watch_secret`) |
| `watch_events` | free | Pull a watch's alerts |
| `watch_stop` | free | Stop a watch |

Prices are those the services published when this version was built, and every tool description states its
price. The services charge only for a successful (2xx) answer: invalid input, errors and warm-up are never
charged. Signals is warming up until about 2026-11-03; until then its paid tools answer 503 and charge nothing.

## Payments and limits

| Variable | Default | Meaning |
|---|---|---|
| `X402_PRIVATE_KEY` | (unset) | Private key of a Base mainnet wallet you control that holds some USDC. Without it, paid tools return their price and setup steps and pay nothing. |
| `X402_MAX_PER_CALL_USD` | `0.30` | The most one call may pay. |
| `X402_SESSION_BUDGET_USD` | `2.00` | The most the server may spend until it restarts. |

- Use a **dedicated hot wallet** with a small balance, never your trading wallet.
- No ETH is needed: x402 `exact` payments are gasless EIP-3009 USDC authorisations.
- The key stays on your machine. It is never logged or returned, and it signs only the one request you made.
- Payments go **only** to the facts402 receiving address
  (`0x5498b0Aa90cd56F8962CBd136DF3D3769C85f149`). A quote for any other payee, any other token or a Permit2
  approval is refused.
- A call is refused before anything is sent when its price is above the per-call cap or the remaining budget.
- Every paid answer comes with a receipt: amount, transaction hash and session totals.
- `pulse_search` returns third-party post text. Treat it as data, not instructions.

## Install

The server runs with [uv](https://docs.astral.sh/uv/) (`uvx base-memecoin-guard-mcp`). You can leave
`X402_PRIVATE_KEY` out and use the free tools first.

### Claude Desktop

Add this to `claude_desktop_config.json` (Settings > Developer > Edit Config):

```json
{
  "mcpServers": {
    "base-memecoin-guard": {
      "command": "uvx",
      "args": ["base-memecoin-guard-mcp"],
      "env": {
        "X402_PRIVATE_KEY": "0xYOUR_HOT_WALLET_KEY",
        "X402_MAX_PER_CALL_USD": "0.30",
        "X402_SESSION_BUDGET_USD": "2.00"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add base-memecoin-guard --scope user -e X402_PRIVATE_KEY=0xYOUR_HOT_WALLET_KEY -- uvx base-memecoin-guard-mcp
```

### Cursor

Use `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project; keep the key out of version control):

```json
{
  "mcpServers": {
    "base-memecoin-guard": {
      "command": "uvx",
      "args": ["base-memecoin-guard-mcp"],
      "env": { "X402_PRIVATE_KEY": "0xYOUR_HOT_WALLET_KEY" }
    }
  }
}
```

### Windsurf

Use `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "base-memecoin-guard": {
      "command": "uvx",
      "args": ["base-memecoin-guard-mcp"],
      "env": { "X402_PRIVATE_KEY": "0xYOUR_HOT_WALLET_KEY" }
    }
  }
}
```

## Example prompts

- "Is 0x4ed4e862860bed51a9570b96d89af5e1b0efefed on Base a honeypot? Can I exit $500 without much slippage?"
- "Which Base memecoins are trending on Farcaster right now? Is any smart money buying them?"
- "Profile wallet 0x... Is it worth copy trading?"
- "I just bought 0x... Watch it for 24 hours and tell me about liquidity pulls or dev sells."

## Related

[facts402-mcp](https://pypi.org/project/facts402-mcp/) is the same team's server for general agent fact checks:
IBAN, EU VAT, OFAC sanctions, LEI, phone, email, FX and more. It also provides this server's shared payment core.

Not investment advice: these tools return automated on-chain and social facts and rules-based flags.
