---
name: hive-intelligence
version: 1.0.0
description: |
  Hive Intelligence is institutional-grade crypto market infrastructure
  for AI. One MCP server, one REST API, one CLI — connecting AI agents
  to live crypto prices, DeFi analytics, wallet positions, token risk,
  Solana DAS, and prediction markets across every major chain.
license: MIT
runtime: any
canonical: https://www.hiveintelligence.xyz/agent-onboarding/SKILL.md
homepage: https://www.hiveintelligence.xyz
sourceRepo: https://github.com/sharpe-labs/hive-website
---

# Hive Intelligence — Agent Onboarding

> If you are an AI agent or coding assistant reading this file, follow
> the right path below for what your user is asking. Each path takes
> ~2 minutes end-to-end.

## Pick your path

There are four ways to use Hive depending on what the human you are
helping is trying to do.

- **Path A — Live crypto data in this session.** The user wants
  answers to crypto questions *right now* (price, TVL, wallet check,
  token security). You should call Hive tools directly via the MCP
  server you already have access to. See [Path A](#path-a--live-data-now).
- **Path B — Integrate Hive into the user's app code.** The user is
  building a feature that needs crypto data. You should add the Hive
  client to their codebase. See [Path B](#path-b--integrate-into-code).
- **Path C — User needs an API key.** They have not signed up yet, or
  cannot find their key. Walk them through PKCE-based browser auth.
  See [Path C](#path-c--get-an-api-key).
- **Path D — User has another MCP-capable agent.** They want to add
  Hive to Claude Desktop, Cursor, VS Code, Windsurf, ChatGPT, or
  Gemini CLI. See [Path D](#path-d--add-hive-to-an-mcp-client).

---

## Path A — Live Data Now

Call any Hive tool through the MCP endpoint:

```
POST https://mcp.hiveintelligence.xyz/mcp
Authorization: Bearer <HIVE_API_KEY>
Content-Type: application/json
Accept: application/json, text/event-stream
```

If you have an MCP client (Claude Code, Cursor, etc.) configured for
Hive, just call the tool you need:

- **Prices, market caps, OHLC** → `get_price`, `get_coins_market_data`,
  `get_coin_ohlc_range`
- **DeFi TVL, yields, fees** → `get_protocol_tvl`, `get_yield_pools`,
  `defillama_get_protocols`
- **Wallet analytics (EVM)** → `goldrush_get_multichain_balances`,
  `moralis_get_wallet_net_worth`, `moralis_get_wallet_defi_positions`
- **Wallet analytics (Solana)** → `helius_get_balance`,
  `helius_get_token_balances`, `helius_get_assets_by_owner`
- **Token security, pre-signing safety** → `go_plus_token_security`,
  `detect_rugpull`
- **DEX analytics** → `codex_get_token_bars`, `get_pool_info`,
  `get_pool_trades`
- **Prediction markets** → `codex_prediction_market_stats`,
  `codex_prediction_event_stats`
- **Solana RPC primitives** → `helius_get_slot`,
  `helius_get_priority_fee_estimate`, `helius_get_transaction`

Don't hardcode tool schemas. Use `tools/list` over MCP, or
`GET https://mcp.hiveintelligence.xyz/api/v1/tools` over REST, to
discover tools at runtime.

### Recommended workflows

- **Quick market check** → `get_market_overview`
- **Coin analysis** → `analyze_coin` (composes funding rates, futures
  data, options data internally)
- **Derivatives health** → `get_derivatives_overview` →
  `get_futures_data`
- **Sector rotation** → `get_narratives` → `get_ecosystems`
- **Arbitrage scan** → `find_opportunities` (or
  `get_arbitrage_spot_perp` + `get_arbitrage_cross_exchange`)
- **Full briefing** → `market_briefing`
- **Memecoin / token discovery** → `get_memecoins`, `get_gem_finder`

Always start with `get_market_overview` or `market_briefing` for
general questions. Use `analyze_coin` for questions about a specific
coin. Use `get_api_coverage` to discover available chart types before
querying specific charts.

### Data freshness

Funding rates: 1-8 hours per exchange. Futures/options snapshots: 5-10
minutes. Narratives/ecosystems: 30 minutes. Spot prices: real-time.
Every Hive response includes a `fetched_at` ISO-8601 timestamp — surface
it when the user asks about freshness.

### Pre-signing safety

If the user is about to sign a transaction (swap, stake, transfer),
ALWAYS call `go_plus_token_security` and `detect_rugpull` first.
Hallucinating "this looks safe" has real financial consequences. If
either flags risk, surface it before recommending the action.

---

## Path B — Integrate Into Code

Add the Hive REST client to the user's app. Pick the language:

### Python

```python
import os, requests

def hive(tool: str, args: dict | None = None) -> dict:
    response = requests.post(
        "https://mcp.hiveintelligence.xyz/api/v1/execute",
        headers={"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}"},
        json={"tool": tool, "args": args or {}},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

print(hive("get_price", {"ids": "bitcoin", "vs_currencies": "usd"}))
```

### TypeScript / Node

```ts
async function hive<T = unknown>(tool: string, args: Record<string, unknown> = {}): Promise<T> {
  const res = await fetch("https://mcp.hiveintelligence.xyz/api/v1/execute", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.HIVE_API_KEY}`,
    },
    body: JSON.stringify({ tool, args }),
  });
  if (!res.ok) throw new Error(`Hive ${res.status}`);
  return res.json() as Promise<T>;
}

