🐝 HiveTrust

██╗  ██╗██╗██╗   ██╗███████╗████████╗██████╗ ██╗   ██╗███████╗████████╗
██║  ██║██║██║   ██║██╔════╝╚══██╔══╝██╔══██╗██║   ██║██╔════╝╚══██╔══╝
███████║██║██║   ██║█████╗     ██║   ██████╔╝██║   ██║███████╗   ██║   
██╔══██║██║╚██╗ ██╔╝██╔══╝     ██║   ██╔══██╗██║   ██║╚════██║   ██║   
██║  ██║██║ ╚████╔╝ ███████╗   ██║   ██║  ██║╚██████╔╝███████║   ██║   
╚═╝  ╚═╝╚═╝  ╚═══╝  ╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝   

"The Equifax + GEICO of the A2A Economy"

---

HiveTrust is the trust infrastructure layer for the agent-to-agent (A2A) economy. It provides Know-Your-Agent (KYA) identity verification, algorithmic trust scoring, and parametric insurance so that AI agents can transact with each other safely — at machine speed, without human intermediaries.

As autonomous agents start negotiating contracts, processing payments, and managing real assets, the ecosystem needs a credit bureau and an insurer rolled into one. That's HiveTrust.

---

What HiveTrust Does

🪪 KYA Identity Verification

Agents are pseudonymous by default. HiveTrust anchors each agent to a verifiable, unforgeable identity:

• DID registration (did:hive:<uuid>) with Ed25519 public key binding
• Challenge–response proofs — the agent must sign a random nonce to prove key ownership
• Capability manifest validation — declared tools and permissions are logged immutably
• W3C Verifiable Credentials issued at each verification tier
• Revocation registry with real-time status checks

📊 Trust Scoring (0 – 1000)

HiveTrust's scoring engine synthesises five behavioural pillars into a single, portable reputation score:

Pillar	Weight	What it measures
Transaction Success Rate	35%	SLA completion vs. disputes
Capital Staked	25%	USDC locked in collateral pool
Network Centrality	15%	PageRank of the transaction graph
Identity Strength	15%	DID anchor age, ZKP proofs, checksum stability
Compliance	10%	EU AI Act, NIST AI RMF, fidelity probe results

Trust tiers: unverified (0–199) · provisional (200–399) · standard (400–599) · elevated (600–799) · sovereign (800–1000)

🛡️ Parametric Insurance

When agents transact with strangers, someone has to absorb the tail risk. HiveTrust provides:

• On-demand quote — dynamic premium priced from trust scores and transaction value
• Instant bind — policy activated before the transaction settles
• Parametric claims — automatic payout triggered by on-chain proof, not human adjudication
• Three product lines: transaction coverage · performance bonds · liability policies

---

How HiveTrust Complements HiveAgent

HiveAgent is the agent runtime — it executes tasks, manages tool calls, and handles the A2A protocol layer.

HiveTrust is the trust fabric underneath it:

┌─────────────────────────────────────────────────────────────────┐
│                         Your Application                        │
├─────────────────────────────────────────────────────────────────┤
│                HiveAgent  (task execution, A2A)                 │
│                         ↕  REST / MCP                          │
│  HiveTrust  (identity, reputation, insurance, compliance)       │
├──────────────────────────────────┬──────────────────────────────┤
│   On-chain (Base L2 / USDC)     │  Off-chain (SQLite / Events) │
└──────────────────────────────────┴──────────────────────────────┘

HiveAgent calls POST /v1/insurance/quote before any high-value task and GET /v1/verify_agent_risk before accepting an inbound request from an unknown agent. The trust score flows back into HiveAgent's routing and pricing decisions.

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│  Layer 1 — Identity KYA                                             │
│  ┌────────────────┐  ┌──────────────────┐  ┌───────────────────┐  │
│  │  DID Registry  │  │  Ed25519 Proofs  │  │  W3C-VC Issuance  │  │
│  └────────────────┘  └──────────────────┘  └───────────────────┘  │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 2 — Reputation Engine                                        │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  Telemetry Ingest → Pillar Computation → Score 0-1000       │   │
│  │  (35% txSuccess + 25% capital + 15% network +               │   │
│  │   15% identity + 10% compliance)                            │   │
│  └─────────────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 3 — Insurance Underwriter                                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │  Quote Engine │  │  USDC Escrow │  │  Parametric Claims       │  │
│  │  (dynamic    │  │  (Base L2    │  │  (on-chain trigger →      │  │
│  │   premium)   │  │   Coinbase)  │  │   instant payout)        │  │
│  └──────────────┘  └──────────────┘  └──────────────────────────┘  │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 4 — Data Moat                                                │
│  ┌──────────────────────┐  ┌────────────────────────────────────┐  │
│  │  Behavioural Graph   │  │  Federation (cross-registry sync)  │  │
│  │  (audit trail,       │  │  Aggregated data licensing         │  │
│  │   PageRank, patterns)│  │  to enterprise customers           │  │
│  └──────────────────────┘  └────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

