---
title: 'Tutorial: Query Crypto Data with the Hive REST API'
lastUpdated: '2026-06-06'
byline: founder
nextjs:
  metadata:
    title: REST API Tutorial | Hive Intelligence
    description: Step-by-step guide to querying live crypto prices, DeFi yields, and token security from Hive Intelligence using the REST API.
    alternates:
      canonical: https://www.hiveintelligence.xyz/tutorials/rest-api
---

{% ai-doc-actions path="/tutorials/rest-api" title="REST API Tutorial" /%}

## What you'll build

A Python script that checks Bitcoin price, scans the top DeFi yield opportunities, and inspects token risk signals - all through one API.

By the end you'll have a reusable `hive_call()` function for server-side scripts, backend jobs, or research tools.

---

## The problem: three APIs for one workflow

Without Hive, getting a basic crypto research workflow running means stitching together multiple services:

| Task | Typical provider | Auth | Response format |
|------|-----------------|------|-----------------|
| Token prices | CoinGecko API | API key header | Nested JSON by coin ID |
| DeFi yields | DeFiLlama API | None (public) | Array of pool objects |
| Token security | GoPlus API | None (public) | Chain-specific nested result |

Three APIs, three auth flows, three response schemas to parse and maintain. When one of them changes their rate limits or deprecates a field, your code breaks in a different way each time.

---

## The solution: one endpoint, one key, one execution contract

With Hive, the same workflow is a single endpoint. You send a `tool` name and `args`, and get a consistent REST execution envelope back - regardless of which upstream provider fulfills the request.

```text
POST https://mcp.hiveintelligence.xyz/api/v1/execute
```

One API key. One request shape. One error format. Tool-specific provider data stays inside `data`.

---

## Step 1: Get your API key

