hive-intelligence

v1.7.2

Published

5 days ago

Evidence-backed crypto due diligence for AI agents, with sources, freshness, and a runtime receipt on every call.

Hive Intelligence

One connection for evidence-backed crypto due diligence. Every Hive-backed answer carries sources, freshness, and a runtime receipt.

Hive gives Claude Code, Cursor, VS Code, OpenAI Responses API, Gemini CLI, Codex, and supported custom agents one compact way to discover and call live crypto data. Agents route through task toolsets, inspect schemas before execution, keep calls bounded, and return provider provenance plus runtime status instead of browsing a wall of raw endpoints. Hive is shipped as a hosted MCP server, local stdio runtime, CLI, and REST API.

npx -y -p hive-intelligence@latest hive init --all --skip-verify

Use the hosted MCP when you want Hive to run auth, rate limits, provider infrastructure, and runtime status. Use local stdio when you want desktop client setup, self-hosting, or provider-key experiments.

What You Get

Evidence-backed workflows for token diligence, wallet investigation, security checks, market research, DeFi, DEX pools, NFTs, Solana, RWA perps, and durable monitoring.
A compact eight-tool root MCP workflow surface — three direct hero tools (get_token_price, check_token_safety, get_wallet_portfolio) plus the five-tool discovery loop, so agents can route before they call.
Task toolsets for market research, token diligence, wallet investigation, security checks, DEX pool analysis, DeFi research, NFT research, Solana analysis, network infrastructure, RWA perp analysis, and stateful monitoring.
CLI commands for auth, client setup, tool discovery, schema inspection, direct execution, diagnostics, aliases, polling, and config generation.
Runtime resources for providers, categories, full tool catalog, task toolsets, canaries, skills, and status metadata.
Bundled agent skills that teach assistants the right Hive workflow: discovery -> schema lookup -> bounded execution -> evidence receipt.
A broad provider catalog remains available behind discovery for agents that need a long-tail endpoint. The current catalog contains 546 tools, but that coverage is not the primary product contract.

Quickstart

Requirements:

Node.js 22.12+ (Node.js 24 LTS recommended)
npm
Browser authorization for interactive hosted MCP after OAuth activation, or a Hive API key for direct CLI, REST, and headless agents

For the fastest proof before setup, run the fixed, read-only public demo. It requires no account and returns the same source/freshness/runtime-receipt shape used by authenticated calls:

https://www.hiveintelligence.xyz/playground

For direct CLI or headless REST access, create a key:

https://www.hiveintelligence.xyz/login?next=/dashboard/keys

After hosted OAuth activation, configure OAuth-capable AI clients without putting a secret in their config:

npx -y -p hive-intelligence@latest hive init --all --skip-verify

Add --browser to sign the CLI in during the same run; --skip-verify keeps the command non-interactive so agents and CI can run it.

For automation, exit code 0 means every detected programmable client, requested skill install, and enabled readiness check completed; partial setup returns non-zero and is detailed in --json output.

For direct CLI or headless REST use, sign in separately:

npx -y -p hive-intelligence@latest hive auth login

Make a first successful call:

npx -y -p hive-intelligence@latest hive market price --ids bitcoin --vs usd --json

Expected output shape:

{
  "ok": true,
  "data": {
    "bitcoin": {
      "usd": 0
    }
  },
  "meta": {
    "provider": "CoinGecko",
    "runtime_status": "ok",
    "fetched_at": "2026-07-11T12:00:00.000Z",
    "observed_at": "2026-07-11T11:59:59.900Z",
    "cache_age_ms": 100,
    "source": "live",
    "receipt_id": "00000000-0000-4000-8000-000000000000",
    "receipt_version": "1.0",
    "server_version": "1.7.2",
    "build_sha": null,
    "digest_algorithm": "sha256",
    "input_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "result_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "duration_ms": 0
  }
}

Use --json for scripts and agents. Use --pretty for human-readable output.

Connect Hosted MCP