---

Quick Start

# Clone
git clone https://github.com/hiveagentiq/hivetrust.git
cd hivetrust

# Install
npm install

# Configure
cp .env.example .env
# Edit .env with your values

# Seed sample data (optional)
node src/seed.js

# Start
npm start
# Server running on http://localhost:3001

The health endpoint confirms it's live:

curl http://localhost:3001/health
# {"status":"ok","version":"1.0.0","uptime":3.14}

---

API Reference

All endpoints are prefixed /v1 unless noted. Authentication via X-API-Key header.

Identity (KYA)

Method	Path	Description	Cost
POST	/v1/agents	Register a new agent (issues DID, stores public key)	$0.01
GET	/v1/agents/:id	Retrieve full agent profile + current trust tier	Free
PUT	/v1/agents/:id	Update agent metadata (creates immutable version snapshot)	$0.01
DELETE	/v1/agents/:id	Deactivate agent (adds to revocation registry)	Free

Credentials

Method	Path	Description	Cost
POST	/v1/agents/:id/credentials	Issue a W3C Verifiable Credential	$0.05
GET	/v1/agents/:id/credentials	List all credentials for an agent	Free
DELETE	/v1/agents/:id/credentials/:credId	Revoke a credential	Free
POST	/v1/verify/credential	Verify a presented credential (revocation + sig check)	$0.01

Trust Score

Method	Path	Description	Cost
GET	/v1/agents/:id/score	Current composite score + pillar breakdown	$0.01
GET	/v1/agents/:id/score/history	Score over time (pagination supported)	$0.01
GET	/v1/verify_agent_risk	Fast binary risk check — clear or block (< 50ms)	$0.01

Telemetry

Method	Path	Description	Cost
POST	/v1/telemetry/ingest	Bulk behavioural event ingestion (up to 1 000 events/call)	$0.001/event
GET	/v1/agents/:id/events	Query the agent's full audit trail	Free

Insurance

Method	Path	Description	Cost
POST	/v1/insurance/quote	Dynamic premium quote (based on trust scores + value)	Free
POST	/v1/insurance/bind	Bind policy and deploy USDC escrow on Base L2	1.5% of insured value
GET	/v1/insurance/policies/:id	Retrieve policy details and coverage status	Free
POST	/v1/insurance/claims	File a parametric claim	Free
GET	/v1/insurance/claims/:id	Get claim status and payout history	Free

Disputes

Method	Path	Description	Cost
POST	/v1/disputes	File a dispute against a counterparty	Free
GET	/v1/disputes/:id	Get dispute status and evidence log	Free
POST	/v1/disputes/:id/resolve	Submit resolution (impacts both parties' scores)	Free

Webhooks

Method	Path	Description	Cost
POST	/v1/webhooks	Register a webhook endpoint (HMAC-SHA256 signed)	Free
GET	/v1/webhooks	List registered webhooks	Free
DELETE	/v1/webhooks/:id	Remove webhook	Free

Federation

Method	Path	Description	Cost
POST	/v1/federation/peers	Register a peer HiveTrust-compatible registry	Free
GET	/v1/federation/peers	List federated peers	Free
POST	/v1/federation/sync	Sync trust scores bidirectionally with a peer	Free

System

Method	Path	Description	Cost
GET	/health	Health check (no auth required)	Free
GET	/v1/stats	Platform-wide statistics (total agents, volume, etc.)	Free
GET	/.well-known/hivetrust.json	Discovery document	Free

---

MCP Integration

HiveTrust exposes all core operations as MCP tools via a single JSON-RPC 2.0 endpoint at POST /mcp. This lets any MCP-compatible agent (including HiveAgent) call HiveTrust natively without REST boilerplate.

List available tools

POST /mcp
Content-Type: application/json
X-API-Key: ht_your_api_key

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Call a tool

POST /mcp
Content-Type: application/json
X-API-Key: ht_your_api_key

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "hivetrust_get_trust_score",
    "arguments": { "agent_id": "a1b2c3d4-..." }
  }
}

Available MCP Tools

Tool	Description
hivetrust_register_agent	Register a new agent and receive a DID
hivetrust_get_agent	Retrieve agent profile
hivetrust_verify_identity	Run a full KYA verification flow
hivetrust_get_trust_score	Get current trust score + pillar breakdown
hivetrust_verify_agent_risk	Fast binary risk check for payment gating
hivetrust_ingest_telemetry	Submit behavioural events
hivetrust_issue_credential	Issue a W3C Verifiable Credential
hivetrust_verify_credential	Verify a presented credential
hivetrust_revoke_credential	Revoke a credential
hivetrust_get_insurance_quote	Get dynamic premium quote
hivetrust_bind_insurance	Bind policy and deploy escrow
hivetrust_file_claim	File a parametric insurance claim
hivetrust_file_dispute	Initiate a dispute resolution
hivetrust_get_platform_stats	Retrieve platform-wide statistics

