Birdeye Skills

AI-native skill system for Birdeye's multi-chain DeFi analytics API — structured as a 3-tier router/domain/workflow architecture.

Supports Claude Code, Cursor, OpenAI Codex CLI, and ChatGPT/OpenAI API.

Quick Start

# Install for all platforms (Claude Code + Cursor + Codex)
npx birdeye-skills install

# With your Birdeye API key (auto-configures MCP)
npx birdeye-skills install --api-key YOUR_KEY

Get an API key at https://bds.birdeye.so → Usages → Security → Generate key

Platform-specific installs

npx birdeye-skills install --claude       # Claude Code only
npx birdeye-skills install --cursor       # Cursor only
npx birdeye-skills install --codex        # OpenAI Codex CLI only
npx birdeye-skills install --bundle       # ChatGPT / OpenAI API (prompt file)

Shell script (no Node.js required)

git clone https://github.com/birdeye-so/birdeye-skills.git
cd birdeye-skills

./install.sh                                    # All platforms
./install.sh --claude                           # Claude Code only
./install.sh --cursor                           # Cursor
./install.sh --codex --project /path/to/app     # Codex AGENTS.md
./install.sh --bundle                           # Bundled prompt file

API Key & MCP

API Key

Get a free key at https://bds.birdeye.so → Usages → Security → Generate key.

The CLI stores the key in your MCP config so skills can read it automatically:

npx birdeye-skills install --api-key YOUR_KEY   # set on first install
npx birdeye-skills install --api-key NEW_KEY    # update any time

How API calls work

Skills call the Birdeye REST API directly — no MCP hop required. The API key is read from ~/.claude/settings.json and used in curl/fetch:

curl -sS "https://public-api.birdeye.so/defi/price?address=<TOKEN>" \
  -H "X-API-KEY: YOUR_KEY" \
  -H "x-chain: solana" \
  -H "accept: application/json"

Official Birdeye MCP (optional)

The official remote MCP (mcp.birdeye.so) is a proxy to the same REST API — it is not required when using these skills. Auto-configured by the CLI for environments that prefer MCP tools over direct curl:

{
  "mcpServers": {
    "birdeye-mcp": {
      "command": "npx",
      "args": ["-y", "[email protected]", "https://mcp.birdeye.so/mcp", "--header", "x-api-key:YOUR_KEY"]
    }
  }
}

Docs Companion MCP (endpoint discovery)

Local MCP server powered by the Birdeye OpenAPI spec, cached and refreshed every 24h. Auto-installed alongside skills. Useful when you need to look up an endpoint not covered in skill files.

{
  "mcpServers": {
    "birdeye-api-docs": {
      "command": "node",
      "args": ["/path/to/birdeye-skills/birdeye-mcp/index.js"]
    }
  }
}

| Tool | Purpose | |---|---| | birdeye_list_endpoints | List all endpoints grouped by domain | | birdeye_search_endpoints | Search endpoints by keyword | | birdeye_get_endpoint_info | Get params, types, required flags, and docs URL |

Usage

Once installed, just describe what you want — the router dispatches automatically:

"Get the current price of SOL"
→ birdeye-router → birdeye-market-data → GET /defi/price

"Find trending tokens on Solana"
→ birdeye-router → birdeye-token-discovery → GET /defi/token_trending

"Analyze this token for security risks: <address>"
→ birdeye-router → birdeye-security-analysis → GET /defi/token_security

"Build a token screener with smart money signals"
→ birdeye-router → birdeye-token-screener-builder (workflow)

"Generate a research report for this token"
→ birdeye-router → birdeye-research-assistant (workflow)

Updating Skills

Skills have a 7-day TTL. The CLI checks ~/.birdeye/skills-config.json and prompts you to update when skills are stale.

# Update to latest
npx birdeye-skills@latest install

# Check version and TTL status
npx birdeye-skills check

# List installed skills
npx birdeye-skills list

# Uninstall everything
npx birdeye-skills uninstall

Architecture

Infrastructure
└── birdeye-indexer                   Canonical endpoint dictionary + shared policies

Tier 1: Router
└── birdeye-router                    Intent dispatcher

Tier 2: Domain Skills (API-focused)
├── birdeye-market-data               Price, OHLCV, stats, historical data
├── birdeye-token-discovery           Token lists, search, trending, meme
├── birdeye-transaction-flow          Trades, transfers, balance changes
├── birdeye-wallet-intelligence       Portfolio, PnL, top traders
├── birdeye-holder-analysis           Holder distribution, concentration
├── birdeye-security-analysis         Token security, risk assessment
├── birdeye-smart-money               Smart money tracking, signals
└── birdeye-realtime-streams          WebSocket subscriptions (9 channels)

Tier 3: Workflow Skills (Multi-domain)
├── birdeye-wallet-dashboard-builder  Portfolio monitors, whale trackers
├── birdeye-token-screener-builder    Token screeners, alpha finders
├── birdeye-alert-agent               Real-time alerting pipelines
└── birdeye-research-assistant        Research reports, token briefs

API Group → Skill Mapping

