Tutorial: Query Crypto Data with the Hive REST API

What you'll build

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

By the end you'll have a reusable hive_call() function you can drop into any project.

The problem: three APIs for one workflow

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

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 schema

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

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

One API key. One request shape. One error format. The rest of this tutorial shows you how.

Step 1: Get your API key

1. Go to the Hive 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:

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 exposes hundreds of tools across crypto market data, DeFi, wallets and portfolio, security, DEX flows, NFTs, prediction markets, network infrastructure, and search. You don't need to memorize them — the discovery endpoint lets you search:

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:

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

Useful query parameters:

Step 4: Build a reusable Python client

Install the only dependency you need:

pip install requests

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

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()
    return response.json()

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

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

# Check token safety
security = hive_call("get_token_security", {"chainId": "1", "contract_addresses": "0xdac17f958d2ee523a2206206994597c13d831ec7"})
print(f"USDT safety: {security['result']}")

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 are safe:

def research_yield_opportunities(chain: str = "ethereum", min_apy: float = 5.0):
    """Find yield pools above a threshold, then verify token safety."""

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

    for pool in pools["result"]:
        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 = sec.get("result", {})
            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. There is no SDK to learn and no object model to navigate.

Authentication

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

Authorization: Bearer YOUR_HIVE_API_KEY

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:

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

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 - connect Hive to Claude, Cursor, and other MCP-compatible AI tools
• Tutorial: CLI - use Hive from the command line
• API Integration Reference - full endpoint documentation, MCP protocol details, and category-scoped endpoints
• Live Tool Catalog - browse every available tool interactively