Metadata-Version: 2.4
Name: ryocryptoguard
Version: 0.2.3
Summary: AI agent safety layer for crypto transactions - blocks honeypots, blacklists, and rug pulls before they happen
Author: yabig
Project-URL: Homepage, https://pypi.org/project/ryocryptoguard/
Keywords: crypto,security,honeypot,blacklist,rug-pull,smart-contract,defi,web3,claude-code,ai-agent,mcp,hook,safety,market-research,ryo
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: ryo
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: responses>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"

<p align="center">
  <img src="assets/banner1.jpg" alt="RyoCryptoGuard" width="100%"/>
</p>

<p align="center">
  <a href="https://pypi.org/project/ryocryptoguard/"><img src="https://img.shields.io/pypi/v/ryocryptoguard?color=6366f1&style=flat-square" alt="PyPI"/></a>
  <a href="https://pypi.org/project/ryocryptoguard/"><img src="https://img.shields.io/pypi/pyversions/ryocryptoguard?color=6366f1&style=flat-square" alt="Python"/></a>
  <a href="https://ryocryptoguard.vercel.app"><img src="https://img.shields.io/badge/docs-ryocryptoguard.vercel.app-6366f1?style=flat-square" alt="Docs"/></a>
</p>

# RyoCryptoGuard

**The complete pre-trade safety layer for AI agents — contract security + live market context.**