| API Group | Skill | |---|---| | Price & OHLCV | birdeye-market-data | | Stats | birdeye-market-data | | Alltime & History | birdeye-market-data | | Token/Market List | birdeye-token-discovery | | Creation & Trending | birdeye-token-discovery | | Meme | birdeye-token-discovery | | Search & Utils | birdeye-token-discovery | | Transactions | birdeye-transaction-flow | | Balance & Transfer | birdeye-transaction-flow | | Blockchain | birdeye-transaction-flow | | Wallet, Networth & PnL | birdeye-wallet-intelligence | | Holder | birdeye-holder-analysis | | Security | birdeye-security-analysis | | Smart Money | birdeye-smart-money | | WebSockets (9 channels) | birdeye-realtime-streams |

Supported Chains

Solana, Ethereum, BSC, Arbitrum, Optimism, Polygon, Avalanche, Base, zkSync, Sui

Cross-Platform Support

| Platform | Command | |---|---| | Claude Code | npx birdeye-skills install --claude → ~/.claude/skills/ | | Cursor | npx birdeye-skills install --cursor → ~/.cursor/rules/ | | OpenAI Codex CLI | npx birdeye-skills install --codex → ~/.codex/AGENTS.md | | ChatGPT / OpenAI API | npx birdeye-skills install --bundle → birdeye-system-prompt.md |

CLI Reference

npx birdeye-skills <command> [options]

Commands:
  install               Install all skills for all platforms (default)
  install --claude      Claude Code only  (~/.claude/skills/)
  install --cursor      Cursor only       (~/.cursor/rules/)
  install --codex       Codex CLI only    (~/.codex/AGENTS.md)
  install --bundle      ChatGPT / OpenAI API (prompt file)
  install --api-key KEY Set/update API key in MCP config

  uninstall             Remove all installed skills and config
  update                Update installed skills to latest version
  check                 Check version and update status
  list                  Show installed skills and versions
  api <sub>             Call Birdeye API directly

API sub-commands:
  api price        <token>           Token price
  api overview     <token>           Full token overview
  api trending     [--limit N]       Trending tokens
  api security     <token>           Security analysis
  api search       <query>           Search tokens by name/symbol
  api holders      <token>           Top token holders (Solana only)
  api wallet       <address>         Wallet portfolio (Solana only)
  api trades       <token>           Recent trades
  api chart        <token>           OHLCV v3 chart data
  api chart-pair   <pair>            OHLCV v3 by pair address
  api history-price <token>          Historical price line
  api smart-money  [--interval 1d]   Smart money list (Solana only)
  api gainers      [--type today]    Top PnL gainers
  api losers       [--type today]    Top PnL losers
  api top-traders  <token>           Top traders by volume

  Options: --chain  --limit  --interval  --from  --to  --type  --sort-by

Examples:
  npx birdeye-skills install                    # All platforms
  npx birdeye-skills install --claude           # Claude only
  npx birdeye-skills install --api-key YOUR_KEY # With API key
  npx birdeye-skills install --bundle           # ChatGPT prompt file
  npx birdeye-skills@latest install             # Update to latest version
  npx birdeye-skills uninstall                  # Remove everything
  npx birdeye-skills api price So11111111111111111111111111111111111111112
  npx birdeye-skills api trending --limit 10
  npx birdeye-skills api chart <token> --interval 4H
  npx birdeye-skills api smart-money --interval 7d --limit 10
  npx birdeye-skills api gainers --type today
  npx birdeye-skills api overview <token> --chain ethereum

Repo Structure

birdeye-skills/
  skills/
    birdeye-indexer/
      SKILL.md
      references/
        canonical-endpoint-dictionary.md  # Ground truth for all endpoints
        session-preflight.md              # Auth, API key location, rate limits
        error-handling.md
        pagination.md
        wss-policy.md
    birdeye-router/
      SKILL.md
      references/                         # Redirect stubs → birdeye-indexer
    birdeye-market-data/
      SKILL.md
      references/
        operation-map.md                  # Endpoint details + curl examples
        request-templates.md
        endpoint-playbook.md
        caveats.md
    ... (8 more domain skills + 4 workflow skills)
  bin/
    cli.js                                # npm CLI
  birdeye-mcp/
    index.js                              # Fallback MCP server (OpenAPI-powered)
  install.sh                              # Shell installer (no Node.js required)
  package.json

Rate Limits

| Tier | Rate Limit | WebSocket | |---|---|---| | Standard | 1 rps | No | | Lite / Starter | 15 rps | No | | Premium | 50 rps / 1000 rpm | No | | Business | 100 rps / 1500 rpm | Yes | | Enterprise | Custom | Yes |

Wallet API (/wallet/v2/*, /v1/wallet/*): 30 RPS burst / 150 RPM sustained, on all tiers.

For Developers

git clone https://github.com/birdeye-so/birdeye-skills
cd birdeye-skills
npm install
npm link

# Now use the CLI anywhere
birdeye-skills install
birdeye-skills check

# When done
npm unlink -g birdeye-skills

Edit files under skills/ or bin/cli.js and re-run commands — no build step needed.