ryocryptoguard 0.2.0__tar.gz

ryocryptoguard-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 momenbasel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ryocryptoguard-0.2.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include cryptoguard *.py
+include assets/banner1.jpg
+include assets/logo.svg
+include assets/logo.png

ryocryptoguard-0.2.0/PKG-INFO

@@ -0,0 +1,440 @@
+Metadata-Version: 2.4
+Name: ryocryptoguard
+Version: 0.2.0
+Summary: AI agent safety layer for crypto transactions - blocks honeypots, blacklists, and rug pulls before they happen
+Author-email: momenbasel <momenbasel@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/momenbasel/CryptoGuard
+Project-URL: Repository, https://github.com/momenbasel/CryptoGuard
+Project-URL: Issues, https://github.com/momenbasel/CryptoGuard/issues
+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://github.com/momenbasel/CryptoGuard/blob/main/LICENSE"><img src="https://img.shields.io/github/license/momenbasel/CryptoGuard?color=00d4ff&style=flat-square" alt="License"/></a>
+  <a href="https://github.com/momenbasel/CryptoGuard/stargazers"><img src="https://img.shields.io/github/stars/momenbasel/CryptoGuard?color=00d4ff&style=flat-square" alt="Stars"/></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/momenbasel/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 [@momenbasel](https://github.com/momenbasel).
+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.**