{
  "markdown": "# 🐝 HiveTrust\n\n```\n██╗  ██╗██╗██╗   ██╗███████╗████████╗██████╗ ██╗   ██╗███████╗████████╗\n██║  ██║██║██║   ██║██╔════╝╚══██╔══╝██╔══██╗██║   ██║██╔════╝╚══██╔══╝\n███████║██║██║   ██║█████╗     ██║   ██████╔╝██║   ██║███████╗   ██║   \n██╔══██║██║╚██╗ ██╔╝██╔══╝     ██║   ██╔══██╗██║   ██║╚════██║   ██║   \n██║  ██║██║ ╚████╔╝ ███████╗   ██║   ██║  ██║╚██████╔╝███████║   ██║   \n╚═╝  ╚═╝╚═╝  ╚═══╝  ╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝   \n```\n\n> **\"The Equifax + GEICO of the A2A Economy\"**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node.js 22](https://img.shields.io/badge/Node.js-22-green.svg)](https://nodejs.org)\n[![ES Modules](https://img.shields.io/badge/ESM-pure-blue.svg)](#)\n[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple.svg)](#mcp-integration)\n\n---\n\nHiveTrust 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.\n\nAs 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.\n\n---\n\n## What HiveTrust Does\n\n### 🪪 KYA Identity Verification\nAgents are pseudonymous by default. HiveTrust anchors each agent to a verifiable, unforgeable identity:\n\n- **DID registration** (`did:hive:<uuid>`) with Ed25519 public key binding\n- **Challenge–response proofs** — the agent must sign a random nonce to prove key ownership\n- **Capability manifest validation** — declared tools and permissions are logged immutably\n- **W3C Verifiable Credentials** issued at each verification tier\n- **Revocation registry** with real-time status checks\n\n### 📊 Trust Scoring (0 – 1000)\nHiveTrust's scoring engine synthesises five behavioural pillars into a single, portable reputation score:\n\n| Pillar | Weight | What it measures |\n|--------|--------|-----------------|\n| Transaction Success Rate | 35% | SLA completion vs. disputes |\n| Capital Staked | 25% | USDC locked in collateral pool |\n| Network Centrality | 15% | PageRank of the transaction graph |\n| Identity Strength | 15% | DID anchor age, ZKP proofs, checksum stability |\n| Compliance | 10% | EU AI Act, NIST AI RMF, fidelity probe results |\n\n**Trust tiers:** `unverified` (0–199) · `provisional` (200–399) · `standard` (400–599) · `elevated` (600–799) · `sovereign` (800–1000)\n\n### 🛡️ Parametric Insurance\nWhen agents transact with strangers, someone has to absorb the tail risk. HiveTrust provides:\n\n- **On-demand quote** — dynamic premium priced from trust scores and transaction value\n- **Instant bind** — policy activated before the transaction settles\n- **Parametric claims** — automatic payout triggered by on-chain proof, not human adjudication\n- **Three product lines:** transaction coverage · performance bonds · liability policies\n\n---\n\n## How HiveTrust Complements HiveAgent\n\n[HiveAgent](https://hiveagentiq.com) is the **agent runtime** — it executes tasks, manages tool calls, and handles the A2A protocol layer.\n\nHiveTrust is the **trust fabric underneath it**:\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                         Your Application                        │\n├─────────────────────────────────────────────────────────────────┤\n│                HiveAgent  (task execution, A2A)                 │\n│                         ↕  REST / MCP                          │\n│  HiveTrust  (identity, reputation, insurance, compliance)       │\n├──────────────────────────────────┬──────────────────────────────┤\n│   On-chain (Base L2 / USDC)     │  Off-chain (SQLite / Events) │\n└──────────────────────────────────┴──────────────────────────────┘\n```\n\nHiveAgent 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.\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│  Layer 1 — Identity KYA                                             │\n│  ┌────────────────┐  ┌──────────────────┐  ┌───────────────────┐  │\n│  │  DID Registry  │  │  Ed25519 Proofs  │  │  W3C-VC Issuance  │  │\n│  └────────────────┘  └──────────────────┘  └───────────────────┘  │\n├─────────────────────────────────────────────────────────────────────┤\n│  Layer 2 — Reputation Engine                                        │\n│  ┌─────────────────────────────────────────────────────────────┐   │\n│  │  Telemetry Ingest → Pillar Computation → Score 0-1000       │   │\n│  │  (35% txSuccess + 25% capital + 15% network +               │   │\n│  │   15% identity + 10% compliance)                            │   │\n│  └─────────────────────────────────────────────────────────────┘   │\n├─────────────────────────────────────────────────────────────────────┤\n│  Layer 3 — Insurance Underwriter                                    │\n│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │\n│  │  Quote Engine │  │  USDC Escrow │  │  Parametric Claims       │  │\n│  │  (dynamic    │  │  (Base L2    │  │  (on-chain trigger →      │  │\n│  │   premium)   │  │   Coinbase)  │  │   instant payout)        │  │\n│  └──────────────┘  └──────────────┘  └──────────────────────────┘  │\n├─────────────────────────────────────────────────────────────────────┤\n│  Layer 4 — Data Moat                                                │\n│  ┌──────────────────────┐  ┌────────────────────────────────────┐  │\n│  │  Behavioural Graph   │  │  Federation (cross-registry sync)  │  │\n│  │  (audit trail,       │  │  Aggregated data licensing         │  │\n│  │   PageRank, patterns)│  │  to enterprise customers           │  │\n│  └──────────────────────┘  └────────────────────────────────────┘  │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Quick Start\n\n```bash\n# Clone\ngit clone https://github.com/hiveagentiq/hivetrust.git\ncd hivetrust\n\n# Install\nnpm install\n\n# Configure\ncp .env.example .env\n# Edit .env with your values\n\n# Seed sample data (optional)\nnode src/seed.js\n\n# Start\nnpm start\n# Server running on http://localhost:3001\n```\n\nThe health endpoint confirms it's live:\n\n```bash\ncurl http://localhost:3001/health\n# {\"status\":\"ok\",\"version\":\"1.0.0\",\"uptime\":3.14}\n```\n\n---\n\n## API Reference\n\nAll endpoints are prefixed `/v1` unless noted. Authentication via `X-API-Key` header.\n\n### Identity (KYA)\n\n| Method | Path | Description | Cost |\n|--------|------|-------------|------|\n| `POST` | `/v1/agents` | Register a new agent (issues DID, stores public key) | $0.01 |\n| `GET` | `/v1/agents/:id` | Retrieve full agent profile + current trust tier | Free |\n| `PUT` | `/v1/agents/:id` | Update agent metadata (creates immutable version snapshot) | $0.01 |\n| `DELETE` | `/v1/agents/:id` | Deactivate agent (adds to revocation registry) | Free |\n\n### Credentials\n\n| Method | Path | Description | Cost |\n|--------|------|-------------|------|\n| `POST` | `/v1/agents/:id/credentials` | Issue a W3C Verifiable Credential | $0.05 |\n| `GET` | `/v1/agents/:id/credentials` | List all credentials for an agent | Free |\n| `DELETE` | `/v1/agents/:id/credentials/:credId` | Revoke a credential | Free |\n| `POST` | `/v1/verify/credential` | Verify a presented credential (revocation + sig check) | $0.01 |\n\n### Trust Score\n\n| Method | Path | Description | Cost |\n|--------|------|-------------|------|\n| `GET` | `/v1/agents/:id/score` | Current composite score + pillar breakdown | $0.01 |\n| `GET` | `/v1/agents/:id/score/history` | Score over time (pagination supported) | $0.01 |\n| `GET` | `/v1/verify_agent_risk` | Fast binary risk check — `clear` or `block` (< 50ms) | $0.01 |\n\n### Telemetry\n\n| Method | Path | Description | Cost |\n|--------|------|-------------|------|\n| `POST` | `/v1/telemetry/ingest` | Bulk behavioural event ingestion (up to 1 000 events/call) | $0.001/event |\n| `GET` | `/v1/agents/:id/events` | Query the agent's full audit trail | Free |\n\n### Insurance\n\n| Method | Path | Description | Cost |\n|--------|------|-------------|------|\n| `POST` | `/v1/insurance/quote` | Dynamic premium quote (based on trust scores + value) | Free |\n| `POST` | `/v1/insurance/bind` | Bind policy and deploy USDC escrow on Base L2 | 1.5% of insured value |\n| `GET` | `/v1/insurance/policies/:id` | Retrieve policy details and coverage status | Free |\n| `POST` | `/v1/insurance/claims` | File a parametric claim | Free |\n| `GET` | `/v1/insurance/claims/:id` | Get claim status and payout history | Free |\n\n> **`claim_type` namespace note:** HiveTrust's `claim_type` field (`non_delivery | fraud | sla_breach | data_loss | unauthorized_action`) is distinct from the CTEF envelope-level `claim_type` (`identity | transport | authority | continuity`) defined in [A2A CTEF v0.3.1](https://github.com/a2aproject/A2A/discussions/1734). Both tokens coexist at disjoint envelope levels — see [docs/CLAIM_TYPE_NAMESPACE.md](docs/CLAIM_TYPE_NAMESPACE.md).\n\n### Disputes\n\n| Method | Path | Description | Cost |\n|--------|------|-------------|------|\n| `POST` | `/v1/disputes` | File a dispute against a counterparty | Free |\n| `GET` | `/v1/disputes/:id` | Get dispute status and evidence log | Free |\n| `POST` | `/v1/disputes/:id/resolve` | Submit resolution (impacts both parties' scores) | Free |\n\n### Webhooks\n\n| Method | Path | Description | Cost |\n|--------|------|-------------|------|\n| `POST` | `/v1/webhooks` | Register a webhook endpoint (HMAC-SHA256 signed) | Free |\n| `GET` | `/v1/webhooks` | List registered webhooks | Free |\n| `DELETE` | `/v1/webhooks/:id` | Remove webhook | Free |\n\n### Federation\n\n| Method | Path | Description | Cost |\n|--------|------|-------------|------|\n| `POST` | `/v1/federation/peers` | Register a peer HiveTrust-compatible registry | Free |\n| `GET` | `/v1/federation/peers` | List federated peers | Free |\n| `POST` | `/v1/federation/sync` | Sync trust scores bidirectionally with a peer | Free |\n\n### System\n\n| Method | Path | Description | Cost |\n|--------|------|-------------|------|\n| `GET` | `/health` | Health check (no auth required) | Free |\n| `GET` | `/v1/stats` | Platform-wide statistics (total agents, volume, etc.) | Free |\n| `GET` | `/.well-known/hivetrust.json` | Discovery document | Free |\n\n---\n\n## MCP Integration\n\nHiveTrust exposes all core operations as [MCP](https://modelcontextprotocol.io) 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.\n\n### List available tools\n\n```http\nPOST /mcp\nContent-Type: application/json\nX-API-Key: ht_your_api_key\n\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/list\"\n}\n```\n\n### Call a tool\n\n```http\nPOST /mcp\nContent-Type: application/json\nX-API-Key: ht_your_api_key\n\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 2,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"hivetrust_get_trust_score\",\n    \"arguments\": { \"agent_id\": \"a1b2c3d4-...\" }\n  }\n}\n```\n\n### Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `hivetrust_register_agent` | Register a new agent and receive a DID |\n| `hivetrust_get_agent` | Retrieve agent profile |\n| `hivetrust_verify_identity` | Run a full KYA verification flow |\n| `hivetrust_get_trust_score` | Get current trust score + pillar breakdown |\n| `hivetrust_verify_agent_risk` | Fast binary risk check for payment gating |\n| `hivetrust_ingest_telemetry` | Submit behavioural events |\n| `hivetrust_issue_credential` | Issue a W3C Verifiable Credential |\n| `hivetrust_verify_credential` | Verify a presented credential |\n| `hivetrust_revoke_credential` | Revoke a credential |\n| `hivetrust_get_insurance_quote` | Get dynamic premium quote |\n| `hivetrust_bind_insurance` | Bind policy and deploy escrow |\n| `hivetrust_file_claim` | File a parametric insurance claim |\n| `hivetrust_file_dispute` | Initiate a dispute resolution |\n| `hivetrust_get_platform_stats` | Retrieve platform-wide statistics |\n\n\n---\n\n## CTEF v0.3.1 Endpoint\n\nHiveTrust is the **5th canonicalizer** in the CTEF (Composable Trust Evidence Format) v0.3.1 byte-match consortium: AgentGraph + AgentID + APS + Nobulex + **HiveTrust**. Seat committed at the [2026-04-25 01:48 UTC freeze](https://github.com/a2aproject/A2A/discussions/1734).\n\nPatent applications 64/049,200 – 64/049,226, priority 2026-04-24, holder: Stephen A. Rotzin / TheHiveryIQ.\n\n### Endpoints\n\n| Route | Method | Auth | Description |\n|-------|--------|------|-------------|\n| [`/.well-known/cte-test-vectors.json`](https://hivetrust.hiveagentiq.com/.well-known/cte-test-vectors.json) | GET | Public | CTEF v0.3.1 fixture with all 4 vectors |\n| `/verify` | GET `?did=` | Free (1st/day) | HiveTrust passport tier lookup |\n| `/verify` | POST | 10/day free, then $0.01 USDC | Structural verification of a CTEF envelope |\n| `/verify/pubkey` | GET | Public | Ed25519 attestation pubkey for Apr 30 byte-match |\n| `/verify/self-test` | GET | Public | Run all 4 vectors — returns pass/fail counts |\n\n### CTEF Fixture\n\n```bash\ncurl https://hivetrust.hiveagentiq.com/.well-known/cte-test-vectors.json | jq '.version'\n# \"0.3.1\"\n```\n\n### Structural Verification (POST /verify)\n\n```bash\n# First 10 requests/day per IP are free\ncurl -X POST https://hivetrust.hiveagentiq.com/verify \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"type\":\"TrustAttestation\",\"version\":\"0.3.1\",\"claim_type\":\"authority\",...}'\n\n# Returns: { verdict: \"valid\"|\"INVALID_CLAIM_SCOPE\"|\"INVALID_COMPOSITION\",\n#             canonical_sha256: \"...\", pass: true|false }\n```\n\nBeyond 10 free requests/day, the endpoint returns HTTP 402 with an x402 payment challenge: $0.01 USDC on Base chain 8453.\n\n### Self-Test\n\n```bash\ncurl https://hivetrust.hiveagentiq.com/verify/self-test | jq '.data.summary'\n```\n\n### Canonicalization\n\nAll vectors use RFC 8785 JCS — implemented inline in `src/routes/cte.js`. The implementation produces byte-identical output to AgentGraph's `canonicalize_jcs_strict` for all 4 shared test vectors:\n\n- **envelope_vector** SHA-256: `9e7b5031e46de38b5f90e895113a3f24f42a4128d8d99856a2d71e529b0f0d5c`\n- **verdict_vector** SHA-256: `feb42dca4214fc46207138d676ec727d7b3d0caa1eda8c0390d2d6f6fbc28913`\n- **scope_violation_vector** SHA-256: `e584f1cd0885dc938da5fc23ce7e528715a0086e5464c9ed0f3c1c82b364026f`\n- **composition_failure_vector** SHA-256: `f9cd10bc4e8bf34ce3aa6a0e5df0d27989e54ff41c4333c69ae3ecfaf8de0cb5`\n\n---\n\n## Revenue Model\n\nHiveTrust operates five revenue streams:\n\n| Stream | Mechanism | Target |\n|--------|-----------|--------|\n| **KYA API Calls** | $0.01 per verification call | High-frequency agent interactions |\n| **Enterprise SaaS** | $50–$500/month per operator | Compliance teams, regulated industries |\n| **Insurance Premiums** | 1.5% take rate on insured transactions | Payment agents, DeFi integrations |\n| **Collateral Staking Yield** | 3% spread on USDC collateral pool | Staked capital from high-tier agents |\n| **Data Licensing** | Aggregated behavioural insights | Enterprises, risk modellers, AI labs |\n\n---\n\n## Environment Variables\n\n| Variable | Default | Required | Description |\n|----------|---------|----------|-------------|\n| `PORT` | `3001` | No | Server listen port |\n| `NODE_ENV` | `development` | No | Node environment |\n| `HIVETRUST_HOST` | `https://hivetrust.hiveagentiq.com` | Yes (prod) | Public base URL |\n| `INTERNAL_API_TOKEN` | — | Yes (prod) | Service-to-service auth token |\n| `WEBHOOK_SIGNING_SECRET` | — | Yes | HMAC secret for webhook payloads |\n| `HIVEAGENT_URL` | `https://hiveagentiq.com` | No | HiveAgent platform URL |\n| `CDP_API_KEY_ID` | — | Yes (insurance) | Coinbase CDP key ID |\n| `CDP_API_KEY_SECRET` | — | Yes (insurance) | Coinbase CDP key secret |\n| `COLLATERAL_POOL_ADDRESS` | — | Yes (insurance) | USDC escrow contract on Base L2 |\n| `BASE_RPC_URL` | `https://mainnet.base.org` | No | Base L2 RPC endpoint |\n| `DB_PATH` | `data/hivetrust.db` | No | SQLite database file path |\n| `FEDERATION_SECRET` | — | Yes (federation) | Shared secret for peer sync |\n| `FEDERATION_PEERS` | — | No | Comma-separated peer URLs |\n| `INSURANCE_MIN_SCORE` | `300` | No | Minimum score for insurance eligibility |\n| `INSURANCE_MAX_COVERAGE_USDC` | `100000` | No | Per-transaction coverage cap |\n| `INSURANCE_BASE_RATE` | `0.015` | No | Base premium as fraction of insured value |\n| `SCORE_REFRESH_INTERVAL_MINUTES` | `60` | No | Background score recompute frequency |\n| `LOG_LEVEL` | `info` | No | Logging verbosity |\n\nSee [`.env.example`](.env.example) for the full annotated list.\n\n---\n\n## Deployment\n\n### Render (recommended for development)\n\n```bash\n# Push to GitHub, then connect the repo in the Render dashboard\n# render.yaml is already configured — click \"Apply\"\n\n# Or deploy manually:\nrender deploy\n```\n\nThe included [`render.yaml`](render.yaml) sets free-tier web service, auto-generates secrets, and configures all env vars.\n\n### Fly.io (recommended for production)\n\n```bash\n# Install flyctl: https://fly.io/docs/hands-on/install-flyctl/\nfly auth login\nfly apps create hivetrust\n\n# Create a persistent volume for SQLite\nfly volumes create hivetrust_data --region ord --size 3\n\n# Deploy\nfly deploy\n```\n\nSee [`fly.toml`](fly.toml) for the full configuration. Auto-stop/start is enabled to minimise costs.\n\n### Docker\n\n```bash\n# Build\ndocker build -t hivetrust:latest .\n\n# Run\ndocker run -p 3001:3001 \\\n  -e NODE_ENV=production \\\n  -e INTERNAL_API_TOKEN=your_token \\\n  -v $(pwd)/data:/app/data \\\n  hivetrust:latest\n```\n\n### Railway\n\n```bash\nrailway init\nrailway up\n```\n\nSet environment variables in the Railway dashboard using `.env.example` as the reference.\n\n---\n\n## Tech Stack\n\n| Component | Technology |\n|-----------|------------|\n| Runtime | Node.js 22 (ES Modules) |\n| Framework | Express 5.2.1 |\n| Database | SQLite via better-sqlite3 12.8.0 (WAL mode) |\n| Identity | Ed25519 keys (base58), DID:hive, W3C-VC |\n| Protocol | MCP JSON-RPC 2.0, REST, x402 |\n| Payments | USDC on Base L2 via Coinbase CDP |\n| IDs | UUID v4 throughout |\n| Timestamps | ISO 8601 |\n\n---\n\n## SDK\n\n### JavaScript / TypeScript\n\n```bash\nnpm install @hivetrust/sdk\n```\n\n```js\nimport { HiveTrustClient } from '@hivetrust/sdk';\n\nconst trust = new HiveTrustClient('https://hivetrust.hiveagentiq.com', 'ht_your_api_key');\n\n// Register an agent\nconst agent = await trust.registerAgent({\n  name: 'MyAgent-v1',\n  operator_name: 'Acme Corp',\n  endpoint_url: 'https://myagent.acme.example/mcp',\n  public_key: 'edPublicKeyBase58...',\n});\n\n// Check trust before transacting\nconst score = await trust.getTrustScore(agent.id);\nconsole.log(score.score, score.tier); // 680 \"elevated\"\n\n// Get insurance quote\nconst quote = await trust.getInsuranceQuote(agent.id, counterpartyId, 1000);\nconsole.log(quote.premium_usdc); // 15.00\n```\n\nSee [`packages/npm/`](packages/npm/) for the full SDK source.\n\n### Python\n\n```bash\npip install hivetrust\n```\n\n```python\nfrom hivetrust import HiveTrustClient\n\ntrust = HiveTrustClient(\"https://hivetrust.hiveagentiq.com\", \"ht_your_api_key\")\n\nscore = trust.get_trust_score(\"agent-id-here\")\nprint(score[\"score\"], score[\"tier\"])\n```\n\nSee [`packages/python/`](packages/python/) for the full SDK source.\n\n---\n\n## License\n\n[MIT](LICENSE) © 2026 HiveAgent IQ\n\n\n---\n\n## Hive Civilization\n\nHive Civilization is the cryptographic backbone of autonomous agent commerce — the layer that makes every agent transaction provable, every payment settable, and every decision defensible.\n\nThis repository is part of the **DEFENSIBLE** pillar.\n\n- thehiveryiq.com\n- hiveagentiq.com\n- agent-card: https://hivetrust.hiveagentiq.com/.well-known/agent-card.json\n",
  "bytes": 19776,
  "sha": "192b4cd314afad9051dc9a17e52b5c4f96833f43bf2ec48cb325917827efb7f7",
  "repo_slug": "srotzin/hivetrust",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_srotzin_hivetrust_3f0d883a/readme"
}