Docs · v3.1 · Updated 2026.05.14

Build with Halo.

Halo is the decentralized reputation layer for AI agents on Solana. This guide will take you from a pnpm add to a settled attestation on devnet in under five minutes. Mainnet works the same way — only the cluster changes.

Quickstart · 5 minutes

You will need a devnet key. Get one in the request form, or grab one over chat in 30 seconds. The same key works on mainnet — only the prefix changes.

$ pnpm add @halo/sdk @solana/web3.js
$ export HALO_KEY="hl_dev_01J9Q2X7Kc…"

import { halo } from "@halo/sdk";
import { Keypair } from "@solana/web3.js";

const agent = await halo.agents.register(({
name:     "shop-mcp.v3",
domains:  ["finance", "defi"],
cluster:  "devnet",
}));

// → agent.did:   did:halo:7Xk9…4Ymr
// → agent.score: 50.0 (genesis · neutral)

await halo.attestations.submit(({
subject: agent.did,
verb:    "settled",
object:  "jupiter.swap",
outcome: "ok",
domain:  "defi",
}));

// → anchored on Solana in ~412ms
// → reputation visible in /explore within 1s

That's the whole quickstart. Everything else is depth, not prerequisites.

Core concepts

Five objects make up the entire data model. Once you have these you can read any endpoint without a glossary.

TypeScript SDK

Reference implementation. Node 18+, edge runtimes (Vercel, Cloudflare Workers), browser. Source on github.com/halo-research/sdk-ts.

import { halo } from "@halo/sdk";

const score = await halo.query.score(({
agent:  "did:halo:7Xk9…4Ymr",
domain: "finance",
}));

if (score.value < 80) return "reject";
return "approve";

Python SDK

Async-first, httpx + solders. Python 3.11+. Source on github.com/halo-research/sdk-py.

from halo import Halo

hl = Halo(api_key=os.environ["HALO_KEY"])

score = await hl.query.score(
agent="did:halo:7Xk9…4Ymr",
domain="finance",
)
if score.value < 80:
return "reject"

Rust SDK

For latency-sensitive runtimes and on-chain verifier programs. Source on github.com/halo-research/sdk-rs.

use halo::Client;

let client = Client::builder().api_key(&key).build();
let score = client.query_score(&did, "finance").await?;

if score.value < 80.0 { return "reject"; }

Register an agent

{
"name":    "shop-mcp.v3",
"pubkey":  "7Xk9…4Ymr",
"domains": ["finance", "defi"],
"controller": "HfRz…vL2T"
}

Submit an attestation

{
"subject": "did:halo:7Xk9…4Ymr",
"verb":    "settled",
"object":  "jupiter.swap",
"outcome": "ok",
"domain":  "defi",
"issuer_sig": "ed25519:0a3f…"
}

Query reputation

GET /v1/score/did:halo:7Xk9…4Ymr?domain=finance

// → 200 OK
{
"did":        "did:halo:7Xk9…4Ymr",
"domain":     "finance",
"score":      86.2,
"tier":       "trusted",
"updated_slot": 297841022,
"sources":    2418
}

Slash flow

Submit evidence with POST /v1/slashes. The protocol opens a 24h challenge window; the subject can refute with counter-evidence. After the window, the slash committee (3-of-5) signs the verdict. Stake is burned, reputation cut, the chain remembers.

Run an oracle

Operator-tier stakers can run as whitelisted oracles. Your attestations carry higher weight, but you carry larger slash exposure. The protocol is opinionated: the more you can hurt, the more you can earn.

Webhooks

Subscribe to events at /v1/webhooks. Payloads are signed with your workspace key, delivered at-least-once, idempotent on event_id.

Error codes

Status

Live status, incident history, and Solana RPC latency live at status.halo.research. Subscribe via RSS, Slack, or webhook. We post an RCA within 48h of any sev-1.