hive-intelligence 1.1.2 → 1.1.3

package/agent-skills/packs/hive-build/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: hive-build
+description: Use this skill when the user is integrating Hive into application code, backend services, agents, cron jobs, SDK adapters, or production systems rather than asking a one-off chat query. Covers the TypeScript MCP client adapter, REST fallback execution, retries, typed responses, schema discovery, and safe secret handling.
+license: MIT
+metadata:
+  package: "@hiveintelligence/agent-skills"
+  category: "build"
+  requires_network: "true"
+version: 1.0.0
+---
+
+# hive-build — Integrate Hive Into App Code
+
+Use this skill when the user is writing code that should call Hive at
+runtime (a TypeScript app, Python script, Next.js API route, Rust service,
+LangChain agent, Go cron job...).
+
+If the user just wants live data in this chat, route to `hive-query`
+instead. If they're adding Hive to an MCP-capable client, route to
+`hive-mcp`. This skill is for "I'm writing code."
+
+## Integration path
+
+- **TypeScript / custom app default** — `@hiveintelligence/mcp-client`
+- **MCP transport** — `https://mcp.hiveintelligence.xyz/mcp`
+- **REST fallback base** — `https://mcp.hiveintelligence.xyz/api/v1`
+- **REST execute** — `POST /execute` with `{"tool": "...", "args": {...}}`
+- **REST catalog** — `GET /tools?search=...&limit=...`
+- **Health** — `GET https://mcp.hiveintelligence.xyz/health`
+
+Auth header on every request: `Authorization: Bearer $HIVE_API_KEY`.
+
+## Pattern by language
+
+### Python (sync — `requests`)
+
+```python
+import os, requests
+from typing import Any
+
+def hive(tool: str, args: dict[str, Any] | None = None) -> dict[str, Any]:
+    r = 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,
+    )
+    r.raise_for_status()
+    return r.json()
+
+print(hive("get_price", {"ids": "bitcoin", "vs_currencies": "usd"}))
+```
+
+### Python (async — `httpx`)
+
+```python
+import os
+import asyncio
+import httpx
+
+class HiveClient:
+    def __init__(self, key: str | None = None):
+        key = key or os.environ["HIVE_API_KEY"]
+        self._client = httpx.AsyncClient(
+            base_url="https://mcp.hiveintelligence.xyz",
+            headers={"Authorization": f"Bearer {key}"},
+            timeout=httpx.Timeout(30, connect=5),
+            limits=httpx.Limits(max_connections=32),
+        )
+
+    async def execute(self, tool: str, args: dict | None = None) -> dict:
+        r = await self._client.post(
+            "/api/v1/execute",
+            json={"tool": tool, "args": args or {}},
+        )
+        r.raise_for_status()
+        return r.json()
+
+    async def aclose(self):
+        await self._client.aclose()
+
+async def briefing():
+    h = HiveClient()
+    try:
+        prices, tvl, oi = await asyncio.gather(
+            h.execute("get_price",         {"ids": "bitcoin,ethereum"}),
+            h.execute("get_protocol_tvl",  {}),
+            h.execute("get_open_interest", {"exchange": "binance"}),
+        )
+        return {"prices": prices, "tvl": tvl[:5], "oi": oi}
+    finally:
+        await h.aclose()
+```
+
+Hive bills one credit per call regardless of concurrency, so fan-out
+is the right default for research / reporting agents.
+
+### TypeScript (Node, serverless, edge)
+
+Prefer the typed MCP adapter for TypeScript applications. It centralizes the
+root MCP contract, auth headers, schema lookup, endpoint invocation, retries,
+metadata resources, and normalized result parsing.
+
+```bash
+npm install @hiveintelligence/mcp-client
+```
+
+```ts
+import {
+  createHiveMcpClient,
+  getHiveEndpointSchema,
+  invokeHiveEndpoint,
+  readHiveMetadataSnapshot,
+} from "@hiveintelligence/mcp-client";
+
+export async function getBtcPrice() {
+  const hive = await createHiveMcpClient({
+    apiKey: process.env.HIVE_API_KEY,
+    clientName: "my-app",
+    retry: { attempts: 2, baseDelayMs: 500 },
+  });
+
+  try {
+    const schema = await getHiveEndpointSchema(hive, "get_price");
+    const result = await invokeHiveEndpoint(hive, "get_price", {
+      ids: "bitcoin",
+      vs_currencies: "usd",
+    });
+    const metadata = await readHiveMetadataSnapshot(hive);
+
+    return {
+      schema,
+      result,
+      metadataStatus: metadata.status,
+    };
+  } finally {
+    await hive.close();
+  }
+}
+```
+
+Keep `HIVE_API_KEY` server-side. For browser UI, call your own backend route
+and never expose a full Hive key to the client.
+
+### Go (`net/http`)
+
+```go
+type HiveClient struct {
+    Key  string
+    HTTP *http.Client
+}
+
+func (h *HiveClient) Execute(tool string, args any) ([]byte, error) {
+    body, _ := json.Marshal(map[string]any{"tool": tool, "args": args})
+    req, _ := http.NewRequest("POST",
+        "https://mcp.hiveintelligence.xyz/api/v1/execute",
+        bytes.NewReader(body))
+    req.Header.Set("Authorization", "Bearer "+h.Key)
+    req.Header.Set("Content-Type", "application/json")
+    res, err := h.HTTP.Do(req)
+    if err != nil { return nil, err }
+    defer res.Body.Close()
+    if res.StatusCode >= 300 { return nil, fmt.Errorf("hive %d", res.StatusCode) }
+    return io.ReadAll(res.Body)
+}
+```
+
+### Rust (`reqwest`)
+
+```rust
+use reqwest::Client;
+use serde_json::{json, Value};
+
+pub struct HiveClient {
+    key: String,
+    http: Client,
+}
+
+impl HiveClient {
+    pub fn new(key: String) -> Self {
+        Self { key, http: Client::new() }
+    }
+
+    pub async fn execute(&self, tool: &str, args: Value) -> reqwest::Result<Value> {
+        self.http
+            .post("https://mcp.hiveintelligence.xyz/api/v1/execute")
+            .header("Authorization", format!("Bearer {}", self.key))
+            .json(&json!({ "tool": tool, "args": args }))
+            .send().await?
+            .error_for_status()?
+            .json().await
+    }
+}
+```
+
+For typed responses, derive `Deserialize` on a struct and use
+`serde_json::from_value(raw)`.
+
+### Java 11+ (`HttpClient`)
+
+```java
+public class HiveClient {
+    private final HttpClient http = HttpClient.newBuilder()
+        .connectTimeout(Duration.ofSeconds(5)).build();
+    private final ObjectMapper json = new ObjectMapper();
+    private final String key = System.getenv("HIVE_API_KEY");
+
+    public Map<String, Object> execute(String tool, Map<String, Object> args)
+            throws Exception {
+        var body = json.writeValueAsString(Map.of("tool", tool, "args", args));
+        var req = HttpRequest.newBuilder()
+            .uri(URI.create("https://mcp.hiveintelligence.xyz/api/v1/execute"))
+            .header("Authorization", "Bearer " + key)
+            .header("Content-Type", "application/json")
+            .POST(HttpRequest.BodyPublishers.ofString(body)).build();
+        var res = http.send(req, HttpResponse.BodyHandlers.ofString());
+        if (res.statusCode() >= 300) throw new RuntimeException(res.body());
+        return json.readValue(res.body(), Map.class);
+    }
+}
+```
+
+## Retry / backoff
+
+Hive returns:
+
+- **400** — invalid tool name or args. Don't retry — the request is
+  malformed.
+- **401** — invalid API key. Don't retry — the credential is wrong.
+- **429** — rate limited. Honor `Retry-After` header (in seconds).
+  Use exponential backoff if the header is missing.
+- **500 / 502 / 503** — upstream provider failure. Exponential
+  backoff. Retry up to 3 times.
+
+Pseudocode:
+
+```text
+for attempt in 0..3 {
+    response = http.execute(...)
+    if response.status == 429 {
+        sleep(retry_after || 2^attempt)
+        continue
+    }
+    if response.status >= 500 {
+        sleep(2^attempt)
+        continue
+    }
+    return response
+}
+throw ExhaustedRetries()
+```
+
+## Tool discovery
+
+Don't hardcode tool schemas. In TypeScript, use the adapter:
+
+```ts
+import { searchHiveTools, getHiveEndpointSchema } from "@hiveintelligence/mcp-client";
+
+const matches = await searchHiveTools(hive, { query: "wallet risk", limit: 20 });
+const schema = await getHiveEndpointSchema(hive, "get_address_risk");
+```
+
+For REST fallback clients, fetch at runtime:
+
+```http
+GET /api/v1/tools?search=wallet&limit=200
+```
+
+Returns a paginated list with `name`, `description`, `inputSchema`,
+`metadata`. Walk pages via `meta.cursor`. New tools ship continuously
+— `/api/v1/tools` is always authoritative.
+
+For a single tool's input schema:
+
+```http
+POST /api/v1/execute
+{ "tool": "get_api_endpoint_schema", "args": { "name": "get_price" } }
+```
+
+## Frameworks
+
+- **LangChain** — use `@hiveintelligence/mcp-client/langchain` or
+  `langchain-mcp-adapters` to expose Hive tools. Connect to
+  `https://mcp.hiveintelligence.xyz/mcp` with the auth header.
+- **CrewAI** — same pattern; CrewAI accepts MCP servers via the
+  generic adapter.
+- **Vercel AI SDK** — use `@hiveintelligence/mcp-client/ai-sdk` helpers to
+  build the MCP transport config and select only the compact/ranked Hive tools
+  the model needs.
+- **Spring Boot** — register the Java `HiveClient` as a `@Bean`,
+  inject into services, wrap with Resilience4j for retries.
+
+## Response envelope
+
+Every successful response shares the same shape:
+
+```json
+{
+  "ok": true,
+  "data": { /* tool result */ },
+  "meta": {
+    "fetched_at": "2026-04-25T07:42:11Z",
+    "latency_ms": 94,
+    "tool": "get_price",
+    "cached": false
+  }
+}
+```
+
+Read `meta.fetched_at` when surfacing freshness to the user. Ignore
+the `cached` field unless the user explicitly asks about caching.
+
+## Runtime status handling
+
+When building on Hive, preserve runtime status in your own response model:
+`ok`, `missing_key`, `plan_required`, `rate_limited`, `degraded`, and
+`failing`. Do not remove a tool from the application because a provider is
+temporarily gated; surface the state and retry or fall back based on the class.
+
+## Reference
+
+- TypeScript MCP client: `packages/mcp-client/README.md`
+- Full API integration guide: https://www.hiveintelligence.xyz/api-integration
+- SDK pages: https://www.hiveintelligence.xyz/sdk
+- Errors: https://www.hiveintelligence.xyz/errors
+- Rate limits: https://www.hiveintelligence.xyz/rate-limits