1. Go to the [Hive Dashboard](https://www.hiveintelligence.xyz/dashboard)
2. Sign in or create an account
3. Copy your API key from the dashboard

Keep this key private. You'll use it in every request as an `Authorization: Bearer` token (the legacy `x-api-key` header is also accepted).

---

## Step 2: Your first API call

Start with a simple price check. Open a terminal and run:

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

You should get back a JSON object with current prices for both tokens. If you see a `401`, double-check your API key. If you see a `404`, make sure the URL is exact.

---

## Step 3: Discover available tools

Hive currently exposes 369 callable tools across crypto market data, DeFi, wallets and portfolio, security, DEX flows, NFTs, prediction markets, network infrastructure, search, and Hive-native stateful workflows. You don't need to memorize them — the discovery endpoint lets you search:

```bash
curl -X GET "https://mcp.hiveintelligence.xyz/api/v1/tools?limit=10" \
  -H "Authorization: Bearer YOUR_HIVE_API_KEY"
```

This returns tool names, descriptions, and input schemas. You can narrow results with `search`:

```bash
curl -X GET "https://mcp.hiveintelligence.xyz/api/v1/tools?search=yield&limit=5" \
  -H "Authorization: Bearer YOUR_HIVE_API_KEY"
```

Useful query parameters:

| Parameter | Example | Purpose |
|-----------|---------|---------|
| `search` | `yield` | Filter tools by keyword |
| `limit` | `10` | Max results per page |
| `cursor` | *(from response)* | Paginate through results |
| `fields` | `name,description,inputSchema` | Return only specific fields |

---

## Step 4: Build a reusable Python client

Install the only dependency you need:

```bash
pip install requests
```

Here's a complete working script that covers the three-API problem from above - prices, yields, and security - in one file:

```python
import requests

HIVE_API = "https://mcp.hiveintelligence.xyz/api/v1/execute"
API_KEY = "YOUR_HIVE_API_KEY"

def hive_call(tool: str, args: dict) -> dict:
    response = requests.post(
        HIVE_API,
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
        json={"tool": tool, "args": args},
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    if not payload.get("ok", False):
        raise RuntimeError(payload.get("error", {}).get("message", "Hive call failed"))
    return payload["data"]

# Check Bitcoin price
price = hive_call("get_price", {"ids": "bitcoin", "vs_currencies": "usd"})
print(f"Bitcoin: ${price['bitcoin']['usd']:,.0f}")

# Get top DeFi yields
yields = hive_call("get_yield_pools", {"chain": "ethereum", "limit": 5})
for pool in yields.get("items", [])[:5]:
    print(f"{pool['symbol']}: {pool['apy']:.1f}% APY")

# Inspect token risk signals
security = hive_call("get_token_security", {"chainId": "1", "contract_addresses": "0xdac17f958d2ee523a2206206994597c13d831ec7"})
print(f"USDT risk signals: {security}")
```

Three different data domains, three lines of business logic each. The `hive_call` function handles all the HTTP plumbing.

---

## Step 5: Combine tools for a complete workflow

Real research involves chaining calls together. Here's a pattern that finds high-yield pools and then checks whether the underlying tokens trigger risk flags:

```python
def research_yield_opportunities(chain: str = "ethereum", min_apy: float = 5.0):
    """Find yield pools above a threshold, then inspect token risk signals."""

    # 1. Fetch pools
    pools = hive_call("get_yield_pools", {"chain": chain, "limit": 20})

    for pool in pools.get("items", []):
        if pool["apy"] < min_apy:
            continue

        print(f"\n--- {pool['symbol']} ({pool['apy']:.1f}% APY) ---")

        # 2. Check security for each underlying token
        for address in pool.get("underlyingTokens", []):
            sec = hive_call("get_token_security", {
                "chainId": "1",
                "contract_addresses": address,
            })
            result = {k: v for k, v in sec.items() if k != "_hive"}
            print(f"  Token {address[:10]}... - {result}")

research_yield_opportunities(chain="ethereum", min_apy=8.0)
```

The pattern is always the same: call `hive_call` with a tool name and arguments, then use the result to decide what to do next. The REST path stays close to standard HTTP: one endpoint, one auth header, and one JSON execution envelope.

---

## Authentication

Both of these headers work for every endpoint. Prefer the Bearer form — it's the standard HTTP auth scheme.

```text
Authorization: Bearer YOUR_HIVE_API_KEY
```

```text
x-api-key: YOUR_HIVE_API_KEY
```

The examples in this tutorial use `Authorization: Bearer`. The `x-api-key` legacy alias is accepted; use whichever fits your HTTP client or framework convention.

---

## Error handling

The API uses standard HTTP status codes. Handle these three and you'll cover the common cases:

| Status | Meaning | What to do |
|--------|---------|------------|
| `401` | Invalid or missing API key | Check your key, make sure the header is present |
| `404` | Tool not found | Verify the tool name via the discovery endpoint |
| `429` | Rate limit exceeded | Back off and retry after the `Retry-After` interval |

In Python, `response.raise_for_status()` will throw an `HTTPError` for any non-2xx response. Wrap your calls if you want graceful degradation:

```python
from requests.exceptions import HTTPError

def safe_hive_call(tool: str, args: dict) -> dict | None:
    try:
        return hive_call(tool, args)
    except HTTPError as e:
        if e.response.status_code == 429:
            print("Rate limited - wait and retry")
        elif e.response.status_code == 401:
            print("Bad API key")
        elif e.response.status_code == 404:
            print(f"Tool '{tool}' not found - check /api/v1/tools")
        else:
            print(f"API error: {e.response.status_code}")
        return None
```

---

## Next steps

- [Tutorial: MCP Integration](/tutorials/mcp-integration) - connect Hive to Claude, Cursor, and supported MCP clients
- [Tutorial: CLI](/cli) - use Hive from the command line
- [API Integration Reference](/api-integration) - full endpoint documentation, MCP protocol details, and category-scoped endpoints
- [Live Tool Catalog](/tools/live-catalog) - browse every available tool interactively