hivemind-sdk

TypeScript SDK for the HiveMind Protocol (HMP) — an AI Agent communication protocol where every message is a transaction.

HMP + x402 = communication is transaction. One HTTP request carries identity verification, task delivery, on-chain USDC payment, and execution proof.

Install

npm install hivemind-sdk

Quick Start

Caller Side (Boss Agent)

import { HMPClient } from "hivemind-sdk";
import { Keypair } from "@solana/web3.js";

const client = new HMPClient({ wallet: Keypair.generate() });

const result = await client.invoke("WorkerWalletAddress", {
  endpoint: "https://worker-agent.example.com",
  task: "analyze-token",
  params: { token: "SOL" },
  payment: 0.5, // USDC
});

console.log(result.result); // Worker's response
console.log(result.proof);  // Execution proof (input_hash, output_hash, timing)

Worker Side (Worker Agent)

import { HMPHandler } from "hivemind-sdk";
import { Keypair } from "@solana/web3.js";

const handler = new HMPHandler({ wallet: Keypair.generate() });

// In your HTTP handler (e.g. Hono, Express):
app.post("/hmp/invoke", async (req) => {
  const message = await handler.verify(req.body);
  const data = await doWork(message.payload.task);
  return handler.result(message, { status: "completed", result: data });
});

Multi-Turn Chat

const chat = client.chat("WorkerWalletAddress", {
  endpoint: "https://worker-agent.example.com",
  paymentPerTurn: 0.1, // USDC per message
  maxTurns: 10,
  maxSpend: 2.0,
});

const r1 = await chat.send("Analyze recent SOL trends");
const r2 = await chat.send("Compare with ETH"); // auto-carries context

console.log(chat.turns);      // 2
console.log(chat.totalSpent); // 0.2

Core Concepts

| Concept | Description | |---------|-------------| | HMP Envelope | Signed message with id, timestamp, from/to wallets, payload, payload_hash, and Ed25519 signature | | x402 Payment | Each invoke carries Solana USDC micropayment (0.1–5 USDC) via x402 headers | | Execution Proof | Worker returns input_hash, output_hash, and timing as proof of work | | Identity | Ed25519 keypair (Solana wallet) — both caller and worker sign every message |

API

Classes

• HMPClient — Caller side. Constructs invokes, sends requests, verifies responses.
• HMPHandler — Worker side. Verifies incoming requests, constructs responses.
• HMPChat — Multi-turn conversation built on top of HMPClient.invoke().

Error Codes

| Range | Category | Codes | |-------|----------|-------| | 1xxx | Protocol | INVALID_FORMAT, SIGNATURE_FAILED, TIMESTAMP_EXPIRED, HASH_MISMATCH, DUPLICATE_ID | | 2xxx | Execution | BUSY, UNSUPPORTED_TASK, EXECUTION_FAILED, EXECUTION_TIMEOUT | | 3xxx | Payment | PAYMENT_REQUIRED, PAYMENT_INSUFFICIENT, PAYMENT_VERIFICATION_FAILED |

Links

• Protocol Docs
• GitHub

License

MIT