Content
# Crypto-Knowledge
**The on-chain brain for autonomous AI agents.** An [MCP](https://modelcontextprotocol.io) server that lets agents perform complex crypto operations — cross-chain routing, contract decoding, portfolio & allowance management, gas/profit estimation and anti-rug security checks — safely and deterministically.
> **Keystore-free by design.** The server never holds private keys and never signs. Every write action returns an *unsigned, ready-to-sign transaction*; the agent signs it with its own wallet. The server is multi-tenant and stateless — bring your own address, get back data + unsigned transactions.
## Tools (11)
| Tool | What it does |
|---|---|
| `route` | Best cross-chain route between any chains/tokens (e.g. CRO → SOL). Queries **LiFi + deBridge** in parallel, compares output, returns the best route plus alternatives, each with a ready-to-sign transaction. |
| `pumpfun` | Direct on-chain pump.fun reads: live bonding-curve reserves, price, graduation progress, market cap, and resolved IPFS metadata. |
| `profitability` | EIP-1559 multi-chain gas estimation + net-profit verdict after gas & slippage (arbitrage guard). |
| `abi` | Fetch any verified EVM contract's ABI (Etherscan V2 / Sourcify), follow EIP-1967 proxies, and tell the agent exactly which parameters each function needs. Decode/encode calldata — `decode_calldata` even works on **unverified** contracts via a 4byte-directory selector lookup. Cached. |
| `portfolio` | Multi-chain balances (native + ERC-20 + SPL) and ERC-20 allowance management (check / approve / revoke) returning unsigned transactions. |
| `security` | Anti-rug scan via **GoPlus + honeypot.is** (EVM **and Solana**): honeypot/non-transferable, taxes, liquidity locks, mint/freeze/blacklist/pause powers, holder concentration → 0-100 risk score with red flags. |
| `mev_protection` | Private-RPC guidance (Flashbots Protect, MEV Blocker) + per-chain sandwich risk so the agent broadcasts safely. |
| `whale_watch` | Recent large ERC-20 transfers ("whale moves") for a token over a block window, decoded + sorted. |
| `solana_swap` | Quote & build same-chain Solana swaps via **Jupiter** (e.g. SOL→USDC, buy a graduated pump token) — returns a serialized unsigned transaction. |
| `simulate` | Dry-run an EVM transaction (eth_call) before signing and decode the revert reason (Error/Panic/custom) — never burn gas on a doomed tx. |
| `catalog` | Discovery: lists every tool, supported chain (id/native asset) and provider mode so an agent can self-configure. |
## Supported chains
Ethereum, Base, Arbitrum, Optimism, Polygon, **Cronos**, ApeChain, BNB Smart Chain, Avalanche, Solana (10). Chain-agnostic by design — adding a chain is a single registry entry (`src/registry/chains.ts`).
## Quick start
```bash
npm install
cp .env.example .env # optional keys — everything degrades to public RPC without them
npm test # 31 deterministic unit tests
npm run dev # run the MCP server over stdio
```
### Use it from an MCP client (e.g. Claude Code)
```json
{
"mcpServers": {
"crypto-knowledge": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/Crypto-Knowledge/src/index.ts"]
}
}
}
```
## Provider modes (per call)
The caller chooses how RPC/data is sourced:
- **`open`** — public RPCs only. Free, but limited data (e.g. no ERC-20 auto-discovery) and lower rate limits.
- **`own_key`** ⭐ *recommended* — pass your own free `heliusKey` / `alchemyKey`. Best performance, your quota. Keys are used transiently and never stored or logged.
- **`tool`** — use the operator's keys (never exposed). Reserved for NFT-holders / paid tier when access gating is enabled.
> Get a free key at [helius.dev](https://helius.dev) (Solana) and [alchemy.com](https://alchemy.com) (EVM). The tool will nudge you when you're on a degraded public RPC.
## Access & monetization (hosted mode)
When `ACCESS_GATING_ENABLED=true` (off by default for local stdio use):
- **Holder** — owns the configured gating NFT (on-chain verified) → free, higher limits, may use the tool's keys.
- **Paid** — \$0.10 per request via [x402](https://x402.org).
- **Free** — public-RPC tier with conservative limits.
## Architecture
```
agent ──▶ MCP tools (6 modules)
└─ core: RPC pool · retry/backoff · canonical errors · provider resolver
└─ access: sliding-window rate limit · NFT gate
returns ONLY unsigned tx + data → agent signs locally
```
See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full design, JSON I/O specs and R&D roadmap.
## Security
- No private keys, ever. Read + build-unsigned-tx only.
- Operator keys are server-side only and never echoed to callers.
- Caller-supplied keys are transient (never persisted/logged).
## License
MIT
