Getting Started

HiveIQ is an intelligent AI compute layer that routes every request to the optimal provider — cutting costs by up to 86% while improving reliability. One endpoint replaces six provider integrations.

Base URL

https://hiveiq.xyz

Quick example

Send your first request. Replace YOUR_API_KEY with the key you generate from your dashboard.

curl https://hiveiq.xyz/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "chat_completion",
    "messages": [
      {"role": "user", "content": "Explain TEEs in one sentence."}
    ],
    "provider": "auto",
    "max_tokens": 128
  }'

Authentication

HiveIQ accepts three authentication methods on protected endpoints. Pick whichever matches your client.

1. User API Key (recommended for production)

Long-lived hiq_* keys you create from the dashboard. Each request is attributed to your account and counted against your tier's quota.

Authorization: Bearer hiq_<your-key>

2. User JWT (for browser sessions)

Short-lived (24h default) JWTs returned by POST /auth/login. Carries sub, email, jti, iat, exp. Revoked on /auth/logout via Redis blacklist.

{
  "email": "user@example.com",
  "password": "at-least-8-chars"
}

{
  "token": "eyJhbGciOiJIUzI1NiIs…",
  "user_id": "3a4f-…",
  "email": "user@example.com"
}

3. Operator key (for self-hosted dashboards)

The HIVEIQ_API_KEY environment variable on the server. Sent the same way as a user key — no per-user attribution, unlimited rate. Intended for internal dashboards and integration tests.

Authorization: Bearer <HIVEIQ_API_KEY>

Tasks API

The core endpoint. Submit a chat completion and HiveIQ picks the optimal provider based on cost, latency, privacy, and reputation.

{
  "task_type": "chat_completion",
  "messages": [
    {"role": "system", "content": "You are concise."},
    {"role": "user",   "content": "Explain CAP theorem in two sentences."}
  ],
  "provider": "auto",
  "routing": "auto",
  "privacy_tier": "public",
  "max_tokens": 256,
  "temperature": 0.5
}

{
  "id": "7f5d3a91-…",
  "provider": "openai",
  "model": "gpt-4o-mini",
  "output": "CAP says any distributed datastore can guarantee at most two of consistency, availability, and partition tolerance simultaneously. In practice you pick CP or AP because partitions are unavoidable on real networks.",
  "input_tokens": 22,
  "output_tokens": 48,
  "estimated_cost_usd": 0.0000321,
  "latency_ms": 812
}

# Each chunk arrives as an SSE message:
event: token
data: {"delta": "CAP "}

event: token
data: {"delta": "says "}

# Final terminator with full metadata:
event: done
data: {"provider": "openai", "cost_usd": 0.0000321, "latency_ms": 812}

Marketplace API

A competitive bidding layer over the provider mesh. Set "routing": "marketplace" on a task and providers compete on cost, latency, and reputation.

How bidding works

1. HiveIQ loads every active provider whose capabilities satisfy required_capabilities and whose privacy tier satisfies the request.
2. Providers without a verified NAC identity are excluded.
3. Each remaining provider produces a bid in parallel within a 200ms window.
4. Bids are scored: score = w_cost · cost_norm + w_latency · latency_norm + w_reputation · rep_norm. Default weights are {cost: 0.4, latency: 0.3, reputation: 0.3} — override with the MARKETPLACE_WEIGHTS env var.
5. The highest-scoring bid wins. Outcome (success / failure / actual latency vs. estimate) is recorded and feeds back into the provider's reputation with α = 0.1 smoothing.
6. NAC level 4 grants a +10% reputation multiplier at scoring time, so high-tier identities win closer auctions.

{
  "success": true,
  "data": [
    {
      "provider_id": "openai",
      "capabilities": ["chat", "reasoning", "code", "vision"],
      "base_price_per_token": 2.5e-7,
      "reputation_score": 0.987,
      "is_active": true,
      "created_at": "2026-04-10T17:26:31Z"
    }
  ],
  "meta": {"count": 6}
}

Multi-Agent Sessions

Decompose a complex task into 2–4 specialist sub-tasks, run them across the provider mesh in parallel where independent, and synthesize a coherent final answer via Claude.

