Metadata-Version: 2.4
Name: ryocryptoguard
Version: 0.2.1
Summary: AI agent safety layer for crypto transactions - blocks honeypots, blacklists, and rug pulls before they happen
Author: yabig
License-Expression: MIT
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
License-File: LICENSE
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"
Dynamic: license-file

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

<p align="center">
  <a href="https://pypi.org/project/ryocryptoguard/"><img src="https://img.shields.io/pypi/v/ryocryptoguard?color=00d4ff&style=flat-square" alt="PyPI"/></a>
  <a href="https://pypi.org/project/ryocryptoguard/"><img src="https://img.shields.io/pypi/l/ryocryptoguard?color=00d4ff&style=flat-square" alt="License"/></a>
  <a href="https://pypi.org/project/ryocryptoguard/"><img src="https://img.shields.io/pypi/pyversions/ryocryptoguard?color=00d4ff&style=flat-square" alt="Python"/></a>
</p>

# RyoCryptoGuard

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

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 now enriches every analysis
with real-time technical data from the RYO market research API.

## The Problem

AI agents are increasingly used to execute crypto transactions — swapping tokens, interacting
with DeFi protocols, and managing wallets. But they 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 transaction
          HIGH -> BLOCK transaction
```

### Data Sources

CryptoGuard queries **6+ independent sources** in parallel:

| 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 *(optional, requires `RYO_MCP_KEY`)* |

### What It Detects

| Risk | Description | Severity |
|------|-------------|----------|
| Honeypot | Cannot sell tokens after buying | CRITICAL |
| Blacklist | Owner can freeze any address | CRITICAL |
| Balance manipulation | Owner can change anyone's balance | CRITICAL |
| Airdrop scam | Malicious token sent to bait interaction | CRITICAL |
| Self-destruct | Contract can destroy itself and drain funds | CRITICAL |
| Per-address tax | Owner can set 100% tax on YOUR address | CRITICAL |
| Cannot sell all | Trapped partial balance | CRITICAL |
| Extreme sell tax | >50% sell tax | CRITICAL |
| Hidden owner | Concealed admin control | HIGH |
| Unlocked liquidity | LP can be pulled (rug pull) | HIGH |
| Unverified source | Code not published for audit | HIGH |
| Whale concentration | Single wallet holds >20% supply | HIGH |
| Creator honeypot history | Deployer made honeypots before | HIGH |
| Modifiable tax/slippage | Fees can be changed post-buy | HIGH |
| Pausable transfers | Owner can halt all trading | HIGH |
| Proxy contract | Logic can be silently upgraded | MEDIUM |
| Mintable supply | New tokens can dilute holdings | MEDIUM |
| Low liquidity | High slippage or unable to sell | MEDIUM |
| Similar scam tokens | Code matches known scams | HIGH |
| RSI overbought ≥ 80 | Technically exhausted entry point | LOW |
| Bearish RYO verdict | RYO deterministic analysis is bearish | LOW |

---

## Quick Start

### Install

```bash
pip install ryocryptoguard
```

### Install the AI Agent Hook (recommended)

```bash
# Automatically installs the Claude Code pre-transaction hook
ryocryptoguard install-hook

# Or with custom risk threshold
ryocryptoguard install-hook --threshold CRITICAL  # Only block critical risks
ryocryptoguard install-hook --threshold MEDIUM    # Block medium and above
```

### One-Line Install

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

### Manual Check

```bash
# Check a token on Ethereum
ryocryptoguard check 0xdAC17F958D2ee523a2206206994597C13D831ec7 --chain ethereum

# Check on BSC
ryocryptoguard check 0x... --chain bsc

# JSON output (for scripts)
ryocryptoguard check 0x... --chain polygon --output json

# Quick check (just risk level, for scripting)
ryocryptoguard check 0x... -q
echo $?  # 0=safe, 1=medium, 2=high/critical
```

---

## Market Research Commands *(requires `RYO_MCP_KEY`)*

Set your RYO builder key once:

```bash
export RYO_MCP_KEY="ryo_mcp_your_private_key"
```

Then use the new market commands:

```bash
# Analyze a single token — price, RSI, ATR, market intel
ryocryptoguard market SOL

# Deep analysis — includes catalysts, risks, ATR-based plan, derivatives
ryocryptoguard market SOL --deep

# Compare two to four tokens side-by-side
ryocryptoguard market SOL AVAX BNB --intent swing

# Check 7-day market-wide sentiment shift
ryocryptoguard sentiment

