bnb-chain · mefai-dev · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -0,0 +1 @@
+* @mefai-dev
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,59 @@
+# Contributing to BNB Chain Skills
+
+Thank you for your interest in contributing. This project provides on-chain analysis tools for BNB Smart Chain and we welcome contributions from the community.
+
+## How to Contribute
+
+1. **Fork** this repository
+2. **Create a feature branch** from `main`
+3. **Make your changes** following the guidelines below
+4. **Submit a pull request** with a clear description of your changes
+
+## Adding a New Skill
+
+Each skill lives in its own directory under `skills/<category>/<skill-name>/` and must include a `SKILL.md` file following this structure:
+
+- YAML frontmatter with `name`, `description`, and `metadata` (author, version)
+- Overview table listing API endpoints, functions, and use cases
+- Use cases section
+- Supported chains table
+- API documentation with method, URL, parameters, example request, response example, and field descriptions
+- Notes section
+
+See any existing `SKILL.md` for reference.
+
+## Adding a New API Endpoint
+
+1. Add the route in `api/routes/bnbchain.py`
+2. Create the corresponding `SKILL.md` in the appropriate category
+3. Add the frontend panel in `frontend/js/panels.js` if applicable
+4. Register the panel in `frontend/js/app.js`
+5. Update the skills table in `README.md`
+
+## Code Style
+
+- **Python**: Follow PEP 8. Use `async/await` for all HTTP calls. Use type hints.
+- **JavaScript**: Vanilla JS, no frameworks. Web Components for panels.
+- **Documentation**: English only. Clear, concise descriptions.
+
+## Testing
+
+Before submitting a PR:
+
+1. Verify the API endpoint returns correct data
+2. Test the frontend panel renders properly
+3. Check that caching works (stale-while-revalidate pattern)
+4. Confirm no broken imports or missing dependencies
+
+## Reporting Issues
+
+Open a GitHub issue with:
+
+- Clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- BSC transaction/block/address examples if applicable
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
diff --git a/README.md b/README.md
@@ -1,101 +1,173 @@
 # BNB Chain Skills
 