{
  "task": "Compare PostgreSQL and Redis as caching layers, then recommend one for a high-write fintech workload.",
  "orchestrator": "claude"
}

{
  "success": true,
  "data": {
    "session_id": "7678cc6e-d08f-425b-af5b-7c0f2e3a635d",
    "orchestrator_model": "claude-3-5-sonnet",
    "status": "active",
    "task_description": "Compare PostgreSQL and Redis…",
    "decomposition_plan": [
      {"agent_role": "analyst", "prompt": "…", "recommended_provider": "anthropic", "depends_on": []},
      {"agent_role": "analyst", "prompt": "…", "recommended_provider": "anthropic", "depends_on": []},
      {"agent_role": "writer",  "prompt": "…", "recommended_provider": "anthropic", "depends_on": [0, 1]}
    ],
    "steps": [/* 3 step records, all status="pending" initially */],
    "total_cost_usd": 0,
    "total_latency_ms": 0
  },
  "meta": {
    "step_count": 3,
    "stream_url": "/agents/sessions/7678cc6e-…/stream"
  }
}

event: snapshot
data: {"type":"snapshot","step_count":3,"steps":[…]}

event: step_completed
data: {"step_index":0,"provider_id":"anthropic","cost_usd":0.001008,"latency_ms":2456}

event: synthesis_started
data: {"session_id":"7678cc6e-…"}

event: session_completed
data: {"status":"completed","total_cost_usd":0.017839,"total_latency_ms":33813}

Model Registry

A curated catalog of every model HiveIQ can route to, with benchmark scores, parameter counts, context windows, and live cost-per-1k figures.

{
  "workload_hint": "reasoning",
  "max_cost_per_1k": 0.005,
  "required_capabilities": ["chat", "reasoning"]
}

Provider Identity

Every HiveIQ provider has an on-chain identity backed by a Non-Fungible Access Certificate (NAC) issued via the Vitreus pallet_nac_managing. Identity gates marketplace participation and influences scoring.

NAC level tiers

{
  "success": true,
  "data": [
    {
      "identity_id": "10294a48-…",
      "provider_id": "openai",
      "nac_level": 4,
      "nac_account": "nac::openai",
      "vtrs_address": "0x5f0e9aF2cD3a89A11d4f1c9d6FB76eD09a4cB10E",
      "verified": true,
      "reputation_multiplier": 1.1,
      "issued_at": "2026-04-11T03:50:54Z",
      "last_verified_at": "2026-04-11T03:51:13Z"
    }
  ],
  "meta": {"count": 6, "verified_count": 6, "source": "vitreus_pallet_nac_managing (simulated)"}
}

A2A Protocol

HiveIQ implements Google's Agent2Agent (A2A) protocol so any A2A-compatible orchestrator can discover HiveIQ and submit tasks without integration work.

{
  "name": "HiveIQ",
  "description": "AI compute orchestration with on-chain reputation, NAC-backed provider identity, and multi-provider routing.",
  "url": "https://hiveiq.xyz/a2a",
  "version": "0.5.0",
  "provider": {"organization": "HiveIQ × Vitreus", "url": "https://vitreus.io"},
  "capabilities": {"streaming": false, "pushNotifications": false, "stateTransitionHistory": true},
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "skills": [
    {"id": "hiveiq.chat-completion",     "name": "HiveIQ Chat Completion",     "…": "…"},
    {"id": "hiveiq.multi-agent-session", "name": "HiveIQ Multi-Agent Session", "…": "…"}
  ]
}

{
  "id": "task-1",
  "sessionId": "chat-9f",
  "input": {
    "message": {
      "role": "user",
      "parts": [
        {"type": "text", "text": "Say hello in haiku form."}
      ]
    }
  },
  "metadata": {"max_tokens": 200, "temperature": 0.5}
}