> Website: **[ryocryptoguard.vercel.app](https://ryocryptoguard.vercel.app)**

RyoCryptoGuard is a pre-transaction hook for AI coding agents (Claude Code, Codex, Cursor, etc.) that automatically analyzes smart contracts **and** live market conditions before any crypto transaction is executed. It detects honeypots, blacklist functions, rug pulls, and scam tokens by cross-referencing multiple independent security oracles — and enriches every analysis with real-time technical data from the RYO market research API.

---

## The Problem

AI agents executing crypto transactions have no built-in safety layer to detect:

- **Honeypot tokens** — You can buy but never sell
- **Blacklist contracts** — The owner can freeze your funds after you buy
- **Rug pulls** — Liquidity can be removed instantly
- **Tax manipulation** — Fees can be changed to 100% after purchase
- **Airdrop scams** — Malicious tokens sent to bait interaction
- **Overbought entries** — Buying into a technically exhausted rally (RSI ≥ 80)

**RyoCryptoGuard stops these before a single wei leaves your wallet.**

---

## How It Works

```
You/AI Agent: "swap 1 ETH for TOKEN_X on Uniswap"
                    |
            [CryptoGuard Hook]
                    |
        +-----------+-----------+-----------+
        |           |           |           |
    GoPlus API   Bytecode    Reputation   RYO Market
    Security     Scanner     Aggregator   Research
        |           |           |           |
        |     +-----------+    |        Price, RSI,
        |     | honeypot.is|   |        ATR, Verdict
        |     | TokenSniffer|  |
        |     | De.Fi       |  |
        |     | QuickIntel  |  |
        |     +-----------+    |
        +-----------+-----------+-----------+
                    |
            Risk Score: 0-100 + Market Context
                    |
          SAFE -> Allow  |  HIGH -> BLOCK
```

### Data Sources

| Source | What it checks |
|--------|----------------|
| **GoPlus Security** | Honeypot, blacklist, tax, ownership, holders, liquidity |
| **Honeypot.is** | Buy/sell simulation on forked chain state |
| **TokenSniffer** | Automated audit score, similar known scams |
| **De.Fi Scanner** | DeFi protocol security issues |
| **QuickIntel** | Multi-chain token intelligence |
| **Bytecode Scanner** | Dangerous opcodes, blacklist selectors, proxy patterns |
| **RYO Market API** | Live price, RSI(14), ATR(14), technical verdict *(requires `RYO_MCP_KEY`)* |

---

## Quick Start

```bash
pip install ryocryptoguard
ryocryptoguard install-hook
```

### Manual Check

```bash
ryocryptoguard check 0xdAC17F958D2ee523a2206206994597C13D831ec7 --chain ethereum
ryocryptoguard check 0x... --chain bsc --output json
ryocryptoguard check 0x... -q   # exit code: 0=safe, 1=medium, 2=high/critical
```

---

## Market Research Commands

Requires `RYO_MCP_KEY`:

```bash
export RYO_MCP_KEY="ryo_mcp_your_private_key"

ryocryptoguard market SOL                       # analyze_token
ryocryptoguard market SOL --deep                # deep_analysis
ryocryptoguard market SOL AVAX BNB --intent swing  # compare_tokens
ryocryptoguard sentiment                        # 7-day sentiment shift
```

When `RYO_MCP_KEY` is set, every `check` automatically fetches market context — the report gains a **RYO Market Context** panel with price, RSI, and key points. The hook blocking message gains a one-line market headline.

---

## Integration

### Claude Code (Automatic Hook)

```json
{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hook": "python -m cryptoguard.hook" }
    ]
  }
}
```

### Python API

```python
from cryptoguard import analyze

result = analyze("0xdAC17F958D2ee523a2206206994597C13D831ec7", chain="ethereum")

print(f"Risk: {result.risk_level.value} ({result.risk_score}/100)")
print(f"Block: {result.should_block}")

if result.ryo_market:
    print(result.ryo_market["summary"]["headline"])
```

### MCP Server

```json
{
  "mcpServers": {
    "ryocryptoguard": {
      "command": "python",
      "args": ["-m", "cryptoguard.mcp_server"]
    }
  }
}
```

Three tools exposed:

| Tool | Input | What it does |
|------|-------|--------------|
| `cryptoguard_check` | `address`, `chain` | Full contract security analysis |
| `ryo_market_context` | `symbol`, `deep?` | Live market + technical analysis |
| `ryo_compare_tokens` | `symbols`, `intent?` | Compare 2–4 tokens side-by-side |

---

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `CRYPTOGUARD_DISABLE` | Set to `1` to bypass the hook | `0` |
| `CRYPTOGUARD_CHAIN` | Default chain if not detected | `ethereum` |
| `CRYPTOGUARD_THRESHOLD` | Min risk level to block (`CRITICAL`, `HIGH`, `MEDIUM`) | `HIGH` |
| `RYO_MCP_KEY` | RYO builder API key — enables market research | *(unset)* |
| `RYO_MCP_URL` | RYO endpoint override | `https://app-ryochan.com/api/mcp` |

Copy `.env.example` to `.env` and fill in your values.

### Supported Chains

Ethereum, BSC, Polygon, Arbitrum, Base, Optimism, Avalanche, Fantom, zkSync Era, Linea, Scroll, Mantle, Blast

---

## Architecture

```
cryptoguard/
  analyzer.py       Core analysis engine + risk scoring
  scanner.py        EVM bytecode pattern analysis
  goplus.py         GoPlus Security API client
  reputation.py     Multi-source reputation aggregator
  ryo.py            RYO market research REST client
  report.py         Terminal report formatter (Rich)
  mcp_server.py     MCP server — 3 tools
  hook.py           AI agent pre-transaction hook
  cli.py            CLI entry point
  constants.py      Chains, selectors, risk weights
```

### Risk Scoring

| Score | Level | Action |
|-------|-------|--------|
| 70–100 | CRITICAL | Block + full report |
| 50–69 | HIGH | Block + findings |
| 30–49 | MEDIUM | Warn, allow with caution |
| 15–29 | LOW | Info only |
| 0–14 | SAFE | Allow silently |

RYO market findings are capped at LOW — they never change the BLOCK decision.

---

## FAQ

**Does this slow down transactions?**
Analysis runs in parallel (2–5s). RYO market enrichment runs in the same pool — no added latency.

**Does it need API keys?**
No keys required for the safety layer. GoPlus, Honeypot.is, TokenSniffer, De.Fi, and QuickIntel all have free public tiers. `RYO_MCP_KEY` is only needed for market research commands.

**Can it detect all scams?**
No tool guarantees 100% detection. CryptoGuard significantly reduces risk by cross-referencing multiple independent sources. Always DYOR.

---

Built by yabig · [ryocryptoguard.vercel.app](https://ryocryptoguard.vercel.app) · Market research by [RYO](https://app-ryochan.com)