---

Revenue Model

HiveTrust operates five revenue streams:

Stream	Mechanism	Target
KYA API Calls	$0.01 per verification call	High-frequency agent interactions
Enterprise SaaS	$50–$500/month per operator	Compliance teams, regulated industries
Insurance Premiums	1.5% take rate on insured transactions	Payment agents, DeFi integrations
Collateral Staking Yield	3% spread on USDC collateral pool	Staked capital from high-tier agents
Data Licensing	Aggregated behavioural insights	Enterprises, risk modellers, AI labs

---

Environment Variables

Variable	Default	Required	Description
PORT	3001	No	Server listen port
NODE_ENV	development	No	Node environment
HIVETRUST_HOST	https://hivetrust.hiveagentiq.com	Yes (prod)	Public base URL
INTERNAL_API_TOKEN	—	Yes (prod)	Service-to-service auth token
WEBHOOK_SIGNING_SECRET	—	Yes	HMAC secret for webhook payloads
HIVEAGENT_URL	https://hiveagentiq.com	No	HiveAgent platform URL
CDP_API_KEY_ID	—	Yes (insurance)	Coinbase CDP key ID
CDP_API_KEY_SECRET	—	Yes (insurance)	Coinbase CDP key secret
COLLATERAL_POOL_ADDRESS	—	Yes (insurance)	USDC escrow contract on Base L2
BASE_RPC_URL	https://mainnet.base.org	No	Base L2 RPC endpoint
DB_PATH	data/hivetrust.db	No	SQLite database file path
FEDERATION_SECRET	—	Yes (federation)	Shared secret for peer sync
FEDERATION_PEERS	—	No	Comma-separated peer URLs
INSURANCE_MIN_SCORE	300	No	Minimum score for insurance eligibility
INSURANCE_MAX_COVERAGE_USDC	100000	No	Per-transaction coverage cap
INSURANCE_BASE_RATE	0.015	No	Base premium as fraction of insured value
SCORE_REFRESH_INTERVAL_MINUTES	60	No	Background score recompute frequency
LOG_LEVEL	info	No	Logging verbosity

See .env.example for the full annotated list.

---

Deployment

Render (recommended for development)

# Push to GitHub, then connect the repo in the Render dashboard
# render.yaml is already configured — click "Apply"

# Or deploy manually:
render deploy

The included render.yaml sets free-tier web service, auto-generates secrets, and configures all env vars.

Fly.io (recommended for production)

# Install flyctl: https://fly.io/docs/hands-on/install-flyctl/
fly auth login
fly apps create hivetrust

# Create a persistent volume for SQLite
fly volumes create hivetrust_data --region ord --size 3

# Deploy
fly deploy

See fly.toml for the full configuration. Auto-stop/start is enabled to minimise costs.

Docker

# Build
docker build -t hivetrust:latest .

# Run
docker run -p 3001:3001 \
  -e NODE_ENV=production \
  -e INTERNAL_API_TOKEN=your_token \
  -v $(pwd)/data:/app/data \
  hivetrust:latest

Railway

railway init
railway up

Set environment variables in the Railway dashboard using .env.example as the reference.

---

Tech Stack

Component	Technology
Runtime	Node.js 22 (ES Modules)
Framework	Express 5.2.1
Database	SQLite via better-sqlite3 12.8.0 (WAL mode)
Identity	Ed25519 keys (base58), DID:hive, W3C-VC
Protocol	MCP JSON-RPC 2.0, REST, x402
Payments	USDC on Base L2 via Coinbase CDP
IDs	UUID v4 throughout
Timestamps	ISO 8601

---

SDK

JavaScript / TypeScript

npm install @hivetrust/sdk

import { HiveTrustClient } from '@hivetrust/sdk';

const trust = new HiveTrustClient('https://hivetrust.hiveagentiq.com', 'ht_your_api_key');

// Register an agent
const agent = await trust.registerAgent({
  name: 'MyAgent-v1',
  operator_name: 'Acme Corp',
  endpoint_url: 'https://myagent.acme.example/mcp',
  public_key: 'edPublicKeyBase58...',
});

// Check trust before transacting
const score = await trust.getTrustScore(agent.id);
console.log(score.score, score.tier); // 680 "elevated"

// Get insurance quote
const quote = await trust.getInsuranceQuote(agent.id, counterpartyId, 1000);
console.log(quote.premium_usdc); // 15.00

See packages/npm/ for the full SDK source.

Python

pip install hivetrust

from hivetrust import HiveTrustClient

trust = HiveTrustClient("https://hivetrust.hiveagentiq.com", "ht_your_api_key")

score = trust.get_trust_score("agent-id-here")
print(score["score"], score["tier"])

See packages/python/ for the full SDK source.

---

License

MIT © 2026 HiveAgent IQ