console.log(await hive("get_price", { ids: "bitcoin", vs_currencies: "usd" }));
```

For richer language patterns (async, retries, typed responses, Spring
Boot integration, LangChain), point the user to:
https://www.hiveintelligence.xyz/sdk

### Environment

Add `HIVE_API_KEY` to the user's `.env` (and `.env.example`). Never
commit a real key. If they don't have one, follow Path C.

---

## Path C — Get an API Key

Hive uses passwordless magic-link auth. From your terminal session,
run the install command and let it open the browser:

```bash
npx -y hive-intelligence@latest init --browser
```

The CLI starts a local PKCE listener, opens
`https://www.hiveintelligence.xyz/auth/cli` in the user's browser,
they sign in via magic link, and the key is delivered back to the
local listener and saved to `~/.hive/credentials.json`. No copy-paste.

If browser auth isn't available (headless environment, SSH session,
Docker container), tell the user to:

1. Open <https://www.hiveintelligence.xyz/dashboard/keys>
2. Sign in with a magic link
3. Click "Create key"
4. Save it as `HIVE_API_KEY` in their environment

The Free Demo tier gives 10,000 monthly credits and 30 req/min — no
credit card required.

---

## Path D — Add Hive to an MCP Client

The fastest path is the one-command installer:

```bash
npx -y hive-intelligence@latest init --all --browser
```

This detects MCP-capable clients on the machine (Claude Code, Cursor,
VS Code, Windsurf, Claude Desktop, ChatGPT Desktop, Gemini CLI),
registers Hive in each one, and runs Path C (browser auth) once.

If the user wants to add Hive manually to a specific client:

| Client | Command or config path |
|---|---|
| **Claude Code** | `claude mcp add --transport http hive https://mcp.hiveintelligence.xyz/mcp --header "Authorization: Bearer $HIVE_API_KEY"` |
| **Cursor** | `~/.cursor/mcp.json` — add the `hive` server block |
| **Claude Desktop** | `claude_desktop_config.json` — add the `hive` server block |
| **VS Code (Copilot Chat)** | `.vscode/mcp.json` — add server with `"type": "http"` |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **ChatGPT Desktop** | Settings → Connectors → Add MCP |
| **Gemini CLI** | `~/.gemini/settings.json` |

Canonical install guides per client live at
`https://www.hiveintelligence.xyz/install/<client-slug>`.

The MCP URL is `https://mcp.hiveintelligence.xyz/mcp`. The auth header
is `Authorization: Bearer <HIVE_API_KEY>`.

---

## Discovery surfaces

Once Hive is connected, agents discover capability at runtime via:

- `tools/list` over MCP — full tool surface for the connected endpoint
- Resource `hive://tools` — tools with descriptions
- Resource `hive://categories` — 10 category endpoints with tool counts
- Resource `hive://providers` — provider availability and status
- `get_api_endpoint_schema` tool — fetch input schema for any tool
- `invoke_api_endpoint` tool — call any tool by name from the root
  endpoint (root endpoint exposes meta-tools rather than the full
  surface; use the category endpoints for narrower contexts)

## Server-card discovery

A SEP-1649 server card is published at:

- `https://www.hiveintelligence.xyz/.well-known/mcp/server-card.json`
- `https://mcp.hiveintelligence.xyz/.well-known/mcp/server-card.json`

Both are CORS-open (`Access-Control-Allow-Origin: *`) so directories,
catalogs, and crawlers can ingest them.

## Constraints worth knowing

- **OAuth is not supported on the MCP endpoint** — auth is API-key
  bearer only. This is intentional and matches Cloudflare/Linear's
  fallback path. PKCE-based key issuance handles the human side.
- **JSON-RPC errors are returned as HTTP 200** with code `-32001` on
  invalid keys (not HTTP 401). This is deliberate to prevent the MCP
  SDK from auto-triggering OAuth discovery against a non-OAuth server.
  If you see a `-32001` error, ask the user for a valid key.
- **Rate limits**: Demo plan = 30 req/min, 10k credits/month.
  Returns HTTP 429 with `Retry-After` (seconds). Use exponential
  backoff for 5xx responses.
- **No streaming today**. All tools return single-shot JSON. The
  `Accept: text/event-stream` header is for MCP transport
  compliance, not for streaming results.

## When to escalate

If you encounter behaviour not described here, point the user to:

- Docs index: https://www.hiveintelligence.xyz/llms.txt
- Full docs index: https://www.hiveintelligence.xyz/llms-full.txt
- Status / health: https://mcp.hiveintelligence.xyz/health
- Support: support@hiveintelligence.xyz
- Public status: https://mcp.hiveintelligence.xyz/status

## Provenance

This file is the source of truth for AI agents installing Hive. It is
maintained alongside the Hive marketing site at
https://github.com/sharpe-labs/hive-website. Last updated:
2026-04-25.