After hosted OAuth activation, use secret-free config prefill for OAuth-capable clients. Review the public URL in the client, approve it, and complete Hive authorization in the browser. These links never contain an API key:

Use these native OAuth paths only after the hosted protected-resource metadata reports OAuth enabled. Until that deployment gate is open, use the API-key fallback from a trusted client/backend; do not paste a key into an install URL.

The setup pages check the live OAuth and release contract before exposing a native install action, so a stale deployment cannot masquerade as a successful one-click install.

Hosted MCP URL:

https://mcp.hiveintelligence.xyz/mcp

Claude Code:

claude mcp add --transport http --scope user hive https://mcp.hiveintelligence.xyz/mcp

OpenAI Codex:

codex mcp add hive --url https://mcp.hiveintelligence.xyz/mcp
codex mcp login hive

Generic OAuth-capable Streamable HTTP config:

{
  "mcpServers": {
    "hive": {
      "url": "https://mcp.hiveintelligence.xyz/mcp"
    }
  }
}

For headless automation that cannot open a browser, add Authorization: Bearer $HIVE_API_KEY from secret storage instead.

Client Compatibility

| Client | Hosted HTTP MCP | Hosted auth | Local stdio | Recommended setup | | ------------------------------------- | ---------------- | ----------------------------------- | ----------- | ---------------------------------------------------------------------------- | | Claude Code | Yes | OAuth or API-key fallback | Yes | claude mcp add --transport http --scope user hive https://mcp.hiveintelligence.xyz/mcp | | Cursor | Yes | OAuth or API-key fallback | Yes | Secret-free config prefill above | | VS Code | Yes | OAuth or API-key fallback | Yes | Secret-free config prefill above | | Windsurf / Devin Desktop | Yes | OAuth or API-key fallback | Yes | Add the hosted URL in MCP settings | | Gemini CLI | Yes | OAuth or API-key fallback | Yes | gemini mcp add hive https://mcp.hiveintelligence.xyz/mcp --transport http --scope user | | Codex | Yes | OAuth or API-key fallback | Yes | codex mcp add hive --url https://mcp.hiveintelligence.xyz/mcp, then codex mcp login hive | | OpenAI Responses API | Yes | API-key authorization token | No | Use a server-side remote MCP tools entry | | ChatGPT custom apps | Deployment-gated | OAuth 2.1 | No | Direct after hosted OAuth + consent activation; use Responses API until then | | Claude custom connectors/directory | Deployment-gated | OAuth 2.1 | No | Direct after hosted OAuth + consent activation | | Grok custom connectors | Deployment-gated | OAuth 2.1 | No | Add the hosted URL at grok.com/connectors |

Header-based API key auth works today for clients or API surfaces that support custom headers or authorization tokens. The server also includes a fail-closed OAuth 2.1 foundation with PKCE, protected-resource discovery, CIMD/DCR, rotating refresh tokens, and revocation. It is disabled until the hosted deployment and the Hive consent page are configured. See MCP OAuth 2.1 operations.

Codex versions that do not show --url in codex mcp add --help must be updated before the remote-MCP command will work. Run codex update when the installed release supports self-update; otherwise update it through the installer or package manager you originally used. Public OpenAI/Codex and Cursor plugin artifacts are staged in the public SDK, but marketplace installs are not advertised as live until external approval and clean-profile verification. See the distribution runbook.

Run Local stdio MCP

Use local stdio when you want a self-hosted MCP process, local desktop config, or your own upstream provider keys.

{
  "mcpServers": {
    "hive-local": {
      "command": "npx",
      "args": ["-y", "-p", "hive-intelligence@latest", "hive"],
      "env": {
        "COINGECKO_PRO_API_KEY": "optional",
        "ALCHEMY_API_KEY": "optional",
        "HELIUS_API_KEY": "optional",
        "MORALIS_API_KEY": "optional"
      }
    }
  }
}

Running hive with no subcommand starts the stdio MCP server. hive-mcp remains available as a backward-compatible binary alias.

Staying Current

