REST API Tutorial | Hive Intelligence

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

Go to the Hive Dashboard
Sign in or create an account
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 375 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 - connect Hive to Claude, Cursor, and supported MCP clients
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