-> A collection of AI agent skills for the [BNB Chain MCP](https://github.com/bnb-chain/bnbchain-mcp) (Model Context Protocol) server.
+> 28 professional on-chain analysis tools for BNB Smart Chain. Built by [Mefai](https://mefai.io).
+
+**Live Demo:** [mefai.io/bnbchain](https://mefai.io/bnbchain)
+
+## Overview
+
+BNB Chain Skills is an open-source collection of real-time blockchain analysis tools built on BSC JSON-RPC and DexScreener APIs. Each skill provides a focused, production-ready analytical capability — from transaction decoding to honeypot detection, from validator monitoring to cross-DEX arbitrage scanning.
+
+## Skills
+
+### Security & Auditing
+| Skill | Description | API Endpoint |
+|-------|-------------|-------------|
+| **Honeypot Check** | Combined honeypot detection: bytecode analysis, buy/sell ratio, owner concentration, dangerous selectors | `/mefai/honeypot-check` |
+| **Contract X-Ray** | Deep bytecode analysis: proxy detection, function scanning, mint/pause/blacklist pattern detection | `/mefai/contract-xray` |
+| **Approval Scanner** | Token approval checker across 9 major DEX routers — finds unlimited allowances | `/mefai/approval-scanner` |
+| **Risk Radar** | Risk scoring (0-100, A-F grade) combining on-chain and market signals | `/mefai/risk-radar` |
+| **Upgrade Monitor** | EIP-1967 proxy contract detection with storage slot inspection, admin identification | `/mefai/upgrade-monitor` |
+| **Contract Audit** | Smart contract security analysis: ownership, proxy, token standards compliance | `/mefai/contract-audit` |
+
+### Alpha & Intelligence
+| Skill | Description | API Endpoint |
+|-------|-------------|-------------|
+| **Sniper Detector** | Detect bot sniping on any token — early buyer analysis, hold/dump tracking, snipe score | `/mefai/sniper-detector` |
+| **Copy Trade** | Alpha wallet activity monitor — tracks known wallets for token interactions | `/mefai/copy-trade` |
+| **Smart Money** | Whale transaction tracker — identifies large-value transfers in real-time | `/mefai/smart-money` |
+| **Wallet Cluster** | On-chain forensics: discover connected wallets via transfer patterns and shared holdings | `/mefai/wallet-cluster` |
+
+### Market Analysis
+| Skill | Description | API Endpoint |
+|-------|-------------|-------------|
+| **DEX Arbitrage** | Cross-DEX price discrepancy finder with gas-adjusted profit estimates | `/mefai/dex-arb` |
+| **Token Battle** | Side-by-side comparison of up to 4 tokens: price, volume, liquidity, burns | `/mefai/token-battle` |
+| **Token Birth** | Token genesis analysis: creator profile, supply distribution, age, liquidity history | `/mefai/token-birth` |
+| **Pair Analytics** | Deep DEX pair analysis with aggregate stats across multiple pairs | `/mefai/pair-analytics` |
+| **PancakeSwap Arena** | PancakeSwap top pairs, volume leaders, trending tokens | `/mefai/pancakeswap-arena` |
+
+### On-Chain Analytics
+| Skill | Description | API Endpoint |
+|-------|-------------|-------------|
+| **TX Decoder** | Decode any BSC transaction: function calls, events, token transfers, gas breakdown | `/mefai/tx-decoder` |
+| **Block Autopsy** | Block gas distribution, transaction type breakdown, top gas consumers | `/mefai/block-autopsy` |
+| **Token Flow** | Track token transfer movements from recent blocks | `/mefai/token-flow` |
+| **Burn Engine** | Real-time BNB and token burn tracking with USD valuations | `/mefai/burn-tracker` |
+| **Wallet Scanner** | Complete wallet portfolio analysis: BNB + token balances with USD values | `/mefai/wallet-scanner` |
+| **Portfolio Heatmap** | Bloomberg-style portfolio view with 24h performance heatmap | `/mefai/portfolio-heatmap` |
+
+### Network & Infrastructure
+| Skill | Description | API Endpoint |
+|-------|-------------|-------------|
+| **Validator Map** | Live BSC validator monitoring: 21 validators, gas utilization, block production, MEV detection | `/mefai/validator-map` |
+| **Network Pulse** | Network congestion gauge: pressure score, TPS, block timing, gas optimization | `/mefai/network-pulse` |
+| **BSC Supremacy** | BSC vs Ethereum comparison: speed, cost, TPS — live data | `/mefai/bsc-supremacy` |
+| **Gas Calculator** | Operation cost estimator: 10 operations with BSC vs ETH cost comparison | `/mefai/gas-calculator` |
+| **Chain Vitals** | Core network health metrics: block height, gas price, peer count | `/mefai/chain-vitals` |
+
+### DeFi
+| Skill | Description | API Endpoint |
+|-------|-------------|-------------|
+| **Yield Finder** | APY estimation from trading fee revenue, sorted by opportunity | `/mefai/yield-finder` |
+| **DeFi Leaderboard** | Top DeFi protocols ranked by TVL, volume, and user count | `/mefai/defi-leaderboard` |
+| **Liquidity Pulse** | Real-time liquidity depth analysis across major BSC pairs | `/mefai/liquidity-pulse` |
+
+## Architecture
 
-## Introduction
+```
++----------------------------------------------+
+|              Frontend (Web Components)        |
+|  50 panels - _MX premium CSS - BasePanel      |
+|  Stale-while-revalidate cache - Auto-refresh  |
++----------------------------------------------+
+|              API Layer (FastAPI)               |
+|  28 /mefai/* endpoints - async - TTL cache    |
++----------------------------------------------+
+|            Data Sources                        |
+|  BSC JSON-RPC - DexScreener - BscScan         |
++----------------------------------------------+
+```
 
-BNB Chain Skills helps AI agents (e.g. Cursor, Claude) install and use the BNB Chain MCP server effectively. It provides structured knowledge on how to connect the MCP server, configure credentials, and use each available tool for blocks, transactions, contracts, tokens, NFTs, wallet operations, ERC-8004 agent registration, and Greenfield storage.
+### Tech Stack
+- **Frontend:** Vanilla JS Web Components, zero dependencies
+- **Backend:** Python FastAPI with async/await, stale-while-revalidate caching
+- **Data:** BSC JSON-RPC (bsc-dataseed1.binance.org), DexScreener API, BscScan API
+- **Deployment:** Nginx reverse proxy, systemd services
 
-## Claude/Cursor skills vs OpenClaw skills
+## API Reference
 
-| | **This repo (bnbchain-skills)** | **OpenClaw skills** |
-|---|--------------------------------|---------------------|
-| **Who installs** | The **user** installs the skill (e.g. `npx skills add bnb-chain/bnbchain-skills` or copy into `~/.cursor/skills/`). | The **OpenClaw bot** fetches the skill page itself (e.g. `curl` the [OpenClaw Skills](https://docs.bnbchain.org/showcase/mcp/skills) URL) and learns from it. |
-| **Who acts** | The **agent** (Cursor/Claude) reads the skill and then **sets up MCP for the user**—adds the bnbchain-mcp server to the user’s MCP config and uses the tools. | The **OpenClaw bot** autonomously knows the `npx @bnb-chain/mcp@latest` command and installs/uses the MCP based on that page. |
-| **Purpose** | Teach the in-IDE agent to configure bnbchain-mcp in the user’s environment and use every MCP tool. | Give OpenClaw (and similar agents) a single fetchable page so they can discover and use BNB Chain MCP on their own. |
+All endpoints are served under `/superbsc/api/bnbchain/mefai/`.
 
-So: **Claude/Cursor skills** = user installs skill → agent uses it to **set MCP for the user** and call tools. **OpenClaw skills** = bot fetches the skill page → bot **installs and uses** MCP autonomously.
+### Authentication
+No authentication required. All endpoints are public and rate-limited via caching.
 
-## What are Skills?
+### Common Response Pattern
+```json
+{
+  "field1": "value",
+  "field2": 123,
+  "error": null
+}
+```
 
-Skills are structured knowledge files that give AI coding agents domain-specific expertise. They follow a portable format that works across different AI tools. When you install a skill, the agent learns how to install bnbchain-mcp and how to use each MCP tool without needing to search external docs.
+Error responses:
+```json
+{
+  "error": "Description of what went wrong"
+}
+```
 
-## Available Skills
+### Example Requests
 
-| Skill | Description |
-|-------|-------------|
-| **bnbchain-mcp-skill** | Install and use BNB Chain MCP — blocks, transactions, contracts, tokens, NFTs, wallet, ERC-8004 agents, Greenfield. Covers connection, credentials, and every MCP tool. |
+```bash
+# Honeypot check
+curl https://mefai.io/superbsc/api/bnbchain/mefai/honeypot-check?address=0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82
 
-## Installation
+# Network pulse
+curl https://mefai.io/superbsc/api/bnbchain/mefai/network-pulse
 
-### Quick Install (Recommended)
+# Validator map
+curl https://mefai.io/superbsc/api/bnbchain/mefai/validator-map
 
-```bash
-npx skills add bnb-chain/bnbchain-skills
+# Gas calculator
+curl https://mefai.io/superbsc/api/bnbchain/mefai/gas-calculator
 ```
 
-Install globally (available across all projects):
+## Self-Hosting
 
-```bash
-npx skills add bnb-chain/bnbchain-skills -g
-```
+### Prerequisites
+- Python 3.11+
+- Node.js 18+ (for frontend dev only)
+- Nginx (production)
 
-### Manual Install (Cursor / Claude)
-
-**Personal skill** (available across all projects):
+### Setup
 
+1. Clone the repository:
 ```bash
-git clone https://github.com/bnb-chain/bnbchain-skills.git
-cp -r bnbchain-skills/skills/* ~/.cursor/skills/
+git clone https://github.com/mefai-dev/bnbchain-skills.git
+cd bnbchain-skills
 ```
 
-**Project skill** (current project only):
-
+2. Install Python dependencies:
 ```bash
-git clone https://github.com/bnb-chain/bnbchain-skills.git
-cp -r bnbchain-skills/skills/* .cursor/skills/
+pip install fastapi uvicorn httpx
 ```
 
-### Using the skill
-
-Once installed, the agent will use the skill when you ask to:
-
-- Install or connect BNB Chain MCP
-- Query blocks, transactions, balances, or contracts on BNB Chain or other EVM networks
-- Transfer tokens or NFTs, or interact with smart contracts
-- Register or resolve ERC-8004 agents
-- Use Greenfield storage (buckets, objects, payments)
+3. Start the backend:
+```bash
+uvicorn api.main:app --host 127.0.0.1 --port 8202
+```
 
-Example prompts:
+4. Serve the frontend:
+```bash
+# Development
+python -m http.server 8080 --directory frontend
 
-- "How do I install bnbchain-mcp in Cursor?"
-- "Get the latest block on BSC"
-- "Check the ERC-20 balance of 0x... on opBNB"
-- "Register this MCP as an ERC-8004 agent"
-- "List my Greenfield buckets"
+# Production: configure nginx to serve frontend/ as static and proxy /api to port 8202
+```
 
-## Skill Structure
+## Contributing
 
-```
-bnbchain-skills/
-├── skills/
-│   └── bnbchain-mcp-skill/
-│       ├── SKILL.md                    # Main skill: install + tool usage
-│       └── references/
-│           ├── evm-tools-reference.md     # Blocks, transactions, contracts, tokens, NFT, wallet, network
-│           ├── erc8004-tools-reference.md  # ERC-8004 agent tools
-│           ├── greenfield-tools-reference.md # Greenfield storage & payment tools
-│           └── prompts-reference.md         # MCP prompts
-├── LICENSE
-└── README.md
-```
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
-## References
+## Related Projects
 
-- **BNB Chain MCP:** https://github.com/bnb-chain/bnbchain-mcp
-- **npm package:** `@bnb-chain/mcp` — run with `npx @bnb-chain/mcp@latest`
-- **ERC-8004** (Identity Registry); **Agent Metadata Profile** for agentURI format.
+- [BNB Chain MCP](https://github.com/bnb-chain/bnbchain-mcp) — Model Context Protocol server for BNB Chain
+- [Binance Skills Hub](https://github.com/binance/binance-skills-hub) — Official Binance skills collection
 
 ## License
 
 MIT License — see [LICENSE](LICENSE) for details.
+
+Built by [Mefai](https://mefai.io) for the BNB Chain community.
diff --git a/api/__init__.py b/api/__init__.py