# JSON output for any market command
ryocryptoguard market SOL --output json
ryocryptoguard sentiment --output json
```

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

---

## Integration

### Claude Code (Automatic)

After `ryocryptoguard install-hook`, every `cast send`, `swap`, `approve`, and other
transaction commands are automatically intercepted and analyzed.

The hook adds this to your `~/.claude/settings.json`:

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

### OpenAI Codex / Other Agents

Use CryptoGuard as a pre-exec wrapper:

```bash
# Wrap any command
ryocryptoguard check 0xTOKEN_ADDRESS --chain ethereum -q && cast send 0xTOKEN_ADDRESS ...
```

### 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"Safe: {result.is_safe}")
print(f"Should block: {result.should_block}")

for finding in result.findings:
    print(f"  [{finding.severity.value}] {finding.title}")

# RYO market data (present when RYO_MCP_KEY is set)
if result.ryo_market:
    print(result.ryo_market["summary"]["headline"])
```

### MCP Server

Add to your Claude Code MCP config or any MCP-compatible client:

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

**Three tools are exposed:**

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

An AI agent can now do the full pre-trade workflow through one MCP server:

```
cryptoguard_check("0xABC...")       → is the contract safe?
ryo_market_context("CAKE")          → is the market timing sensible?
ryo_compare_tokens("SOL, AVAX")     → which asset looks stronger?
```

#### Remote RYO MCP (direct)

If you prefer to call RYO's own MCP endpoint directly from a client:

```json
{
  "mcpServers": {
    "ryo": {
      "url": "https://app-ryochan.com/api/mcp",
      "headers": { "Authorization": "Bearer ${RYO_MCP_KEY}" }
    }
  }
}
```

---

## Configuration

### Environment Variables

| 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 commands and automatic market enrichment | *(unset)* |
| `RYO_MCP_URL` | RYO endpoint override | `https://app-ryochan.com/api/mcp` |

Copy `.env.example` to `.env` and fill in your values. **Never commit a populated `.env`.**

### Supported Chains

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

---

## Architecture

```
cryptoguard/              # Python package (pip install ryocryptoguard)
  __init__.py       # Public API
  cli.py            # Click CLI (ryocryptoguard / cryptoguard commands)
  hook.py           # AI agent pre-transaction hook
  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 (NEW in v0.2)
  report.py         # Terminal report formatter (Rich)
  mcp_server.py     # MCP server for tool-based integration
  constants.py      # Chains, selectors, weights
```

### Risk Scoring

Risk score is 0–100, computed from weighted findings with diminishing returns within categories:

| Score | Level | Action |
|-------|-------|--------|
| 70–100 | CRITICAL | Block transaction, show full report |
| 50–69 | HIGH | Block transaction, show 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 severity — they **never** change the BLOCK decision.
Market context is informational enrichment only.

---

## Development

```bash
git clone https://github.com/yabig/CryptoGuard.git
cd CryptoGuard
pip install -e ".[dev]"

# Run tests
pytest

# Lint
python -m ruff check cryptoguard/

# Build distribution
pip install build
python -m build

# Upload to PyPI
pip install twine
twine upload dist/*
```

---

## FAQ

**Does this slow down my transactions?**
Analysis takes 2–5 seconds (parallel API calls). Market enrichment runs in the same
parallel pool — it adds no extra wall-clock time when `RYO_MCP_KEY` is set.

**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 can guarantee 100% detection. CryptoGuard significantly reduces risk by
cross-referencing multiple independent sources, but novel scam techniques may bypass
detection. Always DYOR.

**Does it work with hardware wallets?**
CryptoGuard analyzes the contract, not the wallet. It works regardless of how you sign
transactions.

**Can I use it without an AI agent?**
Yes. The CLI works standalone:
```bash
ryocryptoguard check 0x... --chain ethereum
ryocryptoguard market SOL
```

**Does RYO market data affect the BLOCK decision?**
No. RYO findings are LOW/INFO severity only. The blocking threshold is driven
entirely by contract security findings. This boundary is intentional and will not change.

---

## License

MIT

## Credits

Built by yabig.
Security data powered by GoPlus, Honeypot.is, TokenSniffer, De.Fi, and QuickIntel.
Market research powered by [RYO](https://app-ryochan.com).

PyPI: [pypi.org/project/ryocryptoguard](https://pypi.org/project/ryocryptoguard/)

---

**If this tool saves you from a scam, star the repo and share it. Every star helps protect more people.**
