Metadata-Version: 2.4
Name: ryocryptoguard
Version: 0.2.4
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

### Requirements

- Python 3.10 or newer
- Internet access for RPC and security-provider requests
- A supported EVM address and chain

### Install from PyPI

```bash
python -m pip install --upgrade ryocryptoguard
ryocryptoguard --version
ryocryptoguard install-hook
```

The package installs the `ryocryptoguard` command.

### Install from the repository

Use this when developing or testing a local checkout:

```bash
git clone https://github.com/RYO-Digital/ryochan-hackathon_repository-229.git
cd CryptoGuard
python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS/Linux
# source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

### Run a check

```bash
ryocryptoguard check <address> --chain ethereum
ryocryptoguard check <address> --chain ethereum --output plain
ryocryptoguard check <address> --chain ethereum --output json
```

Supported chain aliases include `eth`, `bnb`, `matic`, `arb`, `op`, `avax`,
`ftm`, and `zk`. Use the full chain names in scripts when possible.

The command returns exit code `0` for safe/low results, `1` for medium risk,
and `2` for high or critical risk. A medium result caused by unavailable data
means the analysis is incomplete; it is not proof that the token is malicious.

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

`--quiet` prints only the risk level, which is useful in shell scripts and CI.

### Hook setup

Install the automatic Claude Code hook:

```bash
ryocryptoguard install-hook
```

Choose a stricter or more permissive blocking threshold:

```bash
ryocryptoguard install-hook --threshold HIGH
ryocryptoguard install-hook --threshold MEDIUM
ryocryptoguard install-hook --threshold CRITICAL
```

Remove it with:

```bash
ryocryptoguard uninstall-hook
```

---

## Market Research Commands

RYO market commands require `RYO_MCP_KEY`. Set it in the shell before using
the market commands.

**Windows PowerShell** (current terminal only):

```powershell
$env:RYO_MCP_KEY = "your_actual_ryo_key"
```

**Windows Command Prompt** (current terminal only):

```cmd
set RYO_MCP_KEY=your_actual_ryo_key
```

**macOS/Linux**:

```bash
export RYO_MCP_KEY="your_actual_ryo_key"
```

Then run:

```bash

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

The key is needed only for RYO market research. Basic contract security checks
work without it. Never commit API keys or paste them into source files.

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 ryocryptoguard.hook" }
    ]
  }
}
```

### Python API

```python
from ryocryptoguard 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", "ryocryptoguard.mcp_server"]
    }
  }
}
```

Three tools exposed:

| Tool | Input | What it does |
|------|-------|--------------|
| `ryocryptoguard_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 |
|----------|-------------|---------|
| `RYOCRYPTOGUARD_DISABLE` | Set to `1` to bypass the hook | `0` |
| `RYOCRYPTOGUARD_CHAIN` | Default chain if not detected | `ethereum` |
| `RYOCRYPTOGUARD_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.

The hook blocks transactions at the configured threshold. Set
`RYOCRYPTOGUARD_DISABLE=1` only for temporary troubleshooting. Never commit API
keys, wallet private keys, or PyPI tokens to the repository.

### RPC and unavailable data

The Ethereum RPC is configured in `ryocryptoguard/constants.py`. If an RPC
provider returns an error such as HTTP 525, CryptoGuard reports
`Blockchain RPC unavailable` and marks dependent fields as `Unknown`. It does
not treat an RPC failure as an empty wallet or as confirmed token risk. For
local deployments, replace the Ethereum RPC with a reliable provider such as
your authenticated node endpoint or another public Ethereum RPC.

GoPlus and reputation providers can independently return empty data, `401`,
`403`, or `404` responses. Those results are reported as unavailable rather
than treated as positive or negative security evidence.

### Supported Chains

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

---

## Architecture

```
ryocryptoguard/
  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.

## Development

Run the tests and lint checks from the repository root:

```bash
pytest -q
ruff check ryocryptoguard tests
```

Build release artifacts locally:

```bash
python -m build
python -m twine check dist/*
```

Publishing requires a PyPI account and API token. Enter the token only in the
terminal prompt; never place it in source files or chat messages.

## Troubleshooting

**The command says `RPC eth_getCode failed`.**

The configured RPC provider is unavailable or rejected the request. Retry
later or configure a different Ethereum RPC. The report will show unknown
fields until bytecode can be fetched.

**The report shows `401`, `403`, or `404` for a reputation source.**

That provider is unavailable, requires credentials, does not support the
chain, or has changed its endpoint. Other checks still run, but the result is
incomplete.

**The hook blocks a command unexpectedly.**

Run the same address manually with `--output plain`, review the findings, and
check `RYOCRYPTOGUARD_THRESHOLD`. Use `RYOCRYPTOGUARD_DISABLE=1` only temporarily.

---

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