messari · ryansann · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026
diff --git a/README.md b/README.md
@@ -1,50 +1,24 @@
 # Messari Agent Skills
 
-Crypto intelligence for AI agents — MCP, REST API, and agent-native skill files for [Messari](https://messari.io).
+This repository contains [Claude](https://claude.ai) and [OpenClaw](https://openclaw.ai) skill files that wrap the full [Messari REST API](https://docs.messari.io) — giving AI agents access to crypto market data, on-chain metrics, sentiment, news, research, and more across 34,000+ assets.
 
-## For AI Agents
+For AI-powered answers that synthesize across Messari's entire data warehouse, use the [Messari MCP Server](https://docs.messari.io/mcp-server/hosted).
 
-Point your agent at [`SKILL.md`](./SKILL.md) for self-contained integration instructions — all endpoints, authentication, routing logic, and examples in one file.
+## Getting Started
 
-**Raw URL:** `https://raw.githubusercontent.com/messari/skills/master/SKILL.md`
+### 1. Get an API key
 
-## What's Here
-
-### [Messari Hosted MCP Server](https://docs.messari.io/mcp-server/hosted)
-
-Messari's hosted MCP server. Gives any MCP-compatible AI client direct access to Messari's data stack:
-
-- **MessariAI** — Integrate with MessariAI to unlock all of our AI capabilities
-- **Asset & Market Data** — Market data such as price, trading volume and marketcap for over 40,000 assets
-- **Signals** — Track social data and narratives including mindshare and sentiment across individual crypto projects, or at the sector/sub-sector level
-- **News** — Aggregated news from 500+ sources including headlines, links and summaries, with assets tagged per article
-- **Research** — Access to Messari's Protocol Reporting Research
-- **Stablecoins** — Onchain data for 30+ stablecoins such as USDT, USDC and DAI, including stablecoin marketcap, active addresses, transfers, transaction volume and more
-- **Networks** — Onchain data for 25+ Layer-1s and Layer-2s such as Ethereum and Solana, including transaction fees, active addresses, and more
-- **Protocols** — Onchain data for 200+ protocols such as Uniswap and Aave, including Total Value Locked, active addresses, deposits/borrows, trading volume, and more
-- **Exchanges** — Spot volumes, futures volume and futures open interest across cryptocurrency exchanges
-- **Token Unlocks** — Monitor token vesting schedules, upcoming unlock events, and token allocation details for over 200 crypto projects
-- **Fundraising** — Crypto's biggest fundraising database for funding rounds, M&A deals, and investors
-- **Intel** — Real-time onchain and offchain event monitoring with human curated summaries
-- **Topics** — Topic-based content aggregation and trending narrative tracking
-
-Full documentation: **[docs.messari.io/mcp-server/hosted](https://docs.messari.io/mcp-server/hosted)**
-
-### [`openclaw-skill/`](./openclaw-skill/)
-
-An [OpenClaw](https://openclaw.ai) / [ClawHub](https://clawhub.ai) skill that wraps Messari's REST API directly. OpenClaw does not natively support MCP, so this skill provides endpoint routing, authentication, and API reference documentation for standard HTTP requests.
-
-## Quick Start
+Sign up at [messari.io](https://messari.io) and get an [API key](https://messari.io/api).
 
-### 1. Get a Messari account
+### 2. Choose your integration
 
-Sign up at [messari.io](https://messari.io) and get an [API key](https://messari.io/api).
+#### MCP Server (Recommended for AI-powered answers)
 
-### 2. Set up your client
+The Messari MCP Server connects any MCP-compatible client to Messari's data stack, including MessariAI for synthesized, citation-backed responses.
 
-#### Claude / Claude Code
+**Server URL:** `https://mcp.messari.io/mcp`
 
-Run from your terminal:
+**Claude / Claude Code:**
 
 ```bash
 claude mcp add --transport http --scope user messari https://mcp.messari.io/mcp
@@ -62,7 +36,7 @@ Or add to your project's `.mcp.json`:
 }
 ```
 
-#### Codex
+**Codex:**
 
 Add to `~/.codex/config.toml`:
 
@@ -71,9 +45,9 @@ Add to `~/.codex/config.toml`:
 url = "https://mcp.messari.io/mcp"
 ```
 
-#### Cursor
+**Cursor:**
 
-Add to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):
+Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -85,39 +59,64 @@ Add to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):
 }
 ```
 
-#### OpenClaw
+Full MCP documentation: [docs.messari.io/mcp-server/hosted](https://docs.messari.io/mcp-server/hosted)
 
-OpenClaw does not support MCP. Install the skill instead:
+#### Skills (Direct REST API access)
+
+These skills teach your agent to call Messari's REST API directly — useful when your client doesn't support MCP, or when you want full control over which endpoints are called.
+
+**Claude / Claude Code:**
+
+Point your agent at the skill file:
+
+`https://raw.githubusercontent.com/messari/skills/main/claude/messari-api/SKILL.md`
+
+Or see [`claude/messari-api/`](./claude/messari-api/) for the full skill directory.
+
+**OpenClaw / ClawHub:**
 
 ```bash
-clawhub install messari/messari-crypto
+clawhub install messari/messari-api
 ```
 
-The skill calls `https://api.messari.io` directly with the `x-messari-api-key` header. See [`openclaw-skill/`](./openclaw-skill/) for details.
+Or see [`openclaw/messari-api/`](./openclaw/messari-api/) for the full skill directory.
+
+## API Coverage
+
+Both skills provide routing, authentication, and endpoint reference for these Messari API services:
+
+- **AI** — Chat completions and deep research reports across Messari's crypto data warehouse
+- **Metrics** — Price, volume, market cap, and fundamentals for 34,000+ assets
+- **Signal** — Sentiment, mindshare, and trending narrative tracking
+- **News** — Real-time aggregated news from 500+ sources
+- **Research** — Institutional-grade analyst reports and sector deep dives
+- **Stablecoins** — On-chain metrics and per-chain breakdowns for 25+ stablecoins
+- **Exchanges** — Volume and metrics across 210+ exchanges
+- **Networks** — L1/L2 blockchain network activity, fees, active addresses
+- **Protocols** — DeFi protocol metrics (DEXs, lending, liquid staking, bridges)
+- **Token Unlocks** — Vesting schedules and upcoming unlock events
+- **Fundraising** — Funding rounds, investors, funds, M&A activity
+- **Intel** — Governance events, protocol upgrades, project milestones
+- **Topics** — Trending topic classification and timeseries
+- **X-Users** — Crypto X/Twitter user metrics and influence tracking
+- **Bulk Data** — Large-scale CSV/JSONL dataset downloads
 
 ### 3. Start asking questions
 
 ```
 "Which assets over $1B marketcap outperformed Bitcoin over the last 3 months?"
 "What are some upcoming token unlock events this month?"
 "Give me the 10 most recent fundraising rounds in the AI and compute sectors."
-"What is the percent change in price for Aave and Maker over the last month?"
 "What are the latest headlines related to crypto regulation?"
-"What are some recent developments in the DePin sector?"
 "Which investor has been the most active in seed rounds over the last year?"
-"What is decentralized compute and why it is important to AI?"
 "What were the top events for the AAVE protocol during the last quarter?"
-"Give me the latest ecosystem map of Solana."
-"What is the average DexVolume and total fee revenue last month for Ethereum, Solana and Base?"
-"Tell me about the recent investments from a16z crypto."
-"What are some trends that Messari has written about recently?"
-"Has the GMX protocol undergone any audits?"
-"Compare and contrast the native asset functions of BitTensor vs Render."
+"Compare TVL across top lending protocols."
+"What are the trending crypto narratives right now?"
 ```
 
 ## Links
 
 - [MCP Server Documentation](https://docs.messari.io/mcp-server/hosted)
-- [Messari API](https://messari.io/api)
+- [Messari API Documentation](https://docs.messari.io)
+- [Messari API Key](https://messari.io/api)
 - [Messari](https://messari.io)
-- [OpenClaw Skill on ClawHub](https://clawhub.ai/messari/messari-crypto)
diff --git a/claude/messari-api/SKILL.md b/claude/messari-api/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: messari-api
+description: >
+  Queries Messari's REST API for crypto market data across 14 services: AI chat completions,
+  asset metrics and prices, social sentiment and mindshare, news, institutional research,
+  stablecoins, exchanges, L1/L2 networks, DeFi protocols, token unlocks, fundraising rounds,
+  governance intel, trending topics, and X/Twitter user analytics. Covers 34,000+ assets and
+  210+ exchanges. Use when answering questions about crypto markets, token analysis, sentiment,
+  on-chain metrics, protocol data, fundraising, or any blockchain data question.
+---
+
+# Messari REST API
+
+Crypto market intelligence across 14 data services via Messari's REST API.
+
+## Authentication
+
+Every request requires the `x-messari-api-key` header. Obtain a key at [messari.io/api](https://messari.io/api). If no key is available, ask the user to provide one before making requests.
+
+**Base URL:** `https://api.messari.io`
+
+```
+x-messari-api-key: <API_KEY>
+```
+
+All endpoints accept and return JSON. Use `Content-Type: application/json` for POST requests.
+
+## Service Routing
+
+| User is asking about... | Route to | Base path |
+|---|---|---|
+| General crypto question, synthesis, "what do you think about X" | **AI** | `/ai/` |
+| In-depth research report with citations (async, 5-10 min) | **AI** (Deep Research) | `/ai/v1/deep-research` |
+| Price, volume, market cap, ROI, ATH, performance comparison | **Metrics** | `/metrics/v2/` |
+| Sentiment, mindshare, trending tokens, social buzz | **Signal** | `/signal/v1/` |
+| Headlines, recent events, breaking news | **News** | `/news/v1/` |
+| Analyst reports, deep dives, sector overviews | **Research** | `/research/v1/` |
+| Stablecoin supply, flows, chain breakdowns | **Stablecoins** | `/stablecoins/v2/` |
+| Exchange volumes, exchange comparisons | **Exchanges** | `/exchanges/v2/` |
+| L1/L2 network activity, fees, active addresses | **Networks** | `/networks/v2/` |
+| DeFi protocols, TVL, lending, DEX volume | **Protocols** | `/protocols/v2/` |
+| Token unlocks, vesting schedules | **Token Unlocks** | `/token-unlocks/v1/` |
+| Fundraising rounds, investors, VC activity, M&A | **Fundraising** | `/fundraising/v1/` |
+| Governance events, protocol upgrades | **Intel** | `/intel/v1/` |
+| Trending narratives, topic momentum | **Topics** | `/topics/v1/` |
+| Crypto influencers, X/Twitter accounts | **X-Users** | `/signal/v1/x-users/` |
+
+For full endpoint details, parameters, and examples, see [references/endpoints.md](references/endpoints.md).
+
+## Multi-Service Queries
+
+Many questions benefit from combining services. Follow this workflow:
+
+```
+Multi-Service Query Checklist:
+- [ ] Identify which services are relevant to the question
+- [ ] Query each service for its piece of the answer
+- [ ] If any request fails, retry once then note the gap
+- [ ] Synthesize results into a unified answer
+- [ ] Optionally route through AI service for final synthesis
+```
+
+**Examples:**
+
+- **"Is SOL overvalued?"** → Metrics (price, fundamentals) + Signal (sentiment) + Token Unlocks (supply pressure) + AI (synthesize)
+- **"Due diligence on Eigen Layer"** → Research (reports) + Metrics (fundamentals) + Fundraising (investors) + Intel (governance) + AI (synthesize)
+- **"Trending narratives this week"** → Topics (trending classes) + Signal (mindshare gainers) + News (related headlines)
+- **"Compare TVL across lending protocols"** → Protocols/lending (metrics) + Networks (chain context)
+
+When in doubt, start with the **AI** service — it draws from all other sources and provides the broadest context.
+
+## Common Parameters
+
+Most GET endpoints share these query parameters:
+
+- `limit`, `page` — pagination
+- `start`, `end` — date range (ISO 8601)
+- Asset filters: `assetSlugs` (comma-separated slugs like `bitcoin,ethereum`) or `assetIds`
+- `metrics` — specific metrics to return
+- `interval` — timeseries interval (`1d`, `1w`)
+
+## Quick Examples
+
+### AI Chat Completion
+
+```bash
+curl -X POST "https://api.messari.io/ai/v1/chat/completions" \
+  -H "x-messari-api-key: $MESSARI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"messages": [{"role": "user", "content": "What is the bull case for ETH right now?"}]}'
+```
+
+### Asset Metrics
+
+```bash
+curl "https://api.messari.io/metrics/v2/assets?assetSlugs=bitcoin,ethereum" \
+  -H "x-messari-api-key: $MESSARI_API_KEY"
+```
+
+### Signal Mindshare Gainers
+
+```bash
+curl "https://api.messari.io/signal/v1/assets/gainers-losers?type=mindshare&limit=10" \
+  -H "x-messari-api-key: $MESSARI_API_KEY"
+```
+
+### News Feed
+
+```bash
+curl "https://api.messari.io/news/v1/news/feed?limit=20" \
+  -H "x-messari-api-key: $MESSARI_API_KEY"
+```
+
+## Notes
+
+- The **AI** service endpoints (chat completions and deep research) require Messari AI credits (a paid usage quota managed at [messari.io/account](https://messari.io/account)). All other endpoints work with just the API key.
+- Deep Research jobs are asynchronous — submit a query, then poll for results (5-10 min). Each report costs 500 credits.