The hosted MCP (https://mcp.hiveintelligence.xyz/mcp) is managed by Hive. Local stdio installs are pinned to whatever your client last fetched, so:

Keep hive-intelligence@latest in your client config (as shown above) so each host restart re-resolves the newest version.
Run hive upgrade to update a global install and clear the npx cache, then restart your MCP client to load it:

npx -y -p hive-intelligence@latest hive upgrade

hive checks npm for newer versions once a day and surfaces the result through hive doctor and the MCP server instructions, so your agent can prompt you when an update is available. Set HIVE_NO_UPDATE_CHECK=1 to disable the check.

Use The CLI

Search the catalog:

npx -y -p hive-intelligence@latest hive tools search "token risk"

Inspect a schema before execution:

npx -y -p hive-intelligence@latest hive tools info get_price

Call a tool from the terminal:

npx -y -p hive-intelligence@latest hive market price --ids bitcoin --vs usd --json

Check setup and provider status:

npx -y -p hive-intelligence@latest hive doctor
npx -y -p hive-intelligence@latest hive status

Generate client config:

npx -y -p hive-intelligence@latest hive config claude-code
npx -y -p hive-intelligence@latest hive config codex
npx -y -p hive-intelligence@latest hive config cursor
npx -y -p hive-intelligence@latest hive config vscode
npx -y -p hive-intelligence@latest hive config grok

How Agents Should Use Hive

Hive is designed for retrieval-led agent work:

Call search_tools or read the compact hive://toolsets index. Search returns at most three compact workflow matches by default; use its cursors instead of loading the entire catalog.
Load one exact workflow with hive://toolsets/{id} or select the compact matching routes[] entry returned by search_tools. Choose the route whose trigger/question matches the user's decision, preserve its route_id, and follow its ordered primary calls, per-call fallback conditions, four-call budget, and stop condition. The broad coverageCatalog is capability coverage, not an execution plan.
Inspect exact parameters and the endpoint's operation for every selected route step with get_api_endpoint_schema or hive tools info.
Execute reads through invoke_api_endpoint. For a Hive-native state change, obtain explicit user approval and use invoke_stateful_endpoint; clients must not auto-approve that conservatively destructive router.
Copy each material call's server-returned _hive block into the workflow receipt, map each material claims[] entry to exact receipt IDs, account for each canonical coverage[] phase, include the selected route_id, then call validate_task_result before presenting a structured result. Validation checks route membership and order, conditional fallback use, call budget, structure, and consistency; it does not make an invented receipt authentic.
Stop when the decision is answerable, a material gap cannot be resolved, or the workflow budget is reached. Report partial evidence instead of silently expanding scope.

search_tools, get_api_endpoint_schema, validate_task_result, MCP tools/list, and resource reads cost zero Hive credits. Material endpoint executions cost one credit each.

Freshness has two layers. _hive.observed_at is when Hive first observed the response, or the original cache-population time on a cache hit; cache_age_ms: 0 means newly retrieved by Hive, not necessarily that the upstream datum is current. Use a provider timestamp, block, slot, transaction, or candle close for source recency. If the provider supplies none, report upstream recency as unknown.

The runtime receipt also includes server/build version plus SHA-256 input_digest and result_digest self-checks. The result check covers the canonical normalized returned payload with the top-level _hive block removed. They are not signatures and do not imply a retained receipt lookup.

This flow lets an agent answer questions like:

"Is this token safe to buy?"
"What changed in this wallet over the last week?"
"Compare Aave and Curve by TVL, fees, chains, and risk."
"Compare funding for a tokenized stock perp across the RWA venues."
"Show the best pools for this token and explain liquidity risk."
"Remember this wallet monitor and report when important activity changes."

MCP Contract

Root endpoint:

https://mcp.hiveintelligence.xyz/mcp

Local development endpoint:

http://localhost:8080/mcp

Root MCP tools:

search_tools
get_api_endpoint_schema
invoke_api_endpoint for read-only endpoints
invoke_stateful_endpoint for explicitly approved Hive state changes
validate_task_result for structural workflow-output validation

Stateful Monitoring And B2B State

Hive's stateful monitor tools let authenticated agents store durable crypto intelligence intent in Hive instead of relying on chat memory. Direct users get one default state subject per Hive account. B2B partners can use one Hive API key from a trusted backend adapter while isolating downstream customers by signed tenant/end-user subject headers.

The stateful surface includes monitor CRUD, stored run reads, observations, alerts, latest snapshots, memory facts, generated reports, and B2B subject admin tools. The scheduled worker runs wallet, token, protocol, market, watchlist digest, token discovery risk, and risk watch workflows. Inspect the exact endpoint schema first. Reads use invoke_api_endpoint; creates, updates, archives, remembers, forgets, and alert status changes require explicit user approval and use invoke_stateful_endpoint. See docs/DOCUMENTATION.md for the full monitor, subject-signing, worker, table, and smoke-test contract. The same 10-minute worker also persists current-build provider, MCP protocol, task, and workflow canary evidence in Redis for /api/health and /status; missing or stale evidence remains unknown. For partner products, use docs/B2B_PARTNER_ADOPTION.md as the implementation checklist.

TypeScript B2B adapters should use hive-mcp-client/b2b instead of hand-building subject headers or raw monitor calls. If npm returns 404, publish the client package with docs/MCP_CLIENT_RELEASE.md before partners depend on it:

import { createHiveB2BAdapter } from "hive-mcp-client/b2b";

const hive = await createHiveB2BAdapter({
  apiKey: process.env.HIVE_API_KEY!,
  subjectSigningSecret: process.env.HIVE_SUBJECT_SIGNING_SECRET!,
});

await hive.createWatchlistDigestMonitor(
  { tenantId: workspaceId, endUserId: userId },
  {
    name: "Daily portfolio brief",
    target: { wallets, tokens },
    cadence: "daily",
  },
);

Verify a B2B key and signed-subject isolation with:

curl https://mcp.hiveintelligence.xyz/api/v1/b2b/readiness \
  -H "Authorization: Bearer $HIVE_API_KEY"

HIVE_API_KEY="hive_live_..." \
HIVE_SUBJECT_SIGNING_SECRET="hive_subject_..." \
npm run smoke:b2b-partner

Discovery resources:

hive://providers
hive://categories
hive://tools
hive://toolsets
hive://toolsets/{id} for one exact workflow, output schema, and execution policy
hive://task-canaries
hive://skills
hive://skills/{name} for one complete procedural skill
hive://status

Reusable prompts:

analyze_token
compare_protocols
portfolio_audit

Category-scoped MCP endpoints remain available for clients that need direct tool lists:

/hive_market_data/mcp
/hive_onchain_dex/mcp
/hive_portfolio_wallet/mcp
/hive_token_contract/mcp
/hive_defi_protocol/mcp
/hive_nft_analytics/mcp
/hive_security_risk/mcp
/hive_network_infrastructure/mcp
/hive_search_discovery/mcp

Providers

| Provider | Coverage | Env var | | --------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Alchemy | EVM wallet, token, NFT, transfer, simulation, gas, Solana DAS/Photon, and RPC data | ALCHEMY_API_KEY | | CoinGecko | Prices, OHLC, trending, news, on-chain networks, and tokenized RWA markets | Optional COINGECKO_PRO_API_KEY or COINGECKO_DEMO_API_KEY | | DeFiLlama | TVL, yields, fees, bridges | Free | | CCXT | CEX data, funding rates, perpetuals | Free | | GoPlus | Token, wallet, NFT, approval, phishing, and dApp security | GOPLUS_APP_KEY or GOPLUS_API_KEY, plus GOPLUS_APP_SECRET | | Helius | Solana RPC, DAS, priority fees, wallet history, and Parsed Events | HELIUS_API_KEY | | Moralis | Wallet, token, NFT, PnL, DeFi positions | MORALIS_API_KEY | | Tenderly | EVM simulation, tracing, gas estimation, and read-only Node RPC | REST: TENDERLY_API_KEY + TENDERLY_ACCOUNT_SLUG + TENDERLY_PROJECT_SLUG; Node: TENDERLY_NODE_ACCESS_KEY or TENDERLY_GATEWAY_ACCESS_KEY | | Hyperliquid | Full /info surface: perp/spot markets, order books, user state, vaults, staking, borrow/lend, HIP-4 outcome markets | Free | | RWA Perps | Keyless five-venue fan-out for tokenized-asset perps (rwa_ tools): Hyperliquid HIP-3 builder dexes, Ostium, Avantis, Lighter, Extended | Free | | Hive Archive | Supabase-backed derivatives history (archive_ tools) served by Hive | None (Hive-hosted) | | Polymarket | Prediction markets: market and event search, market-implied odds, order books, odds history, wallet positions | Free (keyless) | | Alternative.me | Crypto Fear and Greed Index, current plus daily history | Free (keyless) | | Blockchain.com | Daily Bitcoin on-chain charts: hash rate, active addresses, transaction count | Free (keyless) | | Open Data Fetch | Allowlisted, size-capped access to long-tail public crypto APIs | Free |

Providers without configured keys remain discoverable and return classified runtime status such as missing_key, plan_required, rate_limited, degraded, or failing when execution is unavailable.

REST API

Use REST when your app does not speak MCP.

List tools:

curl -X GET "https://mcp.hiveintelligence.xyz/api/v1/tools?search=price&limit=20" \
  -H "Authorization: Bearer $HIVE_API_KEY"

Execute a tool:

curl -X POST https://mcp.hiveintelligence.xyz/api/v1/execute \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "get_price",
    "args": {
      "ids": "bitcoin",
      "vs_currencies": "usd"
    }
  }'