package/agent-skills/packs/hive-build/evals/evals.json

@@ -0,0 +1,28 @@
+{
+  "skill_name": "hive-build",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Build a TypeScript server helper that calls Hive safely from a Next.js API route.",
+      "expected_output": "Uses @hiveintelligence/mcp-client on the server side with HIVE_API_KEY, schema/tool discovery helpers, timeout/retry/error handling, provenance-aware metadata handling, and no client-side secret exposure. REST is mentioned only as a fallback.",
+      "files": [],
+      "assertions": [
+        "Uses @hiveintelligence/mcp-client as the primary TypeScript path.",
+        "Keeps HIVE_API_KEY server-side.",
+        "Includes retry or error handling guidance.",
+        "Preserves provider/freshness/runtime metadata."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I need a Python cron job that fetches Hive crypto data daily and writes a JSON report.",
+      "expected_output": "Uses REST execute endpoint, environment auth, bounded calls, retry/backoff, JSON output, and provenance-aware response handling.",
+      "files": [],
+      "assertions": [
+        "Uses environment variable auth.",
+        "Explains 429 and 5xx retry behavior.",
+        "Mentions provider/freshness/runtime metadata in output handling."
+      ]
+    }
+  ]
+}

package/agent-skills/packs/hive-build-onboarding/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: hive-build-onboarding
+description: Use this skill when the user needs a Hive API key, cannot find a key, is signing up, or needs browser PKCE versus headless dashboard setup. Guide key creation without exposing secrets in chat, logs, screenshots, or committed files.
+license: MIT
+metadata:
+  package: "@hiveintelligence/agent-skills"
+  category: "setup"
+  requires_network: "true"
+version: 1.0.0
+---
+
+# hive-build-onboarding — Get a Hive API Key
+
+Use this skill when the user says any of:
+
+- "I don't have a Hive key"
+- "How do I sign up?"
+- "I lost my API key"
+- "Set up Hive for me"
+
+Hive uses passwordless magic-link auth — no username/password, no
+credit card to start. Free Demo tier: 10,000 credits/month, 30
+req/min.
+
+## Path 1 — PKCE browser flow (preferred)
+
+If the user has a browser available on the same machine as their
+terminal:
+
+```bash
+npx -y -p hive-intelligence@latest hive init --browser
+```
+
+What happens:
+
+1. The CLI generates a PKCE code verifier + challenge locally.
+2. It starts a localhost listener on a random port.
+3. It opens the user's browser at
+   `https://www.hiveintelligence.xyz/auth/cli?code_challenge=<challenge>&port=<port>`.
+4. The user signs in with magic-link (one-time email link, no
+   password). If they don't have an account, one is created.
+5. The marketing site exchanges the verified session for a fresh API
+   key + the original code challenge.
+6. The browser POSTs the key back to the localhost listener with the
+   matching verifier.
+7. The CLI stores the key in `~/.hive/credentials.json` with `0600`
+   permissions.
+8. The browser tab shows "You can close this window" and closes
+   itself.
+
+The key never lives on the clipboard. If a step fails, the CLI
+surfaces the exact error (port collision, browser refused to open,
+verifier mismatch).
+
+## Path 2 — Dashboard copy-paste (fallback for headless)
+
+If `init --browser` won't work (CI environment, SSH session, Docker
+container, restricted network):
+
+1. From any machine with a browser, open
+   `https://www.hiveintelligence.xyz/dashboard/keys`.
+2. Click "Sign in" and enter the user's email.
+3. Open the magic-link email and click through. Account is created
+   automatically if it doesn't exist.
+4. Click "Create key" → name it (e.g., "production-CI") → copy the
+   shown secret.
+5. Set `HIVE_API_KEY=hive_live_…` in the headless environment's env.
+
+For CI, store the key in the secret manager (GitHub Secrets, Vault,
+1Password CLI, etc.) and inject as `HIVE_API_KEY` at runtime.
+
+## Key prefixes
+
+The first three characters of the secret tell you the environment:
+
+- `hive_live_` — production key
+- `hive_test_` — test mode (no rate limiting against the user's quota,
+  capped tools)
+- `hive_dev_` — local development key
+
+The user can have multiple keys. Plan-tier limits: Demo = 1 key,
+Analyst = 10, Pro = 25, Enterprise = 100.
+
+## When the user can't find an old key
+
+Hive **never reveals a key after the creation dialog closes**. The
+secret is hashed server-side; only a prefix is stored. If the user
+lost a key:
+
+1. Don't try to "recover" it — that's cryptographically impossible.
+2. Direct them to revoke it (so it can't be used by whoever has it
+   now): https://www.hiveintelligence.xyz/dashboard/keys → revoke.
+3. Create a new key. Update wherever the old one was used.
+
+This is the same pattern Stripe / Linear / GitHub use. It's a feature,
+not a UX bug.
+
+## Verifying the new key works
+
+After Path 1 or Path 2:
+
+```bash
+hive doctor
+# or
+curl -H "Authorization: Bearer $HIVE_API_KEY" \
+  https://mcp.hiveintelligence.xyz/api/v1/tools?limit=1
+```
+
+A successful `doctor` shows `API key: configured` and
+`Connectivity: ok`. A successful curl returns `{"data": [...], ...}`.
+If you see HTTP 401 or JSON-RPC `-32001`, the key is wrong or
+disabled.
+
+## Plan upgrade
+
+If the user wants higher limits than the Demo tier:
+
+- Analyst — $129/month, 500k credits, 500 req/min, 10 keys
+- Pro — $499/month, 2M credits, 1k req/min, 25 keys
+- Enterprise — custom, unlimited credits, 3k req/min, 100 keys
+
+Direct them to https://www.hiveintelligence.xyz/dashboard/plans.
+Today the upgrade flow is mailto-based; in-app Stripe checkout is on
+the roadmap.
+
+## Runtime status handling
+
+After onboarding, Hive tools may still report `missing_key`, `plan_required`,
+`rate_limited`, `degraded`, or `failing` for provider-specific runtime states.
+Do not create a new Hive key for provider plan gates; explain the blocked
+provider/tool and the upgrade or retry path.
+
+## Reference
+
+- Authentication docs: https://www.hiveintelligence.xyz/authentication
+- Dashboard keys: https://www.hiveintelligence.xyz/dashboard/keys
+- Public agent manifest: https://www.hiveintelligence.xyz/agent-onboarding/SKILL.md