{
  "id": "task-1",
  "sessionId": "chat-9f",
  "status": {"state": "completed", "timestamp": "2026-04-11T04:15:42Z"},
  "input": {"message": {"role": "user", "parts": [{"type": "text", "text": ""}]}},
  "output": [
    {"type": "text", "text": "Gentle morning light, / Whispers of the dawn arise, / Hello, world anew."}
  ],
  "metadata": {
    "hiveiq": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "input_tokens": 14,
      "output_tokens": 19,
      "estimated_cost_usd": 1.35e-05
    }
  },
  "createdAt": "2026-04-11T04:15:40Z",
  "completedAt": "2026-04-11T04:15:42Z"
}

{
  "id": "task-1",
  "status": {"state": "submitted", "timestamp": "2026-04-11T04:17:50Z"},
  "metadata": {
    "hiveiq": {
      "session_id": "7678cc6e-d08f-425b-af5b-7c0f2e3a635d",
      "step_count": 3,
      "stream_url": "/agents/sessions/7678cc6e-…/stream",
      "poll_url":   "/agents/sessions/7678cc6e-…"
    }
  }
}

A2A task status states

Polling an async session

For sessions created via POST /a2a/sessions, poll the HiveIQ-native endpoint GET /agents/sessions/{session_id} using the session_id from metadata.hiveiq, or subscribe to the SSE stream at {stream_url} for live updates. The session terminates with status: completed or status: failed.

Python SDK

Zero-dependency stdlib client. No requests, no httpx, no transitive deps to vet.

# Install from GitHub (recommended for now):
pip install git+https://github.com/Bison1330/hiveiq-core.git#subdirectory=sdk

# Or grab the single-file SDK directly:
curl -O https://raw.githubusercontent.com/Bison1330/hiveiq-core/main/sdk/hiveiq.py

# Once PyPI publishing completes:
pip install hiveiq

Quickstart

from sdk.hiveiq import HiveIQ, HiveIQAPIError

client = HiveIQ(
    api_key="hiq_...",
    base_url="https://hiveiq.xyz",
)

# Submit a task in auto routing mode
result = client.execute(
    messages=[{"role": "user", "content": "Summarize the CAP theorem."}],
    provider="auto",
    privacy_tier="public",
    max_tokens=256,
)
print(result["output"])
print(f"via {result['provider']} — {result['estimated_cost_usd']:.6f}")

Streaming

for chunk in client.stream(
    messages=[{"role": "user", "content": "Tell me a story."}],
):
    print(chunk["delta"], end="", flush=True)

Marketplace bidding

result = client.execute(
    messages=[{"role": "user", "content": "Generate a function to validate IBANs."}],
    routing="marketplace",
    required_capabilities=["chat", "code"],
)
print(f"winner: {result['provider']}")

Multi-agent session

session = client.create_session(
    task="Compare PostgreSQL vs Redis as a fintech cache layer, then recommend one.",
    orchestrator="claude",
)
print("session_id:", session["session_id"])

# Poll until complete
final = client.wait_for_session(session["session_id"], timeout=120)
print(final["final_result"])

Other helpers

• client.providers() — list every registered provider with availability + pricing
• client.analytics() — aggregate stats for the calling user
• client.history(limit=20) — recent task log

Rate Limits

HiveIQ rate-limits per IP for anonymous traffic and per user for authenticated traffic. Counters live in Redis so they survive restarts and apply across workers.

Limit headers

Every rate-limited response carries the standard slowapi headers so clients can back off gracefully:

X-RateLimit-Limit:     50
X-RateLimit-Remaining: 47
X-RateLimit-Reset:     1712842631
Retry-After:           38

What happens at the limit

Requests over the limit return 429 Too Many Requests. The body includes a human-readable hint specific to the endpoint:

{
  "detail": "Demo rate limit reached. Contact the HiveIQ team for full API access."
}

Error Reference

Phase 6 endpoints (/marketplace/*, /models/*, /identity/*, /agents/sessions/*) use a unified envelope. Legacy endpoints (/tasks/*, /auth/*) keep a flat {detail} shape for SDK back-compat.

Envelope format

{
  "success": false,
  "data":    null,
  "error":   {"code": "not_found", "message": "Session 'abc' not found"},
  "meta":    {"ts": "2026-04-11T04:15:40Z"}
}

Status codes