Troubleshooting

| Symptom | What to check | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | API key required | Run hive auth login, pass --api-key, or set the hosted MCP Authorization: Bearer ... header. | | Unsupported engine or install failure | Use Node.js 22.12 or newer; Node.js 24 LTS is recommended. | | Hosted MCP works in one client but not another | Confirm whether the client uses custom API-key headers or native OAuth. Native connectors require the hosted OAuth deployment and consent page to be enabled. | | A provider tool returns missing_key | The tool is discoverable, but that provider needs an env var such as ALCHEMY_API_KEY, HELIUS_API_KEY, or MORALIS_API_KEY. | | A provider returns rate_limited, degraded, or failing | Check hive status, hive doctor, or hive://status for runtime status and retry guidance. | | npx install/cache errors | Retry with a clean cache: NPM_CONFIG_CACHE=$(mktemp -d) npx -y -p hive-intelligence@latest hive --help. |

Develop Locally

Install:

npm install

Run:

npm run dev          # stdio MCP
npm run dev:http     # HTTP MCP and REST API on :8080

Verify:

npm run check

Focused checks:

npm run build
npm run test:unit
npm run test:mcp-compliance
npm run verify:toolsets
npm run verify:agent-skills
npm run env:render:check

Package Contents

The hive-intelligence npm package includes:

hive, hive-intelligence, hive-mcp, and hive-mcp-server binaries.
Built MCP server and CLI files in build/.
Bundled Hive agent skills in agent-skills/.
Local stdio MCP runtime for desktop clients and self-hosting.

Contributor Context

Core implementation areas:

src/mcpServer.ts builds the MCP servers, tools, resources, prompts, and runtime instructions.
src/server.ts runs Express, Streamable HTTP MCP, REST routes, auth, middleware, discovery descriptors, and shutdown.
src/taskToolsets.ts defines the workflow surface agents should prefer over raw endpoint browsing. See the workflow design contract for composition and receipt requirements.
src/cli.ts and src/cli/ expose auth, setup, discovery, execution, diagnostics, config generation, aliases, and watch mode.
agent-skills/ ships agent-installable Hive skills.