@citadelcoord/immune-sdk

TypeScript SDK for Citadel/TideHunter agent security.

Install

npm i @citadelcoord/immune-sdk

Environment Variables

export TIDEHUNTER_API_KEY="thk_..."                              # required
export CITADEL_AGENT_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"   # required
export BASE_URL="https://citadelcoord.com"                       # optional, defaults to prod

Don't know your Agent ID? Run:

curl -sS https://citadelcoord.com/api/agents/me \
  -H "Authorization: Bearer $TIDEHUNTER_API_KEY"

Quickstart

import { citadelFromEnv } from "@citadelcoord/immune-sdk";

const citadel = citadelFromEnv();

// 1. Connect (kernel handshake) — call once on startup
const hs = await citadel.handshake();
console.log("Connected:", hs.agentId, hs.kernel_active);

// 2. Guard an action before executing it
const result = await citadel.guard("transfer", {
  to: "0xabc...",
  amount: "1.5",
  chain: "ethereum",
});

if (result.allowed) {
  console.log("Approved:", result.tier, result.audit_id);
  // proceed with action
} else {
  console.log("Blocked:", result.decision, result.tier);
  // abort
}

API

citadelFromEnv(): Citadel

Creates a client from environment variables (TIDEHUNTER_API_KEY, CITADEL_AGENT_ID, BASE_URL).

createCitadel(config): Citadel

const citadel = createCitadel({
  baseUrl: "https://citadelcoord.com",
  apiKey: "thk_...",
  agentId: "your-agent-uuid",
  timeoutMs: 15000, // optional, default 15s
});

citadel.handshake(): Promise<HandshakeResult>

Activates the agent kernel. Call once on startup.

citadel.evaluate(input): Promise<EvaluateResult>

Full TideHunter v3 evaluate call with custom action/params/context.

citadel.guard(action, params?): Promise<GuardResult>

Convenience wrapper — returns { allowed, decision, tier, audit_id, proof_hash }.

CitadelError

All API errors throw CitadelError with .code, .status, and .requestId.

import { CitadelError } from "@citadelcoord/immune-sdk";

try {
  await citadel.guard("swap", { amount: "100" });
} catch (err) {
  if (err instanceof CitadelError) {
    console.error(err.code);      // "INVALID_KEY"
    console.error(err.status);    // 401
    console.error(err.requestId); // "abc123..."
  }
}

Curl-first?

If you prefer shell scripts, the bootstrap is one command:

export TIDEHUNTER_API_KEY="thk_..."
curl -s https://citadelcoord.com/.well-known/skill.md | bash

See the full skill docs at https://citadelcoord.com/.well-known/skill-docs.md.