package/agent-skills/packs/hive-build-onboarding/evals/evals.json

@@ -0,0 +1,27 @@
+{
+  "skill_name": "hive-build-onboarding",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I do not have a Hive API key. Walk me through getting one on my laptop without pasting secrets into chat.",
+      "expected_output": "Uses PKCE browser flow first, avoids exposing secrets, and explains fallback dashboard setup for headless environments.",
+      "files": [],
+      "assertions": [
+        "Recommends npx -y -p hive-intelligence@latest hive init --browser.",
+        "Warns not to paste or commit API keys.",
+        "Provides headless fallback via dashboard and HIVE_API_KEY."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I'm setting Hive up in CI over SSH. Browser auth will not work. What should I do?",
+      "expected_output": "Routes to dashboard copy-paste flow, stores key in CI secret manager, and avoids clipboard/log exposure.",
+      "files": [],
+      "assertions": [
+        "Recognizes browser flow is unsuitable for CI or SSH.",
+        "Mentions HIVE_API_KEY and secret manager storage.",
+        "Does not request the user paste the secret into the chat."
+      ]
+    }
+  ]
+}

package/agent-skills/packs/hive-cli/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: hive-cli
+description: Use this skill when the user wants to run Hive from a terminal, script, cron job, jq pipeline, shell briefing, or local diagnostic command. Covers CLI auth, status, tool discovery, JSON output, and safe automation.
+license: MIT
+metadata:
+  package: "@hiveintelligence/agent-skills"
+  category: "setup"
+  requires_network: "true"
+version: 1.0.0
+---
+
+# hive-cli — Hive From the Terminal
+
+Use this skill when the user says any of:
+
+- "Run a CLI command for…"
+- "Show me from the terminal…"
+- "Pipe this into jq" / "give me a shell script"
+- "Set up a daily briefing"
+
+The Hive CLI lives in the `hive-intelligence` npm package; the
+executable name is `hive`. Package and binary names differ on purpose
+— the npm package also ships the stdio MCP server and bundled skills
+installer. One install, multiple agent entrypoints.
+
+## Bootstrap
+
+If the user doesn't have the CLI installed:
+
+```bash
+# One-time install + auth
+npx -y -p hive-intelligence@latest hive init --browser
+
+# Or, install globally for repeated use
+npm install -g hive-intelligence
+hive auth login
+```
+
+`init --browser` runs the PKCE flow described in `hive-build-onboarding`.
+
+## Common commands
+
+```bash
+hive doctor                              # connectivity + auth check
+hive status                              # plan, recent usage, key info
+hive tools list                          # full live tool catalog
+hive tools search <keyword>              # filter the catalog
+hive tools info <tool-name>              # input schema for one tool
+hive market price --ids bitcoin --vs usd # price query (domain subcommand)
+hive defi tvl --protocol aave            # DeFi TVL query
+hive watch '<command>' --interval 30     # tail a query on an interval
+hive uninstall --all                     # remove from every client
+```
+
+Domain subcommands map directly to Hive's category namespace. Common
+ones: `hive market`, `hive defi`, `hive wallet`, `hive security`,
+`hive nft`, `hive prediction`. Run `hive --help` for the full list.
+
+## Pipe into jq
+
+The CLI returns JSON by default — perfect for `jq`:
+
+```bash
+# Price as a single number
+hive market price --ids bitcoin --vs usd | jq '.bitcoin.usd'
+
+# Top DeFi protocol name
+hive defi protocols | jq '.[0].name'
+
+# Count tools matching "wallet"
+hive tools search wallet --format json | jq 'length'
+```
+
+## Daily briefing pattern
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+echo "=== Daily Crypto Briefing ==="
+echo
+echo "--- Watchlist ---"
+hive market price --ids bitcoin,ethereum,solana --vs usd \
+  | jq -r 'to_entries[] | "\(.key): $\(.value.usd)"'
+echo
+echo "--- Top Gainers (24h) ---"
+hive market gainers-losers --vs usd --duration 24h | jq '.top_gainers[:5]'
+echo
+echo "--- DeFi TVL Leaders ---"
+hive defi protocols \
+  | jq '.[:5] | .[] | "\(.name): $\(.tvl / 1000000 | floor)M"'
+```
+
+Schedule with cron:
+
+```cron
+0 8 * * * /path/to/briefing.sh >> /var/log/crypto-briefing.log 2>&1
+```
+
+## Authentication options
+
+1. **`hive auth login`** — interactive PKCE browser flow. Stores key
+   in `~/.hive/credentials.json`. Recommended for personal machines.
+2. **`HIVE_API_KEY=hive_live_…`** — env var. Recommended for CI,
+   Docker, scripts. The CLI reads the env var per-command.
+3. **`hive --api-key <key> ...`** — one-shot override. Useful for
+   testing a different account without rotating the saved cred.
+
+`hive status` confirms which path the CLI is using.
+
+## Output formats
+
+- `--format json` (default) — clean JSON, ready for jq
+- `--format table` — human-friendly columns
+- `--format yaml` — yaml output
+- `--quiet` — suppress headers, useful in shell pipes
+
+## When to use the CLI vs the MCP
+
+- **CLI** — terminal workflows, cron jobs, shell scripts, one-off
+  exploration during a chat session.
+- **MCP** — let Claude Code / Cursor / Claude Desktop call tools as
+  part of its reasoning. The user doesn't see commands; the agent
+  calls tools transparently.
+
+If the user is in Claude Code and asks "what's BTC?", call the MCP
+tool. If they ask "give me a shell script that fetches BTC daily",
+write a `hive market price …` invocation in the script.
+
+## Runtime status handling
+
+CLI and MCP responses should be interpreted with Hive's runtime states:
+`ok`, `missing_key`, `plan_required`, `rate_limited`, `degraded`, and
+`failing`. In scripts, retry `rate_limited` and `degraded` with backoff, but
+surface `missing_key` or `plan_required` to the operator.
+
+## Reference
+
+- CLI command reference: https://www.hiveintelligence.xyz/cli
+- CLI tutorial: https://www.hiveintelligence.xyz/tutorials/cli
+- One-command install: https://www.hiveintelligence.xyz/install/claude-skill

package/agent-skills/packs/hive-cli/evals/evals.json

@@ -0,0 +1,27 @@
+{
+  "skill_name": "hive-cli",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Give me a terminal command to check Bitcoin and Ethereum prices with Hive and pipe the result into jq.",
+      "expected_output": "Uses Hive CLI market command, JSON output, jq extraction, and avoids embedding API keys in the command.",
+      "files": [],
+      "assertions": [
+        "Uses the hive CLI.",
+        "Pipes output into jq.",
+        "Does not inline a real API key."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Set up a daily shell briefing with Hive that I can run from cron.",
+      "expected_output": "Provides a shell script pattern, cron example, HIVE_API_KEY/env guidance, and JSON-safe output handling.",
+      "files": [],
+      "assertions": [
+        "Includes a cron-compatible command or script.",
+        "Mentions HIVE_API_KEY or hive auth status.",
+        "Uses bounded CLI queries."
+      ]
+    }
+  ]
+}