Content
<p align="center">
<img src="public/brand/onchainai-logo.png" alt="OnchainAI logo" width="96" />
</p>
# OnchainAI
> Crypto tools, unified. Discover, vet, and install MCP, CLI, SDK, API, x402, RWA, and AI-agent tools — from the web or straight from your agent.
[](LICENSE)
[](https://github.com/tokio-rs/axum)
[](https://nextjs.org)
[](https://www.onchain-ai.xyz/connect)
[](https://www.onchain-ai.xyz)
**Live: [onchain-ai.xyz](https://www.onchain-ai.xyz)** · **Connect hub: [onchain-ai.xyz/connect](https://www.onchain-ai.xyz/connect)**
## Why?
Crypto tooling is fragmented across CryptoSkill, Smithery, npm, GitHub topics, and
dozens of separate registries — and most of it is hard to judge: is this MCP server
official? Is the install command safe? Does it charge x402 payments on every call?
OnchainAI auto-discovers tools from multiple sources, normalizes them into one
3-axis taxonomy (Function × Asset Class × Actor), scores trust and install risk,
and exposes everything to both humans (web UI) and agents (MCP server, plugin,
skill) — so "find me a safe tool to bridge USDC to Base" is one question, not an
afternoon of research.
## Use it from your agent (60 seconds)
The OnchainAI MCP server is a no-auth endpoint. All discovery tools are free and
read-only; the one exception is `check_endpoint_health`, an optional premium trust
tool paid per call via x402:
```
https://www.onchain-ai.xyz/mcp
```
| Client | Setup |
|---|---|
| **Claude Code** | `claude mcp add --transport http onchainai https://www.onchain-ai.xyz/mcp` |
| **Claude Desktop / Web** | Settings → Connectors → Add custom connector → paste the URL above |
| **Cursor / VS Code** | One-click deeplinks on the [connect hub](https://www.onchain-ai.xyz/connect), or paste the JSON below |
| **ChatGPT** | Settings → Connectors (Developer mode) → new connector with the URL above |
| **Anything else** | `npx add-mcp https://www.onchain-ai.xyz/mcp`, or `npx mcp-remote https://www.onchain-ai.xyz/mcp` for stdio-only clients |
```json
{
"mcpServers": {
"onchainai": { "type": "http", "url": "https://www.onchain-ai.xyz/mcp" }
}
}
```
Full per-client walkthroughs (Codex, Windsurf, Gemini CLI, …): [docs/CONNECT.md](docs/CONNECT.md) or the live [/connect](https://www.onchain-ai.xyz/connect) page.
### MCP tools
| Tool | What it does |
|---|---|
| `search_tools` | Search by capability ("bridge USDC to Base"), filter by category/chain, sort by relevance/trust/stars/recent |
| `get_tool_detail` | Full metadata for one tool: trust score, install risk, chains, repo, x402 pricing |
| `get_install_guide` | Platform-specific install steps (claude / cursor / generic / cli) with safety gating — `critical`-risk commands are withheld |
| `list_categories` | Browse the taxonomy with tool counts |
| `get_dashboard_snapshot` | Public coverage snapshot: totals, categories, trust, x402, featured |
| `compare_tools` | Side-by-side comparison of 2–4 tools on trust, risk, chains, pricing (free today; operator can enable x402 premium) |
| `export_toolkit` | Export a JSON + markdown install kit by slugs or category (free today; operator can enable x402 premium) |
| `check_endpoint_health` | Endpoint liveness + 30-day probe uptime for a listed x402 tool — x402-paid per call (HTTP 402 handshake) |
Linking your account from a coding agent (`/connect#agent-sync`) unlocks three more:
`save_to_toolkit`, `save_stack_to_blueprint`, and `link_status`.
### Claude Code plugin
One command wires up the MCP server, a `/find-tool` command, and a crypto-tools skill:
```
/plugin marketplace add Coinyak/onchainai
/plugin install onchainai@onchainai
```
The bundle lives in [`plugin/onchainai/`](plugin/onchainai/) — it connects only
OnchainAI's own read-only endpoint, never auto-runs install commands, and always
discloses x402 pricing before recommending a paid tool.
### Agent skill
[`plugin/onchainai/skills/onchainai-crypto-tools/SKILL.md`](plugin/onchainai/skills/onchainai-crypto-tools/SKILL.md)
teaches an agent *when* to search the directory, how to rank trust signals, and the
hard safety rules (never install `critical`-risk tools, always surface x402 costs).
It ships with the plugin; you can also copy the skill directory into
`~/.claude/skills/` or upload it to any agent runtime that supports Agent Skills.
## Features
- **Auto-discovery crawler** — CryptoSkill, GitHub topics, npm, web3-mcp-hub, MCP registry, on cron schedules with dedup + relevance scoring
- **3-axis classification** — Function × Asset Class × Actor, plus chain tagging
- **Trust & safety pipeline** — trust scores, identity-cluster checks (repo/npm/homepage), install-risk analysis with a hard block on `critical` commands, operator review queue, quarantine
- **x402 awareness** — paid tools carry price metadata, verification flags, and referral/attribution disclosure ([policy below](#x402--referral-policy))
- **MCP server for agents** — the read-only tools above, rate-limited and sanitized
- **Claude Code plugin + skill** — one-command onboarding for agent users
- **3-way auth** — GitHub OAuth + email magic link + SIWX wallet sign-in (CAIP-122)
- **Community layer** — submissions, comments, upvotes, bookmarks, toolkit, compare, blueprints
- **Admin dashboard** — tool review, categories, crawler control, featured carousel, users, site settings
## x402 & referral policy
OnchainAI is **attribution and trust metadata only**:
- We publish x402 price/endpoint metadata and verification flags (`payment_verified`, `x402_endpoint_verified`, `price_verified`) as trust signals.
- We record anonymous referral/attribution events (views, install-guide fetches) to support revenue-share agreements with tool owners.
- We **never** hold or move funds, proxy payments, act as an x402 facilitator/gateway, or invent undocumented `referrer`/`split` payment fields.
- Unverified x402 tools remain visible when they pass the normal public quality gate — verification is a badge, not a hiding mechanism.
Details: [docs/X402_REFERRAL_SPEC.md](docs/X402_REFERRAL_SPEC.md).
## Architecture
```
┌─ Vercel ──────────────┐ ┌─ Railway ─────────────────────────┐
│ Next.js frontend │──────│ Rust binary (Axum) │
│ /connect, /tools, ... │ /api │ ├─ REST API (/api/v2) │
│ proxies /api /auth │ /mcp │ ├─ MCP server (POST /mcp) │
│ /mcp to the API │ │ ├─ Auth (OAuth/email/SIWX + JWT) │
└───────────────────────┘ │ └─ Crawler (tokio-cron) │
└────────────┬──────────────────────┘
│ sqlx
┌─ Supabase Postgres (RLS) ─┐
└───────────────────────────┘
```
- **API/MCP**: Rust — Axum + sqlx + tokio-cron-scheduler, one binary (`cargo run --features ssr`)
- **Frontend**: Next.js (App Router) on Vercel, rewrites `/api`, `/auth`, `/mcp` to the Railway API
- **DB**: Supabase Postgres with RLS; the public read gate is enforced in both SQL policies and server queries
## Run it yourself
```bash
git clone https://github.com/Coinyak/onchainai
cd onchainai
cp .env.example .env # fill in Supabase URL/keys, GitHub OAuth, JWT secret
# API (port 3000)
cargo run --features ssr
# Frontend (port 3001, proxying to the API)
cd frontend && npm ci && API_PROXY_TARGET=http://localhost:3000 npm run dev -- --port 3001
```
> The crate's default feature set is empty so server deps don't leak into any
> WASM/client build. Plain `cargo` commands that touch server code need
> `--features ssr`.
Common checks:
```bash
cargo test --features ssr # tests
cargo clippy --features ssr -- -W clippy::all # lint
cargo fmt --check # format
./scripts/agent-harness-check.sh # agent/dev harness self-check
```
## Repository layout
| Path | What lives there |
|---|---|
| `src/` | Rust API: MCP server, REST `/api/v2`, auth, crawler, trust/risk pipeline |
| `frontend/` | Next.js app (Vercel): public UI + admin dashboard |
| `plugin/onchainai/` | Claude Code plugin bundle (MCP config, `/find-tool`, skill) |
| `migrations/` | sqlx Postgres migrations (RLS policies included) |
| `docs/` | Design docs, specs, operator guide ([index](docs/INDEX.md)) |
| `scripts/` | Dev/deploy/verification gates (see `AGENTS.md`) |
| `agent/`, `.agents/` | Skills and harness config for AI coding agents working on this repo |
## Documentation
| File | Purpose |
|---|---|
| [docs/CONNECT.md](docs/CONNECT.md) | Connect any MCP client, install the plugin/skill |
| [docs/MVP_DESIGN.md](docs/MVP_DESIGN.md) | Architecture, DB schema, crawler, MCP server |
| [docs/X402_REFERRAL_SPEC.md](docs/X402_REFERRAL_SPEC.md) | x402 referral/attribution design (no-custody) |
| [docs/LAUNCH_READINESS_SPEC.md](docs/LAUNCH_READINESS_SPEC.md) | Public-launch checklist and roadmap spec |
| [docs/SECURITY.md](docs/SECURITY.md) | Security design: auth, RLS, headers, rate limiting |
| [docs/UI_UX_DESIGN.md](docs/UI_UX_DESIGN.md) | Full UI spec |
| [docs/OPERATOR_GUIDE.md](docs/OPERATOR_GUIDE.md) | Operator/admin playbook (Korean) |
| [docs/BUILD_DEPLOY_RULES.md](docs/BUILD_DEPLOY_RULES.md) | Build coherence, smoke gates, Railway/Vercel deploy |
| [AGENTS.md](AGENTS.md) | Entry point for AI coding agents |
## Contributing & security
- Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). The fastest way to help is submitting missing tools at [onchain-ai.xyz/submit](https://www.onchain-ai.xyz/submit).
- Security reports: see [SECURITY.md](SECURITY.md). Please do not open public issues for vulnerabilities.
## License
[MIT](LICENSE)
